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:

  event
  button_press_event
  button_release_event
  scroll_event
  motion_notify_event
  delete_event
  destroy_event
  expose_event
  key_press_event
  key_release_event
  enter_notify_event
  leave_notify_event
  configure_event
  focus_in_event
  focus_out_event
  map_event
  unmap_event
  property_notify_event
  selection_clear_event
  selection_request_event
  selection_notify_event
  proximity_in_event
  proximity_out_event
  visibility_notify_event
  client_event
  no_expose_event
  window_state_event

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 types 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_ENTER
  DRAG_LEAVE
  DRAG_MOTION
  DRAG_STATUS
  DROP_START
  DROP_FINISHED
  CLIENT_EVENT
  VISIBILITY_NOTIFY
  NO_EXPOSE
  SCROLL
  WINDOW_STATE
  SETTING

These values are accessed by prefacing the event type with gtk.gdk. for example gtk.gdk.DRAG_ENTER.

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 True indicates that the event has been handled, and that it should not propagate further. Returning False continues the normal event handling. See Chapter 20, Advanced Event and Signal Handling for more details on this propagation process.

The GDK selection and drag-and-drop APIs also emit a number of events which are reflected in GTK+ by signals. See Section 22.3.2, “Signals On the Source Widget” and Section 22.3.4, “Signals On the Destination Widget” for details on the signatures of the callback functions for these signals:

  selection_received
  selection_get
  drag_begin_event
  drag_end_event
  drag_data_delete
  drag_motion
  drag_drop
  drag_data_get
  drag_data_received