![]() |
![]() |
![]() |
GDK 3 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <gdk/gdk.h> enum GdkEventType; enum GdkEventMask; #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 gboolean gdk_events_pending (void
); GdkEvent * gdk_event_peek (void
); GdkEvent * gdk_event_get (void
); void gdk_event_put (const GdkEvent *event
); GdkEvent * gdk_event_new (GdkEventType type
); GdkEvent * gdk_event_copy (const GdkEvent *event
); void gdk_event_free (GdkEvent *event
); gboolean gdk_event_get_axis (const GdkEvent *event
,GdkAxisUse axis_use
,gdouble *value
); gboolean gdk_event_get_button (const GdkEvent *event
,guint *button
); gboolean gdk_event_get_click_count (const GdkEvent *event
,guint *click_count
); gboolean gdk_event_get_coords (const GdkEvent *event
,gdouble *x_win
,gdouble *y_win
); gboolean gdk_event_get_keycode (const GdkEvent *event
,guint16 *keycode
); gboolean gdk_event_get_keyval (const GdkEvent *event
,guint *keyval
); gboolean gdk_event_get_root_coords (const GdkEvent *event
,gdouble *x_root
,gdouble *y_root
); gboolean gdk_event_get_scroll_direction (const GdkEvent *event
,GdkScrollDirection *direction
); gboolean gdk_event_get_scroll_deltas (const GdkEvent *event
,gdouble *delta_x
,gdouble *delta_y
); gboolean gdk_event_get_state (const GdkEvent *event
,GdkModifierType *state
); guint32 gdk_event_get_time (const GdkEvent *event
); GdkEventSequence; GdkEventSequence * gdk_event_get_event_sequence (const GdkEvent *event
); void gdk_event_request_motions (const GdkEventMotion *event
); gboolean gdk_events_get_angle (GdkEvent *event1
,GdkEvent *event2
,gdouble *angle
); gboolean gdk_events_get_center (GdkEvent *event1
,GdkEvent *event2
,gdouble *x
,gdouble *y
); gboolean gdk_events_get_distance (GdkEvent *event1
,GdkEvent *event2
,gdouble *distance
); gboolean gdk_event_triggers_context_menu (const GdkEvent *event
); void gdk_event_handler_set (GdkEventFunc func
,gpointer data
,GDestroyNotify notify
); void (*GdkEventFunc) (GdkEvent *event
,gpointer data
); gboolean gdk_get_show_events (void
); void gdk_set_show_events (gboolean show_events
); void gdk_event_set_screen (GdkEvent *event
,GdkScreen *screen
); GdkScreen * gdk_event_get_screen (const GdkEvent *event
); GdkDevice * gdk_event_get_device (const GdkEvent *event
); void gdk_event_set_device (GdkEvent *event
,GdkDevice *device
); GdkDevice * gdk_event_get_source_device (const GdkEvent *event
); void gdk_event_set_source_device (GdkEvent *event
,GdkDevice *device
); gboolean gdk_setting_get (const gchar *name
,GValue *value
);
This section describes functions dealing with events from the window system.
In GTK+ applications the events are handled automatically in
gtk_main_do_event()
and passed on to the appropriate widgets, so these
functions are rarely needed. Though some of the fields in the
Event Structures are useful.
typedef enum { GDK_NOTHING = -1, GDK_DELETE = 0, GDK_DESTROY = 1, GDK_EXPOSE = 2, GDK_MOTION_NOTIFY = 3, GDK_BUTTON_PRESS = 4, GDK_2BUTTON_PRESS = 5, GDK_3BUTTON_PRESS = 6, GDK_BUTTON_RELEASE = 7, GDK_KEY_PRESS = 8, GDK_KEY_RELEASE = 9, GDK_ENTER_NOTIFY = 10, GDK_LEAVE_NOTIFY = 11, GDK_FOCUS_CHANGE = 12, GDK_CONFIGURE = 13, GDK_MAP = 14, GDK_UNMAP = 15, GDK_PROPERTY_NOTIFY = 16, GDK_SELECTION_CLEAR = 17, GDK_SELECTION_REQUEST = 18, GDK_SELECTION_NOTIFY = 19, GDK_PROXIMITY_IN = 20, GDK_PROXIMITY_OUT = 21, GDK_DRAG_ENTER = 22, GDK_DRAG_LEAVE = 23, GDK_DRAG_MOTION = 24, GDK_DRAG_STATUS = 25, GDK_DROP_START = 26, GDK_DROP_FINISHED = 27, GDK_CLIENT_EVENT = 28, GDK_VISIBILITY_NOTIFY = 29, GDK_SCROLL = 31, GDK_WINDOW_STATE = 32, GDK_SETTING = 33, GDK_OWNER_CHANGE = 34, GDK_GRAB_BROKEN = 35, GDK_DAMAGE = 36, GDK_TOUCH_BEGIN = 37, GDK_TOUCH_UPDATE = 38, GDK_TOUCH_END = 39, GDK_TOUCH_CANCEL = 40, GDK_EVENT_LAST /* helper variable for decls */ } GdkEventType;
Specifies the type of the event.
Do not confuse these events with the signals that GTK+ widgets emit. Although many of these events result in corresponding signals being emitted, the events are often transformed or filtered along the way.
a special code to indicate a null event. | |
the window manager has requested that the toplevel window be hidden or destroyed, usually when the user clicks on a special icon in the title bar. | |
the window has been destroyed. | |
all or part of the window has become visible and needs to be redrawn. | |
the pointer (usually a mouse) has moved. | |
a mouse button has been pressed. | |
a mouse button has been double-clicked (clicked twice
within a short period of time). Note that each click also generates a
GDK_BUTTON_PRESS event.
|
|
a mouse button has been clicked 3 times in a short period
of time. Note that each click also generates a GDK_BUTTON_PRESS event.
|
|
a mouse button has been released. | |
a key has been pressed. | |
a key has been released. | |
the pointer has entered the window. | |
the pointer has left the window. | |
the keyboard focus has entered or left the window. | |
the size, position or stacking order of the window has changed.
Note that GTK+ discards these events for GDK_WINDOW_CHILD windows.
|
|
the window has been mapped. | |
the window has been unmapped. | |
a property on the window has been changed or deleted. | |
the application has lost ownership of a selection. | |
another application has requested a selection. | |
a selection has been received. | |
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 window while a drag is in progress. | |
the mouse has left the window while a drag is in progress. | |
the mouse has moved in the window while a drag is in progress. | |
the status of the drag operation initiated by the window has changed. | |
a drop operation onto the window has started. | |
the drop operation initiated by the window has completed. | |
a message has been received from another application. | |
the window visibility status has changed. | |
the scroll wheel was turned | |
the state of a window has changed. See GdkWindowState for the possible window states | |
a setting has been modified. | |
the owner of a selection has changed. This event type was added in 2.6 | |
a pointer or keyboard grab was broken. This event type was added in 2.8. | |
the content of the window has been changed. This event type was added in 2.14. | |
A new touch event sequence has just started. This event type was added in 3.4. | |
A touch event sequence has been updated. This event type was added in 3.4. | |
A touch event sequence has finished. This event type was added in 3.4. | |
A touch event sequence has been canceled. This event type was added in 3.4. | |
marks the end of the GdkEventType enumeration. Added in 2.18 |
typedef enum { GDK_EXPOSURE_MASK = 1 << 1, GDK_POINTER_MOTION_MASK = 1 << 2, GDK_POINTER_MOTION_HINT_MASK = 1 << 3, GDK_BUTTON_MOTION_MASK = 1 << 4, GDK_BUTTON1_MOTION_MASK = 1 << 5, GDK_BUTTON2_MOTION_MASK = 1 << 6, GDK_BUTTON3_MOTION_MASK = 1 << 7, GDK_BUTTON_PRESS_MASK = 1 << 8, GDK_BUTTON_RELEASE_MASK = 1 << 9, GDK_KEY_PRESS_MASK = 1 << 10, GDK_KEY_RELEASE_MASK = 1 << 11, GDK_ENTER_NOTIFY_MASK = 1 << 12, GDK_LEAVE_NOTIFY_MASK = 1 << 13, GDK_FOCUS_CHANGE_MASK = 1 << 14, GDK_STRUCTURE_MASK = 1 << 15, GDK_PROPERTY_CHANGE_MASK = 1 << 16, GDK_VISIBILITY_NOTIFY_MASK = 1 << 17, GDK_PROXIMITY_IN_MASK = 1 << 18, GDK_PROXIMITY_OUT_MASK = 1 << 19, GDK_SUBSTRUCTURE_MASK = 1 << 20, GDK_SCROLL_MASK = 1 << 21, GDK_TOUCH_MASK = 1 << 22, GDK_SMOOTH_SCROLL_MASK = 1 << 23, GDK_ALL_EVENTS_MASK = 0xFFFFFE } GdkEventMask;
A set of bit-flags to indicate which events a window is to receive. Most of these masks map onto one or more of the GdkEventType event types above.
GDK_POINTER_MOTION_HINT_MASK
is a special mask which is used to reduce the
number of GDK_MOTION_NOTIFY
events received. Normally a GDK_MOTION_NOTIFY
event is received each time the mouse moves. However, if the application
spends a lot of time processing the event (updating the display, for example),
it can lag behind the position of the mouse. When using
GDK_POINTER_MOTION_HINT_MASK
, fewer GDK_MOTION_NOTIFY
events will be sent,
some of which are marked as a hint (the is_hint member is TRUE
).
To receive more motion events after a motion hint event, the application
needs to asks for more, by calling gdk_event_request_motions()
.
If GDK_TOUCH_MASK
is enabled, the window will receive touch events
from touch-enabled devices. Those will come as sequences of GdkEventTouch
with type GDK_TOUCH_UPDATE
, enclosed by two events with
type GDK_TOUCH_BEGIN
and GDK_TOUCH_END
(or GDK_TOUCH_CANCEL
).
gdk_event_get_event_sequence()
returns the event sequence for these
events, so different sequences may be distinguished.
receive expose events | |
receive all pointer motion events | |
see the explanation above | |
receive pointer motion events while any button is pressed | |
receive pointer motion events while 1 button is pressed | |
receive pointer motion events while 2 button is pressed | |
receive pointer motion events while 3 button is pressed | |
receive button press events | |
receive button release events | |
receive key press events | |
receive key release events | |
receive window enter events | |
receive window leave events | |
receive focus change events | |
receive events about window configuration change | |
receive property change events | |
receive visibility change events | |
receive proximity in events | |
receive proximity out events | |
receive events about window configuration changes of child windows | |
receive scroll events | |
receive touch events. Since 3.4 | |
receive smooth scrolling events. Since 3.4 | |
the combination of all the above event masks. |
#define GDK_CURRENT_TIME 0L
Represents the current time, and can be used anywhere a time is expected.
#define GDK_PRIORITY_EVENTS
This is the priority that events from the X server are given in the GLib Main Loop.
#define GDK_PRIORITY_REDRAW (G_PRIORITY_HIGH_IDLE + 20)
This is the priority that the idle handler processing window updates is given in the GLib Main Loop.
#define GDK_EVENT_PROPAGATE (FALSE)
Use this macro as the return value for continuing the propagation of an event handler.
Since 3.4
#define GDK_EVENT_STOP (TRUE)
Use this macro as the return value for stopping the propagation of an event handler.
Since 3.4
#define GDK_BUTTON_PRIMARY (1)
The primary button. This is typically the left mouse button, or the right button in a left-handed setup.
Since 3.4
#define GDK_BUTTON_SECONDARY (3)
The secondary button. This is typically the right mouse button, or the left button in a left-handed setup.
Since 3.4
gboolean gdk_events_pending (void
);
Checks if any events are ready to be processed for any display.
Returns : |
TRUE if any events are pending. |
GdkEvent * gdk_event_peek (void
);
If there is an event waiting in the event queue of some open
display, returns a copy of it. See gdk_display_peek_event()
.
Returns : |
a copy of the first GdkEvent on some event queue, or NULL if no
events are in any queues. The returned GdkEvent should be freed with
gdk_event_free() . |
GdkEvent * gdk_event_get (void
);
Checks all open displays for a GdkEvent to process,to be processed
on, fetching events from the windowing system if necessary.
See gdk_display_get_event()
.
Returns : |
the next GdkEvent to be processed, or NULL if no events
are pending. The returned GdkEvent should be freed with gdk_event_free() . |
void gdk_event_put (const GdkEvent *event
);
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 NULL
. See gdk_display_put_event()
.
|
a GdkEvent. |
GdkEvent * gdk_event_new (GdkEventType type
);
Creates a new event of the given type. All fields are set to 0.
|
a GdkEventType |
Returns : |
a newly-allocated GdkEvent. The returned GdkEvent
should be freed with gdk_event_free() . |
Since 2.2
GdkEvent * gdk_event_copy (const GdkEvent *event
);
Copies a GdkEvent, copying or incrementing the reference count of the resources associated with it (e.g. GdkWindow's and strings).
|
a GdkEvent |
Returns : |
a copy of event . The returned GdkEvent should be freed with
gdk_event_free() . |
void gdk_event_free (GdkEvent *event
);
Frees a GdkEvent, 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()
.
|
a GdkEvent. |
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.
gboolean gdk_event_get_button (const GdkEvent *event
,guint *button
);
Extract the button number from an event.
|
a GdkEvent |
|
location to store mouse button number. [out] |
Returns : |
TRUE if the event delivered a button number |
Since 3.2
gboolean gdk_event_get_click_count (const GdkEvent *event
,guint *click_count
);
Extracts the click count from an event.
|
a GdkEvent |
|
location to store click count. [out] |
Returns : |
TRUE if the event delivered a click count |
Since 3.2
gboolean gdk_event_get_coords (const GdkEvent *event
,gdouble *x_win
,gdouble *y_win
);
Extract the event window relative x/y coordinates from an event.
gboolean gdk_event_get_keycode (const GdkEvent *event
,guint16 *keycode
);
Extracts the hardware keycode from an event.
|
a GdkEvent |
|
location to store the keycode. [out] |
Returns : |
TRUE if the event delivered a hardware keycode |
Since 3.2
gboolean gdk_event_get_keyval (const GdkEvent *event
,guint *keyval
);
Extracts the keyval from an event.
|
a GdkEvent |
|
location to store the keyval. [out] |
Returns : |
TRUE if the event delivered a key symbol |
Since 3.2
gboolean gdk_event_get_root_coords (const GdkEvent *event
,gdouble *x_root
,gdouble *y_root
);
Extract the root window relative x/y coordinates from an event.
gboolean gdk_event_get_scroll_direction (const GdkEvent *event
,GdkScrollDirection *direction
);
Extracts the scroll direction from an event.
|
a GdkEvent |
|
location to store the scroll direction. [out] |
Returns : |
TRUE if the event delivered a scroll direction |
Since 3.2
gboolean gdk_event_get_scroll_deltas (const GdkEvent *event
,gdouble *delta_x
,gdouble *delta_y
);
Retrieves the scroll deltas from a GdkEvent
|
a GdkEvent |
|
return location for X delta. [out] |
|
return location for Y delta. [out] |
Returns : |
TRUE if the event contains smooth scroll information |
Since 3.4
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). Returns TRUE
if there was a state field
in the event. event
may be NULL
, in which case it's treated
as if the event had no state field.
guint32 gdk_event_get_time (const GdkEvent *event
);
returns GDK_CURRENT_TIME. If event
is NULL
, returns GDK_CURRENT_TIME.
|
a GdkEvent |
Returns : |
time stamp field from event
|
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
.
|
a GdkEvent |
Returns : |
the event sequence that the event belongs to |
Since 3.4
void gdk_event_request_motions (const GdkEventMotion *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_MOTION_NOTIFY
event usually works like this:
1 2 3 4 5 6 7 |
{ /* 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 */ } |
|
a valid GdkEvent |
Since 2.12
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.
|
first GdkEvent |
|
second GdkEvent |
|
return location for the relative angle between both events. [out] |
Returns : |
TRUE if the angle could be calculated. |
Since 3.0
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
.
|
first GdkEvent |
|
second GdkEvent |
|
return location for the X coordinate of the center. [out] |
|
return location for the Y coordinate of the center. [out] |
Returns : |
TRUE if the center could be calculated. |
Since 3.0
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.
|
first GdkEvent |
|
second GdkEvent |
|
return location for the distance. [out] |
Returns : |
TRUE if the distance could be calculated. |
Since 3.0
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
.
|
a GdkEvent, currently only button events are meaningful values |
Returns : |
TRUE if the event should trigger a context menu. |
Since 3.4
void gdk_event_handler_set (GdkEventFunc func
,gpointer data
,GDestroyNotify notify
);
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+.)
|
the function to call to handle events from GDK. |
|
user data to pass to the function. |
|
the function to call when the handler function is removed, i.e. when
gdk_event_handler_set() is called with another event handler. |
void (*GdkEventFunc) (GdkEvent *event
,gpointer data
);
Specifies the type of function passed to gdk_event_handler_set()
to
handle all GDK events.
|
the GdkEvent to process. |
|
user data set when the event handler was installed with
gdk_event_handler_set() . [closure]
|
gboolean gdk_get_show_events (void
);
Gets whether event debugging output is enabled.
Returns : |
TRUE if event debugging output is enabled. |
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.
|
TRUE to output event debugging information. |
void gdk_event_set_screen (GdkEvent *event
,GdkScreen *screen
);
Sets the screen for event
to screen
. The event must
have been allocated by GTK+, for instance, by
gdk_event_copy()
.
Since 2.2
GdkScreen * gdk_event_get_screen (const GdkEvent *event
);
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.
|
a GdkEvent |
Returns : |
the screen for the event. [transfer none] |
Since 2.2
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
.
Since 3.0
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()
.
Since 3.0
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 GdkWindow updates its
geometry or a grab is acquired/released.
If the event does not contain a device field, this function will
return NULL
.
Since 3.0
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()
.
Since 3.0
gboolean gdk_setting_get (const gchar *name
,GValue *value
);
Obtains a desktop-wide setting, such as the double-click time,
for the default screen. See gdk_screen_get_setting()
.