Events

Events — Functions for handling events from the window system

Synopsis


#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);

Description

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.

Details

enum GdkEventType

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_PRESS event.
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_PRESS event.
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_CHILD windows.
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.

enum GdkEventMask

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.

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

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 window updates is given in the GLib Main Loop.


gdk_events_pending ()

gboolean    gdk_events_pending              (void);

Checks if any events are ready to be processed for any display.

Returns : TRUE if any events are pending.

gdk_event_peek ()

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().

gdk_event_get ()

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().

gdk_event_get_graphics_expose ()

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 NULL if a NoExpose event was received.

gdk_event_put ()

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.

gdk_event_new ()

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


gdk_event_copy ()

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 with gdk_event_free().

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_get_graphics_expose() and gdk_event_copy().

event : a GdkEvent.

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. If event is NULL, returns GDK_CURRENT_TIME.

event : a GdkEvent
Returns : time stamp field from event

gdk_event_get_state ()

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 : TRUE if there was a state field in the event

gdk_event_get_axis ()

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 : TRUE if the specified axis was found, otherwise FALSE

gdk_event_get_coords ()

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 : TRUE if the event delivered event window coordinates

gdk_event_get_root_coords ()

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 : TRUE if the event delivered root window coordinates

gdk_event_handler_set ()

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.

GdkEventFunc ()

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().

gdk_event_send_client_message ()

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.

gdk_event_send_client_message_for_display ()

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


gdk_event_send_clientmessage_toall ()

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.

gdk_add_client_message_filter ()

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_type field of the XClientMessage event struct.
func : the function to call to process the event.
data : user data to pass to func.

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.

show_events : TRUE to output event debugging information.

gdk_event_set_screen ()

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().

event : a GdkEvent
screen : a GdkScreen

Since 2.2


gdk_event_get_screen ()

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


gdk_setting_get ()

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 : : TRUE if the setting existed and a value was stored in value, FALSE otherwise.

See Also

Event Structures

The structs used for each type of event.