Mercurial > pidgin
view doc/SIGNAL-HOWTO.dox @ 32507:29e9fe5b9264
Pluck fixes for OIM charset conversion.
*** Plucked rev 3053d6a37cc6d8774aba7607b992a4408216adcd (thijsalkemade@gmail.com):
MSN Patch from Thijs (xnyhps) Alkemade which do verify/convert to UTF-8
incoming OIM.
Fixes #14884
*** Plucked rev ecabfaee8a1ca02e18ebadbb41cdcce19e78bc2e (masca@cpw.pidgin.im):
Apply second patch from xnyhps this time to show the message salvaged to user.
Refs #14884
*** Plucked rev b1b8c222ab921963f43e83502b6c6e2e4489a8c4 (qulogic@pidgin.im):
Add newlines to debug messages, and word-wrap lines.
*** Plucked rev fdb56683f2b5f88f7b388aaef6c53c810d19e374 (qulogic@pidgin.im):
We know the length of decode_msg here.
*** Plucked rev f12c9f6a6c31bcd3512f162209285a88a86595ff (qulogic@pidgin.im):
This extra if-level can be dropped.
author | Elliott Sales de Andrade <qulogic@pidgin.im> |
---|---|
date | Mon, 06 Feb 2012 22:42:32 +0000 |
parents | f3e0b1221765 |
children |
line wrap: on
line source
/** @page signal-howto Signals HOWTO @section Introduction The libpurple signals interface is used for general event notification, such as plugins being loaded or unloaded, allowing the GUI frontend to respond appropriately to changing internal data. Unfortunately, its use is not at all obvious from the information in the header files. This document uses code snippets from the Pidgin/libpurple plugin systems to illustrate the proper use of signals. @section overview Overview of Signals Signals in libpurple are very similar to those in GTK+. When certain events happen, a named signal is "emitted" from a certain object. Emitting the signal triggers a series of callbacks that have been "connected" to that signal for that object. These callbacks take appropriate action in response to the signal. @section registering_signal Registering a Signal The first step of using a signal is registering it with libpurple so that callbacks may be connected to it. This is done using purple_signal_register() Here is a slightly modified example from @c purple_plugins_init in @c libpurple/plugin.c : @code purple_signal_register( purple_plugins_get_handle(), /* Instance */ "plugin-load", /* Signal name */ purple_marshal_VOID__POINTER,/* Marshal function */ NULL, /* Callback return value type */ 1, /* Number of callback arguments (not including void *data) */ purple_value_new(PURPLE_TYPE_SUBTYPE,PURPLE_SUBTYPE_PLUGIN) /* Type of first callback argument */ ); @endcode @subsection Instance A reference to the object from which this signal is emitted, and to which potential callbacks should be connected. In this case, it will be the entire plugin module emitting the signal. @subsection signalname Signal Name Unique identifier for the signal itself. @subsection therest Callback function definition The rest of the arguments specify the form of the callback function. @subsubsection marshalfunc Marshal Function @c purple_marshal_VOID__POINTER represents the callback function prototype, not including a "data" argument, explained later. The form is @c purple_marshal_RETURNVALUETYPE__ARG1TYPE_ARG2TYPE_ETC. See signals.h for more possible types. In this case, the callback will have the form @code void cb(void *arg1, void *data) @endcode If @c purple_marshal_BOOLEAN__POINTER_POINTER_POINTER were specified, it would be: @code gboolean cb(void *arg1, void *arg2, void *arg3, void *data) @endcode The @c void @c *data argument at the end of each callback function provides the data argument given to purple_signal_connect() . @subsubsection cb_ret_type Callback return value type In our case, this is NULL, meaning "returns void". @todo This could be described better. @subsubsection num_args Number of arguments The number of arguments (not including @c data ) that the callback function will take. @subsubsection type_arg Type of argument @c purple_value_new(PURPLE_TYPE_SUBTYPE,PURPLE_SUBTYPE_PLUGIN) specifies that the first argument given to the callback will be a @c PurplePlugin* . You will need as many "type of argument" arguments to purple_signal_register() as you specified in "Number of arguments" above. @todo Describe this more. @see value.h @section connect Connecting to the signal Once the signal is registered, you can connect callbacks to it. First, you must define a callback function, such as this one from gtkplugin.c : @code static void plugin_load_cb(PurplePlugin *plugin, gpointer data) { GtkTreeView *view = (GtkTreeView *)data; plugin_loading_common(plugin, view, TRUE); } @endcode Note that the callback function prototype matches that specified in the call to purple_signal_register() above. Once the callback function is defined, you can connect it to the signal. Again from gtkplugin.c , in @c pidgin_plugin_dialog_show() : @code purple_signal_connect(purple_plugins_get_handle(), "plugin-load", /* What to connect to */ plugin_dialog, /* Object receiving the signal */ PURPLE_CALLBACK(plugin_load_cb), /* Callback function */ event_view, /* Data to pass to the callback function ); @endcode The first two arguments ("What to connect to") specify the object emitting the signal (the plugin module) and what signal to listen for ("plugin-load"). The object receiving the signal is @c plugin_dialog , the Pidgin plugins dialog. When @c plugin_dialog is deleted, then @c purple_signals_disconnect_by_handle(plugin_dialog) should be called to remove all signal connections it is associated with. The callback function is given using a helper macro, and finally the @c data argument to be passed to @c plugin_load_cb is given as @c event_view, a pointer to the GTK widget that @c plugin_load_cb needs to update. @section emit-signal Emitting a signal Connecting callbacks to signals is all well and good, but how do you "fire" the signal and trigger the callback? At some point, you must "emit" the signal, which immediately calls all connected callbacks. As seen in @c purple_plugin_load() in plugin.c : @code purple_signal_emit(purple_plugins_get_handle(), "plugin-load", plugin); @endcode This causes the signal "plugin-load" to be emitted from the plugin module (given by @c purple_plugins_get_handle() ), with the newly loaded plugin as the argument to pass to any registered callback functions. In our example, @c plugin_load_cb is called immediately as @code plugin_load_cb(plugin, event_view); @endcode and does whatever it does. */