Events

Events — Functions for handling events from the window system

Functions

GdkEvent * gdk_event_new ()
GdkEvent * gdk_event_copy ()
gboolean gdk_event_get_axes ()
gboolean gdk_event_get_axis ()
gboolean gdk_event_get_button ()
gboolean gdk_event_get_click_count ()
gboolean gdk_event_get_coords ()
gboolean gdk_event_get_keycode ()
gboolean gdk_event_get_keyval ()
gboolean gdk_event_get_scroll_direction ()
gboolean gdk_event_get_scroll_deltas ()
gboolean gdk_event_is_scroll_stop_event ()
gboolean gdk_event_get_state ()
guint32 gdk_event_get_time ()
GdkSurface * gdk_event_get_surface ()
GdkEventType gdk_event_get_event_type ()
GdkEventSequence * gdk_event_get_event_sequence ()
gboolean gdk_events_get_angle ()
gboolean gdk_events_get_center ()
gboolean gdk_events_get_distance ()
gboolean gdk_event_triggers_context_menu ()
GdkSeat * gdk_event_get_seat ()
int gdk_event_get_scancode ()
gboolean gdk_event_get_pointer_emulated ()
gboolean gdk_event_get_crossing_detail ()
gboolean gdk_event_get_crossing_mode ()
GdkDrop * gdk_event_get_drop ()
gboolean gdk_event_get_focus_in ()
gboolean gdk_event_get_grab_surface ()
GList * gdk_event_get_motion_history ()
gboolean gdk_event_get_key_group ()
gboolean gdk_event_get_key_is_modifier ()
gboolean gdk_event_get_pad_axis_value ()
gboolean gdk_event_get_pad_button ()
gboolean gdk_event_get_pad_group_mode ()
gboolean gdk_event_get_touch_emulating_pointer ()
gboolean gdk_event_get_touchpad_angle_delta ()
gboolean gdk_event_get_touchpad_deltas ()
gboolean gdk_event_get_touchpad_gesture_n_fingers ()
gboolean gdk_event_get_touchpad_gesture_phase ()
gboolean gdk_event_get_touchpad_scale ()
gboolean gdk_event_is_sent ()
gboolean gdk_get_show_events ()
void gdk_set_show_events ()
void gdk_event_set_display ()
GdkDisplay * gdk_event_get_display ()
GdkDevice * gdk_event_get_device ()
void gdk_event_set_device ()
GdkDevice * gdk_event_get_source_device ()
void gdk_event_set_source_device ()
GdkDeviceTool * gdk_event_get_device_tool ()
void gdk_event_set_device_tool ()

Properties

GdkEventType event-type Read / Write / Construct Only

Types and Values

  GdkEvent
enum GdkEventType
enum GdkEventMask
enum GdkScrollDirection
enum GdkCrossingMode
enum GdkNotifyType
#define GDK_CURRENT_TIME
#define GDK_PRIORITY_EVENTS
#define GDK_PRIORITY_REDRAW
#define GDK_EVENT_PROPAGATE
#define GDK_EVENT_STOP
#define GDK_BUTTON_PRIMARY
#define GDK_BUTTON_MIDDLE
#define GDK_BUTTON_SECONDARY
  GdkEventSequence

Object Hierarchy

    GObject
    ╰── GdkEvent

Includes

#include <gdk/gdk.h>

Description

This section describes functions dealing with events from the window system.

In GTK+ applications the events are handled automatically by toplevel widgets and passed on to the appropriate widgets, so these functions are rarely needed.

Functions

gdk_event_new ()

GdkEvent *
gdk_event_new (GdkEventType type);

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

Parameters

type

a GdkEventType

 

Returns

a newly-allocated GdkEvent. Free with g_object_unref()


gdk_event_copy ()

GdkEvent *
gdk_event_copy (const GdkEvent *event);

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

Parameters

event

a GdkEvent

 

Returns

a copy of event . Free with g_object_unref().

[transfer full]


gdk_event_get_axes ()

gboolean
gdk_event_get_axes (GdkEvent *event,
                    gdouble **axes,
                    guint *n_axes);

