18. Advanced Event and Signal Handling

18.1 Signal Functions

18.1.1 Connecting and Disconnecting Signal Handlers

function g_signal_connect (object : PObject;
                           name : pgchar;
                           func : GCallback;
                           func_data : gpointer) : gulong;

function g_signal_connect_after (object : PGObject;
                                 name : pgchar;
                                 func : GCallback;
                                 func_data : gpointer) : gulong;

function g_signal_connect_swapped (object : PGObject;
                                   name : pgchar;
                                   func : GCallback;
                                   slot_object : PGObject) : gulong;

procedure g_signal_handler_disconnect (object : PGObject;
                                       handler_id : gulong);

procedure g_signal_handlers_disconnect_by_func (object : PGObject;
                                                func : GCallback;
                                                data : gpointer);

18.1.2 Blocking and Unblocking Signal Handlers

procedure g_signal_handler_block (object : PGObject;
                                  handler_id : gulong);

procedure g_signal_handlers_block_by_func (object : PGObject;
                                           func : GCallback;
                                           data : gpointer);

procedure g_signal_handler_unblock (object : PGObject;
                                    handler_id : guint);

procedure g_signal_handlers_unblock_by_func (object : PGObject;
                                             func : GCallback;
                                             data : gpointer);

18.1.3 Emitting and Stopping Signals

procedure g_signal_emit (object : PGObject;
                         signal_id : guint;
                         ...);

procedure g_signal_emit_by_name (object : PGObject;
                                 name : pgchar;
                                 ...);

procedure g_signal_emitv (instance_and_params : PGValue;
                          signal_id : guint;
                          detail : GQuark;
                          return_value : PGValue);

procedure g_signal_stop_emission (object : PGObject;
                                  signal_id : guint;
                                  detail : GQuark);

procedure g_signal_stop_emission_by_name (object : PGObject;
                                          detailed_signal : pgchar);

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.