Gdk.Event

Methods

class get ()
class handler_set (func, *data)
class new (type)
class peek ()
class request_motions (event)
  copy ()
  free ()
  get_axis (axis_use)
  get_button ()
  get_click_count ()
  get_coords ()
  get_device ()
  get_device_tool ()
  get_event_sequence ()
  get_event_type ()
  get_keycode ()
  get_keyval ()
  get_pointer_emulated ()
  get_root_coords ()
  get_scancode ()
  get_screen ()
  get_scroll_deltas ()
  get_scroll_direction ()
  get_seat ()
  get_source_device ()
  get_state ()
  get_time ()
  get_window ()
  is_scroll_stop_event ()
  put ()
  set_device (device)
  set_device_tool (tool)
  set_screen (screen)
  set_source_device (device)
  triggers_context_menu ()

Details

class Gdk.Event
classmethod get()[source]
Returns:the next Gdk.Event to be processed, or None if no events are pending. The returned Gdk.Event should be freed with Gdk.Event.free().
Return type:Gdk.Event or None

Checks all open displays for a Gdk.Event to process,to be processed on, fetching events from the windowing system if necessary. See Gdk.Display.get_event().

classmethod handler_set(func, *data)[source]
Parameters:
  • func (Gdk.EventFunc) – the function to call to handle events from GDK.
  • data (object or None) – user data to pass to the function.

Sets the function to call to handle all events from GDK.

Note that GTK+ uses this to install its own event handler, so it is usually not useful for GTK+ applications. (Although an application can call this function then call gtk_main_do_event() to pass events to GTK+.)

classmethod new(type)[source]
Parameters:type (Gdk.EventType) – a Gdk.EventType
Returns:a newly-allocated Gdk.Event. The returned Gdk.Event should be freed with Gdk.Event.free().
Return type:Gdk.Event

Creates a new event of the given type. All fields are set to 0.

New in version 2.2.

classmethod peek()[source]
Returns:a copy of the first Gdk.Event on some event queue, or None if no events are in any queues. The returned Gdk.Event should be freed with Gdk.Event.free().
Return type:Gdk.Event or None

If there is an event waiting in the event queue of some open display, returns a copy of it. See Gdk.Display.peek_event().

classmethod request_motions(event)[source]
Parameters:event (Gdk.EventMotion) – a valid Gdk.Event

Request more motion notifies if event is a motion notify hint event.

This function should be used instead of Gdk.Window.get_pointer() to request further motion notifies, because it also works for extension events where motion notifies are provided for devices other than the core pointer. Coordinate extraction, processing and requesting more motion events from a Gdk.EventType.MOTION_NOTIFY event usually works like this:

{
  // motion_event handler
  x = motion_event->x;
  y = motion_event->y;
  // handle (x,y) motion
  gdk_event_request_motions (motion_event); // handles is_hint events
}

New in version 2.12.

copy()[source]
Returns:a copy of self. The returned Gdk.Event should be freed with Gdk.Event.free().
Return type:Gdk.Event

Copies a Gdk.Event, copying or incrementing the reference count of the resources associated with it (e.g. Gdk.Window’s and strings).

free()[source]

Frees a Gdk.Event, freeing or decrementing any resources associated with it. Note that this function should only be called with events returned from functions such as Gdk.Event.peek(), Gdk.Event.get(), Gdk.Event.copy() and Gdk.Event.new().

get_axis(axis_use)[source]
Parameters:axis_use (Gdk.AxisUse) – the axis use to look for
Returns:True if the specified axis was found, otherwise False
value:location to store the value found
Return type:(bool, value: float)

Extract the axis value for a particular axis use from an event structure.

get_button()[source]
Returns:True if the event delivered a button number
button:location to store mouse button number
Return type:(bool, button: int)

Extract the button number from an event.

New in version 3.2.

get_click_count()[source]
Returns:True if the event delivered a click count
click_count:location to store click count
Return type:(bool, click_count: int)

