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