Extracts all axis values from an event.

Parameters

event

a GdkEvent

 

axes

the array of values for all axes.

[transfer none][out][array length=n_axes]

n_axes

the length of array.

[out]

Returns

TRUE on success, otherwise FALSE


gdk_event_get_axis ()

gboolean
gdk_event_get_axis (const GdkEvent *event,
                    GdkAxisUse axis_use,
                    gdouble *value);

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

Parameters

event

a GdkEvent

 

axis_use

the axis use to look for

 

value

location to store the value found.

[out]

Returns

TRUE if the specified axis was found, otherwise FALSE


gdk_event_get_button ()

gboolean
gdk_event_get_button (const GdkEvent *event,
                      guint *button);

Extract the button number from an event.

Parameters

event

a GdkEvent

 

button

location to store mouse button number.

[out]

Returns

TRUE if the event delivered a button number


gdk_event_get_click_count ()

gboolean
gdk_event_get_click_count (const GdkEvent *event,
                           guint *click_count);

Extracts the click count from an event.

Parameters

event

a GdkEvent

 

click_count

location to store click count.

[out]

Returns

TRUE if the event delivered a click count


gdk_event_get_coords ()

gboolean
gdk_event_get_coords (const GdkEvent *event,
                      gdouble *x_win,
                      gdouble *y_win);

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

Parameters

event

a GdkEvent

 

x_win

location to put event surface x coordinate.

[out][optional]

y_win

location to put event surface y coordinate.

[out][optional]

Returns

TRUE if the event delivered event surface coordinates


gdk_event_get_keycode ()

gboolean
gdk_event_get_keycode (const GdkEvent *event,
                       guint16 *keycode);

Extracts the hardware keycode from an event.

Also see gdk_event_get_scancode().

Parameters

event

a GdkEvent

 

keycode

location to store the keycode.

[out]

Returns

TRUE if the event delivered a hardware keycode


gdk_event_get_keyval ()

gboolean
gdk_event_get_keyval (const GdkEvent *event,
                      guint *keyval);

Extracts the keyval from an event.

Parameters

event

a GdkEvent

 

keyval

location to store the keyval.

[out]

Returns

TRUE if the event delivered a key symbol


gdk_event_get_scroll_direction ()

gboolean
gdk_event_get_scroll_direction (const GdkEvent *event,
                                GdkScrollDirection *direction);

Extracts the scroll direction from an event.

Parameters

event

a GdkEvent

 

direction

location to store the scroll direction.

[out]

Returns

TRUE if the event delivered a scroll direction


gdk_event_get_scroll_deltas ()

gboolean
gdk_event_get_scroll_deltas (const GdkEvent *event,
                             gdouble *delta_x,
                             gdouble *delta_y);

Retrieves the scroll deltas from a GdkEvent

Parameters

event

a GdkEvent

 

delta_x

return location for X delta.

[out]

delta_y

return location for Y delta.

[out]

Returns

TRUE if the event contains smooth scroll information


gdk_event_is_scroll_stop_event ()

gboolean
gdk_event_is_scroll_stop_event (const GdkEvent *event);

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 delta of 0/0.

Parameters

event

a GdkEvent

 

Returns

TRUE if the event is a scroll stop event


gdk_event_get_state ()

gboolean
gdk_event_get_state (const GdkEvent *event,
                     GdkModifierType *state);

If the event contains a “state” field, puts that field in state .

Otherwise stores an empty state (0). event may be NULL, in which case it’s treated as if the event had no state field.

Parameters

event

a GdkEvent or NULL.

[allow-none]

state

return location for state.

[out]

Returns

TRUE if there was a state field in the event


gdk_event_get_time ()

guint32
gdk_event_get_time (const GdkEvent *event);

Returns the time stamp from event , if there is one; otherwise returns GDK_CURRENT_TIME. If event is NULL, returns GDK_CURRENT_TIME.

Parameters

event

a GdkEvent

 

Returns

time stamp field from event


gdk_event_get_surface ()

GdkSurface *
gdk_event_get_surface (const GdkEvent *event);

Extracts the GdkSurface associated with an event.

