Events

Events — Functions for handling events from the window system

Functions

GdkEvent * gdk_event_ref ()
void gdk_event_unref ()
GdkEventType gdk_event_get_event_type ()
GdkSurface * gdk_event_get_surface ()
GdkDevice * gdk_event_get_device ()
GdkDevice * gdk_event_get_source_device ()
GdkDeviceTool * gdk_event_get_device_tool ()
guint32 gdk_event_get_time ()
GdkDisplay * gdk_event_get_display ()
GdkEventSequence * gdk_event_get_event_sequence ()
GdkModifierType gdk_event_get_modifier_state ()
gboolean gdk_event_get_position ()
gboolean gdk_event_get_axes ()
gboolean gdk_event_get_axis ()
gboolean gdk_event_get_pointer_emulated ()
guint gdk_button_event_get_button ()
GdkScrollDirection gdk_scroll_event_get_direction ()
void gdk_scroll_event_get_deltas ()
gboolean gdk_scroll_event_is_stop ()
guint gdk_key_event_get_keyval ()
guint gdk_key_event_get_keycode ()
guint gdk_key_event_get_scancode ()
guint gdk_key_event_get_group ()
gboolean gdk_key_event_is_modifier ()
gboolean gdk_focus_event_get_in ()
gboolean gdk_touch_event_get_emulating_pointer ()
GdkCrossingMode gdk_crossing_event_get_mode ()
GdkNotifyType gdk_crossing_event_get_detail ()
void gdk_configure_event_get_size ()
GdkTouchpadGesturePhase gdk_touchpad_event_get_gesture_phase ()
guint gdk_touchpad_event_get_n_fingers ()
void gdk_touchpad_event_get_deltas ()
double gdk_touchpad_pinch_event_get_angle_delta ()
double gdk_touchpad_pinch_event_get_scale ()
guint gdk_pad_button_event_get_button ()
void gdk_pad_axis_event_get_value ()
void gdk_pad_event_get_group_mode ()
GdkDrop * gdk_drag_event_get_drop ()
GdkSurface * gdk_grab_broken_event_get_grab_surface ()
GList * gdk_event_get_motion_history ()
gboolean gdk_events_get_angle ()
gboolean gdk_events_get_center ()
gboolean gdk_events_get_distance ()

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

    GBoxed
    ╰── 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 event controllers of appropriate widgets, so these functions are rarely needed.

Functions

gdk_event_ref ()

GdkEvent *
gdk_event_ref (GdkEvent *event);

Increase the ref count of event .

Parameters

event

a GdkEvent

 

Returns

event


gdk_event_unref ()

void
gdk_event_unref (GdkEvent *event);

Decrease the ref count of event , and free it if the last reference is dropped.

Parameters

event

a GdkEvent

 

gdk_event_get_event_type ()

GdkEventType
gdk_event_get_event_type (GdkEvent *event);

Retrieves the type of the event.

Parameters

event

a GdkEvent

 

Returns

a GdkEventType


gdk_event_get_surface ()

