<refentry id="gdk-Events">
<refmeta>
<refentrytitle>Events</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Events</refname><refpurpose>functions for handling events from the window system.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gdk/gdk.h&gt;


enum        <link linkend="GdkEventType">GdkEventType</link>;
enum        <link linkend="GdkEventMask">GdkEventMask</link>;
#define     <link linkend="GDK-CURRENT-TIME-CAPS">GDK_CURRENT_TIME</link>
#define     <link linkend="GDK-PRIORITY-EVENTS-CAPS">GDK_PRIORITY_EVENTS</link>
#define     <link linkend="GDK-PRIORITY-REDRAW-CAPS">GDK_PRIORITY_REDRAW</link>

<link linkend="gboolean">gboolean</link>    <link linkend="gdk-events-pending">gdk_events_pending</link>              (void);
<link linkend="GdkEvent">GdkEvent</link>*   <link linkend="gdk-event-peek">gdk_event_peek</link>                  (void);
<link linkend="GdkEvent">GdkEvent</link>*   <link linkend="gdk-event-get">gdk_event_get</link>                   (void);
<link linkend="GdkEvent">GdkEvent</link>*   <link linkend="gdk-event-get-graphics-expose">gdk_event_get_graphics_expose</link>   (<link linkend="GdkWindow">GdkWindow</link> *window);
void        <link linkend="gdk-event-put">gdk_event_put</link>                   (<link linkend="GdkEvent">GdkEvent</link> *event);
<link linkend="GdkEvent">GdkEvent</link>*   <link linkend="gdk-event-copy">gdk_event_copy</link>                  (<link linkend="GdkEvent">GdkEvent</link> *event);
void        <link linkend="gdk-event-free">gdk_event_free</link>                  (<link linkend="GdkEvent">GdkEvent</link> *event);
<link linkend="guint32">guint32</link>     <link linkend="gdk-event-get-time">gdk_event_get_time</link>              (<link linkend="GdkEvent">GdkEvent</link> *event);
<link linkend="gboolean">gboolean</link>    <link linkend="gdk-event-get-state">gdk_event_get_state</link>             (<link linkend="GdkEvent">GdkEvent</link> *event,
                                             <link linkend="GdkModifierType">GdkModifierType</link> *state);
<link linkend="gboolean">gboolean</link>    <link linkend="gdk-event-get-axis">gdk_event_get_axis</link>              (<link linkend="GdkEvent">GdkEvent</link> *event,
                                             <link linkend="GdkAxisUse">GdkAxisUse</link> axis_use,
                                             <link linkend="gdouble">gdouble</link> *value);
<link linkend="gboolean">gboolean</link>    <link linkend="gdk-event-get-coords">gdk_event_get_coords</link>            (<link linkend="GdkEvent">GdkEvent</link> *event,
                                             <link linkend="gdouble">gdouble</link> *x_win,
                                             <link linkend="gdouble">gdouble</link> *y_win);
<link linkend="gboolean">gboolean</link>    <link linkend="gdk-event-get-root-coords">gdk_event_get_root_coords</link>       (<link linkend="GdkEvent">GdkEvent</link> *event,
                                             <link linkend="gdouble">gdouble</link> *x_root,
                                             <link linkend="gdouble">gdouble</link> *y_root);

void        <link linkend="gdk-event-handler-set">gdk_event_handler_set</link>           (<link linkend="GdkEventFunc">GdkEventFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> notify);
void        (<link linkend="GdkEventFunc">*GdkEventFunc</link>)                 (<link linkend="GdkEvent">GdkEvent</link> *event,
                                             <link linkend="gpointer">gpointer</link> data);

<link linkend="gboolean">gboolean</link>    <link linkend="gdk-event-send-client-message">gdk_event_send_client_message</link>   (<link linkend="GdkEvent">GdkEvent</link> *event,
                                             <link linkend="guint32">guint32</link> xid);
