18. Advanced Event and Signal Handling

18.1 Signal Functions

Connecting and Disconnecting Signal Handlers

guint gtk_signal_connect( GtkObject     *object,
                          const gchar   *name,
                          GtkSignalFunc  func,
                          gpointer       func_data );

guint gtk_signal_connect_after( GtkObject     *object,
                                const gchar   *name,
                                GtkSignalFunc  func,
                                gpointer       func_data );

guint gtk_signal_connect_object( GtkObject     *object,
                                 const gchar   *name,
                                 GtkSignalFunc  func,
                                 GtkObject     *slot_object );

guint gtk_signal_connect_object_after( GtkObject     *object,
                                       const gchar   *name,
                                       GtkSignalFunc  func,
                                       GtkObject     *slot_object );

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

guint gtk_signal_connect_interp( GtkObject          *object,
                                 const gchar        *name,
                                 GtkCallbackMarshal  func,
                                 gpointer            data,
                                 GtkDestroyNotify    destroy_func,
                                 gint                after );

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

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

void gtk_signal_disconnect( GtkObject *object,
                            guint      handler_id );

void gtk_signal_disconnect_by_func( GtkObject     *object,
                                    GtkSignalFunc  func,
                                    gpointer       data );

Blocking and Unblocking Signal Handlers

void gtk_signal_handler_block( GtkObject *object,
                               guint      handler_id);

void gtk_signal_handler_block_by_func( GtkObject     *object,
                                       GtkSignalFunc  func,
                                       gpointer       data );

void gtk_signal_handler_block_by_data( GtkObject *object,
                                       gpointer   data );

void gtk_signal_handler_unblock( GtkObject *object,
                                 guint      handler_id );

void gtk_signal_handler_unblock_by_func( GtkObject     *object,
                                         GtkSignalFunc  func,
                                         gpointer       data );

void gtk_signal_handler_unblock_by_data( GtkObject *object,
                                         gpointer   data );

Emitting and Stopping Signals

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

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

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

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

guint gtk_signal_n_emissions( GtkObject *object,
                              guint      signal_id );

guint gtk_signal_n_emissions_by_name( GtkObject   *object,
                                      const gchar *name );

void gtk_signal_emit_stop( GtkObject *object,
                           guint      signal_id );

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

18.2 Signal Emission and Propagation

Signal emission is the process whereby GTK runs all handlers for a specific object and signal.

First, note that the return value from a signal emission is the return value of the last handler executed. Since event signals are all of type GTK_RUN_LAST, this will be the default (GTK supplied) handler, unless you connect with gtk_signal_connect_after().

The way an event (say "button_press_event") is handled, is:

• Start with the widget where the event occured.
• Emit the generic "event" signal. If that signal handler returns a value of TRUE, stop all processing.
• Otherwise, emit a specific, "button_press_event" signal. If that returns TRUE, stop all processing.
• Otherwise, go to the widget's parent, and repeat the above two steps.
• Continue until some signal handler returns TRUE, or until the top-level widget is reached.

Some consequences of the above are:

• Your handler's return value will have no effect if there is a default handler, unless you connect with gtk_signal_connect_after().
• To prevent the default handler from being run, you need to connect with gtk_signal_connect() and use gtk_signal_emit_stop_by_name() - the return value only affects whether the signal is propagated, not the current emission.