view doc/PERL-HOWTO.dox @ 9460:eae7e049d639

[gaim-migrate @ 10285] " This patch completely eliminates the use of the old numeric prpl identifiers. I've noticed that some plugins (both in gaim's cvs and external) continue to use the constants even though they are essentially no longer valid - code that relies on them being unique will fail - the new built-in prpls (SILC and novell) ,and any recent external prpls don't have numeric values. The once side effect that the removal causes is that the code for importing of the old .gaimrc and *.blist files is a little more kludgy (using magic numbers instead of the old constants). IMHO this isn't a big deal as the code will go away eventually anyway. **This patch also fixes the raw plugin so that i compiles once again. **Someone should make sure that the gaim-remote and raw plugins still work. (If the raw doesn't work, it may be unrelated as it hasn't been updated since the latest significant MSN changes - i just made a minor change to make it compile)" --Daniel Atallah (13:44:44) Me: what think you of getting rid of prpl numbers? (13:45:05) Sean: what do you mean? (13:45:27) Me: right now they are listed as deprecated, but still used in a few of our own plugins as well as in some 3rd party stuff (13:45:32) Me: and the enum still exists in the core (13:45:44) Me: and the newwer prpls such as novell don't use them (13:45:59) Me: datallah has submitted a patch to get rid of them entirely (13:46:31) Me: the only thing it would break would be the old blist import, which he hacked into working with magic numbers, but which i tend to think we could remove entirely anyway (13:50:03) Sean: Let's get rid of them, then. (13:50:10) Sean: and take out old .blist code too (13:50:14) Me: cool (13:52:37) Sean: we should get rid of .gaimrc code too, sometime. (13:53:02) Sean: If anyone's seriously just now upgrading from 0.59.x, or whatever, they deserve to lose their preferences. (12:27:56) LSchiere: Paco-Paco: what do you think of getting rid of the deprecated prpl numbers? (12:28:14) Paco-Paco: LSchiere: I think it shouldh ave happened long ago committer: Tailor Script <tailor@pidgin.im>
author Luke Schierer <lschiere@pidgin.im>
date Tue, 06 Jul 2004 18:06:43 +0000
parents 775ee46b67a2
children f17e538bf9e0
line wrap: on
line source

/** @page perl-howto Perl Scripting HOWTO

 @section Introduction
  Perl is the first scripting language compatible with Gaim, and has been a
  valuable aid to developers wishing to write scripts to modify the behavior
  of their favorite instant messenger. A perl script acts like a normal
  plugin, and appears in the list of plugins in Gaim's preferences pane.
  Until now, they have been very basic, and consisted of only a few
  functions. However, with the latest changes to Gaim's perl API, a much
  larger part of Gaim is now open. In time, even such things as Gtk+
  preference panes for perl scripts will be possible.

 @section first-script Writing your first perl script
  Enough of that. You want to know how to write a perl script, right?

  First off, we're going to assume here that you are familiar with perl. Perl
  scripts in Gaim are just normal perl scripts, which happen to use Gaim's
  loadable perl module.

  Now, you're going to want to place your script in $HOME/.gaim/plugins/.
  That's the place where all plugins and scripts go, regardless of language.

  The first thing you're going to write in your script is the necessary code
  to actually register and initialize your script, which looks something like
  this:


  @code
use Gaim;

%PLUGIN_INFO = (
    perl_api_version => 2,
    name             => "Your Plugin's Name",
    version          => "0.1",
    summary          => "Brief summary of your plugin.",
    description      => "Detailed description of what your plugin does.",
    author           => "Your Name <email\@address>",
    url              => "http://yoursite.com/",

    load             => "plugin_load",
    unload           => "plugin_unload"
);

sub plugin_init {
    return %PLUGIN_INFO;
}

sub plugin_load {
    my $plugin = shift;
}

sub plugin_unload {
    my $plugin = shift;
}
  @endcode


  The first thing you see is a hash called @c @%PLUGIN_INFO. It contains
  the basic information on your plugin. In the future, additional fields
  may be allowed, such as ones to setup a Gtk+ preferences pane.

  The @c plugin_init function is required in all perl scripts. Its job
  is to return the @c @%PLUGIN_INFO hash, which Gaim will use to register
  and initialize your plugin.

  The @c plugin_load function is called when the user loads your plugin
  from the preferences, or on startup. It is passed one variable, which
  is a handle to the plugin. This must be used when registering signal
  handlers or timers.

  The @c plugin_unload function is called when the user is unloading your
  plugin. Its job is to clean up anything that must be dealt with before
  unloading, such as removing temporary files or saving configuration
  information. It does @em not have to unregister signal handlers or timers,
  as Gaim will do that for you.

  @warning Do @b NOT put any executable code outside of these functions
           or your own user-defined functions. Variable declarations are
           okay, as long as they're set to be local. Bad Things (TM) can
           happen if you don't follow this simple instruction.


 @section Timeouts
  One feature useful to many perl plugin writers are timeouts. Timeouts allow
  code to be ran after a specified number of seconds, and are rather
  simple to setup. Here's one way of registering a timeout.


  @code
sub timeout_cb {
    my $data = shift;

    Gaim::debug_info("my perl plugin",
                     "Timeout callback called! data says: $data\n");
}

sub plugin_load {
    my $plugin = shift;

    # Start a timeout for 5 seconds.
    Gaim::timeout_add($plugin, 5, \&timeout_cb, "Hello!");
}
  @endcode


  Here's another way of calling a timeout:


  @code
sub plugin_load {
    my $plugin = shift;

    # Start a timeout for 5 seconds.
    Gaim::timeout_add($plugin, 5,
        sub {
            my $data = shift;

            Gaim::debug_info("my perl plugin",
                             "Timeout callback called! data says: $data\n");
        }, "Hello!");
}
  @endcode


  A timeout automatically unregisters when it reaches 0 (which is also
  when the callback is called). If you want a timeout to call a function
  every specified number of seconds, just re-register the timeout
  at the end of the callback.

  The data parameter is optional. If you don't have data to pass to the
  callback, simply omit the parameter.

 @section Signals
  Signals are how gaim plugins get events. There are a number of
  @ref Signals signals available.

  A signal is registered by connecting a signal name owned by an
  instance handle to a callback on the plugin handle. This is best
  illustrated with an example.


  @code
sub signed_on_cb {
    my ($gc, $data) = @_;
    my $account = $gc->get_account();

    Gaim::debug_info("my perl plugin",
                     "Account " . $account->get_username() . " signed on.\n");
}

sub plugin_load {
    my $plugin = shift;
    my $data = "";

    Gaim::signal_connect(Gaim::Connections::handle, "signed-on",
                         $plugin, \&signed_on_cb, $data);
}
  @endcode


  Like timeouts, the callback can be an embedded subroutine, and also
  like timeouts, the data parameter can be omitted.

 @section Notes
  The API in perl is very similar to Gaim's C API. The functions have been
  gathered into packages, but most are the same, and the documentation can
  be a big help at times.

 @section Resources
  @see Signals
  @see Perl API Reference

*/

// vim: syntax=c tw=75 et