Top |
Functions
Types and Values
GdkEvent | |
enum | GdkEventType |
struct | GdkKeymapKey |
enum | GdkKeyMatch |
enum | GdkTouchpadGesturePhase |
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 | |
GdkButtonEvent | |
GdkScrollEvent | |
GdkMotionEvent | |
GdkKeyEvent | |
GdkFocusEvent | |
GdkCrossingEvent | |
GdkGrabBrokenEvent | |
GdkDeleteEvent | |
GdkDNDEvent | |
GdkTouchEvent | |
GdkTouchpadEvent | |
GdkPadEvent | |
GdkProximityEvent |
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_unref ()
void
gdk_event_unref (GdkEvent *event
);
Decrease the ref count of event
, and free it
if the last reference is dropped.
gdk_event_get_event_type ()
GdkEventType
gdk_event_get_event_type (GdkEvent *event
);
Retrieves the type of the event.
gdk_event_get_surface ()
GdkSurface *
gdk_event_get_surface (GdkEvent *event
);
Extracts the GdkSurface associated with an event.
gdk_event_get_device ()
GdkDevice *
gdk_event_get_device (GdkEvent *event
);
Returns the device of an event.
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()
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.
gdk_event_get_display ()
GdkDisplay *
gdk_event_get_display (GdkEvent *event
);
Retrieves the GdkDisplay associated to the event
.
gdk_event_get_seat ()
GdkSeat *
gdk_event_get_seat (GdkEvent *event
);
Returns the seat that originated the event.
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
.
gdk_event_get_modifier_state ()
GdkModifierType
gdk_event_get_modifier_state (GdkEvent *event
);
Returns the modifier state field of an 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] |
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] |
gdk_event_get_history ()
GdkTimeCoord * gdk_event_get_history (GdkEvent *event
,guint *out_n_coords
);
Retrieves the history of the event
, as a list of time and coordinates.
The history includes events that are not delivered to the application
because they occurred in the same frame as event
.
Note that only motion and scroll events record history, and motion events only if one of the mouse buttons is down.
Parameters
event |
a motion or scroll GdkEvent |
|
out_n_coords |
Return location for the length of the returned array. |
[out] |
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.
gdk_event_triggers_context_menu ()
gboolean
gdk_event_triggers_context_menu (GdkEvent *event
);
This function returns whether a GdkEvent should trigger a context menu, according to platform conventions. The right mouse button always triggers context menus.
This function should always be used instead of simply checking for
event->button == GDK_BUTTON_SECONDARY
.
gdk_button_event_get_button ()
guint
gdk_button_event_get_button (GdkEvent *event
);
Extract the button number from a button event.
gdk_scroll_event_get_direction ()
GdkScrollDirection
gdk_scroll_event_get_direction (GdkEvent *event
);
Extracts the direction of a scroll 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
.
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.
gdk_key_event_get_keyval ()
guint
gdk_key_event_get_keyval (GdkEvent *event
);
Extracts the keyval from a key event.
gdk_key_event_get_keycode ()
guint
gdk_key_event_get_keycode (GdkEvent *event
);
Extracts the keycode from a key event.
gdk_key_event_get_consumed_modifiers ()
GdkModifierType
gdk_key_event_get_consumed_modifiers (GdkEvent *event
);
Extracts the consumed modifiers from a key event.
gdk_key_event_get_layout ()
guint
gdk_key_event_get_layout (GdkEvent *event
);
Extracts the layout from a key event.
gdk_key_event_get_level ()
guint
gdk_key_event_get_level (GdkEvent *event
);
Extracts the shift level from a key event.
gdk_key_event_is_modifier ()
gboolean
gdk_key_event_is_modifier (GdkEvent *event
);
Extracts whether the key event is for a modifier key.
gdk_key_event_matches ()
GdkKeyMatch gdk_key_event_matches (GdkEvent *event
,guint keyval
,GdkModifierType modifiers
);
Matches a key event against a keyboard shortcut that is specified as a keyval and modifiers. Partial matches are possible where the combination matches if the currently active group is ignored.
Note that we ignore Caps Lock for matching.
Parameters
event |
a key GdkEvent. |
[type GdkKeyEvent] |
keyval |
the keyval to match |
|
modifiers |
the modifiers to match |
gdk_key_event_get_match ()
gboolean gdk_key_event_get_match (GdkEvent *event
,guint *keyval
,GdkModifierType *modifiers
);
Gets a keyval and modifier combination that will cause
gdk_key_event_matches()
to successfully match the given event.
Parameters
event |
a key GdkEvent. |
[type GdkKeyEvent] |
keyval |
return location for a keyval. |
[out] |
modifiers |
return location for modifiers. |
[out] |
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.
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.
gdk_crossing_event_get_mode ()
GdkCrossingMode
gdk_crossing_event_get_mode (GdkEvent *event
);
Extracts the crossing mode from a crossing event.
gdk_crossing_event_get_detail ()
GdkNotifyType
gdk_crossing_event_get_detail (GdkEvent *event
);
Extracts the notify detail from a crossing event.
gdk_crossing_event_get_focus ()
gboolean
gdk_crossing_event_get_focus (GdkEvent *event
);
Checks if the event
surface is the focus surface.
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.
gdk_grab_broken_event_get_implicit ()
gboolean
gdk_grab_broken_event_get_implicit (GdkEvent *event
);
Checks whether the grab broken event is for an implicit grab.
gdk_dnd_event_get_drop ()
GdkDrop *
gdk_dnd_event_get_drop (GdkEvent *event
);
Gets the GdkDrop from a DND event.
gdk_touchpad_event_get_gesture_phase ()
GdkTouchpadGesturePhase
gdk_touchpad_event_get_gesture_phase (GdkEvent *event
);
Extracts the touchpad gesture phase from a touchpad 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.
gdk_touchpad_event_get_deltas ()
void gdk_touchpad_event_get_deltas (GdkEvent *event
,double *dx
,double *dy
);
Extracts delta information from a touchpad event.
gdk_touchpad_event_get_pinch_angle_delta ()
double
gdk_touchpad_event_get_pinch_angle_delta
(GdkEvent *event
);
Extracts the angle delta from a touchpad pinch event.
gdk_touchpad_event_get_pinch_scale ()
double
gdk_touchpad_event_get_pinch_scale (GdkEvent *event
);
Extracts the scale from a touchpad pinch event.
gdk_pad_event_get_axis_value ()
void gdk_pad_event_get_axis_value (GdkEvent *event
,guint *index
,double *value
);
Extracts the information from a pad strip or ring event.
gdk_pad_event_get_button ()
guint
gdk_pad_event_get_button (GdkEvent *event
);
Extracts information about the pressed button from a pad event.
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.
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.
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
.
Types and Values
GdkEvent
typedef struct _GdkEvent GdkEvent;
The GdkEvent struct contains only private fields and should not be accessed directly.
enum GdkEventType
Specifies the type of the event.
Members
the window manager has requested that the toplevel surface be hidden or destroyed, usually when the user clicks on a special icon in the title bar. |
||
the pointer (usually a mouse) has moved. |
||
a mouse button has been pressed. |
||
a mouse button has been released. |
||
a key has been pressed. |
||
a key has been released. |
||
the pointer has entered the surface. |
||
the pointer has left the surface. |
||
the keyboard focus has entered or left the surface. |
||
an input device has moved into contact with a sensing surface (e.g. a touchscreen or graphics tablet). |
||
an input device has moved out of contact with a sensing surface. |
||
the mouse has entered the surface while a drag is in progress. |
||
the mouse has left the surface while a drag is in progress. |
||
the mouse has moved in the surface while a drag is in progress. |
||
a drop operation onto the surface has started. |
||
the scroll wheel was turned |
||
a pointer or keyboard grab was broken. |
||
A new touch event sequence has just started. |
||
A touch event sequence has been updated. |
||
A touch event sequence has finished. |
||
A touch event sequence has been canceled. |
||
A touchpad swipe gesture event, the current state is determined by its phase field. |
||
A touchpad pinch gesture event, the current state is determined by its phase field. |
||
A tablet pad button press event. |
||
A tablet pad button release event. |
||
A tablet pad axis event from a "ring". |
||
A tablet pad axis event from a "strip". |
||
A tablet pad group mode change. |
||
marks the end of the GdkEventType enumeration. |
struct GdkKeymapKey
struct GdkKeymapKey { guint keycode; int group; int level; };
A GdkKeymapKey is a hardware key that can be mapped to a keyval.
Members
the hardware keycode. This is an identifying number for a physical key. |
||
indicates movement in a horizontal direction. Usually groups are used for two different languages. In group 0, a key might have two English characters, and in group 1 it might have two Hebrew characters. The Hebrew characters will be printed on the key next to the English characters. |
||
indicates which symbol on the key will be used, in a vertical direction. So on a standard US keyboard, the key with the number “1” on it also has the exclamation point ("!") character on it. The level indicates whether to use the “1” or the “!” symbol. The letter keys are considered to have a lowercase letter at level 0, and an uppercase letter at level 1, though only the uppercase letter is printed. |
enum GdkKeyMatch
The possible return values from gdk_key_event_matches()
describe how well an event matches a given keyval and modifiers.
enum GdkTouchpadGesturePhase
Specifies the current state of a touchpad gesture. All gestures are
guaranteed to begin with an event with phase GDK_TOUCHPAD_GESTURE_PHASE_BEGIN
,
followed by 0 or several events with phase GDK_TOUCHPAD_GESTURE_PHASE_UPDATE
.
A finished gesture may have 2 possible outcomes, an event with phase
GDK_TOUCHPAD_GESTURE_PHASE_END
will be emitted when the gesture is
considered successful, this should be used as the hint to perform any
permanent changes.
Cancelled gestures may be so for a variety of reasons, due to hardware
or the compositor, or due to the gesture recognition layers hinting the
gesture did not finish resolutely (eg. a 3rd finger being added during
a pinch gesture). In these cases, the last event will report the phase
GDK_TOUCHPAD_GESTURE_PHASE_CANCEL
, this should be used as a hint
to undo any visible/permanent changes that were done throughout the
progress of the gesture.
enum GdkScrollDirection
Specifies the direction for scroll events.
Members
the surface is scrolled up. |
||
the surface is scrolled down. |
||
the surface is scrolled to the left. |
||
the surface is scrolled to the right. |
||
the scrolling is determined by the delta values
in scroll events. See |
enum GdkCrossingMode
Specifies the crossing mode for enter and leave events.
Members
crossing because of pointer motion. |
||
crossing because a grab is activated. |
||
crossing because a grab is deactivated. |
||
crossing because a GTK grab is activated. |
||
crossing because a GTK grab is deactivated. |
||
crossing because a GTK widget changed state (e.g. sensitivity). |
||
crossing because a touch sequence has begun, this event is synthetic as the pointer might have not left the surface. |
||
crossing because a touch sequence has ended, this event is synthetic as the pointer might have not left the surface. |
||
crossing because of a device switch (i.e. a mouse taking control of the pointer after a touch device), this event is synthetic as the pointer didn’t leave the surface. |
enum GdkNotifyType
Specifies the kind of crossing for enter and leave events.
See the X11 protocol specification of LeaveNotify for full details of crossing event generation.
Members
the surface is entered from an ancestor or left towards an ancestor. |
||
the pointer moves between an ancestor and an inferior of the surface. |
||
the surface is entered from an inferior or left towards an inferior. |
||
the surface is entered from or left towards a surface which is neither an ancestor nor an inferior. |
||
the pointer moves between two surfaces which are not ancestors of each other and the surface is part of the ancestor chain between one of these surfaces and their least common ancestor. |
||
an unknown type of enter/leave event occurred. |
GDK_CURRENT_TIME
#define GDK_CURRENT_TIME 0L
Represents the current time, and can be used anywhere a time is expected.
GDK_PRIORITY_EVENTS
#define GDK_PRIORITY_EVENTS (G_PRIORITY_DEFAULT)
This is the priority that events from the X server are given in the GLib Main Loop.
GDK_PRIORITY_REDRAW
#define GDK_PRIORITY_REDRAW (G_PRIORITY_HIGH_IDLE + 20)
This is the priority that the idle handler processing surface updates is given in the GLib Main Loop.
GDK_EVENT_PROPAGATE
#define GDK_EVENT_PROPAGATE (FALSE)
Use this macro as the return value for continuing the propagation of an event handler.
GDK_EVENT_STOP
#define GDK_EVENT_STOP (TRUE)
Use this macro as the return value for stopping the propagation of an event handler.
GDK_BUTTON_PRIMARY
#define GDK_BUTTON_PRIMARY (1)
The primary button. This is typically the left mouse button, or the right button in a left-handed setup.
GDK_BUTTON_SECONDARY
#define GDK_BUTTON_SECONDARY (3)
The secondary button. This is typically the right mouse button, or the left button in a left-handed setup.
GdkEventSequence
typedef struct _GdkEventSequence GdkEventSequence;
GdkEventSequence is an opaque type representing a sequence of related touch events.
GdkButtonEvent
typedef struct _GdkButtonEvent GdkButtonEvent;
An event related to a button on a pointer device/
GdkScrollEvent
typedef struct _GdkScrollEvent GdkScrollEvent;
An event related to a scrolling motion.
GdkMotionEvent
typedef struct _GdkMotionEvent GdkMotionEvent;
An event related to a pointer or touch device motion.
GdkCrossingEvent
typedef struct _GdkCrossingEvent GdkCrossingEvent;
An event caused by a pointing device moving between surfaces.
GdkGrabBrokenEvent
typedef struct _GdkGrabBrokenEvent GdkGrabBrokenEvent;
An event related to a broken windowing system grab.
GdkDeleteEvent
typedef struct _GdkDeleteEvent GdkDeleteEvent;
An event related to closing a top-level surface.
GdkTouchEvent
typedef struct _GdkTouchEvent GdkTouchEvent;
An event related to a touch-based device.
GdkTouchpadEvent
typedef struct _GdkTouchpadEvent GdkTouchpadEvent;
An event related to a touchpad device.