Qu'est ce qu'un signal ?

Les signaux sont une façon de capter les notifications quand quelque chose arrive et pour modifier le comportement des objets en apportant ce que l'utilisateur veut. Tout signal est identifié de façon unique par un nom, "nom_classe::nom_signal", où nom_signal doit être quelque chose comme  "clicked" et nom_classe doit être "GtkButton". Notez que certaines autres classes peuvent aussi définir un callback "clicked",  à condition qu'il ne dérive pas de GtkButton.

Quand ils sont créés, ils sont aussi assignés à un entier positif unique, l'id du signal (1 est le premier signal, l'id -0 est utilisé pour signaler une erreur). Chaque signal est aussi attaché à un tableau de types qui décrit le prototype du ou des pointeur(s) de fonction (handlers) que vous devez connecter au signal. Finalement, chaque signal a un gestionnaire par défaut (handler) qui est donnée par le pointeur de fonction  dans sa structure de classe : il est exécuté par défaut quand le signal est émis. ( Il est possible qu'un signal soit émis et qu'un gestionnaire définit par l'utilisateur empêche le gestionnaire par défaut d'être exécuté.)

Les signaux sont utilisés par tout le monde, mais ils sont créés uniquement à partir d'un classe de base (on a per class basis) -- aussi vous ne devez pas appeler  gtk_signal_new() sans écrire un nouveau type  GtkObject. Autrement, si vous voulez créer un nouveau signal pour un type existant, vous devez utiliser  gtk_object_class_user_signal_new() pour créer un signal qui ne correspondra pas aux méthodes de construction de classe.

Comment les signaux sont-ils utilisés?

Il y a deux actions de base dans le jeu de manipulation d'un signal. Si vous voulez notifier d'un événement, vous devez connecter un pointeur de fonction et un pointeur de données à un signal; le pointeur de données sera pasé comme dernier argument de la fonction ( à condition que vous utilisiez les fonctions de triage (marshalling) par défaut). Vous recevrez un identifiant id de connexion, un entier unique et positif qui correspondra à cette connexion.

Les fonctions qui veulent notifier à l'utilisateur certaines actions, émettent des signaux..

Terminologie de Base

Note brève sur comment ça marche.

Les fonctions responsables de la traduction des tableaux de GtkArgs dans la sémantique normale de votre compilateur C sont appelées des Marshallers. Elle sont identifiées par gtk_marshal_return_value__parameter_list() par exemple une fonction C retournant un gboolean et prenant un  gint  peut être appelée  gtk_marshal_BOOL__INT(). Toutes les combinaisons possibles de retourné/ paramètre ne sont pas valables, bien sûr, aussi si vous avez écrit un GtkObject avec des paramètres vous pouvez avoir à écrire un  marshaller.

GTK_SIGNAL_OFFSET

#define GTK_SIGNAL_OFFSET	                      GTK_STRUCT_OFFSET

Utilisez à la place de  offsetof(), qui est utilisé s'il existe.

enum GtkSignalRunType

typedef enum			/*< flags >*/
{
  GTK_RUN_FIRST      = G_SIGNAL_RUN_FIRST,
  GTK_RUN_LAST       = G_SIGNAL_RUN_LAST,
  GTK_RUN_BOTH       = (GTK_RUN_FIRST | GTK_RUN_LAST),
  GTK_RUN_NO_RECURSE = G_SIGNAL_NO_RECURSE,
  GTK_RUN_ACTION     = G_SIGNAL_ACTION,
  GTK_RUN_NO_HOOKS   = G_SIGNAL_NO_HOOKS
} GtkSignalRunType;

Configure l'émission du signal et contrôle si le signal peut être émis de façon récursive sur un objet et s'il faut exécuter la méthode par défaut avant ou après le gestionnaire défini par l'utilisateur. 

gtk_signal_new ()

guint gtk_signal_new (const gchar *name,
GtkSignalRunType signal_flags,
GtkType object_type,
guint function_offset,
GtkSignalMarshaller marshaller,
GtkType return_val,
guint n_args,
...);

Creates a new signal type. (This is usually done in the class initializer.)

gtk_signal_newv ()