Extracts the click count from an event.

New in version 3.2.

get_coords()[source]
Returns:True if the event delivered event window coordinates
x_win:location to put event window x coordinate
y_win:location to put event window y coordinate
Return type:(bool, x_win: float, y_win: float)

Extract the event window relative x/y coordinates from an event.

get_device()[source]
Returns:a Gdk.Device, or None.
Return type:Gdk.Device or None

If the event contains a “device” field, this function will return it, else it will return None.

New in version 3.0.

get_device_tool()[source]
Returns:The current device tool, or None
Return type:Gdk.DeviceTool

If the event was generated by a device that supports different tools (eg. a tablet), this function will return a Gdk.DeviceTool representing the tool that caused the event. Otherwise, None will be returned.

Note: the Gdk.DeviceTool s will be constant during the application lifetime, if settings must be stored persistently across runs, see Gdk.DeviceTool.get_serial()

New in version 3.22.

get_event_sequence()[source]
Returns:the event sequence that the event belongs to
Return type:Gdk.EventSequence

If self if of type Gdk.EventType.TOUCH_BEGIN, Gdk.EventType.TOUCH_UPDATE, Gdk.EventType.TOUCH_END or Gdk.EventType.TOUCH_CANCEL, returns the Gdk.EventSequence to which the event belongs. Otherwise, return None.

New in version 3.4.

get_event_type()[source]
Returns:a Gdk.EventType
Return type:Gdk.EventType

Retrieves the type of the event.

New in version 3.10.

get_keycode()[source]
Returns:True if the event delivered a hardware keycode
keycode:location to store the keycode
Return type:(bool, keycode: int)

Extracts the hardware keycode from an event.

Also see Gdk.Event.get_scancode().

New in version 3.2.

get_keyval()[source]
Returns:True if the event delivered a key symbol
keyval:location to store the keyval
Return type:(bool, keyval: int)

Extracts the keyval from an event.

New in version 3.2.

get_pointer_emulated()[source]
Returns:True if this event is emulated
Return type:bool

#event: a Gdk.Event Returns whether this event is an ‘emulated’ pointer event (typically from a touch event), as opposed to a real one.

New in version 3.22.

get_root_coords()[source]
Returns:True if the event delivered root window coordinates
x_root:location to put root window x coordinate
y_root:location to put root window y coordinate
Return type:(bool, x_root: float, y_root: float)

Extract the root window relative x/y coordinates from an event.

get_scancode()[source]
Returns:The associated keyboard scancode or 0
Return type:int

Gets the keyboard low-level scancode of a key event.

This is usually hardware_keycode. On Windows this is the high word of WM_KEY{DOWN,UP} lParam which contains the scancode and some extended flags.

New in version 3.22.

get_screen()[source]
Returns:the screen for the event
Return type:Gdk.Screen

Returns the screen for the event. The screen is typically the screen for event->any.window, but for events such as mouse events, it is the screen where the pointer was when the event occurs - that is, the screen which has the root window to which event->motion.x_root and event->motion.y_root are relative.

New in version 2.2.

get_scroll_deltas()[source]
Returns:True if the event contains smooth scroll information and False otherwise
delta_x:return location for X delta
delta_y:return location for Y delta
Return type:(bool, delta_x: float, delta_y: float)

Retrieves the scroll deltas from a Gdk.Event

See also: Gdk.Event.get_scroll_direction()

New in version 3.4.

get_scroll_direction()[source]
Returns:True if the event delivered a scroll direction and False otherwise
direction:location to store the scroll direction
Return type:(bool, direction: Gdk.ScrollDirection)

Extracts the scroll direction from an event.

If self is not of type Gdk.EventType.SCROLL, the contents of direction are undefined.

If you wish to handle both discrete and smooth scrolling, you should check the return value of this function, or of Gdk.Event.get_scroll_deltas(); for instance:

GdkScrollDirection direction;
double vscroll_factor = 0.0;
double x_scroll, y_scroll;

