Events: GDK 2 Reference Manual

## Events Events |

## Functions

gboolean | gdk_events_pending ()
GdkEvent * | gdk_event_peek ()
GdkEvent * | gdk_event_get ()
GdkEvent * | gdk_event_get_graphics_expose ()
void | gdk_event_put ()
GdkEvent * | gdk_event_new ()
GdkEvent * | gdk_event_copy ()
void | gdk_event_free ()
guint32 | gdk_event_get_time ()
gboolean | gdk_event_get_state ()
gboolean | gdk_event_get_axis ()
gboolean | gdk_event_get_coords ()
gboolean | gdk_event_get_root_coords ()
void | gdk_event_request_motions ()
void | gdk_event_handler_set ()
void | (*GdkEventFunc) ()
gboolean | gdk_event_send_client_message ()
gboolean | gdk_event_send_client_message_for_display ()
void | gdk_event_send_clientmessage_toall ()
void | gdk_add_client_message_filter ()
gboolean | gdk_get_show_events ()
void | gdk_set_show_events ()
void | gdk_event_set_screen ()
GdkScreen * | gdk_event_get_screen ()
gboolean | gdk_setting_get ()

## Types and Values

enum | GdkEventType
enum | GdkEventMask
#define | GDK_CURRENT_TIME
#define | GDK_PRIORITY_EVENTS
#define | GDK_PRIORITY_REDRAW

## Includes

    #include <gdk/gdk.h>

## Description

## Functions

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

`gdk_event_get_graphics_expose` has been deprecated since version 2.18 and should not be used in newly-written code.

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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 (const GdkEvent *event);

Copies a GdkEvent, copying or incrementing the reference count of the resources associated with it (e.g. GdkWindow's and strings).

#### Parameters

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()` and `gdk_event_new()`.

#### Parameters

event | a GdkEvent. |

### gdk_event_get_time ()

    guint32
    gdk_event_get_time (const 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.

#### Parameters

event | a GdkEvent |

#### Returns

time stamp field from `event`

### gdk_event_get_state ()

    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.

#### Parameters

event | a GdkEvent or NULL |
state | return location for state. | [out]

#### Returns

`TRUE` if there was a state field in the event

### gdk_event_get_axis ()

    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.

#### Parameters

event | a GdkEvent |
axis_use | the axis use to look for |
value | location to store the value found. | [out]

#### Returns

`TRUE` if the specified axis was found, otherwise `FALSE`

### gdk_event_get_coords ()

    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.

#### Parameters

event | a GdkEvent |
x_win | location to put event window x coordinate. | [out]
y_win | location to put event window y coordinate. | [out]

#### Returns

`TRUE` if the event delivered event window coordinates

### gdk_event_get_root_coords ()

    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.

#### Parameters

event | a GdkEvent |
x_root | location to put root window x coordinate. | [out]
y_root | location to put root window y coordinate. | [out]

#### Returns

`TRUE` if the event delivered root window coordinates

### gdk_event_request_motions ()

    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 */
    }

#### Parameters

event | a valid GdkEvent |

Since: 2.12

### 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+.)

#### Parameters

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

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

event | a GdkEvent |
screen | a GdkScreen |

Since: 2.2

### gdk_event_get_screen ()

    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.

#### Parameters

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

#### Parameters

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.

## Types and Values

### enum GdkEventType

#### Members

GDK_NOTHING |  |
GDK_DELETE |  |
GDK_DESTROY |  |
GDK_EXPOSE |  |
GDK_MOTION_NOTIFY |  |
GDK_BUTTON_PRESS |  |
GDK_2BUTTON_PRESS |  |
GDK_3BUTTON_PRESS |  |
GDK_BUTTON_RELEASE |  |
GDK_KEY_PRESS |  |
GDK_KEY_RELEASE |  |
GDK_ENTER_NOTIFY |  |
GDK_LEAVE_NOTIFY |  |
GDK_FOCUS_CHANGE |  |
GDK_CONFIGURE |  |
GDK_MAP |  |
GDK_UNMAP |  |
GDK_PROPERTY_NOTIFY |  |
GDK_SELECTION_CLEAR |  |
GDK_SELECTION_REQUEST |  |
GDK_SELECTION_NOTIFY |  |
GDK_PROXIMITY_IN |  |
GDK_PROXIMITY_OUT |  |
GDK_DRAG_ENTER |  |
GDK_DRAG_LEAVE |  |
GDK_DRAG_MOTION |  |
GDK_DRAG_STATUS |  |
GDK_DROP_START |  |
GDK_DROP_FINISHED |  |
GDK_CLIENT_EVENT |  |
GDK_VISIBILITY_NOTIFY |  |
GDK_NO_EXPOSE |  |
GDK_SCROLL |  |
GDK_WINDOW_STATE |  |
GDK_SETTING |  |
GDK_OWNER_CHANGE |  |
GDK_GRAB_BROKEN |  |
GDK_DAMAGE |  |
GDK_EVENT_LAST |  |

### enum GdkEventMask

#### Members

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_SCROLL_MASK |  |
GDK_ALL_EVENTS_MASK |  |

### GDK_CURRENT_TIME

    #define GDK_CURRENT_TIME     0L

### GDK_PRIORITY_EVENTS

    #define             GDK_PRIORITY_EVENTS

### GDK_PRIORITY_REDRAW

    #define GDK_PRIORITY_REDRAW     (G_PRIORITY_HIGH_IDLE + 20)