void        <link linkend="gdk-event-send-clientmessage-toall">gdk_event_send_clientmessage_toall</link>
                                            (<link linkend="GdkEvent">GdkEvent</link> *event);
void        <link linkend="gdk-add-client-message-filter">gdk_add_client_message_filter</link>   (<link linkend="GdkAtom">GdkAtom</link> message_type,
                                             <link linkend="GdkFilterFunc">GdkFilterFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> data);

<link linkend="gboolean">gboolean</link>    <link linkend="gdk-get-show-events">gdk_get_show_events</link>             (void);
void        <link linkend="gdk-set-show-events">gdk_set_show_events</link>             (<link linkend="gboolean">gboolean</link> show_events);

<link linkend="gboolean">gboolean</link>    <link linkend="gdk-setting-get">gdk_setting_get</link>                 (const <link linkend="gchar">gchar</link> *name,
                                             <link linkend="GValue">GValue</link> *value);

</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
This section describes functions dealing with events from the window system.
</para>
<para>
In GTK+ applications the events are handled automatically in
<link linkend="gtk-main-do-event">gtk_main_do_event</link>() and passed on to the appropriate widgets, so these
functions are rarely needed. Though some of the fields in the
<link linkend="gdk-Event-Structures">Event Structures</link> are useful.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GdkEventType">enum GdkEventType</title>
<programlisting>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
} GdkEventType;
</programlisting>
<para>
Specifies the type of the event.
</para>
<para>
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.
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>GDK_NOTHING</literal></entry>
<entry>a special code to indicate a null event.
</entry>
</row>
<row>
<entry><literal>GDK_DELETE</literal></entry>
<entry>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.
</entry>
</row>
<row>
<entry><literal>GDK_DESTROY</literal></entry>
<entry>the window has been destroyed.
</entry>
</row>
<row>
<entry><literal>GDK_EXPOSE</literal></entry>
<entry>all or part of the window has become visible and needs to be
redrawn.
</entry>
</row>
<row>
<entry><literal>GDK_MOTION_NOTIFY</literal></entry>
<entry>the pointer (usually a mouse) has moved.
</entry>
</row>
<row>
<entry><literal>GDK_BUTTON_PRESS</literal></entry>
<entry>a mouse button has been pressed.
</entry>
</row>
<row>
<entry><literal>GDK_2BUTTON_PRESS</literal></entry>
<entry>a mouse button has been double-clicked (clicked twice
within a short period of time). Note that each click also generates a
<literal>GDK_BUTTON_PRESS</literal> event.
</entry>
</row>
<row>
<entry><literal>GDK_3BUTTON_PRESS</literal></entry>
<entry>a mouse button has been clicked 3 times in a short period
of time. Note that each click also generates a <literal>GDK_BUTTON_PRESS</literal> event.
</entry>
</row>
<row>
<entry><literal>GDK_BUTTON_RELEASE</literal></entry>
<entry>a mouse button has been released.
</entry>
</row>
<row>
<entry><literal>GDK_KEY_PRESS</literal></entry>
<entry>a key has been pressed.
</entry>
</row>
<row>
<entry><literal>GDK_KEY_RELEASE</literal></entry>
<entry>a key has been released.
</entry>
</row>
<row>
<entry><literal>GDK_ENTER_NOTIFY</literal></entry>
<entry>the pointer has entered the window.
</entry>
</row>
<row>
<entry><literal>GDK_LEAVE_NOTIFY</literal></entry>
<entry>the pointer has left the window.
</entry>
</row>
<row>
<entry><literal>GDK_FOCUS_CHANGE</literal></entry>
<entry>the keyboard focus has entered or left the window.
</entry>
</row>
<row>
<entry><literal>GDK_CONFIGURE</literal></entry>
<entry>the size, position or stacking order of the window has changed.
Note that GTK+ discards these events for <literal>GDK_WINDOW_CHILD</literal> windows.
</entry>
</row>
<row>
<entry><literal>GDK_MAP</literal></entry>
<entry>the window has been mapped.
</entry>
</row>
<row>
<entry><literal>GDK_UNMAP</literal></entry>
<entry>the window has been unmapped.
</entry>
</row>
<row>
<entry><literal>GDK_PROPERTY_NOTIFY</literal></entry>
<entry>a property on the window has been changed or deleted.
</entry>
</row>
<row>
<entry><literal>GDK_SELECTION_CLEAR</literal></entry>
<entry>the application has lost ownership of a selection.
</entry>
</row>
<row>
<entry><literal>GDK_SELECTION_REQUEST</literal></entry>
<entry>another application has requested a selection.
</entry>
</row>
<row>
<entry><literal>GDK_SELECTION_NOTIFY</literal></entry>
<entry>a selection has been received.
</entry>
</row>
<row>
<entry><literal>GDK_PROXIMITY_IN</literal></entry>
<entry>an input device has moved into contact with a sensing
surface (e.g. a touchscreen or graphics tablet).
</entry>
</row>
<row>
<entry><literal>GDK_PROXIMITY_OUT</literal></entry>
<entry>an input device has moved out of contact with a sensing
surface.
</entry>
</row>
<row>
<entry><literal>GDK_DRAG_ENTER</literal></entry>
<entry>the mouse has entered the window while a drag is in progress.
</entry>
</row>
<row>
<entry><literal>GDK_DRAG_LEAVE</literal></entry>
<entry>the mouse has left the window while a drag is in progress.
</entry>
</row>
<row>
<entry><literal>GDK_DRAG_MOTION</literal></entry>
<entry>the mouse has moved in the window while a drag is in
progress.
</entry>
</row>
<row>
<entry><literal>GDK_DRAG_STATUS</literal></entry>
<entry>the status of the drag operation initiated by the window
has changed.
</entry>
</row>
<row>
<entry><literal>GDK_DROP_START</literal></entry>
<entry>a drop operation onto the window has started.
</entry>
</row>
<row>
<entry><literal>GDK_DROP_FINISHED</literal></entry>
<entry>the drop operation initiated by the window has completed.
</entry>
</row>
<row>
<entry><literal>GDK_CLIENT_EVENT</literal></entry>
<entry>a message has been received from another application.
</entry>
</row>
<row>
<entry><literal>GDK_VISIBILITY_NOTIFY</literal></entry>
<entry>the window visibility status has changed.
</entry>
</row>
<row>
<entry><literal>GDK_NO_EXPOSE</literal></entry>
<entry>indicates that the source region was completely available
when parts of a drawable were copied. This is not very useful.
</entry>
</row>
<row>
<entry><literal>GDK_SCROLL</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_WINDOW_STATE</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_SETTING</literal></entry>
<entry>

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GdkEventMask">enum GdkEventMask</title>
<programlisting>typedef enum
{
  GDK_EXPOSURE_MASK		= 1 &lt;&lt; 1,
  GDK_POINTER_MOTION_MASK	= 1 &lt;&lt; 2,
  GDK_POINTER_MOTION_HINT_MASK	= 1 &lt;&lt; 3,
  GDK_BUTTON_MOTION_MASK	= 1 &lt;&lt; 4,
  GDK_BUTTON1_MOTION_MASK	= 1 &lt;&lt; 5,
  GDK_BUTTON2_MOTION_MASK	= 1 &lt;&lt; 6,
  GDK_BUTTON3_MOTION_MASK	= 1 &lt;&lt; 7,
  GDK_BUTTON_PRESS_MASK		= 1 &lt;&lt; 8,
  GDK_BUTTON_RELEASE_MASK	= 1 &lt;&lt; 9,
  GDK_KEY_PRESS_MASK		= 1 &lt;&lt; 10,
  GDK_KEY_RELEASE_MASK		= 1 &lt;&lt; 11,
  GDK_ENTER_NOTIFY_MASK		= 1 &lt;&lt; 12,
  GDK_LEAVE_NOTIFY_MASK		= 1 &lt;&lt; 13,
  GDK_FOCUS_CHANGE_MASK		= 1 &lt;&lt; 14,
  GDK_STRUCTURE_MASK		= 1 &lt;&lt; 15,
  GDK_PROPERTY_CHANGE_MASK	= 1 &lt;&lt; 16,
  GDK_VISIBILITY_NOTIFY_MASK	= 1 &lt;&lt; 17,
  GDK_PROXIMITY_IN_MASK		= 1 &lt;&lt; 18,
  GDK_PROXIMITY_OUT_MASK	= 1 &lt;&lt; 19,
  GDK_SUBSTRUCTURE_MASK		= 1 &lt;&lt; 20,
  GDK_SCROLL_MASK               = 1 &lt;&lt; 21,
  GDK_ALL_EVENTS_MASK		= 0x3FFFFE
} GdkEventMask;
</programlisting>
<para>
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 <link linkend="GdkEventType">GdkEventType</link> event types
above.
</para>
<para>
<literal>GDK_POINTER_MOTION_HINT_MASK</literal> is a special mask which is used to reduce the
number of <literal>GDK_MOTION_NOTIFY</literal> events received. Normally a <literal>GDK_MOTION_NOTIFY</literal>
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
<literal>GDK_POINTER_MOTION_HINT_MASK</literal> the server will only send <literal>GDK_MOTION_NOTIFY</literal>
events when the application asks for them, by calling <link linkend="gdk-window-get-pointer">gdk_window_get_pointer</link>().
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>GDK_EXPOSURE_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_POINTER_MOTION_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_POINTER_MOTION_HINT_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_BUTTON_MOTION_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_BUTTON1_MOTION_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_BUTTON2_MOTION_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_BUTTON3_MOTION_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_BUTTON_PRESS_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_BUTTON_RELEASE_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_KEY_PRESS_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_KEY_RELEASE_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_ENTER_NOTIFY_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_LEAVE_NOTIFY_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_FOCUS_CHANGE_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_STRUCTURE_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_PROPERTY_CHANGE_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_VISIBILITY_NOTIFY_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_PROXIMITY_IN_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_PROXIMITY_OUT_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_SUBSTRUCTURE_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_SCROLL_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>GDK_ALL_EVENTS_MASK</literal></entry>
<entry>the combination of all the above event masks.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GDK-CURRENT-TIME-CAPS">GDK_CURRENT_TIME</title>
<programlisting>#define GDK_CURRENT_TIME     0L
</programlisting>
<para>
Represents the current time, and can be used anywhere a time is expected.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-PRIORITY-EVENTS-CAPS">GDK_PRIORITY_EVENTS</title>
<programlisting>#define     GDK_PRIORITY_EVENTS</programlisting>
<para>
This is the priority that events from the X server are given in the
<link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link>.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-PRIORITY-REDRAW-CAPS">GDK_PRIORITY_REDRAW</title>
<programlisting>#define GDK_PRIORITY_REDRAW     (G_PRIORITY_HIGH_IDLE + 20)
</programlisting>
<para>
This is the priority that the idle handler processing window updates
is given in the <link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link>.
</para></refsect2>
<refsect2>
<title><anchor id="gdk-events-pending">gdk_events_pending ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gdk_events_pending              (void);</programlisting>
<para>
Checks if any events are waiting to be processed.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if any events are pending.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-event-peek">gdk_event_peek ()</title>
<programlisting><link linkend="GdkEvent">GdkEvent</link>*   gdk_event_peek                  (void);</programlisting>
<para>
Gets a copy of the first <link linkend="GdkEvent">GdkEvent</link> 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.)
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a copy of the first <link linkend="GdkEvent">GdkEvent</link> on the event queue, or <literal>NULL</literal> if no
events are in the queue. The returned <link linkend="GdkEvent">GdkEvent</link> should be freed with
<link linkend="gdk-event-free">gdk_event_free</link>().


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-event-get">gdk_event_get ()</title>
<programlisting><link linkend="GdkEvent">GdkEvent</link>*   gdk_event_get                   (void);</programlisting>
<para>
Gets the next <link linkend="GdkEvent">GdkEvent</link> to be processed, fetching events from the X server if
necessary.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the next <link linkend="GdkEvent">GdkEvent</link> to be processed, or <literal>NULL</literal> if no events are pending.
The returned <link linkend="GdkEvent">GdkEvent</link> should be freed with <link linkend="gdk-event-free">gdk_event_free</link>().


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-event-get-graphics-expose">gdk_event_get_graphics_expose ()</title>
<programlisting><link linkend="GdkEvent">GdkEvent</link>*   gdk_event_get_graphics_expose   (<link linkend="GdkWindow">GdkWindow</link> *window);</programlisting>
<para>
Waits for a GraphicsExpose or NoExpose event from the X server.
This is used in the <link linkend="GtkText">GtkText</link> and <link linkend="GtkCList">GtkCList</link> widgets in GTK+ to make sure any
GraphicsExpose events are handled before the widget is scrolled.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>window</parameter>&nbsp;:</entry>
<entry>the <link linkend="GdkWindow">GdkWindow</link> to wait for the events for.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a <link linkend="GdkEventExpose">GdkEventExpose</link> if a GraphicsExpose was received, or <literal>NULL</literal> if a
NoExpose event was received.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-event-put">gdk_event_put ()</title>
<programlisting>void        gdk_event_put                   (<link linkend="GdkEvent">GdkEvent</link> *event);</programlisting>
<para>
Appends a copy of the given event onto the front of the event queue.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>event</parameter>&nbsp;:</entry>
<entry>a <link linkend="GdkEvent">GdkEvent</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-event-copy">gdk_event_copy ()</title>
<programlisting><link linkend="GdkEvent">GdkEvent</link>*   gdk_event_copy                  (<link linkend="GdkEvent">GdkEvent</link> *event);</programlisting>
<para>
Copies a <link linkend="GdkEvent">GdkEvent</link>, copying or incrementing the reference count of the
resources associated with it (e.g. <link linkend="GdkWindow">GdkWindow</link>'s and strings).
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>event</parameter>&nbsp;:</entry>
<entry>a <link linkend="GdkEvent">GdkEvent</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a copy of <parameter>event</parameter>. The returned <link linkend="GdkEvent">GdkEvent</link> should be freed with
<link linkend="gdk-event-free">gdk_event_free</link>().


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-event-free">gdk_event_free ()</title>
<programlisting>void        gdk_event_free                  (<link linkend="GdkEvent">GdkEvent</link> *event);</programlisting>
<para>
Frees a <link linkend="GdkEvent">GdkEvent</link>, freeing or decrementing any resources associated with it.
Note that this function should only be called with events returned from
<link linkend="gdk-event-peek">gdk_event_peek</link>(), <link linkend="gdk-event-get">gdk_event_get</link>(), <link linkend="gdk-event-get-graphics-expose">gdk_event_get_graphics_expose</link>() and
<link linkend="gdk-event-copy">gdk_event_copy</link>().
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>event</parameter>&nbsp;:</entry>
<entry>a <link linkend="GdkEvent">GdkEvent</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-event-get-time">gdk_event_get_time ()</title>
<programlisting><link linkend="guint32">guint32</link>     gdk_event_get_time              (<link linkend="GdkEvent">GdkEvent</link> *event);</programlisting>
<para>
Returns the time stamp from <parameter>event</parameter>, if there is one; otherwise
returns <link linkend="GDK-CURRENT-TIME-CAPS">GDK_CURRENT_TIME</link>. If <parameter>event</parameter> is <literal>NULL</literal>, returns <link linkend="GDK-CURRENT-TIME-CAPS">GDK_CURRENT_TIME</link>.</para>
<para>
Gets the timestamp from a <link linkend="GdkEvent">GdkEvent</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>event</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkEvent">GdkEvent</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> time stamp field from <parameter>event</parameter>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-event-get-state">gdk_event_get_state ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gdk_event_get_state             (<link linkend="GdkEvent">GdkEvent</link> *event,
                                             <link linkend="GdkModifierType">GdkModifierType</link> *state);</programlisting>
<para>
If the event contains a "state" field, puts that field in <parameter>state</parameter>. Otherwise
stores an empty state (0). Returns <literal>TRUE</literal> if there was a state field
in the event. <parameter>event</parameter> may be <literal>NULL</literal>, in which case it's treated
as if the event had no state field.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>event</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkEvent">GdkEvent</link> or NULL
</entry></row>
<row><entry align="right"><parameter>state</parameter>&nbsp;:</entry>
<entry> return location for state
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if there was a state field in the event 
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-event-get-axis">gdk_event_get_axis ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gdk_event_get_axis              (<link linkend="GdkEvent">GdkEvent</link> *event,
                                             <link linkend="GdkAxisUse">GdkAxisUse</link> axis_use,
                                             <link linkend="gdouble">gdouble</link> *value);</programlisting>
