Event Structures
<!-- ##### SECTION Short_Description ##### -->
-data structures specific to each type of event.
+Data structures specific to each type of event
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### UNION GdkEvent ##### -->
<para>
The #GdkEvent struct contains a union of all of the event structs,
@type: the type of the event.
@window: the window which received the event.
-@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@send_event: %TRUE if the event was sent explicitly (e.g. using
+<function>XSendEvent</function>).
<!-- ##### STRUCT GdkEventKey ##### -->
<para>
@type: the type of the event (%GDK_KEY_PRESS or %GDK_KEY_RELEASE).
@window: the window which received the event.
-@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@send_event: %TRUE if the event was sent explicitly (e.g. using
+<function>XSendEvent</function>).
@time: the time of the event in milliseconds.
@state: a bit-mask representing the state of the modifier keys (e.g. Control,
Shift and Alt) and the pointer buttons. See #GdkModifierType.
-@keyval: the key that was pressed or released. See the <gdk/gdkkeysym.h>
+@keyval: the key that was pressed or released. See the
+<filename><gdk/gdkkeysyms.h></filename>
header file for a complete list of GDK key codes.
@length: the length of @string.
-@string: a null-terminated multi-byte string containing the composed characters
-resulting from the key press. When text is being input, in a GtkEntry for
-example, it is these characters which should be added to the input buffer.
-When using <link linkend="gdk-Input-Methods"> Input Methods</link> to support
-internationalized text input, the composed characters appear here after the
-pre-editing has been completed.
-@hardware_keycode:
-@group:
+@string: a string containing the an approximation of the text that
+would result from this keypress. The only correct way to handle text
+input of text is using input methods (see #GtkIMContext), so this
+field is deprecated and should never be used.
+(gdk_unicode_to_keyval() provides a non-deprecated way of getting
+an approximate translation for a key.) The string is encoded in the encoding
+of the current locale (Note: this for backwards compatibility:
+strings in GTK+ and GDK are typically in UTF-8.) and NUL-terminated.
+In some cases, the translation of the key code will be a single
+NUL byte, in which case looking at @length is necessary to distinguish
+it from the an empty translation.
+@hardware_keycode: the raw code of the key that was pressed or released.
+@group: the keyboard group.
<!-- ##### STRUCT GdkEventButton ##### -->
<para>
@type: the type of the event (%GDK_BUTTON_PRESS, %GDK_2BUTTON_PRESS,
%GDK_3BUTTON_PRESS or %GDK_BUTTON_RELEASE).
@window: the window which received the event.
-@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@send_event: %TRUE if the event was sent explicitly (e.g. using
+<function>XSendEvent</function>).
@time: the time of the event in milliseconds.
-@x: the x coordinate of the mouse relative to the window.
-@y: the y coordinate of the mouse relative to the window.
-@axes:
+@x: the x coordinate of the pointer relative to the window.
+@y: the y coordinate of the pointer relative to the window.
+@axes: @x, @y translated to the axes of @device, or %NULL if @device is
+ the mouse.
@state: a bit-mask representing the state of the modifier keys (e.g. Control,
Shift and Alt) and the pointer buttons. See #GdkModifierType.
@button: the button which was pressed or released, numbered from 1 to 5.
Normally button 1 is the left mouse button, 2 is the middle button,
and 3 is the right button. On 2-button mice, the middle button can often
be simulated by pressing both mouse buttons together.
-@device:
-@x_root: the x coordinate of the mouse relative to the root of the screen.
-@y_root: the y coordinate of the mouse relative to the root of the screen.
+@device: the device where the event originated.
+@x_root: the x coordinate of the pointer relative to the root of the screen.
+@y_root: the y coordinate of the pointer relative to the root of the screen.
<!-- ##### STRUCT GdkEventScroll ##### -->
<para>
-
+Generated from button presses for the buttons 4 to 7. Wheel mice are
+usually configured to generate button press events for buttons 4 and 5
+when the wheel is turned.
</para>
-@type:
-@window:
-@send_event:
-@time:
-@x:
-@y:
-@state:
-@direction:
-@device:
-@x_root:
-@y_root:
+@type: the type of the event (%GDK_SCROLL).
+@window: the window which received the event.
+@send_event: %TRUE if the event was sent explicitly (e.g. using
+<function>XSendEvent</function>).
+@time: the time of the event in milliseconds.
+@x: the x coordinate of the pointer relative to the window.
+@y: the y coordinate of the pointer relative to the window.
+@state: a bit-mask representing the state of the modifier keys (e.g. Control,
+Shift and Alt) and the pointer buttons. See #GdkModifierType.
+@direction: the direction to scroll to (one of %GDK_SCROLL_UP,
+ %GDK_SCROLL_DOWN, %GDK_SCROLL_LEFT and %GDK_SCROLL_RIGHT).
+@device: the device where the event originated.
+@x_root: the x coordinate of the pointer relative to the root of the screen.
+@y_root: the y coordinate of the pointer relative to the root of the screen.
<!-- ##### STRUCT GdkEventMotion ##### -->
<para>
-
+Generated when the pointer moves.
</para>
@type: the type of the event.
@window: the window which received the event.
-@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
-@time:
-@x:
-@y:
-@axes:
-@state:
-@is_hint:
-@device:
-@x_root:
-@y_root:
+@send_event: %TRUE if the event was sent explicitly (e.g. using
+<function>XSendEvent</function>).
+@time: the time of the event in milliseconds.
+@x: the x coordinate of the pointer relative to the window.
+@y: the y coordinate of the pointer relative to the window.
+@axes: @x, @y translated to the axes of @device, or %NULL if @device is
+ the mouse.
+@state: a bit-mask representing the state of the modifier keys (e.g. Control,
+ Shift and Alt) and the pointer buttons. See #GdkModifierType.
+@is_hint: set to 1 if this event is just a hint, see the %GDK_POINTER_MOTION_HINT_MASK
+ value of #GdkEventMask.
+@device: the device where the event originated.
+@x_root: the x coordinate of the pointer relative to the root of the screen.
+@y_root: the y coordinate of the pointer relative to the root of the screen.
<!-- ##### STRUCT GdkEventExpose ##### -->
<para>
@type: the type of the event (%GDK_EXPOSE).
@window: the window which received the event.
-@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
-@area: the area that needs to be redrawn.
-@region:
+@send_event: %TRUE if the event was sent explicitly (e.g. using
+<function>XSendEvent</function>).
+@area: bounding box of @region.
+@region: the region that needs to be redrawn.
@count: the number of contiguous %GDK_EXPOSE events following this one.
The only use for this is "exposure compression", i.e. handling all contiguous
%GDK_EXPOSE events in one go, though GDK performs some exposure compression
@type: the type of the event (%GDK_VISIBILITY_NOTIFY).
@window: the window which received the event.
-@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@send_event: %TRUE if the event was sent explicitly (e.g. using
+<function>XSendEvent</function>).
@state: the new visibility state (%GDK_VISIBILITY_FULLY_OBSCURED,
%GDK_VISIBILITY_PARTIAL or %GDK_VISIBILITY_UNOBSCURED).
<!-- ##### STRUCT GdkEventCrossing ##### -->
<para>
-
+Generated when the pointer enters or leaves a window.
</para>
-@type: the type of the event.
+@type: the type of the event (%GDK_ENTER_NOTIFY or %GDK_LEAVE_NOTIFY).
@window: the window which received the event.
-@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
-@subwindow:
+@send_event: %TRUE if the event was sent explicitly (e.g. using
+<function>XSendEvent</function>).
+@subwindow: the window that was entered or left.
@time: the time of the event in milliseconds.
-@x:
-@y:
-@x_root:
-@y_root:
-@mode:
-@detail:
-@focus:
-@state:
+@x: the x coordinate of the pointer relative to the window.
+@y: the y coordinate of the pointer relative to the window.
+@x_root: the x coordinate of the pointer relative to the root of the screen.
+@y_root: the y coordinate of the pointer relative to the root of the screen.
+@mode: the crossing mode (%GDK_CROSSING_NORMAL, %GDK_CROSSING_GRAB or
+ %GDK_CROSSING_UNGRAB).
+@detail: the kind of crossing that happened (%GDK_NOTIFY_INFERIOR,
+ %GDK_NOTIFY_ANCESTOR, %GDK_NOTIFY_VIRTUAL, %GDK_NOTIFY_NONLINEAR or
+ %GDK_NOTIFY_NONLINEAR_VIRTUAL).
+@focus: %TRUE if @window is the focus window or an inferior.
+@state: a bit-mask representing the state of the modifier keys (e.g. Control,
+ Shift and Alt) and the pointer buttons. See #GdkModifierType.
<!-- ##### STRUCT GdkEventFocus ##### -->
<para>
@type: the type of the event (%GDK_FOCUS_CHANGE).
@window: the window which received the event.
-@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
-@in: TRUE if the window has gained the keyboard focus, FALSE if it has lost
+@send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
+@in: %TRUE if the window has gained the keyboard focus, %FALSE if it has lost
the focus.
<!-- ##### STRUCT GdkEventConfigure ##### -->
@type: the type of the event (%GDK_CONFIGURE).
@window: the window which received the event.
-@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
@x: the new x coordinate of the window, relative to its parent.
@y: the new y coordinate of the window, relative to its parent.
@width: the new width of the window.
@type: the type of the event (%GDK_PROPERTY_NOTIFY).
@window: the window which received the event.
-@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
@atom: the property that was changed.
@time: the time of the event in milliseconds.
@state: whether the property was changed (%GDK_PROPERTY_NEW_VALUE) or
<!-- ##### STRUCT GdkEventSelection ##### -->
<para>
-
+Generated when a selection is requested or ownership of a selection
+is taken over by another client application.
</para>
-@type: the type of the event.
+@type: the type of the event (%GDK_SELECTION_CLEAR, %GDK_SELECTION_NOTIFY or
+%GDK_SELECTION_REQUEST).
@window: the window which received the event.
-@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
-@selection:
-@target:
-@property:
+@send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
+@selection: the selection.
+@target: the target to which the selection should be converted.
+@property: the property in which to place the result of the conversion.
@time: the time of the event in milliseconds.
-@requestor:
+@requestor: the native window on which to place @property.
<!-- ##### TYPEDEF GdkNativeWindow ##### -->
<para>
-
+Used to represent native windows (<type>Window</type>s for the X11 backend,
+<type>HWND</type>s for Win32).
</para>
<!-- ##### STRUCT GdkEventDND ##### -->
<para>
-
+Generated during DND operations.
</para>
-@type: the type of the event.
+@type: the type of the event (%GDK_DRAG_ENTER, %GDK_DRAG_LEAVE,
+ %GDK_DRAG_MOTION, %GDK_DRAG_STATUS, %GDK_DROP_START or %GDK_DROP_FINISHED).
@window: the window which received the event.
-@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
-@context:
+@send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
+@context: the #GdkDragContext for the current DND operation.
@time: the time of the event in milliseconds.
-@x_root:
-@y_root:
+@x_root: the x coordinate of the pointer relative to the root of the screen,
+ only set for %GDK_DRAG_MOTION and %GDK_DROP_START.
+@y_root: the y coordinate of the pointer relative to the root of the screen,
+ only set for %GDK_DRAG_MOTION and %GDK_DROP_START.
<!-- ##### STRUCT GdkEventProximity ##### -->
<para>
-
+Proximity events are generated when using GDK's wrapper for the
+XInput extension. The XInput extension is an add-on for standard X
+that allows you to use nonstandard devices such as graphics tablets.
+A proximity event indicates that the stylus has moved in or out of
+contact with the tablet, or perhaps that the user's finger has moved
+in or out of contact with a touch screen.
</para>
-@type: the type of the event.
+@type: the type of the event (%GDK_PROXIMITY_IN or %GDK_PROXIMITY_OUT).
@window: the window which received the event.
-@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
@time: the time of the event in milliseconds.
-@device:
+@device: the device where the event originated.
<!-- ##### STRUCT GdkEventClient ##### -->
<para>
@type: the type of the event (%GDK_CLIENT_EVENT).
@window: the window which received the event.
-@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
@message_type: the type of the message, which can be defined by the
application.
@data_format: the format of the data, given as the number of bits in each
<!-- ##### STRUCT GdkEventNoExpose ##### -->
<para>
-Generated when the area of a #GdkDrawable being copied, with gdk_draw_pixmap()
+Generated when the area of a #GdkDrawable being copied, with gdk_draw_drawable()
or gdk_window_copy_area(), was completely available.
</para>
<para>
@type: the type of the event (%GDK_NO_EXPOSE).
@window: the window which received the event.
-@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
<!-- ##### STRUCT GdkEventWindowState ##### -->
<para>
+Generated when the state of a toplevel window changes.
+</para>
+
+@type: the type of the event (%GDK_WINDOW_STATE).
+@window: the window which received the event.
+@send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
+@changed_mask: mask specifying what flags have changed.
+@new_window_state: the new window state, a combination of #GdkWindowState bits.
+<!-- ##### STRUCT GdkEventSetting ##### -->
+<para>
+Generated when a setting is modified.
</para>
-@type:
-@window:
-@send_event:
-@changed_mask:
-@new_window_state:
+@type: the type of the event (%GDK_SETTING).
+@window: the window which received the event.
+@send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
+@action: what happened to the setting (%GDK_SETTING_ACTION_NEW,
+ %GDK_SETTING_ACTION_CHANGED or %GDK_SETTING_ACTION_DELETED).
+@name: the name of the setting.
-<!-- ##### ENUM GdkScrollDirection ##### -->
+<!-- ##### STRUCT GdkEventOwnerChange ##### -->
<para>
+Generated when the owner of a selection changes. On X11, this information is
+only available if the X server supports the XFIXES extension.
+</para>
+
+@type: the type of the event (%GDK_OWNER_CHANGE).
+@window: the window which received the event
+@send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
+@owner: the new owner of the selection
+@reason: the reason for the ownership change as a #GdkOwnerChange value
+@selection: the atom identifying the selection
+@time: the timestamp of the event
+@selection_time: the time at which the selection ownership was taken over
+@Since: 2.6
+<!-- ##### STRUCT GdkEventGrabBroken ##### -->
+<para>
+Generated when a pointer or keyboard grab is broken. On X11, this happens
+when the grab window becomes unviewable (i.e. it or one of its ancestors
+is unmapped), or if the same application grabs the pointer or keyboard
+again.
+</para>
+
+@type: the type of the event (%GDK_GRAB_BROKEN)
+@window: the window which received the event, i.e. the window
+ that previously owned the grab
+@send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
+@keyboard: %TRUE if a keyboard grab was broken, %FALSE if a pointer
+ grab was broken
+@Since: 2.8
+
+<!-- ##### ENUM GdkScrollDirection ##### -->
+<para>
+Specifies the direction for #GdkEventScroll.
</para>
-@GDK_SCROLL_UP:
-@GDK_SCROLL_DOWN:
-@GDK_SCROLL_LEFT:
-@GDK_SCROLL_RIGHT:
+@GDK_SCROLL_UP: the window is scrolled up.
+@GDK_SCROLL_DOWN: the window is scrolled down.
+@GDK_SCROLL_LEFT: the window is scrolled to the left.
+@GDK_SCROLL_RIGHT: the window is scrolled to the right.
<!-- ##### ENUM GdkVisibilityState ##### -->
<para>
<!-- ##### ENUM GdkCrossingMode ##### -->
<para>
-
+Specifies the crossing mode for #GdkEventCrossing.
</para>
-@GDK_CROSSING_NORMAL:
-@GDK_CROSSING_GRAB:
-@GDK_CROSSING_UNGRAB:
+@GDK_CROSSING_NORMAL: crossing because of pointer motion.
+@GDK_CROSSING_GRAB: crossing because a grab is activated.
+@GDK_CROSSING_UNGRAB: crossing because a grab is deactivated.
<!-- ##### ENUM GdkNotifyType ##### -->
<para>
-
+Specifies the kind of crossing for #GdkEventCrossing.
+</para>
+<para>
+See the X11 protocol specification of <type>LeaveNotify</type> for
+full details of crossing event generation.
</para>
-@GDK_NOTIFY_ANCESTOR:
-@GDK_NOTIFY_VIRTUAL:
-@GDK_NOTIFY_INFERIOR:
-@GDK_NOTIFY_NONLINEAR:
-@GDK_NOTIFY_NONLINEAR_VIRTUAL:
+@GDK_NOTIFY_ANCESTOR: the window is entered from an ancestor or
+ left towards an ancestor.
+@GDK_NOTIFY_VIRTUAL: the pointer moves between an ancestor and an
+ inferior of the window.
+@GDK_NOTIFY_INFERIOR: the window is entered from an inferior or
+ left towards an inferior.
+@GDK_NOTIFY_NONLINEAR: the window is entered from or left towards
+ a window which is neither an ancestor nor an inferior.
+@GDK_NOTIFY_NONLINEAR_VIRTUAL: the pointer moves between two windows
+ which are not ancestors of each other and the window is part of
+ the ancestor chain between one of these windows and their least
+ common ancestor.
@GDK_NOTIFY_UNKNOWN:
<!-- ##### ENUM GdkPropertyState ##### -->
Specifies the type of a property change for a #GdkEventProperty.
</para>
-@GDK_PROPERTY_NEW_VALUE: the property value wan changed.
+@GDK_PROPERTY_NEW_VALUE: the property value was changed.
@GDK_PROPERTY_DELETE: the property was deleted.
<!-- ##### ENUM GdkWindowState ##### -->
<para>
+Specifies the state of a toplevel window.
+</para>
+
+@GDK_WINDOW_STATE_WITHDRAWN: the window is not shown.
+@GDK_WINDOW_STATE_ICONIFIED: the window is minimized.
+@GDK_WINDOW_STATE_MAXIMIZED: the window is maximized.
+@GDK_WINDOW_STATE_STICKY: the window is sticky.
+@GDK_WINDOW_STATE_FULLSCREEN: the window is maximized without decorations.
+@GDK_WINDOW_STATE_ABOVE: the window is kept above other windows.
+@GDK_WINDOW_STATE_BELOW: the window is kept below other windows.
+<!-- ##### ENUM GdkSettingAction ##### -->
+<para>
+Specifies the kind of modification applied to a setting in a #GdkEventSetting.
+</para>
+
+@GDK_SETTING_ACTION_NEW: a setting was added.
+@GDK_SETTING_ACTION_CHANGED: a setting was changed.
+@GDK_SETTING_ACTION_DELETED: a setting was deleted.
+
+<!-- ##### ENUM GdkOwnerChange ##### -->
+<para>
+Specifies why a selection ownership was changed.
</para>
-@GDK_WINDOW_STATE_WITHDRAWN:
-@GDK_WINDOW_STATE_ICONIFIED:
-@GDK_WINDOW_STATE_MAXIMIZED:
-@GDK_WINDOW_STATE_STICKY:
+@GDK_OWNER_CHANGE_NEW_OWNER: some other app claimed the ownership
+@GDK_OWNER_CHANGE_DESTROY: the window was destroyed
+@GDK_OWNER_CHANGE_CLOSE: the client was closed
projects / ~andy / gtk / blobdiff