GdkSurface *
gdk_event_get_surface (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_device ()

GdkDevice *
gdk_event_get_device (GdkEvent *event);

Returns the device of an event.

Parameters

event

a GdkEvent.

 

Returns

a GdkDevice, or NULL.

[nullable][transfer none]


gdk_event_get_source_device ()

GdkDevice *
gdk_event_get_source_device (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_get_device_tool ()

GdkDeviceTool *
gdk_event_get_device_tool (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 GdkDeviceTools 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_get_time ()

guint32
gdk_event_get_time (GdkEvent *event);

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

Parameters

event

a GdkEvent

 

Returns

time stamp field from event


gdk_event_get_display ()

GdkDisplay *
gdk_event_get_display (GdkEvent *event);

Retrieves the GdkDisplay associated to the event .

Parameters

event

a GdkEvent

 

Returns

a GdkDisplay.

[transfer none][nullable]


gdk_event_get_event_sequence ()

GdkEventSequence *
gdk_event_get_event_sequence (GdkEvent *event);

If event is a touch event, 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_event_get_modifier_state ()

GdkModifierType
gdk_event_get_modifier_state (GdkEvent *event);

Returns the modifier state field of an event.

Parameters

event

a GdkEvent

 

Returns

the modifier state of event


gdk_event_get_position ()

gboolean
gdk_event_get_position (GdkEvent *event,
                        double *x,
                        double *y);

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

Parameters

event

a GdkEvent

 

x

location to put event surface x coordinate.

[out]

y

location to put event surface y coordinate.

[out]

gdk_event_get_axes ()

gboolean
gdk_event_get_axes (GdkEvent *event,
                    double **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 (GdkEvent *event,
                    GdkAxisUse axis_use,
                    double *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_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_button_event_get_button ()

guint
gdk_button_event_get_button (GdkEvent *event);

Extract the button number from a button event.

Parameters

event

a button event

 

Returns

the button of event


gdk_scroll_event_get_direction ()

GdkScrollDirection
gdk_scroll_event_get_direction (GdkEvent *event);

Extracts the direction of a scroll event.

Parameters

event

a scroll event

 

Returns

the scroll direction of event


gdk_scroll_event_get_deltas ()

void
gdk_scroll_event_get_deltas (GdkEvent *event,
                             double *delta_x,
                             double *delta_y);

Extracts the scroll deltas of a scroll event.

The deltas will be zero unless the scroll direction is GDK_SCROLL_SMOOTH.

Parameters

event

a scroll event

 

delta_x

return location for x scroll delta.

[out]

delta_y

return location for y scroll delta.

[out]

gdk_scroll_event_is_stop ()

gboolean
gdk_scroll_event_is_stop (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 scroll event

 

Returns

TRUE if the event is a scroll stop event


gdk_key_event_get_keyval ()

guint
gdk_key_event_get_keyval (GdkEvent *event);

Extracts the keyval from a key event.

Parameters

event

a key event

 

Returns

the keyval of event


gdk_key_event_get_keycode ()

guint
gdk_key_event_get_keycode (GdkEvent *event);

Extracts the keycode from a key event.

Parameters

event

a key event

 

Returns

the keycode of event


gdk_key_event_get_scancode ()

guint
gdk_key_event_get_scancode (GdkEvent *event);

Extracts the scancode from a key event.

Parameters

event

a key event

 

Returns

the scancode of event


gdk_key_event_get_group ()

guint
gdk_key_event_get_group (GdkEvent *event);

Extracts the group from a key event.

Parameters

event

a key event

 

Returns

the group of event


gdk_key_event_is_modifier ()

gboolean
gdk_key_event_is_modifier (GdkEvent *event);

Extracts whether the key event is for a modifier key.

Parameters

event

a key event

 

Returns

TRUE if the event is for a modifier key


gdk_focus_event_get_in ()

gboolean
gdk_focus_event_get_in (GdkEvent *event);

Extracts whether this event is about focus entering or leaving the surface.

Parameters

event

a focus change event

 

Returns

TRUE of the focus is entering


gdk_touch_event_get_emulating_pointer ()

gboolean
gdk_touch_event_get_emulating_pointer (GdkEvent *event);

Extracts whether a touch event is emulating a pointer event.

Parameters

event

a touch event

 

Returns

TRUE if event is emulating


gdk_crossing_event_get_mode ()

GdkCrossingMode
gdk_crossing_event_get_mode (GdkEvent *event);

Extracts the crossing mode from a crossing event.

Parameters

event

a crossing event

 

Returns

the mode of event


gdk_crossing_event_get_detail ()

GdkNotifyType
gdk_crossing_event_get_detail (GdkEvent *event);

Extracts the notify detail from a crossing event.

Parameters

event

a crossing event

 

Returns

the notify detail of event


gdk_configure_event_get_size ()

void
gdk_configure_event_get_size (GdkEvent *event,
                              int *width,
                              int *height);

Extracts the surface size from a configure event.

Parameters

event

a configure event

 

width

return location for surface width.

[out]

height

return location for surface height.

[out]

gdk_touchpad_event_get_gesture_phase ()

GdkTouchpadGesturePhase
gdk_touchpad_event_get_gesture_phase (GdkEvent *event);

Extracts the touchpad gesture phase from a touchpad event.

Parameters

event

a touchpad GdkEvent

 

Returns

the gesture phase of event


gdk_touchpad_event_get_n_fingers ()

guint
gdk_touchpad_event_get_n_fingers (GdkEvent *event);

Extracts the number of fingers from a touchpad event.

Parameters

event

a touchpad event

 

Returns

the number of fingers for event


gdk_touchpad_event_get_deltas ()

void
gdk_touchpad_event_get_deltas (GdkEvent *event,
                               double *dx,
                               double *dy);

Extracts delta information from a touchpad event.

Parameters

event

a touchpad event

 

dx

return location for x.

[out]

dy

return location for y.

[out]

gdk_touchpad_pinch_event_get_angle_delta ()

double
gdk_touchpad_pinch_event_get_angle_delta
                               (GdkEvent *event);

Extracts the angle delta from a touchpad pinch event.

Parameters

event

a touchpad pinch event

 

Returns

the angle delta of event


gdk_touchpad_pinch_event_get_scale ()

double
gdk_touchpad_pinch_event_get_scale (GdkEvent *event);

Extracts the scale from a touchpad pinch event.

Parameters

event

a touchpad pinch event

 

Returns

the scale of event


gdk_pad_button_event_get_button ()

guint
gdk_pad_button_event_get_button (GdkEvent *event);

Extracts information about the pressed button from a pad event.

Parameters

event

a pad button event

 

Returns

the button of event


gdk_pad_axis_event_get_value ()

void
gdk_pad_axis_event_get_value (GdkEvent *event,
                              guint *index,
                              double *value);

Extracts the information from a pad strip or ring event.

Parameters

event

a pad strip or ring event

 

index

Return location for the axis index.

[out]

value

Return location for the axis value.

[out]

gdk_pad_event_get_group_mode ()

void
gdk_pad_event_get_group_mode (GdkEvent *event,
                              guint *group,
                              guint *mode);

Extracts group and mode information from a pad event.

Parameters

event

a pad event

 

group

return location for the group.

[out]

mode

return location for the mode.

[out]

gdk_drag_event_get_drop ()

GdkDrop *
gdk_drag_event_get_drop (GdkEvent *event);

Gets the GdkDrop from a DND event.

Parameters

event

a DND event

 

Returns

the drop.

[transfer none][nullable]


gdk_grab_broken_event_get_grab_surface ()

GdkSurface *
gdk_grab_broken_event_get_grab_surface
                               (GdkEvent *event);

Extracts the grab surface from a grab broken event.

Parameters

event

a grab broken event

 

Returns

the grab surface of event .

[transfer none]


gdk_event_get_motion_history ()

GList *
gdk_event_get_motion_history (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_events_get_angle ()

gboolean
gdk_events_get_angle (GdkEvent *event1,
                      GdkEvent *event2,
                      double *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,
                       double *x,
                       double *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,
                         double *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.