Chapter 20. Advanced Event and Signal Handling
Prev |  | Next

## Chapter 20. Advanced Event and Signal Handling

## 20.1. Signal Methods

The signal methods are `gobject.GObject` methods that are inherited by the `gtk.Object`s including all the GTK+ widgets.

### 20.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 `gtk.Object` (`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.

### 20.1.2. Blocking and Unblocking Signal Handlers

The following methods:

      object.handler_block(handler_id)

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

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

Prev | Up | Next
19.3. Idle Functions | Home | 20.2. Signal Emission and Propagation