<para>
Extract the axis value for a particular axis use from
an event structure.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>event</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkEvent">GdkEvent</link>
</entry></row>
<row><entry align="right"><parameter>axis_use</parameter>&nbsp;:</entry>
<entry> the axis use to look for
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry> location to store the value found
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the specified axis was found, otherwise <literal>FALSE</literal>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-event-get-coords">gdk_event_get_coords ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gdk_event_get_coords            (<link linkend="GdkEvent">GdkEvent</link> *event,
                                             <link linkend="gdouble">gdouble</link> *x_win,
                                             <link linkend="gdouble">gdouble</link> *y_win);</programlisting>
<para>
Extract the event window relative x/y coordinates from an event.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>event</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkEvent">GdkEvent</link>
</entry></row>
<row><entry align="right"><parameter>x_win</parameter>&nbsp;:</entry>
<entry> location to put event window x coordinate
</entry></row>
<row><entry align="right"><parameter>y_win</parameter>&nbsp;:</entry>
<entry> location to put event window y coordinate
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the event delivered event window coordinates
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-event-get-root-coords">gdk_event_get_root_coords ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gdk_event_get_root_coords       (<link linkend="GdkEvent">GdkEvent</link> *event,
                                             <link linkend="gdouble">gdouble</link> *x_root,
                                             <link linkend="gdouble">gdouble</link> *y_root);</programlisting>
