[~andy/gtk] / docs / reference / gdk / tmpl / events.sgml

<!-- ##### SECTION Title ##### -->
Events

<!-- ##### SECTION Short_Description ##### -->
Functions for handling events from the window system

<!-- ##### SECTION Long_Description ##### -->
<para>
This section describes functions dealing with events from the window system.
</para>
<para>
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
<link linkend="gdk-Event-Structures">Event Structures</link> are useful.
</para>

<!-- ##### SECTION See_Also ##### -->
<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>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### ENUM GdkEventType ##### -->
<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>

@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.
@GDK_DAMAGE: the content of the window has been changed. This event type
  was added in 2.14.

<!-- ##### ENUM GdkEventMask ##### -->
<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 #GdkEventType event types
above.
</para>
<para>
%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 lag behind the position of the mouse. When using
%GDK_POINTER_MOTION_HINT_MASK, fewer %GDK_MOTION_NOTIFY events will be sent,
some of which are marked as a hint (the is_hint member is %TRUE).
To receive more motion events after a motion hint event, the application
needs to asks for more, by calling gdk_event_request_motions().
</para>

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

<!-- ##### MACRO GDK_CURRENT_TIME ##### -->
<para>
Represents the current time, and can be used anywhere a time is expected.
</para>



<!-- ##### MACRO GDK_PRIORITY_EVENTS ##### -->
<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>



<!-- ##### MACRO GDK_PRIORITY_REDRAW ##### -->
<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>



<!-- ##### FUNCTION gdk_events_pending ##### -->
<para>
</para>

@Returns: 


<!-- ##### FUNCTION gdk_event_peek ##### -->
<para>
</para>

@Returns: 


<!-- ##### FUNCTION gdk_event_get ##### -->
<para>
</para>

@Returns: 


<!-- ##### FUNCTION gdk_event_get_graphics_expose ##### -->
<para>
</para>

@window: 
@Returns: 


<!-- ##### FUNCTION gdk_event_put ##### -->
<para>
</para>

@event: 


<!-- ##### FUNCTION gdk_event_new ##### -->
<para>

</para>

@type: 
@Returns: 


<!-- ##### FUNCTION gdk_event_copy ##### -->
<para>
</para>

@event: 
@Returns: 


<!-- ##### FUNCTION gdk_event_free ##### -->
<para>
</para>

@event: a #GdkEvent.


<!-- ##### FUNCTION gdk_event_get_time ##### -->
<para>
</para>

@event: 
@Returns: 


<!-- ##### FUNCTION gdk_event_get_state ##### -->
<para>

</para>

@event: 
@state: 
@Returns: 


<!-- ##### FUNCTION gdk_event_get_axis ##### -->
<para>

</para>

@event: 
@axis_use: 
@value: 
@Returns: 


<!-- ##### FUNCTION gdk_event_get_coords ##### -->
<para>

</para>

@event: 
@x_win: 
@y_win: 
@Returns: 


<!-- ##### FUNCTION gdk_event_get_root_coords ##### -->
<para>

</para>

@event: 
@x_root: 
@y_root: 
@Returns: 


<!-- ##### FUNCTION gdk_event_request_motions ##### -->
<para>

</para>

@event: 


<!-- ##### FUNCTION gdk_event_handler_set ##### -->
<para>
</para>

@func: 
@data: 
@notify: 


<!-- ##### USER_FUNCTION GdkEventFunc ##### -->
<para>
Specifies the type of function passed to gdk_event_handler_set() to handle
all GDK events.
</para>

@event: the #GdkEvent to process.
@data: user data set when the event handler was installed with
gdk_event_handler_set().


<!-- ##### FUNCTION gdk_event_send_client_message ##### -->
<para>
</para>

@event: 
@winid: 
@Returns: 


<!-- ##### FUNCTION gdk_event_send_client_message_for_display ##### -->
<para>

</para>

@display: 
@event: 
@winid: 
@Returns: 


<!-- ##### FUNCTION gdk_event_send_clientmessage_toall ##### -->
<para>
</para>

@event: 


<!-- ##### FUNCTION gdk_add_client_message_filter ##### -->
<para>
</para>

@message_type: 
@func: 
@data: 


<!-- ##### FUNCTION gdk_get_show_events ##### -->
<para>
</para>

@Returns: 


<!-- ##### FUNCTION gdk_set_show_events ##### -->
<para>
</para>

@show_events: 


<!-- ##### FUNCTION gdk_event_set_screen ##### -->
<para>

</para>

@event: 
@screen: 


<!-- ##### FUNCTION gdk_event_get_screen ##### -->
<para>

</para>

@event: 
@Returns: 


<!-- ##### FUNCTION gdk_setting_get ##### -->
<para>
</para>

@name: 
@value: 
@Returns: