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,
@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 <filename><gdk/gdkkeysym.h></filename>
+@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 nul-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.
+@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.
@window: the window which received the event.
@send_event: %TRUE if the event was sent explicitly (e.g. using
<function>XSendEvent</function>).
-@time:
+@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,
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:
+@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.
@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 happended (%GDK_NOTIFY_INFERIOR,
+@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.
<!-- ##### STRUCT GdkEventProximity ##### -->
<para>
-FIXME: Lookup XProximityNotifyEvent.
+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 (%GDK_PROXIMITY_IN or %GDK_PROXIMITY_OUT).
<!-- ##### 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>
%GDK_SETTING_ACTION_CHANGED or %GDK_SETTING_ACTION_DELETED).
@name: the name of the setting.
+<!-- ##### 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.
@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>
@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_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
+