<para>
Extract the root window relative x/y coordinates from an event.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>event</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkEvent">GdkEvent</link>
</entry></row>
<row><entry align="right"><parameter>x_root</parameter>&nbsp;:</entry>
<entry> location to put root window x coordinate
</entry></row>
<row><entry align="right"><parameter>y_root</parameter>&nbsp;:</entry>
<entry> location to put root window y coordinate
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the event delivered root window coordinates
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-event-handler-set">gdk_event_handler_set ()</title>
<programlisting>void        gdk_event_handler_set           (<link linkend="GdkEventFunc">GdkEventFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> notify);</programlisting>
<para>
Sets the function to call to handle all events from GDK.
</para>
<para>
Note that GTK+ uses this to install its own event handler, so it is probably
not useful for GTK+ applications.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>func</parameter>&nbsp;:</entry>
<entry>the function to call to handle events from GDK.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>user data to pass to the function.
</entry></row>
<row><entry align="right"><parameter>notify</parameter>&nbsp;:</entry>
<entry>the function to call when the handler function is removed, i.e. when
<link linkend="gdk-event-handler-set">gdk_event_handler_set</link>() is called with another event handler.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GdkEventFunc">GdkEventFunc ()</title>
<programlisting>void        (*GdkEventFunc)                 (<link linkend="GdkEvent">GdkEvent</link> *event,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Specifies the type of function passed to <link linkend="gdk-event-handler-set">gdk_event_handler_set</link>() to handle
all GDK events.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>event</parameter>&nbsp;:</entry>
<entry>the <link linkend="GdkEvent">GdkEvent</link> to process.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>user data set when the event handler was installed with
<link linkend="gdk-event-handler-set">gdk_event_handler_set</link>().


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-event-send-client-message">gdk_event_send_client_message ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gdk_event_send_client_message   (<link linkend="GdkEvent">GdkEvent</link> *event,
                                             <link linkend="guint32">guint32</link> xid);</programlisting>