if (gdk_event_get_scroll_direction (event, &direction))
  {
    // Handle discrete scrolling with a known constant delta;
    const double delta = 12.0;

    switch (direction)
      {
      case GDK_SCROLL_UP:
        vscroll_factor = -delta;
        break;
      case GDK_SCROLL_DOWN:
        vscroll_factor = delta;
        break;
      default:
        // no scrolling
        break;
      }
  }
else if (gdk_event_get_scroll_deltas (event, &x_scroll, &y_scroll))
  {
    // Handle smooth scrolling directly
    vscroll_factor = y_scroll;
  }

New in version 3.2.

get_seat()[source]
Returns:The Gdk.Seat of this event
Return type:Gdk.Seat

Returns the Gdk.Seat this event was generated for.

New in version 3.20.

get_source_device()[source]
Returns:a Gdk.Device, or None.
Return type:Gdk.Device or None

This function returns the hardware (slave) Gdk.Device that has triggered the event, falling back to the virtual (master) device (as in Gdk.Event.get_device()) if the event wasn’t caused by interaction with a hardware device. This may happen for example in synthesized crossing events after a Gdk.Window updates its geometry or a grab is acquired/released.

If the event does not contain a device field, this function will return None.

New in version 3.0.

get_state()[source]
Returns:True if there was a state field in the event
state:return location for state
Return type:(bool, state: Gdk.ModifierType)

If the event contains a “state” field, puts that field in state. Otherwise stores an empty state (0). Returns True if there was a state field in the event. self may be None, in which case it’s treated as if the event had no state field.

get_time()[source]
Returns:time stamp field from self
Return type:int

Returns the time stamp from self, if there is one; otherwise returns Gdk.CURRENT_TIME. If self is None, returns Gdk.CURRENT_TIME.

get_window()[source]
Returns:The Gdk.Window associated with the event
Return type:Gdk.Window

Extracts the Gdk.Window associated with an event.

New in version 3.10.

is_scroll_stop_event()[source]
Returns:True if the event is a scroll stop event
Return type:bool

Check whether a scroll event is a stop scroll event. Scroll sequences with smooth scroll information may provide a stop scroll event once the interaction with the device finishes, e.g. by lifting a finger. This stop scroll event is the signal that a widget may trigger kinetic scrolling based on the current velocity.

Stop scroll events always have a a delta of 0/0.

New in version 3.20.

put()[source]

Appends a copy of the given event onto the front of the event queue for event->any.window’s display, or the default event queue if event->any.window is None. See Gdk.Display.put_event().

set_device(device)[source]
Parameters:device (Gdk.Device) – a Gdk.Device

Sets the device for self to device. The event must have been allocated by GTK+, for instance, by Gdk.Event.copy().

New in version 3.0.

set_device_tool(tool)[source]
Parameters:tool (Gdk.DeviceTool or None) – tool to set on the event, or None

Sets the device tool for this event, should be rarely used.

New in version 3.22.

set_screen(screen)[source]
Parameters:screen (Gdk.Screen) – a Gdk.Screen

Sets the screen for self to screen. The event must have been allocated by GTK+, for instance, by Gdk.Event.copy().

New in version 2.2.

set_source_device(device)[source]
Parameters:device (Gdk.Device) – a Gdk.Device

Sets the slave device for self to device.

The event must have been allocated by GTK+, for instance by Gdk.Event.copy().

New in version 3.0.

triggers_context_menu()[source]
Returns:True if the event should trigger a context menu.
Return type:bool

This function returns whether a Gdk.EventButton should trigger a context menu, according to platform conventions. The right mouse button always triggers context menus. Additionally, if Gdk.Keymap.get_modifier_mask() returns a non-0 mask for Gdk.ModifierIntent.CONTEXT_MENU, then the left mouse button will also trigger a context menu if this modifier is pressed.

This function should always be used instead of simply checking for event->button == Gdk.BUTTON_SECONDARY.

New in version 3.4.