|  |  |  | GDK Reference Manual |  | 
|---|
| EventsEvents — Functions for handling events from the window system | 
#include <gdk/gdk.h> enum GdkEventType; enum GdkEventMask; #define GDK_CURRENT_TIME #define GDK_PRIORITY_EVENTS #define GDK_PRIORITY_REDRAW gboolean gdk_events_pending (void); GdkEvent* gdk_event_peek (void); GdkEvent* gdk_event_get (void); GdkEvent* gdk_event_get_graphics_expose (GdkWindow *window); void gdk_event_put (GdkEvent *event); GdkEvent* gdk_event_new (GdkEventType type); GdkEvent* gdk_event_copy (GdkEvent *event); void gdk_event_free (GdkEvent *event); guint32 gdk_event_get_time (GdkEvent *event); gboolean gdk_event_get_state (GdkEvent *event, GdkModifierType *state); gboolean gdk_event_get_axis (GdkEvent *event, GdkAxisUse axis_use, gdouble *value); gboolean gdk_event_get_coords (GdkEvent *event, gdouble *x_win, gdouble *y_win); gboolean gdk_event_get_root_coords (GdkEvent *event, gdouble *x_root, gdouble *y_root); void gdk_event_handler_set (GdkEventFunc func, gpointer data, GDestroyNotify notify); void (*GdkEventFunc) (GdkEvent *event, gpointer data); gboolean gdk_event_send_client_message (GdkEvent *event, GdkNativeWindow winid); gboolean gdk_event_send_client_message_for_display (GdkDisplay *display, GdkEvent *event, GdkNativeWindow winid); void gdk_event_send_clientmessage_toall (GdkEvent *event); void gdk_add_client_message_filter (GdkAtom message_type, GdkFilterFunc func, 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 (GdkEvent *event); 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_NO_EXPOSE		= 30,
  GDK_SCROLL            = 31,
  GDK_WINDOW_STATE      = 32,
  GDK_SETTING           = 33,
  GDK_OWNER_CHANGE      = 34,
  GDK_GRAB_BROKEN       = 35
} 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.
| GDK_NOTHING | a special code to indicate a null event. | 
| GDK_DELETE | 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. | 
| GDK_DESTROY | the window has been destroyed. | 
| GDK_EXPOSE | all or part of the window has become visible and needs to be redrawn. | 
| GDK_MOTION_NOTIFY | the pointer (usually a mouse) has moved. | 
| GDK_BUTTON_PRESS | a mouse button has been pressed. | 
| GDK_2BUTTON_PRESS | a mouse button has been double-clicked (clicked twice
within a short period of time). Note that each click also generates a GDK_BUTTON_PRESSevent. | 
| GDK_3BUTTON_PRESS | a mouse button has been clicked 3 times in a short period
of time. Note that each click also generates a GDK_BUTTON_PRESSevent. | 
| GDK_BUTTON_RELEASE | a mouse button has been released. | 
| GDK_KEY_PRESS | a key has been pressed. | 
| GDK_KEY_RELEASE | a key has been released. | 
| GDK_ENTER_NOTIFY | the pointer has entered the window. | 
| GDK_LEAVE_NOTIFY | the pointer has left the window. | 
| GDK_FOCUS_CHANGE | the keyboard focus has entered or left the window. | 
| GDK_CONFIGURE | the size, position or stacking order of the window has changed.
Note that GTK+ discards these events for GDK_WINDOW_CHILDwindows. | 
| GDK_MAP | the window has been mapped. | 
| GDK_UNMAP | the window has been unmapped. | 
| GDK_PROPERTY_NOTIFY | a property on the window has been changed or deleted. | 
| GDK_SELECTION_CLEAR | the application has lost ownership of a selection. | 
| GDK_SELECTION_REQUEST | another application has requested a selection. | 
| GDK_SELECTION_NOTIFY | a selection has been received. | 
| GDK_PROXIMITY_IN | an input device has moved into contact with a sensing surface (e.g. a touchscreen or graphics tablet). | 
| GDK_PROXIMITY_OUT | an input device has moved out of contact with a sensing surface. | 
| GDK_DRAG_ENTER | the mouse has entered the window while a drag is in progress. | 
| GDK_DRAG_LEAVE | the mouse has left the window while a drag is in progress. | 
| GDK_DRAG_MOTION | the mouse has moved in the window while a drag is in progress. | 
| GDK_DRAG_STATUS | the status of the drag operation initiated by the window has changed. | 
| GDK_DROP_START | a drop operation onto the window has started. | 
| GDK_DROP_FINISHED | the drop operation initiated by the window has completed. | 
| GDK_CLIENT_EVENT | a message has been received from another application. | 
| GDK_VISIBILITY_NOTIFY | the window visibility status has changed. | 
| GDK_NO_EXPOSE | indicates that the source region was completely available when parts of a drawable were copied. This is not very useful. | 
| GDK_SCROLL | the scroll wheel was turned | 
| GDK_WINDOW_STATE | the state of a window has changed. See GdkWindowState for the possible window states | 
| GDK_SETTING | a setting has been modified. | 
| GDK_OWNER_CHANGE | the owner of a selection has changed. This event type was added in 2.6 | 
| GDK_GRAB_BROKEN | a pointer or keyboard grab was broken. This event type was added in 2.8. | 
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_ALL_EVENTS_MASK		= 0x3FFFFE
} 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 easily lag behind the position of the mouse. When using the
GDK_POINTER_MOTION_HINT_MASK the server will only send a single 
GDK_MOTION_NOTIFY event (which is marked as a hint) until the application 
asks for more, by calling gdk_window_get_pointer().
| GDK_EXPOSURE_MASK | receive expose events | 
| GDK_POINTER_MOTION_MASK | receive all pointer motion events | 
| GDK_POINTER_MOTION_HINT_MASK | see the explanation above | 
| GDK_BUTTON_MOTION_MASK | receive pointer motion events while any button is pressed | 
| GDK_BUTTON1_MOTION_MASK | receive pointer motion events while 1 button is pressed | 
| GDK_BUTTON2_MOTION_MASK | receive pointer motion events while 2 button is pressed | 
| GDK_BUTTON3_MOTION_MASK | receive pointer motion events while 3 button is pressed | 
| GDK_BUTTON_PRESS_MASK | receive button press events | 
| GDK_BUTTON_RELEASE_MASK | receive button release events | 
| GDK_KEY_PRESS_MASK | receive key press events | 
| GDK_KEY_RELEASE_MASK | receive key release events | 
| GDK_ENTER_NOTIFY_MASK | receive window enter events | 
| GDK_LEAVE_NOTIFY_MASK | receive window leave events | 
| GDK_FOCUS_CHANGE_MASK | receive focus change events | 
| GDK_STRUCTURE_MASK | receive events about window configuration change | 
| GDK_PROPERTY_CHANGE_MASK | receive property change events | 
| GDK_VISIBILITY_NOTIFY_MASK | receive visibility change events | 
| GDK_PROXIMITY_IN_MASK | receive proximity in events | 
| GDK_PROXIMITY_OUT_MASK | receive proximity out events | 
| GDK_SUBSTRUCTURE_MASK | receive events about window configuration changes of child windows | 
| GDK_SCROLL_MASK | receive scroll events | 
| GDK_ALL_EVENTS_MASK | 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.
gboolean gdk_events_pending (void);
Checks if any events are ready to be processed for any display.
| Returns : | TRUEif 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 NULLif no
events are in any queues. The returned GdkEvent should be freed withgdk_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 NULLif no events
are pending. The returned GdkEvent should be freed withgdk_event_free(). | 
GdkEvent* gdk_event_get_graphics_expose (GdkWindow *window);
Waits for a GraphicsExpose or NoExpose event from the X server. This is used in the GtkText and GtkCList widgets in GTK+ to make sure any GraphicsExpose events are handled before the widget is scrolled.
| window: | the GdkWindow to wait for the events for. | 
| Returns : | a GdkEventExpose if a GraphicsExpose was received, or NULLif a
NoExpose event was received. | 
void gdk_event_put (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().
| event: | a GdkEvent. | 
GdkEvent* gdk_event_new (GdkEventType type);
Creates a new event of the given type. All fields are set to 0.
| type: | a GdkEventType | 
| Returns : | a newly-allocated GdkEvent. The returned GdkEvent 
should be freed with gdk_event_free(). | 
Since 2.2
GdkEvent* gdk_event_copy (GdkEvent *event);
Copies a GdkEvent, copying or incrementing the reference count of the resources associated with it (e.g. GdkWindow's and strings).
| event: | a GdkEvent | 
| Returns : | a copy of event. The returned GdkEvent should be freed withgdk_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_get_graphics_expose() and gdk_event_copy().
| event: | a GdkEvent. | 
guint32 gdk_event_get_time (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.
| event: | a GdkEvent | 
| Returns : | time stamp field from event | 
gboolean gdk_event_get_state (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.
| event: | a GdkEvent or NULL | 
| state: | return location for state | 
| Returns : | TRUEif there was a state field in the event | 
gboolean gdk_event_get_axis (GdkEvent *event, GdkAxisUse axis_use, gdouble *value);
Extract the axis value for a particular axis use from an event structure.
| event: | a GdkEvent | 
| axis_use: | the axis use to look for | 
| value: | location to store the value found | 
| Returns : | TRUEif the specified axis was found, otherwiseFALSE | 
gboolean gdk_event_get_coords (GdkEvent *event, gdouble *x_win, gdouble *y_win);
Extract the event window relative x/y coordinates from an event.
| event: | a GdkEvent | 
| x_win: | location to put event window x coordinate | 
| y_win: | location to put event window y coordinate | 
| Returns : | TRUEif the event delivered event window coordinates | 
gboolean gdk_event_get_root_coords (GdkEvent *event, gdouble *x_root, gdouble *y_root);
Extract the root window relative x/y coordinates from an event.
| event: | a GdkEvent | 
| x_root: | location to put root window x coordinate | 
| y_root: | location to put root window y coordinate | 
| Returns : | TRUEif the event delivered root window coordinates | 
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+.)
| func: | the function to call to handle events from GDK. | 
| data: | user data to pass to the function. | 
| notify: | 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.
| event: | the GdkEvent to process. | 
| data: | user data set when the event handler was installed with gdk_event_handler_set(). | 
gboolean gdk_event_send_client_message (GdkEvent *event, GdkNativeWindow winid);
Sends an X ClientMessage event to a given window (which must be on the default GdkDisplay.) This could be used for communicating between different applications, though the amount of data is limited to 20 bytes.
| event: | the GdkEvent to send, which should be a GdkEventClient. | 
| winid: | the window to send the X ClientMessage event to. | 
| Returns : | non-zero on success. | 
gboolean gdk_event_send_client_message_for_display (GdkDisplay *display, GdkEvent *event, GdkNativeWindow winid);
On X11, sends an X ClientMessage event to a given window. On Windows, sends a message registered with the name GDK_WIN32_CLIENT_MESSAGE.
This could be used for communicating between different applications, though the amount of data is limited to 20 bytes on X11, and to just four bytes on Windows.
| display: | the GdkDisplay for the window where the message is to be sent. | 
| event: | the GdkEvent to send, which should be a GdkEventClient. | 
| winid: | the window to send the client message to. | 
| Returns : | non-zero on success. | 
Since 2.2
void        gdk_event_send_clientmessage_toall
                                            (GdkEvent *event);
Sends an X ClientMessage event to all toplevel windows on the default GdkScreen.
Toplevel windows are determined by checking for the WM_STATE property, as described in the Inter-Client Communication Conventions Manual (ICCCM). If no windows are found with the WM_STATE property set, the message is sent to all children of the root window.
| event: | the GdkEvent to send, which should be a GdkEventClient. | 
void gdk_add_client_message_filter (GdkAtom message_type, GdkFilterFunc func, gpointer data);
Adds a filter to the default display to be called when X ClientMessage events
are received. See gdk_display_add_client_message_filter().
| message_type: | the type of ClientMessage events to receive. This will be
    checked against the message_typefield of the
    XClientMessage event struct. | 
| func: | the function to call to process the event. | 
| data: | user data to pass to func. | 
gboolean gdk_get_show_events (void);
Gets whether event debugging output is enabled.
| Returns : | TRUEif 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.
| show_events: | TRUEto 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 (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.
| event: | a GdkEvent | 
| Returns : | the screen for the event | 
Since 2.2
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().
| name: | the name of the setting. | 
| value: | location to store the value of the setting. | 
| Returns : | : TRUEif the setting existed and a value was stored
  invalue,FALSEotherwise. | 
| << Windows | Event Structures >> |