GDK Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# Events

## Name

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

    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_copy                  (GdkEvent *event);
    void        gdk_event_free                  (GdkEvent *event);
    guint32     gdk_event_get_time              (GdkEvent *event);

    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,
                                                 guint32 xid);
    void        gdk_event_send_clientmessage_toall
                                                (GdkEvent *event);
    void        gdk_add_client_message_filter   (GdkAtom message_type,
                                                 GdkFilterFunc func,
                                                 gpointer data);

    gint        gdk_get_show_events             (void);
    void        gdk_set_show_events             (gint show_events);

## 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
    } 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.

### 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_ALL_EVENTS_MASK		= 0x0FFFFF
    } 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 `GDK_MOTION_NOTIFY` events when the application asks for them, by calling gdk_window_get_pointer().

`GDK_EXPOSURE_MASK` |
`GDK_POINTER_MOTION_MASK` |
`GDK_POINTER_MOTION_HINT_MASK` |
`GDK_BUTTON_MOTION_MASK` |
`GDK_BUTTON1_MOTION_MASK` |
`GDK_BUTTON2_MOTION_MASK` |
`GDK_BUTTON3_MOTION_MASK` |
`GDK_BUTTON_PRESS_MASK` |
`GDK_BUTTON_RELEASE_MASK` |
`GDK_KEY_PRESS_MASK` |
`GDK_KEY_RELEASE_MASK` |
`GDK_ENTER_NOTIFY_MASK` |
`GDK_LEAVE_NOTIFY_MASK` |
`GDK_FOCUS_CHANGE_MASK` |
`GDK_STRUCTURE_MASK` |
`GDK_PROPERTY_CHANGE_MASK` |
`GDK_VISIBILITY_NOTIFY_MASK` |
`GDK_PROXIMITY_IN_MASK` |
`GDK_PROXIMITY_OUT_MASK` |
`GDK_SUBSTRUCTURE_MASK` |
`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		(G_PRIORITY_DEFAULT)

This is the priority that events from the X server are given in the GLib Main Loop.

### gdk_events_pending ()

    gboolean    gdk_events_pending              (void);

Checks if any events are waiting to be processed.

Returns : | TRUE if any events are pending.

### gdk_event_peek ()

    GdkEvent*   gdk_event_peek                  (void);

Gets a copy of the first GdkEvent in the event queue. (Note that this function will not get more events from the X server. It only checks the events that have already been moved to the GDK event queue.)

Returns : | a copy of the first GdkEvent on the event queue, or NULL if no events are in the queue. The returned GdkEvent should be freed with gdk_event_free().

### gdk_event_get ()

    GdkEvent*   gdk_event_get                   (void);

Gets the next GdkEvent to be processed, fetching events from the X server if necessary.

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.

`event` : | a GdkEvent.

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

Gets the timestamp from a GdkEvent.

`event` : | a GdkEvent.
Returns : | the timestamp from `event`, or GDK_CURRENT_TIME if the event has no timestamp.

### 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 probably not useful for GTK+ applications.

`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,
                                                 guint32 xid);

Sends an X ClientMessage event to a given window.

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.
`xid` : | the window to send the X ClientMessage event to.
Returns : | non-zero on success.

### gdk_event_send_clientmessage_toall ()

    void        gdk_event_send_clientmessage_toall
                                                (GdkEvent *event);

Sends an X ClientMessage event to all toplevel windows.

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 be called when X ClientMessage events are received.

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

    gint        gdk_get_show_events             (void);

Returns non-zero if event debugging output is enabled.

Returns : | non-zero if event debugging output is enabled.

### gdk_set_show_events ()

    void        gdk_set_show_events             (gint show_events);

Sets whether event debugging information is output. Note that GTK+ must be compiled with debugging enabled, i.e. using the '--enable-debug' configure option.

`show_events` : | TRUE to output event debugging information.

## See Also

Event Structures

  The structs used for each type of event.

<<< Previous Page | Home | Up | Next Page >>>
Windows | Event Structures