# HG changeset patch # User Christian Hammond # Date 1061701448 0 # Node ID 76683fe3c96d44ddaa338dcb94fadbca92b367e2 # Parent 1521c3b63d7fced4e12c6b86100795fbed820d43 [gaim-migrate @ 7126] Cleaned up the page a bit. It's better organized now, and uses doxygen's section stuff. committer: Tailor Script diff -r 1521c3b63d7f -r 76683fe3c96d doc/PERL-HOWTO.dox --- a/doc/PERL-HOWTO.dox Sun Aug 24 04:53:24 2003 +0000 +++ b/doc/PERL-HOWTO.dox Sun Aug 24 05:04:08 2003 +0000 @@ -1,130 +1,126 @@ /** @page perl-howto Perl Scripting 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. + @endsection + + @section 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: -

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. - -

Writing your first perl script

+ @code +use Gaim; - 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: - +%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 ", + url => "http://yoursite.com/", - @code - use Gaim; + load => "plugin_load", + unload => "plugin_unload" +) - %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 ", - url => "http://yoursite.com/", +sub plugin_init { + return %PLUGIN_INFO; +} - load => "plugin_load", - unload => "plugin_unload" - ) - - sub plugin_init { - return %PLUGIN_INFO; - } +sub plugin_load { + my $plugin = shift; +} - sub plugin_load { - my $plugin = shift; - } - - sub plugin_unload { - my $plugin = shift; - } - @endcode +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 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_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_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. + 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. - + @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. -

Timeouts

+ @endsection - 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. + @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; + @code +sub timeout_cb { + my $data = shift; - Gaim::debug_info("my perl plugin", - "Timeout callback called! data says: $data\n"); - } + Gaim::debug_info("my perl plugin", + "Timeout callback called! data says: $data\n"); +} - sub plugin_load { - my $plugin = shift; +sub plugin_load { + my $plugin = shift; - # Start a timeout for 5 seconds. - Gaim::timeout_add($plugin, 5, \&timeout_cb, "Hello!"); - } - @endcode + # Start a timeout for 5 seconds. + Gaim::timeout_add($plugin, 5, \&timeout_cb, "Hello!"); +} + @endcode - Here's another way of calling a timeout: + Here's another way of calling a timeout: - @code - sub plugin_load { - my $plugin = shift; + @code +sub plugin_load { + my $plugin = shift; - # Start a timeout for 5 seconds. - Gaim::timeout_add($plugin, 5, - sub { - my $data = 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!"); - } + Gaim::debug_info("my perl plugin", + "Timeout callback called! data says: $data\n"); + }, "Hello!"); +} @endcode @@ -135,10 +131,9 @@ The data parameter is optional. If you don't have data to pass to the callback, simply omit the parameter. - + @endsection -

Signals

- + @section Signals Signals are how gaim plugins get events. There are a number of @ref Signals signals available. @@ -148,38 +143,38 @@ @code - sub connection_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 connection_signed_on_cb { + my ($gc, $data) = @_; + my $account = $gc->get_account(); - sub plugin_load { - my $plugin = shift; - my $data = ""; + 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); - } + 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. - + @endsection -

Notes

- + @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. - + @endsection -

Resources

- + @section Resources @see Signals @see Perl API Reference + @endsection + */ // vim: syntax=c tw=75 et