guint gtk_signal_newv (const gchar *name,
GtkSignalRunType signal_flags,
GtkType object_type,
guint function_offset,
GtkSignalMarshaller marshaller,
GtkType return_val,
guint n_args,
GtkType *args);

Creates a new signal type. (This is usually done in a class initializer.)

This function take the types as an array, instead of a list following the arguments. Otherwise the same as gtk_signal_new().

gtk_signal_lookup()

#define gtk_signal_lookup(name,object_type)

Given the name of the signal and the type of object it connects to, get the signal's identifying integer. Emitting the signal by number is somewhat faster than using the name each time.

It also tries the ancestors of the given type.

gtk_signal_name()

#define gtk_signal_name(signal_id)

Given the signal's identifier, finds its name.

Two different signals may have the same name, if they have differing types.

gtk_signal_emit ()

void gtk_signal_emit (GtkObject *object,
guint signal_id,
...);

Emits a signal. This causes the default handler and user-defined handlers to be run.

Here is what gtk_signal_emit() does:

1. Calls the default handler and the user-connected handlers. The default handler will be called first if GTK_RUN_FIRST is set, and last if GTK_RUN_LAST is set.

2. Calls all handlers connected with the "after" flag set.

gtk_signal_emit_by_name ()

void gtk_signal_emit_by_name (GtkObject *object,
const gchar *name,
...);

Emits a signal. This causes the default handler and user-connected handlers to be run.

gtk_signal_emitv ()

void gtk_signal_emitv (GtkObject *object,
guint signal_id,
GtkArg *args);

Emits a signal. This causes the default handler and user-connected handlers to be run. This differs from gtk_signal_emit() by taking an array of GtkArgs instead of using C's varargs mechanism.

gtk_signal_emitv_by_name ()

void gtk_signal_emitv_by_name (GtkObject *object,
const gchar *name,
GtkArg *args);

Emits a signal by name. This causes the default handler and user-connected handlers to be run. This differs from gtk_signal_emit() by taking an array of GtkArgs instead of using C's varargs mechanism.

gtk_signal_emit_stop()

#define gtk_signal_emit_stop(object,signal_id)

This function aborts a signal's current emission.

It will prevent the default method from running, if the signal was GTK_RUN_LAST and you connected normally (i.e. without the "after" flag).

It will print a warning if used on a signal which isn't being emitted.

gtk_signal_emit_stop_by_name ()

void gtk_signal_emit_stop_by_name (GtkObject *object,
const gchar *name);

This function aborts a signal's current emission.

It is just like gtk_signal_emit_stop() except it will lookup the signal id for you.

gtk_signal_connect()

#define gtk_signal_connect(object,name,func,func_data)

Attaches a function pointer and user data to a signal for a particular object.

The GtkSignalFunction takes a GtkObject as its first parameter. It will be the same object as the one you're connecting the hook to. The func_data will be passed as the last parameter to the hook.

All else being equal, signal handlers are invoked in the order connected (see gtk_signal_emit() for the other details of which order things are called in).

Here is how one passes an integer as user data, for when you just want to specify a constant int as parameter to your function:

static void button_clicked_int (GtkButton* button, gpointer func_data)
{
g_print ("button pressed: %d\n", GPOINTER_TO_INT (func_data));
}
/* By calling this function, you will make the g_print above
* execute, printing the number passed as `to_print'. */
static void attach_print_signal (GtkButton* button, gint to_print)
{
gtk_signal_connect (GTK_OBJECT (button), "clicked",
GTK_SIGNAL_FUNC (button_clicked_int),
GINT_TO_POINTER (to_print));
}

gtk_signal_connect_after()

#define gtk_signal_connect_after(object,name,func,func_data)

Attaches a function pointer and user data to a signal so that this handler will be called after the other handlers.

gtk_signal_connect_object()

#define gtk_signal_connect_object(object,name,func,slot_object)

This function is for registering a callback that will call another object's callback. That is, instead of passing the object which is responsible for the event as the first parameter of the callback, it is switched with the user data (so the object which emits the signal will be the last parameter, which is where the user data usually is).

This is useful for passing a standard function in as a callback. For example, if you wanted a button's press to gtk_widget_show() some widget, you could write:

gtk_signal_connect_object (button, "clicked", gtk_widget_show, window);