Parameters

event

a GdkEvent

 

Returns

The GdkSurface associated with the event.

[transfer none]


gdk_event_get_event_type ()

GdkEventType
gdk_event_get_event_type (const GdkEvent *event);

Retrieves the type of the event.

Parameters

event

a GdkEvent

 

Returns

a GdkEventType


gdk_event_get_event_sequence ()

GdkEventSequence *
gdk_event_get_event_sequence (const GdkEvent *event);

If event if of type GDK_TOUCH_BEGIN, GDK_TOUCH_UPDATE, GDK_TOUCH_END or GDK_TOUCH_CANCEL, returns the GdkEventSequence to which the event belongs. Otherwise, return NULL.

Parameters

event

a GdkEvent

 

Returns

the event sequence that the event belongs to.

[transfer none]


gdk_events_get_angle ()

gboolean
gdk_events_get_angle (GdkEvent *event1,
                      GdkEvent *event2,
                      gdouble *angle);

If both events contain X/Y information, this function will return TRUE and return in angle the relative angle from event1 to event2 . The rotation direction for positive angles is from the positive X axis towards the positive Y axis.

Parameters

event1

first GdkEvent

 

event2

second GdkEvent

 

angle

return location for the relative angle between both events.

[out]

Returns

TRUE if the angle could be calculated.


gdk_events_get_center ()

gboolean
gdk_events_get_center (GdkEvent *event1,
                       GdkEvent *event2,
                       gdouble *x,
                       gdouble *y);

If both events contain X/Y information, the center of both coordinates will be returned in x and y .

Parameters

event1

first GdkEvent

 

event2

second GdkEvent

 

x

return location for the X coordinate of the center.

[out]

y

return location for the Y coordinate of the center.

[out]

Returns

TRUE if the center could be calculated.


gdk_events_get_distance ()

gboolean
gdk_events_get_distance (GdkEvent *event1,
                         GdkEvent *event2,
                         gdouble *distance);

If both events have X/Y information, the distance between both coordinates (as in a straight line going from event1 to event2 ) will be returned.

Parameters

event1

first GdkEvent

 

event2

second GdkEvent

 

distance

return location for the distance.

[out]

Returns

TRUE if the distance could be calculated.


gdk_event_triggers_context_menu ()

gboolean
gdk_event_triggers_context_menu (const GdkEvent *event);

This function returns whether a GdkEventButton 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_MODIFIER_INTENT_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.

Parameters

event

a GdkEvent, currently only button events are meaningful values

 

Returns

TRUE if the event should trigger a context menu.


gdk_event_get_seat ()

GdkSeat *
gdk_event_get_seat (const GdkEvent *event);

Returns the GdkSeat this event was generated for.

Parameters

event

a GdkEvent

 

Returns

The GdkSeat of this event.

[transfer none]


gdk_event_get_scancode ()

int
gdk_event_get_scancode (GdkEvent *event);

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.

Parameters

event

a GdkEvent

 

Returns

The associated keyboard scancode or 0


gdk_event_get_pointer_emulated ()

gboolean
gdk_event_get_pointer_emulated (GdkEvent *event);

Returns whether this event is an 'emulated' pointer event (typically from a touch event), as opposed to a real one.

Parameters

event

a GdkEvent

 

Returns

TRUE if this event is emulated


gdk_event_get_crossing_detail ()

gboolean
gdk_event_get_crossing_detail (const GdkEvent *event,
                               GdkNotifyType *detail);

Extracts the crossing detail from an event.

Parameters

event

a GdkEvent

 

detail

return location for the crossing detail.

[out]

Returns

TRUE on success, otherwise FALSE


gdk_event_get_crossing_mode ()

gboolean
gdk_event_get_crossing_mode (const GdkEvent *event,
                             GdkCrossingMode *mode);

Extracts the crossing mode from an event.

Parameters

event

a GdkEvent

 

mode

return location for the crossing mode.

[out]

Returns

TRUE on success, otherwise FALSE


gdk_event_get_drop ()

GdkDrop *
gdk_event_get_drop (const GdkEvent *event);

