# HG changeset patch # User Christian Hammond # Date 1061698926 0 # Node ID 2f6850c7d98076bd0b6cf86c5a80aa3893610561 # Parent fe569b675cd22703a789c9468acc5a6612621a20 [gaim-migrate @ 7122] Added the new Perl Scripting HOWTO. committer: Tailor Script diff -r fe569b675cd2 -r 2f6850c7d980 Doxyfile.in --- a/Doxyfile.in Sun Aug 24 04:08:35 2003 +0000 +++ b/Doxyfile.in Sun Aug 24 04:22:06 2003 +0000 @@ -357,7 +357,7 @@ # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = src +INPUT = src doc # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp @@ -366,7 +366,7 @@ # *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp # *.h++ *.idl *.odl *.cs -FILE_PATTERNS = *.h +FILE_PATTERNS = *.h *.dox # The RECURSIVE tag can be used to turn specify whether or not subdirectories # should be searched for input files as well. Possible values are YES and NO. diff -r fe569b675cd2 -r 2f6850c7d980 doc/PERL-HOWTO.dox --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/PERL-HOWTO.dox Sun Aug 24 04:22:06 2003 +0000 @@ -0,0 +1,185 @@ +/** @page perl-howto Perl Scripting HOWTO + +

Perl Scripting HOWTO

+ + +

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

+ + 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 ", + 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. + + +

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

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

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

Resources

+ + @see Signals + @see Perl API Reference +*/ +// vim: syntax=c tw=75 et diff -r fe569b675cd2 -r 2f6850c7d980 plugins/perl/common/Gaim.pm --- a/plugins/perl/common/Gaim.pm Sun Aug 24 04:08:35 2003 +0000 +++ b/plugins/perl/common/Gaim.pm Sun Aug 24 04:22:06 2003 +0000 @@ -65,8 +65,8 @@ =head1 ABSTRACT -This module provides the interface for using perl scripts as plugins -in Gaim. + This module provides the interface for using perl scripts as plugins + in Gaim. =head1 DESCRIPTION @@ -79,6 +79,36 @@ API, which can be viewed at http://gaim.sourceforge.net/api/ or in the header files in the Gaim source tree. +=head1 FUNCTIONS + +=over + +=item @accounts = Gaim::accounts + +Returns a list of all accounts, online or offline. + +=item @chats = Gaim::chats + +Returns a list of all chats currently open. + +=item @connections = Gaim:connections + +Returns a list of all active connections. + +=item @conversations = Gaim::conversations + +Returns a list of all conversations, both IM and chat, currently open. + +=item @conv_windows = Gaim::conv_windows + +Returns a list of all conversation windows currently open. + +=item @ims = Gaim::ims + +Returns a list of all instant messages currently open. + +=back + =head1 SEE ALSO Gaim C API documentation - http//gaim.sourceforge.net/api/