forked from AuroraMiddleware/gtk
d0c4e08535
Fri Oct 18 15:13:24 2002 Owen Taylor <otaylor@redhat.com>
* gdk/tmpl/event_structs.sgml: Update the docs for
the event->key.string to say that @string is deprecated.
485 lines
18 KiB
Plaintext
485 lines
18 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
Event Structures
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
data structures specific to each type of event.
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
The event structs contain data specific to each type of event in GDK.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
A common mistake is to forget to set the event mask of a widget so that the
|
|
required events are received. See gtk_widget_set_events().
|
|
</para>
|
|
</note>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### UNION GdkEvent ##### -->
|
|
<para>
|
|
The #GdkEvent struct contains a union of all of the event structs,
|
|
and allows access to the data fields in a number of ways.
|
|
</para>
|
|
<para>
|
|
The event type is always the first field in all of the event structs, and
|
|
can always be accessed with the following code, no matter what type of event
|
|
it is:
|
|
<informalexample>
|
|
<programlisting>
|
|
GdkEvent *event;
|
|
GdkEventType type;
|
|
|
|
type = event->type;
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<para>
|
|
To access other fields of the event structs, the pointer to the event can be
|
|
cast to the appropriate event struct pointer, or the union member name can be
|
|
used. For example if the event type is %GDK_BUTTON_PRESS then the x coordinate
|
|
of the button press can be accessed with:
|
|
<informalexample>
|
|
<programlisting>
|
|
GdkEvent *event;
|
|
gdouble x;
|
|
|
|
x = ((GdkEventButton*)event)->x;
|
|
</programlisting>
|
|
</informalexample>
|
|
or:
|
|
<informalexample>
|
|
<programlisting>
|
|
GdkEvent *event;
|
|
gdouble x;
|
|
|
|
x = event->button.x;
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
|
|
<!-- ##### STRUCT GdkEventAny ##### -->
|
|
<para>
|
|
Contains the fields which are common to all event structs.
|
|
Any event pointer can safely be cast to a pointer to a #GdkEventAny to access
|
|
these fields.
|
|
</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
|
|
<function>XSendEvent</function>).
|
|
|
|
<!-- ##### STRUCT GdkEventKey ##### -->
|
|
<para>
|
|
Describes a key press or key release event.
|
|
</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
|
|
<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 <filename><gdk/gdkkeysym.h></filename>
|
|
header file for a complete list of GDK key codes.
|
|
@length: the length of @string.
|
|
@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>
|
|
Used for button press and button release events. The
|
|
<structfield>type</structfield> field will be one of %GDK_BUTTON_PRESS,
|
|
%GDK_2BUTTON_PRESS, %GDK_3BUTTON_PRESS, and %GDK_BUTTON_RELEASE.
|
|
</para>
|
|
<para>
|
|
Double and triple-clicks result in a sequence of events being received.
|
|
For double-clicks the order of events will be:
|
|
<orderedlist>
|
|
<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
|
|
<listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
|
|
<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
|
|
<listitem><para>%GDK_2BUTTON_PRESS</para></listitem>
|
|
<listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
|
|
</orderedlist>
|
|
Note that the first click is received just like a normal
|
|
button press, while the second click results in a %GDK_2BUTTON_PRESS being
|
|
received just after the %GDK_BUTTON_PRESS.
|
|
</para>
|
|
<para>
|
|
Triple-clicks are very similar to double-clicks, except that %GDK_3BUTTON_PRESS
|
|
is inserted after the third click. The order of the events is:
|
|
<orderedlist>
|
|
<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
|
|
<listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
|
|
<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
|
|
<listitem><para>%GDK_2BUTTON_PRESS</para></listitem>
|
|
<listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
|
|
<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
|
|
<listitem><para>%GDK_3BUTTON_PRESS</para></listitem>
|
|
<listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
|
|
</orderedlist>
|
|
</para>
|
|
<para>
|
|
For a double click to occur, the second button press must occur within 1/4 of
|
|
a second of the first. For a triple click to occur, the third button press
|
|
must also occur within 1/2 second of the first button press.
|
|
</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
|
|
<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.
|
|
@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: 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: 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
|
|
<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:
|
|
@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>
|
|
Generated when all or part of a window becomes visible and needs to be
|
|
redrawn.
|
|
</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
|
|
<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
|
|
so this is not normally needed.
|
|
|
|
<!-- ##### STRUCT GdkEventVisibility ##### -->
|
|
<para>
|
|
Generated when the window visibility status has changed.
|
|
</para>
|
|
|
|
@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
|
|
<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 (%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
|
|
<function>XSendEvent</function>).
|
|
@subwindow: the window that was entered or left.
|
|
@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.
|
|
@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>
|
|
Describes a change of keyboard focus.
|
|
</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 <function>XSendEvent</function>).
|
|
@in: %TRUE if the window has gained the keyboard focus, %FALSE if it has lost
|
|
the focus.
|
|
|
|
<!-- ##### STRUCT GdkEventConfigure ##### -->
|
|
<para>
|
|
Generated when a window size or position has changed.
|
|
</para>
|
|
|
|
@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 <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.
|
|
@height: the new height of the window.
|
|
|
|
<!-- ##### STRUCT GdkEventProperty ##### -->
|
|
<para>
|
|
Describes a property change on a window.
|
|
</para>
|
|
|
|
@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 <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
|
|
deleted (%GDK_PROPERTY_DELETE).
|
|
|
|
<!-- ##### 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 (%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 <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: 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 (%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 <function>XSendEvent</function>).
|
|
@context: the #GdkDragContext for the current DND operation.
|
|
@time: the time of the event in milliseconds.
|
|
@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 (%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 <function>XSendEvent</function>).
|
|
@time: the time of the event in milliseconds.
|
|
@device: the device where the event originated.
|
|
|
|
<!-- ##### STRUCT GdkEventClient ##### -->
|
|
<para>
|
|
An event sent by another client application.
|
|
</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 <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
|
|
data element, i.e. 8, 16, or 32. 8-bit data uses the b array of the data
|
|
union, 16-bit data uses the s array, and 32-bit data uses the l array.
|
|
|
|
<!-- ##### STRUCT GdkEventNoExpose ##### -->
|
|
<para>
|
|
Generated when the area of a #GdkDrawable being copied, with gdk_draw_drawable()
|
|
or gdk_window_copy_area(), was completely available.
|
|
</para>
|
|
<para>
|
|
FIXME: add more here.
|
|
</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 <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: 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 ##### -->
|
|
<para>
|
|
Specifies the direction for #GdkEventScroll.
|
|
</para>
|
|
|
|
@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>
|
|
Specifies the visiblity status of a window for a #GdkEventVisibility.
|
|
</para>
|
|
|
|
@GDK_VISIBILITY_UNOBSCURED: the window is completely visible.
|
|
@GDK_VISIBILITY_PARTIAL: the window is partially visible.
|
|
@GDK_VISIBILITY_FULLY_OBSCURED: the window is not visible at all.
|
|
|
|
<!-- ##### ENUM GdkCrossingMode ##### -->
|
|
<para>
|
|
Specifies the crossing mode for #GdkEventCrossing.
|
|
</para>
|
|
|
|
@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: 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 ##### -->
|
|
<para>
|
|
Specifies the type of a property change for a #GdkEventProperty.
|
|
</para>
|
|
|
|
@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:
|
|
|
|
<!-- ##### 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.
|
|
|