forked from AuroraMiddleware/gtk
4caf4dc787
2000-02-03 Damon Chaplin <damon@karuna.freeserve.co.uk> * gdk/gdk-sections.txt: rearranged a bit. * gdk/tmpl/event_structs.sgml: updated. * gtk/gtk-sections.txt: added INCLUDE tag for Private Info section. * gdk/tmpl/color_contexts.sgml: added note saying it is deprecated. * gdk/tmpl/dnd.sgml: added note saying read the GTK+ DnD docs.
369 lines
12 KiB
Plaintext
369 lines
12 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 XSendEvent).
|
|
|
|
<!-- ##### STRUCT GdkEventKey ##### -->
|
|
<para>
|
|
Describes a key press or key release event.
|
|
</para>
|
|
|
|
@type: the type of the event (%GDK_KEY_RELEASE or %GDK_KEY_RELEASE).
|
|
@window: the window which received the event.
|
|
@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
|
|
@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>
|
|
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.
|
|
|
|
<!-- ##### 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 XSendEvent).
|
|
@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.
|
|
@pressure: the pressure of the button press, intended for input devices such
|
|
as graphics tablets. It defaults to 0.5.
|
|
@xtilt: the horizontal tilt of the input device. Defaults to 0.
|
|
@ytilt: the vertical tilt of the input device. Defaults to 0.
|
|
@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.
|
|
@source: the input device where the event came from, usually %GDK_SOURCE_MOUSE.
|
|
@deviceid: the input device ID, usually %GDK_CORE_POINTER but may be
|
|
different if touch screens or graphics tablets are being used.
|
|
@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.
|
|
|
|
<!-- ##### STRUCT GdkEventMotion ##### -->
|
|
<para>
|
|
|
|
</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:
|
|
@pressure:
|
|
@xtilt:
|
|
@ytilt:
|
|
@state:
|
|
@is_hint:
|
|
@source:
|
|
@deviceid:
|
|
@x_root:
|
|
@y_root:
|
|
|
|
<!-- ##### 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 XSendEvent).
|
|
@area: the area 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 XSendEvent).
|
|
@state: the new visibility state (%GDK_VISIBILITY_FULLY_OBSCURED,
|
|
%GDK_VISIBILITY_PARTIAL or %GDK_VISIBILITY_UNOBSCURED).
|
|
|
|
<!-- ##### 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.
|
|
|
|
<!-- ##### STRUCT GdkEventCrossing ##### -->
|
|
<para>
|
|
|
|
</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).
|
|
@subwindow:
|
|
@time: the time of the event in milliseconds.
|
|
@x:
|
|
@y:
|
|
@x_root:
|
|
@y_root:
|
|
@mode:
|
|
@detail:
|
|
@focus:
|
|
@state:
|
|
|
|
<!-- ##### ENUM GdkCrossingMode ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@GDK_CROSSING_NORMAL:
|
|
@GDK_CROSSING_GRAB:
|
|
@GDK_CROSSING_UNGRAB:
|
|
|
|
<!-- ##### ENUM GdkNotifyType ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@GDK_NOTIFY_ANCESTOR:
|
|
@GDK_NOTIFY_VIRTUAL:
|
|
@GDK_NOTIFY_INFERIOR:
|
|
@GDK_NOTIFY_NONLINEAR:
|
|
@GDK_NOTIFY_NONLINEAR_VIRTUAL:
|
|
@GDK_NOTIFY_UNKNOWN:
|
|
|
|
<!-- ##### 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 XSendEvent).
|
|
@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 XSendEvent).
|
|
@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 XSendEvent).
|
|
@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).
|
|
|
|
<!-- ##### ENUM GdkPropertyState ##### -->
|
|
<para>
|
|
Specifies the type of a property change for a #GdkEventProperty.
|
|
</para>
|
|
|
|
@GDK_PROPERTY_NEW_VALUE: the property value wan changed.
|
|
@GDK_PROPERTY_DELETE: the property was deleted.
|
|
|
|
<!-- ##### STRUCT GdkEventSelection ##### -->
|
|
<para>
|
|
|
|
</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).
|
|
@selection:
|
|
@target:
|
|
@property:
|
|
@requestor:
|
|
@time: the time of the event in milliseconds.
|
|
|
|
<!-- ##### STRUCT GdkEventDND ##### -->
|
|
<para>
|
|
|
|
</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).
|
|
@context:
|
|
@time: the time of the event in milliseconds.
|
|
@x_root:
|
|
@y_root:
|
|
|
|
<!-- ##### STRUCT GdkEventProximity ##### -->
|
|
<para>
|
|
|
|
</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: the time of the event in milliseconds.
|
|
@source:
|
|
@deviceid:
|
|
|
|
<!-- ##### 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 XSendEvent).
|
|
@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_pixmap()
|
|
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 XSendEvent).
|
|
|