GTK v1.2 Tutorial: Advanced Event and Signal Handling

Next Previous Contents

## 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.

Next Previous Contents