Chapter 19. Advanced Event and Signal Handling

Table of Contents
19.1. Signal Functions
19.2. Signal Emission and Propagation

19.1. Signal Methods

19.1.1. Connecting and Disconnecting Signal Handlers

handler_id = object.connect(name, cb, cb_args)

handler_id = object.connect_after(name, cb, cb_args)

handler_id = object.connect_object(name, cb, slot_object, cb_args)

handler_id = object.connect_object_after(name, cb, slot_object, cb_args)

object.disconnect(handler_id)

The first four methods connect a signal handler (cb) to a GtkObject (object) for the given signal name. and return a handler_id that identifies the connection. cb_args is zero or more arguments that will be passed last (in order) to cb. The connect_after() and connect_object_after() methods will have their signal handlers called after other signal handlers (including the default handlers) connected to the same object and signal name. Each object signal handler has its own set of arguments that it expects. You have to refer to the GTK documentation to figure out what arguments need to be handled by a signal handler though information for the common widgets is available in Appendix A GTK Signals. The general signal handler is similar to:
 
def signal_handler(object, ...., cb_args):

Signal handlers that are defined as part of a Python object class (specified in the connect() methods as self.cb) will have an additional argument passed as the first argument - the object instance self:
 
signal_handler(self, object, ...., cb_args)

The connect_object() and connect_object_after() methods call the signal handler with the slot_object substituted in place of the object as the first argument:
 
def signal_handler(slot_object, ...., func_args):
def signal_handler(self, slot_object, ...., func_args):

The disconnect() method destroys the connection between a signal handler and an object signal. The handler_id specifies which connection to destroy.

19.1.2. Blocking and Unblocking Signal Handlers

The following methods:
 
object.signal_handler_block(handler_id)

object.signal_handler_unblock(handler_id)

block and unblock the signal handler specified by handler_id. When a signal handler is blocked it will not be invoked when the signal occurs.

19.1.3. Emitting and Stopping Signals

The following methods:
object.emit(name, ...)

object.emit_stop_by_name(name)

emit and stop the signal name respectively. Emitting the signal causes its default and user defined handlers to be run. The emit_stop_by_name() method will abort the current signal name emission.