2.3. Events

In addition to the signal mechanism described above, there is a set of events that reflect the X event mechanism. Callbacks may also be attached to these events. These events are: In order to connect a callback function to one of these events you use the method connect() , as described above, using one of the above event names as the name parameter. The callback function (or method) for events has a slightly different form than that for signals:
 
def callback_func(widget, event, callback_data ):
def callback_meth(self, widget, event, callback_data ):

GdkEvent is a python object type whose type attribute will indicate which of the above events has occurred. The other attributes of the event will depend upon the type of the event. Possible values for the type are:
 
  NOTHING
  DELETE
  DESTROY
  EXPOSE
  MOTION_NOTIFY
  BUTTON_PRESS
  _2BUTTON_PRESS
  _3BUTTON_PRESS
  BUTTON_RELEASE
  KEY_PRESS
  KEY_RELEASE
  ENTER_NOTIFY
  LEAVE_NOTIFY
  FOCUS_CHANGE
  CONFIGURE
  MAP
  UNMAP
  PROPERTY_NOTIFY
  SELECTION_CLEAR
  SELECTION_REQUEST
  SELECTION_NOTIFY
  PROXIMITY_IN
  PROXIMITY_OUT
  DRAG_BEGIN
  DRAG_REQUEST
  DROP_ENTER
  DROP_LEAVE
  DROP_DATA_AVAIL
  CLIENT_EVENT
  VISIBILITY_NOTIFY
  NO_EXPOSE
  OTHER_EVENT       # Deprecated, use filters instead

These values are defined in the GDK.py module; use "import GDK" to access these definitions. (And don't forget to specify the GDK. prefix.)

So, to connect a callback function to one of these events we would use something like:
 
button.connect("button_press_event", button_press_callback)

This assumes that button is a GtkButton widget. Now, when the mouse is over the button and a mouse button is pressed, the function button_press_callback will be called. This function may be defined as:
 
def button_press_callback(widget, event, data ):

The value returned from this function indicates whether the event should be propagated further by the GTK event handling mechanism. Returning gtk.TRUE indicates that the event has been handled, and that it should not propagate further. Returning gtk.FALSE continues the normal event handling. See the section on Advanced Event and Signal Handling for more details on this propagation process.