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
  77 <function>XSendEvent</function>).
  78
  79 <!-- ##### STRUCT GdkEventKey ##### -->
  80 <para>
  81 Describes a key press or key release event.
  82 </para>
  83
  84 @type: the type of the event (%GDK_KEY_PRESS or %GDK_KEY_RELEASE).
  85 @window: the window which received the event.
  86 @send_event: %TRUE if the event was sent explicitly (e.g. using
  87 <function>XSendEvent</function>).
  88 @time: the time of the event in milliseconds.
  89 @state: a bit-mask representing the state of the modifier keys (e.g. Control,
  90 Shift and Alt) and the pointer buttons. See #GdkModifierType.
  91 @keyval: the key that was pressed or released. See the <filename>&lt;gdk/gdkkeysym.h&gt;</filename>
  92 header file for a complete list of GDK key codes.
  93 @length: the length of @string.
  94 @string: a string containing the an approximation of the text that
  95 would result from this keypress. The only correct way to handle text
  96 input of text is using input methods (see #GtkIMContext), so this
  97 field is deprecated and should never be used.
  98 (gdk_unicode_to_keyval() provides a non-deprecated way of getting
  99 an approximate translation for a key.) The string is encoded in the encoding
 100 of the current locale (Note: this for backwards compatibility:
 101 strings in GTK+ and GDK are typically in UTF-8.) and NUL-terminated.
 102 In some cases, the translation of the key code will be a single
 103 NUL byte, in which case looking at @length is necessary to distinguish
 104 it from the an empty translation.
 105 @hardware_keycode: the raw code of the key that was pressed or released.
 106 @group: the keyboard group.
 107
 108 <!-- ##### STRUCT GdkEventButton ##### -->
 109 <para>
 110 Used for button press and button release events. The
 111 <structfield>type</structfield> field will be one of %GDK_BUTTON_PRESS,
 112 %GDK_2BUTTON_PRESS, %GDK_3BUTTON_PRESS, and %GDK_BUTTON_RELEASE.
 113 </para>
 114 <para>
 115 Double and triple-clicks result in a sequence of events being received.
 116 For double-clicks the order of events will be:
 117 <orderedlist>
 118 <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
 119 <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
 120 <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
 121 <listitem><para>%GDK_2BUTTON_PRESS</para></listitem>
 122 <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
 123 </orderedlist>
 124 Note that the first click is received just like a normal
 125 button press, while the second click results in a %GDK_2BUTTON_PRESS being
 126 received just after the %GDK_BUTTON_PRESS.
 127 </para>
 128 <para>
 129 Triple-clicks are very similar to double-clicks, except that %GDK_3BUTTON_PRESS
 130 is inserted after the third click. The order of the events is:
 131 <orderedlist>
 132 <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
 133 <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
 134 <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
 135 <listitem><para>%GDK_2BUTTON_PRESS</para></listitem>
 136 <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
 137 <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
 138 <listitem><para>%GDK_3BUTTON_PRESS</para></listitem>
 139 <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
 140 </orderedlist>
 141 </para>
 142 <para>
 143 For a double click to occur, the second button press must occur within 1/4 of
 144 a second of the first. For a triple click to occur, the third button press
 145 must also occur within 1/2 second of the first button press.
 146 </para>
 147
 148 @type: the type of the event (%GDK_BUTTON_PRESS, %GDK_2BUTTON_PRESS,
 149 %GDK_3BUTTON_PRESS or %GDK_BUTTON_RELEASE).
 150 @window: the window which received the event.
 151 @send_event: %TRUE if the event was sent explicitly (e.g. using
 152 <function>XSendEvent</function>).
 153 @time: the time of the event in milliseconds.
 154 @x: the x coordinate of the pointer relative to the window.
 155 @y: the y coordinate of the pointer relative to the window.
 156 @axes: @x, @y translated to the axes of @device, or %NULL if @device is
 157   the mouse.
 158 @state: a bit-mask representing the state of the modifier keys (e.g. Control,
 159 Shift and Alt) and the pointer buttons. See #GdkModifierType.
 160 @button: the button which was pressed or released, numbered from 1 to 5.
 161 Normally button 1 is the left mouse button, 2 is the middle button,
 162 and 3 is the right button. On 2-button mice, the middle button can often
 163 be simulated by pressing both mouse buttons together.
 164 @device: the device where the event originated.
 165 @x_root: the x coordinate of the pointer relative to the root of the screen.
 166 @y_root: the y coordinate of the pointer relative to the root of the screen.
 167
 168 <!-- ##### STRUCT GdkEventScroll ##### -->
 169 <para>
 170 Generated from button presses for the buttons 4 to 7. Wheel mice are
 171 usually configured to generate button press events for buttons 4 and 5
 172 when the wheel is turned.
 173 </para>
 174
 175 @type: the type of the event (%GDK_SCROLL).
 176 @window: the window which received the event.
 177 @send_event: %TRUE if the event was sent explicitly (e.g. using
 178 <function>XSendEvent</function>).
 179 @time: the time of the event in milliseconds.
 180 @x: the x coordinate of the pointer relative to the window.
 181 @y: the y coordinate of the pointer relative to the window.
 182 @state: a bit-mask representing the state of the modifier keys (e.g. Control,
 183 Shift and Alt) and the pointer buttons. See #GdkModifierType.
 184 @direction: the direction to scroll to (one of %GDK_SCROLL_UP,
 185   %GDK_SCROLL_DOWN, %GDK_SCROLL_LEFT and %GDK_SCROLL_RIGHT).
 186 @device: the device where the event originated.
 187 @x_root: the x coordinate of the pointer relative to the root of the screen.
 188 @y_root: the y coordinate of the pointer relative to the root of the screen.
 189
 190 <!-- ##### STRUCT GdkEventMotion ##### -->
 191 <para>
 192 Generated when the pointer moves.
 193 </para>
 194
 195 @type: the type of the event.
 196 @window: the window which received the event.
 197 @send_event: %TRUE if the event was sent explicitly (e.g. using
 198 <function>XSendEvent</function>).
 199 @time: the time of the event in milliseconds.
 200 @x: the x coordinate of the pointer relative to the window.
 201 @y: the y coordinate of the pointer relative to the window.
 202 @axes: @x, @y translated to the axes of @device, or %NULL if @device is
 203   the mouse.
 204 @state: a bit-mask representing the state of the modifier keys (e.g. Control,
 205   Shift and Alt) and the pointer buttons. See #GdkModifierType.
 206 @is_hint:
 207 @device: the device where the event originated.
 208 @x_root: the x coordinate of the pointer relative to the root of the screen.
 209 @y_root: the y coordinate of the pointer relative to the root of the screen.
 210
 211 <!-- ##### STRUCT GdkEventExpose ##### -->
 212 <para>
 213 Generated when all or part of a window becomes visible and needs to be
 214 redrawn.
 215 </para>
 216
 217 @type: the type of the event (%GDK_EXPOSE).
 218 @window: the window which received the event.
 219 @send_event: %TRUE if the event was sent explicitly (e.g. using
 220 <function>XSendEvent</function>).
 221 @area: bounding box of @region.
 222 @region: the region that needs to be redrawn.
 223 @count: the number of contiguous %GDK_EXPOSE events following this one.
 224 The only use for this is "exposure compression", i.e. handling all contiguous
 225 %GDK_EXPOSE events in one go, though GDK performs some exposure compression
 226 so this is not normally needed.
 227
 228 <!-- ##### STRUCT GdkEventVisibility ##### -->
 229 <para>
 230 Generated when the window visibility status has changed.
 231 </para>
 232
 233 @type: the type of the event (%GDK_VISIBILITY_NOTIFY).
 234 @window: the window which received the event.
 235 @send_event: %TRUE if the event was sent explicitly (e.g. using
 236 <function>XSendEvent</function>).
 237 @state: the new visibility state (%GDK_VISIBILITY_FULLY_OBSCURED,
 238 %GDK_VISIBILITY_PARTIAL or %GDK_VISIBILITY_UNOBSCURED).
 239
 240 <!-- ##### STRUCT GdkEventCrossing ##### -->
 241 <para>
 242 Generated when the pointer enters or leaves a window.
 243 </para>
 244
 245 @type: the type of the event (%GDK_ENTER_NOTIFY or %GDK_LEAVE_NOTIFY).
 246 @window: the window which received the event.
 247 @send_event: %TRUE if the event was sent explicitly (e.g. using
 248 <function>XSendEvent</function>).
 249 @subwindow: the window that was entered or left.
 250 @time: the time of the event in milliseconds.
 251 @x: the x coordinate of the pointer relative to the window.
 252 @y: the y coordinate of the pointer relative to the window.
 253 @x_root: the x coordinate of the pointer relative to the root of the screen.
 254 @y_root: the y coordinate of the pointer relative to the root of the screen.
 255 @mode: the crossing mode (%GDK_CROSSING_NORMAL, %GDK_CROSSING_GRAB or
 256   %GDK_CROSSING_UNGRAB).
 257 @detail: the kind of crossing that happened (%GDK_NOTIFY_INFERIOR,
 258   %GDK_NOTIFY_ANCESTOR, %GDK_NOTIFY_VIRTUAL, %GDK_NOTIFY_NONLINEAR or
 259   %GDK_NOTIFY_NONLINEAR_VIRTUAL).
 260 @focus: %TRUE if @window is the focus window or an inferior.
 261 @state: a bit-mask representing the state of the modifier keys (e.g. Control,
 262   Shift and Alt) and the pointer buttons. See #GdkModifierType.
 263
 264 <!-- ##### STRUCT GdkEventFocus ##### -->
 265 <para>
 266 Describes a change of keyboard focus.
 267 </para>
 268
 269 @type: the type of the event (%GDK_FOCUS_CHANGE).
 270 @window: the window which received the event.
 271 @send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
 272 @in: %TRUE if the window has gained the keyboard focus, %FALSE if it has lost
 273 the focus.
 274
 275 <!-- ##### STRUCT GdkEventConfigure ##### -->
 276 <para>
 277 Generated when a window size or position has changed.
 278 </para>
 279
 280 @type: the type of the event (%GDK_CONFIGURE).
 281 @window: the window which received the event.
 282 @send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
 283 @x: the new x coordinate of the window, relative to its parent.
 284 @y: the new y coordinate of the window, relative to its parent.
 285 @width: the new width of the window.
 286 @height: the new height of the window.
 287
 288 <!-- ##### STRUCT GdkEventProperty ##### -->
 289 <para>
 290 Describes a property change on a window.
 291 </para>
 292
 293 @type: the type of the event (%GDK_PROPERTY_NOTIFY).
 294 @window: the window which received the event.
 295 @send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
 296 @atom: the property that was changed.
 297 @time: the time of the event in milliseconds.
 298 @state: whether the property was changed (%GDK_PROPERTY_NEW_VALUE) or
 299 deleted (%GDK_PROPERTY_DELETE).
 300
 301 <!-- ##### STRUCT GdkEventSelection ##### -->
 302 <para>
 303 Generated when a selection is requested or ownership of a selection
 304 is taken over by another client application.
 305 </para>
 306
 307 @type: the type of the event (%GDK_SELECTION_CLEAR, %GDK_SELECTION_NOTIFY or
 308 %GDK_SELECTION_REQUEST).
 309 @window: the window which received the event.
 310 @send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
 311 @selection: the selection.
 312 @target: the target to which the selection should be converted.
 313 @property: the property in which to place the result of the conversion.
 314 @time: the time of the event in milliseconds.
 315 @requestor: the native window on which to place @property.
 316
 317 <!-- ##### TYPEDEF GdkNativeWindow ##### -->
 318 <para>
 319 Used to represent native windows (<type>Window</type>s for the X11 backend,
 320 <type>HWND</type>s for Win32).
 321 </para>
 322
 323
 324 <!-- ##### STRUCT GdkEventDND ##### -->
 325 <para>
 326 Generated during DND operations.
 327 </para>
 328
 329 @type: the type of the event (%GDK_DRAG_ENTER, %GDK_DRAG_LEAVE,
 330   %GDK_DRAG_MOTION, %GDK_DRAG_STATUS, %GDK_DROP_START or %GDK_DROP_FINISHED).
 331 @window: the window which received the event.
 332 @send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
 333 @context: the #GdkDragContext for the current DND operation.
 334 @time: the time of the event in milliseconds.
 335 @x_root: the x coordinate of the pointer relative to the root of the screen,
 336   only set for %GDK_DRAG_MOTION and %GDK_DROP_START.
 337 @y_root: the y coordinate of the pointer relative to the root of the screen,
 338   only set for %GDK_DRAG_MOTION and %GDK_DROP_START.
 339
 340 <!-- ##### STRUCT GdkEventProximity ##### -->
 341 <para>
 342 Proximity events are generated when using GDK's wrapper for the
 343 XInput extension. The XInput extension is an add-on for standard X
 344 that allows you to use nonstandard devices such as graphics tablets.
 345 A proximity event indicates that the stylus has moved in or out of
 346 contact with the tablet, or perhaps that the user's finger has moved
 347 in or out of contact with a touch screen.
 348 </para>
 349
 350 @type: the type of the event (%GDK_PROXIMITY_IN or %GDK_PROXIMITY_OUT).
 351 @window: the window which received the event.
 352 @send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
 353 @time: the time of the event in milliseconds.
 354 @device: the device where the event originated.
 355
 356 <!-- ##### STRUCT GdkEventClient ##### -->
 357 <para>
 358 An event sent by another client application.
 359 </para>
 360
 361 @type: the type of the event (%GDK_CLIENT_EVENT).
 362 @window: the window which received the event.
 363 @send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
 364 @message_type: the type of the message, which can be defined by the
 365 application.
 366 @data_format: the format of the data, given as the number of bits in each
 367 data element, i.e. 8, 16, or 32. 8-bit data uses the b array of the data
 368 union, 16-bit data uses the s array, and 32-bit data uses the l array.
 369
 370 <!-- ##### STRUCT GdkEventNoExpose ##### -->
 371 <para>
 372 Generated when the area of a #GdkDrawable being copied, with gdk_draw_drawable()
 373 or gdk_window_copy_area(), was completely available.
 374 </para>
 375 <para>
 376 FIXME: add more here.
 377 </para>
 378
 379 @type: the type of the event (%GDK_NO_EXPOSE).
 380 @window: the window which received the event.
 381 @send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
 382
 383 <!-- ##### STRUCT GdkEventWindowState ##### -->
 384 <para>
 385 Generated when the state of a toplevel window changes.
 386 </para>
 387
 388 @type: the type of the event (%GDK_WINDOW_STATE).
 389 @window: the window which received the event.
 390 @send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
 391 @changed_mask: mask specifying what flags have changed.
 392 @new_window_state: the new window state, a combination of #GdkWindowState bits.
 393
 394 <!-- ##### STRUCT GdkEventSetting ##### -->
 395 <para>
 396 Generated when a setting is modified.
 397 </para>
 398
 399 @type: the type of the event (%GDK_SETTING).
 400 @window: the window which received the event.
 401 @send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
 402 @action: what happened to the setting (%GDK_SETTING_ACTION_NEW,
 403   %GDK_SETTING_ACTION_CHANGED or %GDK_SETTING_ACTION_DELETED).
 404 @name: the name of the setting.
 405
 406 <!-- ##### ENUM GdkScrollDirection ##### -->
 407 <para>
 408 Specifies the direction for #GdkEventScroll.
 409 </para>
 410
 411 @GDK_SCROLL_UP: the window is scrolled up.
 412 @GDK_SCROLL_DOWN: the window is scrolled down.
 413 @GDK_SCROLL_LEFT: the window is scrolled to the left.
 414 @GDK_SCROLL_RIGHT: the window is scrolled to the right.
 415
 416 <!-- ##### ENUM GdkVisibilityState ##### -->
 417 <para>
 418 Specifies the visiblity status of a window for a #GdkEventVisibility.
 419 </para>
 420
 421 @GDK_VISIBILITY_UNOBSCURED: the window is completely visible.
 422 @GDK_VISIBILITY_PARTIAL: the window is partially visible.
 423 @GDK_VISIBILITY_FULLY_OBSCURED: the window is not visible at all.
 424
 425 <!-- ##### ENUM GdkCrossingMode ##### -->
 426 <para>
 427 Specifies the crossing mode for #GdkEventCrossing.
 428 </para>
 429
 430 @GDK_CROSSING_NORMAL: crossing because of pointer motion.
 431 @GDK_CROSSING_GRAB: crossing because a grab is activated.
 432 @GDK_CROSSING_UNGRAB: crossing because a grab is deactivated.
 433
 434 <!-- ##### ENUM GdkNotifyType ##### -->
 435 <para>
 436 Specifies the kind of crossing for #GdkEventCrossing.
 437 </para>
 438 <para>
 439 See the X11 protocol specification of <type>LeaveNotify</type> for
 440 full details of crossing event generation.
 441 </para>
 442
 443 @GDK_NOTIFY_ANCESTOR: the window is entered from an ancestor or
 444    left towards an ancestor.
 445 @GDK_NOTIFY_VIRTUAL: the pointer moves between an ancestor and an
 446     inferior of the window.
 447 @GDK_NOTIFY_INFERIOR: the window is entered from an inferior or
 448    left towards an inferior.
 449 @GDK_NOTIFY_NONLINEAR:  the window is entered from or left towards
 450    a window which is neither an ancestor nor an inferior.
 451 @GDK_NOTIFY_NONLINEAR_VIRTUAL: the pointer moves between two windows
 452    which are not ancestors of each other and the window is part of
 453    the ancestor chain between one of these windows and their least
 454    common ancestor.
 455 @GDK_NOTIFY_UNKNOWN:
 456
 457 <!-- ##### ENUM GdkPropertyState ##### -->
 458 <para>
 459 Specifies the type of a property change for a #GdkEventProperty.
 460 </para>
 461
 462 @GDK_PROPERTY_NEW_VALUE: the property value was changed.
 463 @GDK_PROPERTY_DELETE: the property was deleted.
 464
 465 <!-- ##### ENUM GdkWindowState ##### -->
 466 <para>
 467 Specifies the state of a toplevel window.
 468 </para>
 469
 470 @GDK_WINDOW_STATE_WITHDRAWN: the window is not shown.
 471 @GDK_WINDOW_STATE_ICONIFIED: the window is minimized.
 472 @GDK_WINDOW_STATE_MAXIMIZED: the window is maximized.
 473 @GDK_WINDOW_STATE_STICKY: the window is sticky.
 474 @GDK_WINDOW_STATE_FULLSCREEN:
 475
 476 <!-- ##### ENUM GdkSettingAction ##### -->
 477 <para>
 478 Specifies the kind of modification applied to a setting in a #GdkEventSetting.
 479 </para>
 480
 481 @GDK_SETTING_ACTION_NEW: a setting was added.
 482 @GDK_SETTING_ACTION_CHANGED: a setting was changed.
 483 @GDK_SETTING_ACTION_DELETED: a setting was deleted.
 484