19.2. Signal Emission and Propagation

Signal emission is the process whereby PyGTK 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 RUN_LAST, this will be the default (GTK supplied) handler, unless you connect with the connect_after() method.

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 connect_after().

To prevent the default handler from being run, you need to connect with connect() and use emit_stop_by_name() - the return value only affects whether the signal is propagated, not the current emission.