Gets the GdkDrop from a DND event.

Parameters

event

a GdkEvent

 

Returns

the drop.

[transfer none][nullable]


gdk_event_get_focus_in ()

gboolean
gdk_event_get_focus_in (const GdkEvent *event,
                        gboolean *focus_in);

Extracts whether this is a focus-in or focus-out event.

Parameters

event

a GdkEvent

 

focus_in

return location for focus direction.

[out]

Returns

TRUE on success, otherwise FALSE


gdk_event_get_grab_surface ()

gboolean
gdk_event_get_grab_surface (const GdkEvent *event,
                            GdkSurface **surface);

Extracts the grab surface from a grab broken event.

Parameters

event

a GdkEvent

 

surface

Return location for the grab surface.

[out][transfer none]

Returns

TRUE on success, otherwise FALSE


gdk_event_get_motion_history ()

GList *
gdk_event_get_motion_history (const GdkEvent *event);

Retrieves the history of the event motion, as a list of time and coordinates.

Parameters

event

a GdkEvent of type GDK_MOTION_NOTIFY

 

Returns

a list of time and coordinates.

[transfer container][element-type GdkTimeCoord][nullable]


gdk_event_get_key_group ()

gboolean
gdk_event_get_key_group (const GdkEvent *event,
                         guint *group);

Extracts the key group from an event.

Parameters

event

a GdkEvent

 

group

return location for the key group.

[out]

Returns

TRUE on success, otherwise FALSE


gdk_event_get_key_is_modifier ()

gboolean
gdk_event_get_key_is_modifier (const GdkEvent *event,
                               gboolean *is_modifier);

Extracts whether the event is a key event for a modifier key.

Parameters

event

a GdkEvent

 

is_modifier

return location for the value.

[out]

Returns

TRUE on success, otherwise FALSE


gdk_event_get_pad_axis_value ()

gboolean
gdk_event_get_pad_axis_value (const GdkEvent *event,
                              guint *index,
                              gdouble *value);

Extracts the information from a pad event.

Parameters

event

a GdkEvent

 

index

Return location for the axis index.

[out]

value

Return location for the axis value.

[out]

Returns

TRUE on success, otherwise FALSE


gdk_event_get_pad_button ()

gboolean
gdk_event_get_pad_button (const GdkEvent *event,
                          guint *button);

Extracts information about the pressed button from a pad event.

Parameters

event

a GdkEvent

 

button

Return location for the button.

[out]

Returns

TRUE on success, otherwise FALSE


gdk_event_get_pad_group_mode ()

gboolean
gdk_event_get_pad_group_mode (const GdkEvent *event,
                              guint *group,
                              guint *mode);

Extracts group and mode information from a pad event.

Parameters

event

a GdkEvent

 

group

return location for the group.

[out]

mode

return location for the mode.

[out]

Returns

TRUE on success, otherwise FALSE


gdk_event_get_touch_emulating_pointer ()

gboolean
gdk_event_get_touch_emulating_pointer (const GdkEvent *event,
                                       gboolean *emulating);

Extracts whether a touch event is emulating a pointer event.

Parameters

event

a GdkEvent

 

emulating

Return location for information.

[out]

Returns

TRUE on success, otherwise FALSE


gdk_event_get_touchpad_angle_delta ()

gboolean
gdk_event_get_touchpad_angle_delta (const GdkEvent *event,
                                    double *delta);

Extracts the angle from a touchpad event.

Parameters

event

a GdkEvent

 

delta

Return location for angle.

[out]

Returns

TRUE on success, otherwise FALSE


gdk_event_get_touchpad_deltas ()

gboolean
gdk_event_get_touchpad_deltas (const GdkEvent *event,
                               double *dx,
                               double *dy);

Extracts delta information from a touchpad event.

Parameters

event

a GdkEvent

 

dx

return location for x.

[out]

dy

return location for y.

[out]

Returns

TRUE on success, otherwise FALSE


gdk_event_get_touchpad_gesture_n_fingers ()

gboolean
gdk_event_get_touchpad_gesture_n_fingers
                               (const GdkEvent *event,
                                guint *n_fingers);

