event_structs.sgml

This GTK+ version 2.12.3. GTK+ is a multi-platform toolkit for creating graphical user interfaces.

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

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


<!-- ##### 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>&lt;gdk/gdkkeysyms.h&gt;</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.
@is_modifier: a flag that indicates if @hardware_keycode is mapped to a
  modifier. Since 2.10

<!-- ##### 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: 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>
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.