Mercurial > pidgin.yaz
view doc/PERL-HOWTO.dox @ 7724:613b20c69d2c
[gaim-migrate @ 8369]
this didn't cause me any problems yesterday, and it compiles, and bug fixing is a good thing.
"Some month ago I introduced translatable texts for "gaim --help" and
"gaim-remote --help".
Unfortunately the output of the translated text is often unreadable.
The problem is, that Gaim's *.po files have the UTF-8 locale (because
this is the default charset for GTK+ 2.0). But the users may have
configured other locales. For instance my SuSE Linux 9.0 system is
configured with LANG=de_DE@euro. "euro" is ISO-8859-1 (Western
character set, 8 Bit, with the Euro currency symbol). Lots of UTF-8
characters are unreadable if they are displayed in a 8 Bit charset
without conversion. Only the 7 Bit chars are displayed right.
There are two possible solutions:
1) Make the console texts untranslatable. This isn't very clever.
2) Convert the texts from UTF-8 to user's locale.
I choose the second solution.
The conversion cannot be made during the translation, because gettext
does not allow a mix of different character sets in one po-file.
My patch converts the console strings from UTF-8 to users locale.
Normally this works right, because most users have a locale which is
compatible with their language.
The case where a user uses a language (for instance German:
LANG=de_DE) with an incompatible character set (for instance the 7Bit
charset LC_CTYPE=C) is also handled. The user then sees a warning and
the original UTF-8 message.
At first I tried to make a new UTF-8 function in src/util.c. But the
function is needed 5 times in src/gaim-remote.c and 2 times in
src/main.c. gaim-remote is not linked against util.o. Also there are a
lot of dependencies from util.o to other files, so I will introduce a
lot of trouble to link gaim-remote against util.o.
So I only wrote a function in src/gaim-remote.c and used the UTF-8
conversion inline in src/main.c." --Bjoern Voigt
committer: Tailor Script <tailor@pidgin.im>
author | Luke Schierer <lschiere@pidgin.im> |
---|---|
date | Wed, 03 Dec 2003 13:21:55 +0000 |
parents | 90ed8fcca27c |
children | 775ee46b67a2 |
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