Pileus Git - ~andy/gtk/blob - docs/reference/gdk/tmpl/event_structs.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Event Structures
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 data structures specific to each type of event.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The event structs contain data specific to each type of event in GDK.
  10 </para>
  11 <note>
  12 <para>
  13 A common mistake is to forget to set the event mask of a widget so that the
  14 required events are received. See gtk_widget_set_events().
  15 </para>
  16 </note>
  17
  18 <!-- ##### SECTION See_Also ##### -->
  19 <para>
  20
  21 </para>
  22
  23 <!-- ##### UNION GdkEvent ##### -->
  24 <para>
  25 The #GdkEvent struct contains a union of all of the event structs,
  26 and allows access to the data fields in a number of ways.
  27 </para>
  28 <para>
  29 The event type is always the first field in all of the event structs, and
  30 can always be accessed with the following code, no matter what type of event
  31 it is:
  32 <informalexample>
  33 <programlisting>
  34   GdkEvent *event;
  35   GdkEventType type;
  36
  37   type = event->type;
  38 </programlisting>
  39 </informalexample>
  40 </para>
  41
  42 <para>
  43 To access other fields of the event structs, the pointer to the event can be
  44 cast to the appropriate event struct pointer, or the union member name can be
  45 used. For example if the event type is %GDK_BUTTON_PRESS then the x coordinate
  46 of the button press can be accessed with:
  47 <informalexample>
  48 <programlisting>
  49   GdkEvent *event;
  50   gdouble x;
  51
  52   x = ((GdkEventButton*)event)->x;
  53 </programlisting>
  54 </informalexample>
  55 or:
  56 <informalexample>
  57 <programlisting>
  58   GdkEvent *event;
  59   gdouble x;
  60
  61   x = event->button.x;
  62 </programlisting>
  63 </informalexample>
  64 </para>
  65
  66
  67 <!-- ##### STRUCT GdkEventAny ##### -->
  68 <para>
  69 Contains the fields which are common to all event structs.
  70 Any event pointer can safely be cast to a pointer to a #GdkEventAny to access
  71 these fields.
  72 </para>
  73
  74 @type: the type of the event.
  75 @window: the window which received the event.
  76 @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
  77
  78 <!-- ##### STRUCT GdkEventKey ##### -->
  79 <para>
  80 Describes a key press or key release event.
  81 </para>
  82
  83 @type: the type of the event (%GDK_KEY_PRESS or %GDK_KEY_RELEASE).
  84 @window: the window which received the event.
  85 @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
  86 @time: the time of the event in milliseconds.
  87 @state: a bit-mask representing the state of the modifier keys (e.g. Control,
  88 Shift and Alt) and the pointer buttons. See #GdkModifierType.
  89 @keyval: the key that was pressed or released. See the &lt;gdk/gdkkeysym.h&gt;
  90 header file for a complete list of GDK key codes.
  91 @length: the length of @string.
  92 @string: a null-terminated multi-byte string containing the composed characters
  93 resulting from the key press. When text is being input, in a GtkEntry for
  94 example, it is these characters which should be added to the input buffer.
  95 When using <link linkend="gdk-Input-Methods"> Input Methods</link> to support
  96 internationalized text input, the composed characters appear here after the
  97 pre-editing has been completed.
  98 @hardware_keycode:
  99 @group:
 100
 101 <!-- ##### STRUCT GdkEventButton ##### -->
 102 <para>
 103 Used for button press and button release events. The
 104 <structfield>type</structfield> field will be one of %GDK_BUTTON_PRESS,
 105 %GDK_2BUTTON_PRESS, %GDK_3BUTTON_PRESS, and %GDK_BUTTON_RELEASE.
 106 </para>
 107 <para>
 108 Double and triple-clicks result in a sequence of events being received.
 109 For double-clicks the order of events will be:
 110 <orderedlist>
 111 <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
 112 <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
 113 <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
 114 <listitem><para>%GDK_2BUTTON_PRESS</para></listitem>
 115 <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
 116 </orderedlist>
 117 Note that the first click is received just like a normal
 118 button press, while the second click results in a %GDK_2BUTTON_PRESS being
 119 received just after the %GDK_BUTTON_PRESS.
 120 </para>
 121 <para>
 122 Triple-clicks are very similar to double-clicks, except that %GDK_3BUTTON_PRESS
 123 is inserted after the third click. The order of the events is:
 124 <orderedlist>
 125 <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
 126 <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
 127 <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
 128 <listitem><para>%GDK_2BUTTON_PRESS</para></listitem>
 129 <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
 130 <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
 131 <listitem><para>%GDK_3BUTTON_PRESS</para></listitem>
 132 <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
 133 </orderedlist>
 134 </para>
 135 <para>
 136 For a double click to occur, the second button press must occur within 1/4 of
 137 a second of the first. For a triple click to occur, the third button press
 138 must also occur within 1/2 second of the first button press.
 139 </para>
 140
 141 @type: the type of the event (%GDK_BUTTON_PRESS, %GDK_2BUTTON_PRESS,
 142 %GDK_3BUTTON_PRESS or %GDK_BUTTON_RELEASE).
 143 @window: the window which received the event.
 144 @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
 145 @time: the time of the event in milliseconds.
 146 @x: the x coordinate of the mouse relative to the window.
 147 @y: the y coordinate of the mouse relative to the window.
 148 @axes:
 149 @state: a bit-mask representing the state of the modifier keys (e.g. Control,
 150 Shift and Alt) and the pointer buttons. See #GdkModifierType.
 151 @button: the button which was pressed or released, numbered from 1 to 5.
 152 Normally button 1 is the left mouse button, 2 is the middle button,
 153 and 3 is the right button. On 2-button mice, the middle button can often
 154 be simulated by pressing both mouse buttons together.
 155 @device:
 156 @x_root: the x coordinate of the mouse relative to the root of the screen.
 157 @y_root: the y coordinate of the mouse relative to the root of the screen.
 158
 159 <!-- ##### STRUCT GdkEventScroll ##### -->
 160 <para>
 161
 162 </para>
 163
 164 @type:
 165 @window:
 166 @send_event:
 167 @time:
 168 @x:
 169 @y:
 170 @state:
 171 @direction:
 172 @device:
 173 @x_root:
 174 @y_root:
 175
 176 <!-- ##### STRUCT GdkEventMotion ##### -->
 177 <para>
 178
 179 </para>
 180
 181 @type: the type of the event.
 182 @window: the window which received the event.
 183 @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
 184 @time:
 185 @x:
 186 @y:
 187 @axes:
 188 @state:
 189 @is_hint:
 190 @device:
 191 @x_root:
 192 @y_root:
 193
 194 <!-- ##### STRUCT GdkEventExpose ##### -->
 195 <para>
 196 Generated when all or part of a window becomes visible and needs to be
 197 redrawn.
 198 </para>
 199
 200 @type: the type of the event (%GDK_EXPOSE).
 201 @window: the window which received the event.
 202 @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
 203 @area: the area that needs to be redrawn.
 204 @count: the number of contiguous %GDK_EXPOSE events following this one.
 205 The only use for this is "exposure compression", i.e. handling all contiguous
 206 %GDK_EXPOSE events in one go, though GDK performs some exposure compression
 207 so this is not normally needed.
 208
 209 <!-- ##### STRUCT GdkEventVisibility ##### -->
 210 <para>
 211 Generated when the window visibility status has changed.
 212 </para>
 213
 214 @type: the type of the event (%GDK_VISIBILITY_NOTIFY).
 215 @window: the window which received the event.
 216 @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
 217 @state: the new visibility state (%GDK_VISIBILITY_FULLY_OBSCURED,
 218 %GDK_VISIBILITY_PARTIAL or %GDK_VISIBILITY_UNOBSCURED).
 219
 220 <!-- ##### STRUCT GdkEventCrossing ##### -->
 221 <para>
 222
 223 </para>
 224
 225 @type: the type of the event.
 226 @window: the window which received the event.
 227 @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
 228 @subwindow:
 229 @time: the time of the event in milliseconds.
 230 @x:
 231 @y:
 232 @x_root:
 233 @y_root:
 234 @mode:
 235 @detail:
 236 @focus:
 237 @state:
 238
 239 <!-- ##### STRUCT GdkEventFocus ##### -->
 240 <para>
 241 Describes a change of keyboard focus.
 242 </para>
 243
 244 @type: the type of the event (%GDK_FOCUS_CHANGE).
 245 @window: the window which received the event.
 246 @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
 247 @in: TRUE if the window has gained the keyboard focus, FALSE if it has lost
 248 the focus.
 249
 250 <!-- ##### STRUCT GdkEventConfigure ##### -->
 251 <para>
 252 Generated when a window size or position has changed.
 253 </para>
 254
 255 @type: the type of the event (%GDK_CONFIGURE).
 256 @window: the window which received the event.
 257 @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
 258 @x: the new x coordinate of the window, relative to its parent.
 259 @y: the new y coordinate of the window, relative to its parent.
 260 @width: the new width of the window.
 261 @height: the new height of the window.
 262
 263 <!-- ##### STRUCT GdkEventProperty ##### -->
 264 <para>
 265 Describes a property change on a window.
 266 </para>
 267
 268 @type: the type of the event (%GDK_PROPERTY_NOTIFY).
 269 @window: the window which received the event.
 270 @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
 271 @atom: the property that was changed.
 272 @time: the time of the event in milliseconds.
 273 @state: whether the property was changed (%GDK_PROPERTY_NEW_VALUE) or
 274 deleted (%GDK_PROPERTY_DELETE).
 275
 276 <!-- ##### STRUCT GdkEventSelection ##### -->
 277 <para>
 278
 279 </para>
 280
 281 @type: the type of the event.
 282 @window: the window which received the event.
 283 @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
 284 @selection:
 285 @target:
 286 @property:
 287 @time: the time of the event in milliseconds.
 288 @requestor:
 289
 290 <!-- ##### TYPEDEF GdkNativeWindow ##### -->
 291 <para>
 292
 293 </para>
 294
 295
 296 <!-- ##### STRUCT GdkEventDND ##### -->
 297 <para>
 298
 299 </para>
 300
 301 @type: the type of the event.
 302 @window: the window which received the event.
 303 @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
 304 @context:
 305 @time: the time of the event in milliseconds.
 306 @x_root:
 307 @y_root:
 308
 309 <!-- ##### STRUCT GdkEventProximity ##### -->
 310 <para>
 311
 312 </para>
 313
 314 @type: the type of the event.
 315 @window: the window which received the event.
 316 @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
 317 @time: the time of the event in milliseconds.
 318 @device:
 319
 320 <!-- ##### STRUCT GdkEventClient ##### -->
 321 <para>
 322 An event sent by another client application.
 323 </para>
 324
 325 @type: the type of the event (%GDK_CLIENT_EVENT).
 326 @window: the window which received the event.
 327 @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
 328 @message_type: the type of the message, which can be defined by the
 329 application.
 330 @data_format: the format of the data, given as the number of bits in each
 331 data element, i.e. 8, 16, or 32. 8-bit data uses the b array of the data
 332 union, 16-bit data uses the s array, and 32-bit data uses the l array.
 333
 334 <!-- ##### STRUCT GdkEventNoExpose ##### -->
 335 <para>
 336 Generated when the area of a #GdkDrawable being copied, with gdk_draw_pixmap()
 337 or gdk_window_copy_area(), was completely available.
 338 </para>
 339 <para>
 340 FIXME: add more here.
 341 </para>
 342
 343 @type: the type of the event (%GDK_NO_EXPOSE).
 344 @window: the window which received the event.
 345 @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
 346
 347 <!-- ##### ENUM GdkScrollDirection ##### -->
 348 <para>
 349
 350 </para>
 351
 352 @GDK_SCROLL_UP:
 353 @GDK_SCROLL_DOWN:
 354 @GDK_SCROLL_LEFT:
 355 @GDK_SCROLL_RIGHT:
 356
 357 <!-- ##### ENUM GdkVisibilityState ##### -->
 358 <para>
 359 Specifies the visiblity status of a window for a #GdkEventVisibility.
 360 </para>
 361
 362 @GDK_VISIBILITY_UNOBSCURED: the window is completely visible.
 363 @GDK_VISIBILITY_PARTIAL: the window is partially visible.
 364 @GDK_VISIBILITY_FULLY_OBSCURED: the window is not visible at all.
 365
 366 <!-- ##### ENUM GdkCrossingMode ##### -->
 367 <para>
 368
 369 </para>
 370
 371 @GDK_CROSSING_NORMAL:
 372 @GDK_CROSSING_GRAB:
 373 @GDK_CROSSING_UNGRAB:
 374
 375 <!-- ##### ENUM GdkNotifyType ##### -->
 376 <para>
 377
 378 </para>
 379
 380 @GDK_NOTIFY_ANCESTOR:
 381 @GDK_NOTIFY_VIRTUAL:
 382 @GDK_NOTIFY_INFERIOR:
 383 @GDK_NOTIFY_NONLINEAR:
 384 @GDK_NOTIFY_NONLINEAR_VIRTUAL:
 385 @GDK_NOTIFY_UNKNOWN:
 386
 387 <!-- ##### ENUM GdkPropertyState ##### -->
 388 <para>
 389 Specifies the type of a property change for a #GdkEventProperty.
 390 </para>
 391
 392 @GDK_PROPERTY_NEW_VALUE: the property value wan changed.
 393 @GDK_PROPERTY_DELETE: the property was deleted.
 394