<para>
Sends an X ClientMessage event to a given window.
</para>
<para>
This could be used for communicating between different applications,
though the amount of data is limited to 20 bytes.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>event</parameter>&nbsp;:</entry>
<entry>the <link linkend="GdkEvent">GdkEvent</link> to send, which should be a <link linkend="GdkEventClient">GdkEventClient</link>.
</entry></row>
<row><entry align="right"><parameter>xid</parameter>&nbsp;:</entry>
<entry>the window to send the X ClientMessage event to.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>non-zero on success.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-event-send-clientmessage-toall">gdk_event_send_clientmessage_toall ()</title>
<programlisting>void        gdk_event_send_clientmessage_toall
                                            (<link linkend="GdkEvent">GdkEvent</link> *event);</programlisting>
<para>
Sends an X ClientMessage event to all toplevel windows.
</para>
<para>
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.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>event</parameter>&nbsp;:</entry>
<entry>the <link linkend="GdkEvent">GdkEvent</link> to send, which should be a <link linkend="GdkEventClient">GdkEventClient</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-add-client-message-filter">gdk_add_client_message_filter ()</title>
<programlisting>void        gdk_add_client_message_filter   (<link linkend="GdkAtom">GdkAtom</link> message_type,
                                             <link linkend="GdkFilterFunc">GdkFilterFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Adds a filter to be called when X ClientMessage events are received.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>message_type</parameter>&nbsp;:</entry>
<entry>the type of ClientMessage events to receive. This will be
checked against the <structfield>message_type</structfield> field of the
XClientMessage event struct.
</entry></row>
<row><entry align="right"><parameter>func</parameter>&nbsp;:</entry>
<entry>the function to call to process the event.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>user data to pass to <parameter>func</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-get-show-events">gdk_get_show_events ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gdk_get_show_events             (void);</programlisting>
<para>
Returns non-zero if event debugging output is enabled.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>non-zero if event debugging output is enabled.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-set-show-events">gdk_set_show_events ()</title>
<programlisting>void        gdk_set_show_events             (<link linkend="gboolean">gboolean</link> show_events);</programlisting>
<para>
Sets whether event debugging information is output.
Note that GTK+ must be compiled with debugging enabled, i.e. using the
<option>--enable-debug</option> configure option.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>show_events</parameter>&nbsp;:</entry>
<entry><literal>TRUE</literal> to output event debugging information.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-setting-get">gdk_setting_get ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gdk_setting_get                 (const <link linkend="gchar">gchar</link> *name,
                                             <link linkend="GValue">GValue</link> *value);</programlisting>
<para>
Obtains a desktop-wide setting, such as the double-click time.
</para>
<para>
FIXME needs a list of valid settings here, or a link to 
more information.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>name</parameter>&nbsp;:</entry>
<entry>the name of the setting.
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry>location to store the value of the setting.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if the value has been successfully stored.


</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
<para>
<variablelist>
<varlistentry>
<term><link linkend="gdk-Event-Structures">Event Structures</link></term>
<listitem><para>
The structs used for each type of event.
</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>

</refentry>