gtk_signal_connect_object_after()

#define gtk_signal_connect_object_after(object,name,func,slot_object)

Attaches a signal hook to a signal, passing in an alternate object as the first parameter, and guaranteeing that the default handler and all normal handlers are called first.

gtk_signal_connect_full ()

gulong gtk_signal_connect_full (GtkObject *object,
const gchar *name,
GtkSignalFunc func,
GtkCallbackMarshal unsupported,
gpointer data,
GtkDestroyNotify destroy_func,
gint object_signal,
gint after);

Attaches a function pointer and user data to a signal with more control.

gtk_signal_connect_while_alive ()

void gtk_signal_connect_while_alive (GtkObject *object,
const gchar *name,
GtkSignalFunc func,
gpointer func_data,
GtkObject *alive_object);

Attaches a function pointer and another GtkObject to a signal.

This function takes an object whose "destroy" signal should be trapped. That way, you don't have to clean up the signal handler when you destroy the object. It is a little less efficient though.

(Instead you may call gtk_signal_disconnect_by_data(), if you want to explicitly delete all attachments to this object. This is perhaps not recommended since it could be confused with an integer masquerading as a pointer (through GINT_TO_POINTER()).)

gtk_signal_connect_object_while_alive ()

void gtk_signal_connect_object_while_alive
(GtkObject *object,
const gchar *name,
GtkSignalFunc func,
GtkObject *alive_object);

These signal connectors are for signals which refer to objects, so they must not be called after the object is deleted.

Unlike gtk_signal_connect_while_alive(), this swaps the object and user data, making it suitable for use with functions which primarily operate on the user data.

This function acts just like gtk_signal_connect_object() except it traps the "destroy" signal to prevent you from having to clean up the handler.

gtk_signal_disconnect()

#define gtk_signal_disconnect(object,handler_id)

Destroys a user-defined handler connection.

gtk_signal_disconnect_by_func()

#define gtk_signal_disconnect_by_func(object,func,data)

Destroys all connections for a particular object, with the given function-pointer and user-data.

gtk_signal_disconnect_by_data()

#define gtk_signal_disconnect_by_data(object,data)

Destroys all connections for a particular object, with the given user-data.

gtk_signal_handler_block()

#define gtk_signal_handler_block(object,handler_id)

Prevents a user-defined handler from being invoked. All other signal processing will go on as normal, but this particular handler will ignore it.

gtk_signal_handler_block_by_func()

#define gtk_signal_handler_block_by_func(object,func,data)

Prevents a user-defined handler from being invoked, by reference to the user-defined handler's function pointer and user data. (It may result in multiple hooks being blocked, if you've called connect multiple times.)

gtk_signal_handler_block_by_data()

#define gtk_signal_handler_block_by_data(object,data)

Prevents all user-defined handlers with a certain user data from being invoked.

gtk_signal_handler_unblock()

#define gtk_signal_handler_unblock(object,handler_id)

Undoes a block, by connection id. Note that undoing a block doesn't necessarily make the hook callable, because if you block a hook twice, you must unblock it twice.

gtk_signal_handler_unblock_by_func()

#define gtk_signal_handler_unblock_by_func(object,func,data)

Undoes a block, by function pointer and data. Note that undoing a block doesn't necessarily make the hook callable, because if you block a hook twice, you must unblock it twice.

gtk_signal_handler_unblock_by_data()

#define gtk_signal_handler_unblock_by_data(object,data)

Undoes block(s), to all signals for a particular object with a particular user-data pointer

gtk_signal_handler_pending()

#define gtk_signal_handler_pending(object,signal_id,may_be_blocked)

Returns a connection id corresponding to a given signal id and object.

One example of when you might use this is when the arguments to the signal are difficult to compute. A class implementor may opt to not emit the signal if no one is attached anyway, thus saving the cost of building the arguments.

gtk_signal_handler_pending_by_func()

#define gtk_signal_handler_pending_by_func(object,signal_id,may_be_blocked,func,data)

Returns a connection id corresponding to a given signal id, object, function pointer and user data.

gtk_signal_default_marshaller

#define gtk_signal_default_marshaller g_cclosure_marshal_VOID__VOID

A marshaller that returns void and takes no extra parameters.