Howto create and use signals

Simple use of signals
How to provide more flexibility to users?
How most people do the same thing with less code
How users can abuse signals (and why some think it is good)

The signal system which was built in GType is pretty complex and flexible: it is possible for its users to connect at runtime any number of callbacks (implemented in any language for which a binding exists) [15] to any signal and to stop the emission of any signal at any state of the signal emission process. This flexibility makes it possible to use GSignal for much more than just emit events which can be received by numerous clients.

Simple use of signals

The most basic use of signals is to implement simple event notification: for example, if we have a MamanFile object, and if this object has a write method, we might wish to be notified whenever someone uses this method. The code below shows how the user can connect a callback to the write signal. Full code for this simple example is located in sample/signal/maman-file.{h|c} and in sample/signal/test.c

file = g_object_new (MAMAN_FILE_TYPE, NULL);

g_signal_connect (G_OBJECT (file), "write",
                  (GCallback)write_event,
                  NULL);

maman_file_write (file, buffer, 50);

The MamanFile signal is registered in the class_init function:

klass->write_signal_id = 
  g_signal_newv ("write",
                 G_TYPE_FROM_CLASS (g_class),
                 G_SIGNAL_RUN_LAST | G_SIGNAL_NO_RECURSE | G_SIGNAL_NO_HOOKS,
                 NULL /* class closure */,
                 NULL /* accumulator */,
                 NULL /* accu_data */,
                 g_cclosure_marshal_VOID__VOID,
                 G_TYPE_NONE /* return_type */,
                 0     /* n_params */,
                 NULL  /* param_types */);

and the signal is emited in maman_file_write:

void maman_file_write (MamanFile *self, guint8 *buffer, guint32 size)
{
  /* First write data. */
  /* Then, notify user of data written. */
  g_signal_emit (self, MAMAN_FILE_GET_CLASS (self)->write_signal_id,
                 0 /* details */, 
                 NULL);
}

As shown above, you can safely set the details parameter to zero if you do not know what it can be used for. For a discussion of what you could used it for, see the section called “The detail argument”

The signature of the signal handler in the above example is defined as g_cclosure_marshal_VOID__VOID. Its name follows a simple convention which encodes the function parameter and return value types in the function name. Specifically, the value infront of the double underscore is the type of the return value, while the value(s) after the double underscore denote the parameter types. The header gobject/gmarshal.h defines a set of commonly needed closures that one can use.



[15] A python callback can be connected to any signal on any C-based GObject.