Extracts the number of fingers from a touchpad event.

Parameters

event

a GdkEvent

 

n_fingers

return location for the number of fingers.

[out]

Returns

TRUE on success, otherwise FALSE


gdk_event_get_touchpad_gesture_phase ()

gboolean
gdk_event_get_touchpad_gesture_phase (const GdkEvent *event,
                                      GdkTouchpadGesturePhase *phase);

Extracts the touchpad gesture phase from a touchpad event.

Parameters

event

a GdkEvent

 

phase

Return location for the gesture phase.

[out]

Returns

TRUE on success, otherwise FALSE


gdk_event_get_touchpad_scale ()

gboolean
gdk_event_get_touchpad_scale (const GdkEvent *event,
                              double *scale);

Extracts the scale from a touchpad event.

Parameters

event

a GdkEvent

 

scale

Return location for scale.

[out]

Returns

TRUE on success, otherwise FALSE


gdk_event_is_sent ()

gboolean
gdk_event_is_sent (const GdkEvent *event);

Returns whether the event was sent explicitly.

Parameters

event

a GdkEvent

 

Returns

TRUE if the event was sent explicitly


gdk_get_show_events ()

gboolean
gdk_get_show_events (void);

Gets whether event debugging output is enabled.

Returns

TRUE if event debugging output is enabled.


gdk_set_show_events ()

void
gdk_set_show_events (gboolean show_events);

Sets whether a trace of received events is output. Note that GTK+ must be compiled with debugging (that is, configured using the --enable-debug option) to use this option.

Parameters

show_events

TRUE to output event debugging information.

 

gdk_event_set_display ()

void
gdk_event_set_display (GdkEvent *event,
                       GdkDisplay *display);

Sets the display that an event is associated with.

Parameters

event

a GdkEvent

 

display

a GdkDisplay

 

gdk_event_get_display ()

GdkDisplay *
gdk_event_get_display (const GdkEvent *event);

Retrieves the GdkDisplay associated to the event .

Parameters

event

a GdkEvent

 

Returns

a GdkDisplay.

[transfer none][nullable]


gdk_event_get_device ()

GdkDevice *
gdk_event_get_device (const GdkEvent *event);

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

Parameters

event

a GdkEvent.

 

Returns

a GdkDevice, or NULL.

[nullable][transfer none]


gdk_event_set_device ()

void
gdk_event_set_device (GdkEvent *event,
                      GdkDevice *device);

Sets the device for event to device . The event must have been allocated by GTK+, for instance, by gdk_event_copy().

Parameters

event

a GdkEvent

 

device

a GdkDevice

 

gdk_event_get_source_device ()

GdkDevice *
gdk_event_get_source_device (const GdkEvent *event);

This function returns the hardware (slave) GdkDevice 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 GdkSurface updates its geometry or a grab is acquired/released.

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

Parameters

event

a GdkEvent

 

Returns

a GdkDevice, or NULL.

[nullable][transfer none]


gdk_event_set_source_device ()

void
gdk_event_set_source_device (GdkEvent *event,
                             GdkDevice *device);

Sets the slave device for event to device .

The event must have been allocated by GTK+, for instance by gdk_event_copy().

Parameters

event

a GdkEvent

 

device

a GdkDevice

 

gdk_event_get_device_tool ()

GdkDeviceTool *
gdk_event_get_device_tool (const GdkEvent *event);

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

Note: the GdkDeviceTool<!-- -->s will be constant during the application lifetime, if settings must be stored persistently across runs, see gdk_device_tool_get_serial()

Parameters

event

a GdkEvent

 

Returns

The current device tool, or NULL.

[transfer none]


gdk_event_set_device_tool ()

void
gdk_event_set_device_tool (GdkEvent *event,
                           GdkDeviceTool *tool);

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

Parameters

event

a GdkEvent

 

tool

tool to set on the event, or NULL.

[nullable]

Property Details

The “event-type” property

  “event-type”               GdkEventType

Event type.

Owner: GdkEvent

Flags: Read / Write / Construct Only

Default value: GDK_NOTHING

See Also

Event Structures