Pileus Git - ~andy/gtk/blob - gdk/gdkevents.h

   1 /* GDK - The GIMP Drawing Kit
   2  * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 /*
  21  * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
  22  * file for a list of people on the GTK+ Team.  See the ChangeLog
  23  * files for a list of changes.  These files are distributed with
  24  * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  25  */
  26
  27 #if !defined (__GDK_H_INSIDE__) && !defined (GDK_COMPILATION)
  28 #error "Only <gdk/gdk.h> can be included directly."
  29 #endif
  30
  31 #ifndef __GDK_EVENTS_H__
  32 #define __GDK_EVENTS_H__
  33
  34 #include <gdk/gdkcolor.h>
  35 #include <gdk/gdktypes.h>
  36 #include <gdk/gdkdnd.h>
  37 #include <gdk/gdkdevice.h>
  38
  39 G_BEGIN_DECLS
  40
  41
  42 /**
  43  * SECTION:event_structs
  44  * @Short_description: Data structures specific to each type of event
  45  * @Title: Event Structures
  46  *
  47  * The event structs contain data specific to each type of event in GDK.
  48  *
  49  * <note>
  50  * <para>
  51  * A common mistake is to forget to set the event mask of a widget so that
  52  * the required events are received. See gtk_widget_set_events().
  53  * </para>
  54  * </note>
  55  */
  56
  57
  58 #define GDK_TYPE_EVENT          (gdk_event_get_type ())
  59
  60 /**
  61  * GDK_PRIORITY_EVENTS:
  62  *
  63  * This is the priority that events from the X server are given in the
  64  * <link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link>.
  65  */
  66 #define GDK_PRIORITY_EVENTS     (G_PRIORITY_DEFAULT)
  67
  68 /**
  69  * GDK_PRIORITY_REDRAW:
  70  *
  71  * This is the priority that the idle handler processing window updates
  72  * is given in the
  73  * <link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link>.
  74  */
  75 #define GDK_PRIORITY_REDRAW     (G_PRIORITY_HIGH_IDLE + 20)
  76
  77
  78 typedef struct _GdkEventAny         GdkEventAny;
  79 typedef struct _GdkEventExpose      GdkEventExpose;
  80 typedef struct _GdkEventVisibility  GdkEventVisibility;
  81 typedef struct _GdkEventMotion      GdkEventMotion;
  82 typedef struct _GdkEventButton      GdkEventButton;
  83 typedef struct _GdkEventScroll      GdkEventScroll;
  84 typedef struct _GdkEventKey         GdkEventKey;
  85 typedef struct _GdkEventFocus       GdkEventFocus;
  86 typedef struct _GdkEventCrossing    GdkEventCrossing;
  87 typedef struct _GdkEventConfigure   GdkEventConfigure;
  88 typedef struct _GdkEventProperty    GdkEventProperty;
  89 typedef struct _GdkEventSelection   GdkEventSelection;
  90 typedef struct _GdkEventOwnerChange GdkEventOwnerChange;
  91 typedef struct _GdkEventProximity   GdkEventProximity;
  92 typedef struct _GdkEventDND         GdkEventDND;
  93 typedef struct _GdkEventWindowState GdkEventWindowState;
  94 typedef struct _GdkEventSetting     GdkEventSetting;
  95 typedef struct _GdkEventGrabBroken  GdkEventGrabBroken;
  96
  97 typedef union  _GdkEvent            GdkEvent;
  98
  99 /**
 100  * GdkEventFunc:
 101  * @event: the #GdkEvent to process.
 102  * @data: (closure): user data set when the event handler was installed with
 103  *   gdk_event_handler_set().
 104  *
 105  * Specifies the type of function passed to gdk_event_handler_set() to
 106  * handle all GDK events.
 107  */
 108 typedef void (*GdkEventFunc) (GdkEvent *event,
 109                               gpointer  data);
 110
 111 /* Event filtering */
 112
 113 /**
 114  * GdkXEvent:
 115  *
 116  * Used to represent native events (<type>XEvent</type>s for the X11
 117  * backend, <type>MSG</type>s for Win32).
 118  */
 119 typedef void GdkXEvent;   /* Can be cast to window system specific
 120                            * even type, XEvent on X11, MSG on Win32.
 121                            */
 122
 123 /**
 124  * GdkFilterReturn:
 125  * @GDK_FILTER_CONTINUE: event not handled, continue processing.
 126  * @GDK_FILTER_TRANSLATE: native event translated into a GDK event and stored
 127  *  in the <literal>event</literal> structure that was passed in.
 128  * @GDK_FILTER_REMOVE: event handled, terminate processing.
 129  *
 130  * Specifies the result of applying a #GdkFilterFunc to a native event.
 131  */
 132 typedef enum {
 133   GDK_FILTER_CONTINUE,    /* Event not handled, continue processesing */
 134   GDK_FILTER_TRANSLATE,   /* Native event translated into a GDK event and
 135                              stored in the "event" structure that was
 136                              passed in */
 137   GDK_FILTER_REMOVE       /* Terminate processing, removing event */
 138 } GdkFilterReturn;
 139
 140 /**
 141  * GdkFilterFunc:
 142  * @xevent: the native event to filter.
 143  * @event: the GDK event to which the X event will be translated.
 144  * @data: user data set when the filter was installed.
 145  *
 146  * Specifies the type of function used to filter native events before they are
 147  * converted to GDK events.
 148  *
 149  * When a filter is called, @event is unpopulated, except for
 150  * <literal>event->window</literal>. The filter may translate the native
 151  * event to a GDK event and store the result in @event, or handle it without
 152  * translation. If the filter translates the event and processing should
 153  * continue, it should return %GDK_FILTER_TRANSLATE.
 154  *
 155  * Returns: a #GdkFilterReturn value.
 156  */
 157 typedef GdkFilterReturn (*GdkFilterFunc) (GdkXEvent *xevent,
 158                                           GdkEvent *event,
 159                                           gpointer  data);
 160
 161
 162 /**
 163  * GdkEventType:
 164  * @GDK_NOTHING: a special code to indicate a null event.
 165  * @GDK_DELETE: the window manager has requested that the toplevel window be
 166  *   hidden or destroyed, usually when the user clicks on a special icon in the
 167  *   title bar.
 168  * @GDK_DESTROY: the window has been destroyed.
 169  * @GDK_EXPOSE: all or part of the window has become visible and needs to be
 170  *   redrawn.
 171  * @GDK_MOTION_NOTIFY: the pointer (usually a mouse) has moved.
 172  * @GDK_BUTTON_PRESS: a mouse button has been pressed.
 173  * @GDK_2BUTTON_PRESS: a mouse button has been double-clicked (clicked twice
 174  *   within a short period of time). Note that each click also generates a
 175  *   %GDK_BUTTON_PRESS event.
 176  * @GDK_3BUTTON_PRESS: a mouse button has been clicked 3 times in a short period
 177  *   of time. Note that each click also generates a %GDK_BUTTON_PRESS event.
 178  * @GDK_BUTTON_RELEASE: a mouse button has been released.
 179  * @GDK_KEY_PRESS: a key has been pressed.
 180  * @GDK_KEY_RELEASE: a key has been released.
 181  * @GDK_ENTER_NOTIFY: the pointer has entered the window.
 182  * @GDK_LEAVE_NOTIFY: the pointer has left the window.
 183  * @GDK_FOCUS_CHANGE: the keyboard focus has entered or left the window.
 184  * @GDK_CONFIGURE: the size, position or stacking order of the window has changed.
 185  *   Note that GTK+ discards these events for %GDK_WINDOW_CHILD windows.
 186  * @GDK_MAP: the window has been mapped.
 187  * @GDK_UNMAP: the window has been unmapped.
 188  * @GDK_PROPERTY_NOTIFY: a property on the window has been changed or deleted.
 189  * @GDK_SELECTION_CLEAR: the application has lost ownership of a selection.
 190  * @GDK_SELECTION_REQUEST: another application has requested a selection.
 191  * @GDK_SELECTION_NOTIFY: a selection has been received.
 192  * @GDK_PROXIMITY_IN: an input device has moved into contact with a sensing
 193  *   surface (e.g. a touchscreen or graphics tablet).
 194  * @GDK_PROXIMITY_OUT: an input device has moved out of contact with a sensing
 195  *   surface.
 196  * @GDK_DRAG_ENTER: the mouse has entered the window while a drag is in progress.
 197  * @GDK_DRAG_LEAVE: the mouse has left the window while a drag is in progress.
 198  * @GDK_DRAG_MOTION: the mouse has moved in the window while a drag is in
 199  *   progress.
 200  * @GDK_DRAG_STATUS: the status of the drag operation initiated by the window
 201  *   has changed.
 202  * @GDK_DROP_START: a drop operation onto the window has started.
 203  * @GDK_DROP_FINISHED: the drop operation initiated by the window has completed.
 204  * @GDK_CLIENT_EVENT: a message has been received from another application.
 205  * @GDK_VISIBILITY_NOTIFY: the window visibility status has changed.
 206  * @GDK_SCROLL: the scroll wheel was turned
 207  * @GDK_WINDOW_STATE: the state of a window has changed. See #GdkWindowState
 208  *   for the possible window states
 209  * @GDK_SETTING: a setting has been modified.
 210  * @GDK_OWNER_CHANGE: the owner of a selection has changed. This event type
 211  *   was added in 2.6
 212  * @GDK_GRAB_BROKEN: a pointer or keyboard grab was broken. This event type
 213  *   was added in 2.8.
 214  * @GDK_DAMAGE: the content of the window has been changed. This event type
 215  *   was added in 2.14.
 216  * @GDK_EVENT_LAST: marks the end of the GdkEventType enumeration. Added in 2.18
 217  *
 218  * Specifies the type of the event.
 219  *
 220  * Do not confuse these events with the signals that GTK+ widgets emit.
 221  * Although many of these events result in corresponding signals being emitted,
 222  * the events are often transformed or filtered along the way.
 223  */
 224 typedef enum
 225 {
 226   GDK_NOTHING           = -1,
 227   GDK_DELETE            = 0,
 228   GDK_DESTROY           = 1,
 229   GDK_EXPOSE            = 2,
 230   GDK_MOTION_NOTIFY     = 3,
 231   GDK_BUTTON_PRESS      = 4,
 232   GDK_2BUTTON_PRESS     = 5,
 233   GDK_3BUTTON_PRESS     = 6,
 234   GDK_BUTTON_RELEASE    = 7,
 235   GDK_KEY_PRESS         = 8,
 236   GDK_KEY_RELEASE       = 9,
 237   GDK_ENTER_NOTIFY      = 10,
 238   GDK_LEAVE_NOTIFY      = 11,
 239   GDK_FOCUS_CHANGE      = 12,
 240   GDK_CONFIGURE         = 13,
 241   GDK_MAP               = 14,
 242   GDK_UNMAP             = 15,
 243   GDK_PROPERTY_NOTIFY   = 16,
 244   GDK_SELECTION_CLEAR   = 17,
 245   GDK_SELECTION_REQUEST = 18,
 246   GDK_SELECTION_NOTIFY  = 19,
 247   GDK_PROXIMITY_IN      = 20,
 248   GDK_PROXIMITY_OUT     = 21,
 249   GDK_DRAG_ENTER        = 22,
 250   GDK_DRAG_LEAVE        = 23,
 251   GDK_DRAG_MOTION       = 24,
 252   GDK_DRAG_STATUS       = 25,
 253   GDK_DROP_START        = 26,
 254   GDK_DROP_FINISHED     = 27,
 255   GDK_CLIENT_EVENT      = 28,
 256   GDK_VISIBILITY_NOTIFY = 29,
 257   GDK_SCROLL            = 31,
 258   GDK_WINDOW_STATE      = 32,
 259   GDK_SETTING           = 33,
 260   GDK_OWNER_CHANGE      = 34,
 261   GDK_GRAB_BROKEN       = 35,
 262   GDK_DAMAGE            = 36,
 263   GDK_EVENT_LAST        /* helper variable for decls */
 264 } GdkEventType;
 265
 266 /**
 267  * GdkVisibilityState:
 268  * @GDK_VISIBILITY_UNOBSCURED: the window is completely visible.
 269  * @GDK_VISIBILITY_PARTIAL: the window is partially visible.
 270  * @GDK_VISIBILITY_FULLY_OBSCURED: the window is not visible at all.
 271  *
 272  * Specifies the visiblity status of a window for a #GdkEventVisibility.
 273  */
 274 typedef enum
 275 {
 276   GDK_VISIBILITY_UNOBSCURED,
 277   GDK_VISIBILITY_PARTIAL,
 278   GDK_VISIBILITY_FULLY_OBSCURED
 279 } GdkVisibilityState;
 280
 281 /**
 282  * GdkScrollDirection:
 283  * @GDK_SCROLL_UP: the window is scrolled up.
 284  * @GDK_SCROLL_DOWN: the window is scrolled down.
 285  * @GDK_SCROLL_LEFT: the window is scrolled to the left.
 286  * @GDK_SCROLL_RIGHT: the window is scrolled to the right.
 287  *
 288  * Specifies the direction for #GdkEventScroll.
 289  */
 290 typedef enum
 291 {
 292   GDK_SCROLL_UP,
 293   GDK_SCROLL_DOWN,
 294   GDK_SCROLL_LEFT,
 295   GDK_SCROLL_RIGHT
 296 } GdkScrollDirection;
 297
 298 /**
 299  * GdkNotifyType:
 300  * @GDK_NOTIFY_ANCESTOR: the window is entered from an ancestor or
 301  *   left towards an ancestor.
 302  * @GDK_NOTIFY_VIRTUAL: the pointer moves between an ancestor and an
 303  *   inferior of the window.
 304  * @GDK_NOTIFY_INFERIOR: the window is entered from an inferior or
 305  *   left towards an inferior.
 306  * @GDK_NOTIFY_NONLINEAR: the window is entered from or left towards
 307  *   a window which is neither an ancestor nor an inferior.
 308  * @GDK_NOTIFY_NONLINEAR_VIRTUAL: the pointer moves between two windows
 309  *   which are not ancestors of each other and the window is part of
 310  *   the ancestor chain between one of these windows and their least
 311  *   common ancestor.
 312  * @GDK_NOTIFY_UNKNOWN: an unknown type of enter/leave event occurred.
 313  *
 314  * Specifies the kind of crossing for #GdkEventCrossing.
 315  *
 316  * See the X11 protocol specification of <type>LeaveNotify</type> for
 317  * full details of crossing event generation.
 318  */
 319 typedef enum
 320 {
 321   GDK_NOTIFY_ANCESTOR           = 0,
 322   GDK_NOTIFY_VIRTUAL            = 1,
 323   GDK_NOTIFY_INFERIOR           = 2,
 324   GDK_NOTIFY_NONLINEAR          = 3,
 325   GDK_NOTIFY_NONLINEAR_VIRTUAL  = 4,
 326   GDK_NOTIFY_UNKNOWN            = 5
 327 } GdkNotifyType;
 328
 329 /**
 330  * GdkCrossingMode:
 331  * @GDK_CROSSING_NORMAL: crossing because of pointer motion.
 332  * @GDK_CROSSING_GRAB: crossing because a grab is activated.
 333  * @GDK_CROSSING_UNGRAB: crossing because a grab is deactivated.
 334  * @GDK_CROSSING_GTK_GRAB: crossing because a GTK+ grab is activated.
 335  * @GDK_CROSSING_GTK_UNGRAB: crossing because a GTK+ grab is deactivated.
 336  * @GDK_CROSSING_STATE_CHANGED: crossing because a GTK+ widget changed
 337  *   state (e.g. sensitivity).
 338  *
 339  * Specifies the crossing mode for #GdkEventCrossing.
 340  */
 341 typedef enum
 342 {
 343   GDK_CROSSING_NORMAL,
 344   GDK_CROSSING_GRAB,
 345   GDK_CROSSING_UNGRAB,
 346   GDK_CROSSING_GTK_GRAB,
 347   GDK_CROSSING_GTK_UNGRAB,
 348   GDK_CROSSING_STATE_CHANGED
 349 } GdkCrossingMode;
 350
 351 /**
 352  * GdkPropertyState:
 353  * @GDK_PROPERTY_NEW_VALUE: the property value was changed.
 354  * @GDK_PROPERTY_DELETE: the property was deleted.
 355  *
 356  * Specifies the type of a property change for a #GdkEventProperty.
 357  */
 358 typedef enum
 359 {
 360   GDK_PROPERTY_NEW_VALUE,
 361   GDK_PROPERTY_DELETE
 362 } GdkPropertyState;
 363
 364 /**
 365  * GdkWindowState:
 366  * @GDK_WINDOW_STATE_WITHDRAWN: the window is not shown.
 367  * @GDK_WINDOW_STATE_ICONIFIED: the window is minimized.
 368  * @GDK_WINDOW_STATE_MAXIMIZED: the window is maximized.
 369  * @GDK_WINDOW_STATE_STICKY: the window is sticky.
 370  * @GDK_WINDOW_STATE_FULLSCREEN: the window is maximized without
 371  *   decorations.
 372  * @GDK_WINDOW_STATE_ABOVE: the window is kept above other windows.
 373  * @GDK_WINDOW_STATE_BELOW: the window is kept below other windows.
 374  * @GDK_WINDOW_STATE_FOCUSED: the window is presented as focused (with active decorations).
 375  *
 376  * Specifies the state of a toplevel window.
 377  */
 378 typedef enum
 379 {
 380   GDK_WINDOW_STATE_WITHDRAWN  = 1 << 0,
 381   GDK_WINDOW_STATE_ICONIFIED  = 1 << 1,
 382   GDK_WINDOW_STATE_MAXIMIZED  = 1 << 2,
 383   GDK_WINDOW_STATE_STICKY     = 1 << 3,
 384   GDK_WINDOW_STATE_FULLSCREEN = 1 << 4,
 385   GDK_WINDOW_STATE_ABOVE      = 1 << 5,
 386   GDK_WINDOW_STATE_BELOW      = 1 << 6,
 387   GDK_WINDOW_STATE_FOCUSED    = 1 << 7
 388 } GdkWindowState;
 389
 390 /**
 391  * GdkSettingAction:
 392  * @GDK_SETTING_ACTION_NEW: a setting was added.
 393  * @GDK_SETTING_ACTION_CHANGED: a setting was changed.
 394  * @GDK_SETTING_ACTION_DELETED: a setting was deleted.
 395  *
 396  * Specifies the kind of modification applied to a setting in a
 397  * #GdkEventSetting.
 398  */
 399 typedef enum
 400 {
 401   GDK_SETTING_ACTION_NEW,
 402   GDK_SETTING_ACTION_CHANGED,
 403   GDK_SETTING_ACTION_DELETED
 404 } GdkSettingAction;
 405
 406 /**
 407  * GdkOwnerChange:
 408  * @GDK_OWNER_CHANGE_NEW_OWNER: some other app claimed the ownership
 409  * @GDK_OWNER_CHANGE_DESTROY: the window was destroyed
 410  * @GDK_OWNER_CHANGE_CLOSE: the client was closed
 411  *
 412  * Specifies why a selection ownership was changed.
 413  */
 414 typedef enum
 415 {
 416   GDK_OWNER_CHANGE_NEW_OWNER,
 417   GDK_OWNER_CHANGE_DESTROY,
 418   GDK_OWNER_CHANGE_CLOSE
 419 } GdkOwnerChange;
 420
 421 /**
 422  * GdkEventAny:
 423  * @type: the type of the event.
 424  * @window: the window which received the event.
 425  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 426  *   <function>XSendEvent</function>).
 427  *
 428  * Contains the fields which are common to all event structs.
 429  * Any event pointer can safely be cast to a pointer to a #GdkEventAny to
 430  * access these fields.
 431  */
 432 struct _GdkEventAny
 433 {
 434   GdkEventType type;
 435   GdkWindow *window;
 436   gint8 send_event;
 437 };
 438
 439 /**
 440  * GdkEventExpose:
 441  * @type: the type of the event (%GDK_EXPOSE or %GDK_DAMAGE).
 442  * @window: the window which received the event.
 443  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 444  *   <function>XSendEvent</function>).
 445  * @area: bounding box of @region.
 446  * @region: the region that needs to be redrawn.
 447  * @count: the number of contiguous %GDK_EXPOSE events following this one.
 448  *   The only use for this is "exposure compression", i.e. handling all
 449  *   contiguous %GDK_EXPOSE events in one go, though GDK performs some
 450  *   exposure compression so this is not normally needed.
 451  *
 452  * Generated when all or part of a window becomes visible and needs to be
 453  * redrawn.
 454  */
 455 struct _GdkEventExpose
 456 {
 457   GdkEventType type;
 458   GdkWindow *window;
 459   gint8 send_event;
 460   GdkRectangle area;
 461   cairo_region_t *region;
 462   gint count; /* If non-zero, how many more events follow. */
 463 };
 464
 465 /**
 466  * GdkEventVisibility:
 467  * @type: the type of the event (%GDK_VISIBILITY_NOTIFY).
 468  * @window: the window which received the event.
 469  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 470  *   <function>XSendEvent</function>).
 471  * @state: the new visibility state (%GDK_VISIBILITY_FULLY_OBSCURED,
 472  *   %GDK_VISIBILITY_PARTIAL or %GDK_VISIBILITY_UNOBSCURED).
 473  *
 474  * Generated when the window visibility status has changed.
 475  */
 476 struct _GdkEventVisibility
 477 {
 478   GdkEventType type;
 479   GdkWindow *window;
 480   gint8 send_event;
 481   GdkVisibilityState state;
 482 };
 483
 484 /**
 485  * GdkEventMotion:
 486  * @type: the type of the event.
 487  * @window: the window which received the event.
 488  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 489  *   <function>XSendEvent</function>).
 490  * @time: the time of the event in milliseconds.
 491  * @x: the x coordinate of the pointer relative to the window.
 492  * @y: the y coordinate of the pointer relative to the window.
 493  * @axes: @x, @y translated to the axes of @device, or %NULL if @device is
 494  *   the mouse.
 495  * @state: (type GdkModifierType): a bit-mask representing the state of
 496  *   the modifier keys (e.g. Control, Shift and Alt) and the pointer
 497  *   buttons. See #GdkModifierType.
 498  * @is_hint: set to 1 if this event is just a hint, see the
 499  *   %GDK_POINTER_MOTION_HINT_MASK value of #GdkEventMask.
 500  * @device: the device where the event originated.
 501  * @x_root: the x coordinate of the pointer relative to the root of the
 502  *   screen.
 503  * @y_root: the y coordinate of the pointer relative to the root of the
 504  *   screen.
 505  *
 506  * Generated when the pointer moves.
 507  */
 508 struct _GdkEventMotion
 509 {
 510   GdkEventType type;
 511   GdkWindow *window;
 512   gint8 send_event;
 513   guint32 time;
 514   gdouble x;
 515   gdouble y;
 516   gdouble *axes;
 517   guint state;
 518   gint16 is_hint;
 519   GdkDevice *device;
 520   gdouble x_root, y_root;
 521 };
 522
 523 /**
 524  * GdkEventButton:
 525  * @type: the type of the event (%GDK_BUTTON_PRESS, %GDK_2BUTTON_PRESS,
 526  *   %GDK_3BUTTON_PRESS or %GDK_BUTTON_RELEASE).
 527  * @window: the window which received the event.
 528  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 529  *   <function>XSendEvent</function>).
 530  * @time: the time of the event in milliseconds.
 531  * @x: the x coordinate of the pointer relative to the window.
 532  * @y: the y coordinate of the pointer relative to the window.
 533  * @axes: @x, @y translated to the axes of @device, or %NULL if @device is
 534  *   the mouse.
 535  * @state: (type GdkModifierType): a bit-mask representing the state of
 536  *   the modifier keys (e.g. Control, Shift and Alt) and the pointer
 537  *   buttons. See #GdkModifierType.
 538  * @button: the button which was pressed or released, numbered from 1 to 5.
 539  *   Normally button 1 is the left mouse button, 2 is the middle button,
 540  *   and 3 is the right button. On 2-button mice, the middle button can
 541  *   often be simulated by pressing both mouse buttons together.
 542  * @device: the device where the event originated.
 543  * @x_root: the x coordinate of the pointer relative to the root of the
 544  *   screen.
 545  * @y_root: the y coordinate of the pointer relative to the root of the
 546  *   screen.
 547  *
 548  * Used for button press and button release events. The
 549  * @type field will be one of %GDK_BUTTON_PRESS,
 550  * %GDK_2BUTTON_PRESS, %GDK_3BUTTON_PRESS, and %GDK_BUTTON_RELEASE.
 551  *
 552  * Double and triple-clicks result in a sequence of events being received.
 553  * For double-clicks the order of events will be:
 554  * <orderedlist>
 555  * <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
 556  * <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
 557  * <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
 558  * <listitem><para>%GDK_2BUTTON_PRESS</para></listitem>
 559  * <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
 560  * </orderedlist>
 561  * Note that the first click is received just like a normal
 562  * button press, while the second click results in a %GDK_2BUTTON_PRESS
 563  * being received just after the %GDK_BUTTON_PRESS.
 564  *
 565  * Triple-clicks are very similar to double-clicks, except that
 566  * %GDK_3BUTTON_PRESS is inserted after the third click. The order of the
 567  * events is:
 568  * <orderedlist>
 569  * <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
 570  * <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
 571  * <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
 572  * <listitem><para>%GDK_2BUTTON_PRESS</para></listitem>
 573  * <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
 574  * <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
 575  * <listitem><para>%GDK_3BUTTON_PRESS</para></listitem>
 576  * <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
 577  * </orderedlist>
 578  *
 579  * For a double click to occur, the second button press must occur within
 580  * 1/4 of a second of the first. For a triple click to occur, the third
 581  * button press must also occur within 1/2 second of the first button press.
 582  */
 583 struct _GdkEventButton
 584 {
 585   GdkEventType type;
 586   GdkWindow *window;
 587   gint8 send_event;
 588   guint32 time;
 589   gdouble x;
 590   gdouble y;
 591   gdouble *axes;
 592   guint state;
 593   guint button;
 594   GdkDevice *device;
 595   gdouble x_root, y_root;
 596 };
 597
 598 /**
 599  * GdkEventScroll:
 600  * @type: the type of the event (%GDK_SCROLL).
 601  * @window: the window which received the event.
 602  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 603  *   <function>XSendEvent</function>).
 604  * @time: the time of the event in milliseconds.
 605  * @x: the x coordinate of the pointer relative to the window.
 606  * @y: the y coordinate of the pointer relative to the window.
 607  * @state: (type GdkModifierType): a bit-mask representing the state of
 608  *   the modifier keys (e.g. Control, Shift and Alt) and the pointer
 609  *   buttons. See #GdkModifierType.
 610  * @direction: the direction to scroll to (one of %GDK_SCROLL_UP,
 611  *   %GDK_SCROLL_DOWN, %GDK_SCROLL_LEFT and %GDK_SCROLL_RIGHT).
 612  * @device: the device where the event originated.
 613  * @x_root: the x coordinate of the pointer relative to the root of the
 614  *   screen.
 615  * @y_root: the y coordinate of the pointer relative to the root of the
 616  *   screen.
 617  *
 618  * Generated from button presses for the buttons 4 to 7. Wheel mice are
 619  * usually configured to generate button press events for buttons 4 and 5
 620  * when the wheel is turned.
 621  */
 622 struct _GdkEventScroll
 623 {
 624   GdkEventType type;
 625   GdkWindow *window;
 626   gint8 send_event;
 627   guint32 time;
 628   gdouble x;
 629   gdouble y;
 630   guint state;
 631   GdkScrollDirection direction;
 632   GdkDevice *device;
 633   gdouble x_root, y_root;
 634 };
 635
 636 /**
 637  * GdkEventKey:
 638  * @type: the type of the event (%GDK_KEY_PRESS or %GDK_KEY_RELEASE).
 639  * @window: the window which received the event.
 640  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 641  *   <function>XSendEvent</function>).
 642  * @time: the time of the event in milliseconds.
 643  * @state: (type GdkModifierType): a bit-mask representing the state of
 644  *   the modifier keys (e.g. Control, Shift and Alt) and the pointer
 645  *   buttons. See #GdkModifierType.
 646  * @keyval: the key that was pressed or released. See the
 647  *   <filename>&lt;gdk/gdkkeysyms.h&gt;</filename> header file for a
 648  *   complete list of GDK key codes.
 649  * @length: the length of @string.
 650  * @string: a string containing the an approximation of the text that
 651  *   would result from this keypress. The only correct way to handle text
 652  *   input of text is using input methods (see #GtkIMContext), so this
 653  *   field is deprecated and should never be used.
 654  *   (gdk_unicode_to_keyval() provides a non-deprecated way of getting
 655  *   an approximate translation for a key.) The string is encoded in the
 656  *   encoding of the current locale (Note: this for backwards compatibility:
 657  *   strings in GTK+ and GDK are typically in UTF-8.) and NUL-terminated.
 658  *   In some cases, the translation of the key code will be a single
 659  *   NUL byte, in which case looking at @length is necessary to distinguish
 660  *   it from the an empty translation.
 661  * @hardware_keycode: the raw code of the key that was pressed or released.
 662  * @group: the keyboard group.
 663  * @is_modifier: a flag that indicates if @hardware_keycode is mapped to a
 664  *   modifier. Since 2.10
 665  *
 666  * Describes a key press or key release event.
 667  */
 668 struct _GdkEventKey
 669 {
 670   GdkEventType type;
 671   GdkWindow *window;
 672   gint8 send_event;
 673   guint32 time;
 674   guint state;
 675   guint keyval;
 676   gint length;
 677   gchar *string;
 678   guint16 hardware_keycode;
 679   guint8 group;
 680   guint is_modifier : 1;
 681 };
 682
 683 /**
 684  * GdkEventCrossing:
 685  * @type: the type of the event (%GDK_ENTER_NOTIFY or %GDK_LEAVE_NOTIFY).
 686  * @window: the window which received the event.
 687  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 688  *  <function>XSendEvent</function>).
 689  * @subwindow: the window that was entered or left.
 690  * @time: the time of the event in milliseconds.
 691  * @x: the x coordinate of the pointer relative to the window.
 692  * @y: the y coordinate of the pointer relative to the window.
 693  * @x_root: the x coordinate of the pointer relative to the root of the screen.
 694  * @y_root: the y coordinate of the pointer relative to the root of the screen.
 695  * @mode: the crossing mode (%GDK_CROSSING_NORMAL, %GDK_CROSSING_GRAB,
 696  *  %GDK_CROSSING_UNGRAB, %GDK_CROSSING_GTK_GRAB, %GDK_CROSSING_GTK_UNGRAB or
 697  *  %GDK_CROSSING_STATE_CHANGED).  %GDK_CROSSING_GTK_GRAB, %GDK_CROSSING_GTK_UNGRAB,
 698  *  and %GDK_CROSSING_STATE_CHANGED were added in 2.14 and are always synthesized,
 699  *  never native.
 700  * @detail: the kind of crossing that happened (%GDK_NOTIFY_INFERIOR,
 701  *  %GDK_NOTIFY_ANCESTOR, %GDK_NOTIFY_VIRTUAL, %GDK_NOTIFY_NONLINEAR or
 702  *  %GDK_NOTIFY_NONLINEAR_VIRTUAL).
 703  * @focus: %TRUE if @window is the focus window or an inferior.
 704  * @state: (type GdkModifierType): a bit-mask representing the state of
 705  *   the modifier keys (e.g. Control, Shift and Alt) and the pointer
 706  *   buttons. See #GdkModifierType.
 707  *
 708  * Generated when the pointer enters or leaves a window.
 709  */
 710 struct _GdkEventCrossing
 711 {
 712   GdkEventType type;
 713   GdkWindow *window;
 714   gint8 send_event;
 715   GdkWindow *subwindow;
 716   guint32 time;
 717   gdouble x;
 718   gdouble y;
 719   gdouble x_root;
 720   gdouble y_root;
 721   GdkCrossingMode mode;
 722   GdkNotifyType detail;
 723   gboolean focus;
 724   guint state;
 725 };
 726
 727 /**
 728  * GdkEventFocus:
 729  * @type: the type of the event (%GDK_FOCUS_CHANGE).
 730  * @window: the window which received the event.
 731  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 732  *   <function>XSendEvent</function>).
 733  * @in: %TRUE if the window has gained the keyboard focus, %FALSE if
 734  *   it has lost the focus.
 735  *
 736  * Describes a change of keyboard focus.
 737  */
 738 struct _GdkEventFocus
 739 {
 740   GdkEventType type;
 741   GdkWindow *window;
 742   gint8 send_event;
 743   gint16 in;
 744 };
 745
 746 /**
 747  * GdkEventConfigure:
 748  * @type: the type of the event (%GDK_CONFIGURE).
 749  * @window: the window which received the event.
 750  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 751  *   <function>XSendEvent</function>).
 752  * @x: the new x coordinate of the window, relative to its parent.
 753  * @y: the new y coordinate of the window, relative to its parent.
 754  * @width: the new width of the window.
 755  * @height: the new height of the window.
 756  *
 757  * Generated when a window size or position has changed.
 758  */
 759 struct _GdkEventConfigure
 760 {
 761   GdkEventType type;
 762   GdkWindow *window;
 763   gint8 send_event;
 764   gint x, y;
 765   gint width;
 766   gint height;
 767 };
 768
 769 /**
 770  * GdkEventProperty:
 771  * @type: the type of the event (%GDK_PROPERTY_NOTIFY).
 772  * @window: the window which received the event.
 773  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 774  *   <function>XSendEvent</function>).
 775  * @atom: the property that was changed.
 776  * @time: the time of the event in milliseconds.
 777  * @state: whether the property was changed (%GDK_PROPERTY_NEW_VALUE) or
 778  *   deleted (%GDK_PROPERTY_DELETE).
 779  *
 780  * Describes a property change on a window.
 781  */
 782 struct _GdkEventProperty
 783 {
 784   GdkEventType type;
 785   GdkWindow *window;
 786   gint8 send_event;
 787   GdkAtom atom;
 788   guint32 time;
 789   guint state;
 790 };
 791
 792 /**
 793  * GdkEventSelection:
 794  * @type: the type of the event (%GDK_SELECTION_CLEAR,
 795  *   %GDK_SELECTION_NOTIFY or %GDK_SELECTION_REQUEST).
 796  * @window: the window which received the event.
 797  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 798  *   <function>XSendEvent</function>).
 799  * @selection: the selection.
 800  * @target: the target to which the selection should be converted.
 801  * @property: the property in which to place the result of the conversion.
 802  * @time: the time of the event in milliseconds.
 803  * @requestor: the window on which to place @property or %NULL if none.
 804  *
 805  * Generated when a selection is requested or ownership of a selection
 806  * is taken over by another client application.
 807  */
 808 struct _GdkEventSelection
 809 {
 810   GdkEventType type;
 811   GdkWindow *window;
 812   gint8 send_event;
 813   GdkAtom selection;
 814   GdkAtom target;
 815   GdkAtom property;
 816   guint32 time;
 817   GdkWindow *requestor;
 818 };
 819
 820 /**
 821  * GdkEventOwnerChange:
 822  * @type: the type of the event (%GDK_OWNER_CHANGE).
 823  * @window: the window which received the event
 824  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 825  *   <function>XSendEvent</function>)
 826  * @owner: the new owner of the selection, or %NULL if there is none
 827  * @reason: the reason for the ownership change as a #GdkOwnerChange value
 828  * @selection: the atom identifying the selection
 829  * @time: the timestamp of the event
 830  * @selection_time: the time at which the selection ownership was taken
 831  *   over
 832  *
 833  * Generated when the owner of a selection changes. On X11, this
 834  * information is only available if the X server supports the XFIXES
 835  * extension.
 836  *
 837  * Since: 2.6
 838  */
 839 struct _GdkEventOwnerChange
 840 {
 841   GdkEventType type;
 842   GdkWindow *window;
 843   gint8 send_event;
 844   GdkWindow *owner;
 845   GdkOwnerChange reason;
 846   GdkAtom selection;
 847   guint32 time;
 848   guint32 selection_time;
 849 };
 850
 851 /**
 852  * GdkEventProximity:
 853  * @type: the type of the event (%GDK_PROXIMITY_IN or %GDK_PROXIMITY_OUT).
 854  * @window: the window which received the event.
 855  * @send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
 856  * @time: the time of the event in milliseconds.
 857  * @device: the device where the event originated.
 858  *
 859  * Proximity events are generated when using GDK's wrapper for the
 860  * XInput extension. The XInput extension is an add-on for standard X
 861  * that allows you to use nonstandard devices such as graphics tablets.
 862  * A proximity event indicates that the stylus has moved in or out of
 863  * contact with the tablet, or perhaps that the user's finger has moved
 864  * in or out of contact with a touch screen.
 865  *
 866  * This event type will be used pretty rarely. It only is important for
 867  * XInput aware programs that are drawing their own cursor.
 868  */
 869 struct _GdkEventProximity
 870 {
 871   GdkEventType type;
 872   GdkWindow *window;
 873   gint8 send_event;
 874   guint32 time;
 875   GdkDevice *device;
 876 };
 877
 878 /**
 879  * GdkEventSetting:
 880  * @type: the type of the event (%GDK_SETTING).
 881  * @window: the window which received the event.
 882  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 883  *   <function>XSendEvent</function>).
 884  * @action: what happened to the setting (%GDK_SETTING_ACTION_NEW,
 885  *   %GDK_SETTING_ACTION_CHANGED or %GDK_SETTING_ACTION_DELETED).
 886  * @name: the name of the setting.
 887  *
 888  * Generated when a setting is modified.
 889  */
 890 struct _GdkEventSetting
 891 {
 892   GdkEventType type;
 893   GdkWindow *window;
 894   gint8 send_event;
 895   GdkSettingAction action;
 896   char *name;
 897 };
 898
 899 /**
 900  * GdkEventWindowState:
 901  * @type: the type of the event (%GDK_WINDOW_STATE).
 902  * @window: the window which received the event.
 903  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 904  *   <function>XSendEvent</function>).
 905  * @changed_mask: mask specifying what flags have changed.
 906  * @new_window_state: the new window state, a combination of
 907  *   #GdkWindowState bits.
 908  *
 909  * Generated when the state of a toplevel window changes.
 910  */
 911 struct _GdkEventWindowState
 912 {
 913   GdkEventType type;
 914   GdkWindow *window;
 915   gint8 send_event;
 916   GdkWindowState changed_mask;
 917   GdkWindowState new_window_state;
 918 };
 919
 920 /**
 921  * GdkEventGrabBroken:
 922  * @type: the type of the event (%GDK_GRAB_BROKEN)
 923  * @window: the window which received the event, i.e. the window
 924  *   that previously owned the grab
 925  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 926  *   <function>XSendEvent</function>).
 927  * @keyboard: %TRUE if a keyboard grab was broken, %FALSE if a pointer
 928  *   grab was broken
 929  * @implicit: %TRUE if the broken grab was implicit
 930  * @grab_window: If this event is caused by another grab in the same
 931  *   application, @grab_window contains the new grab window. Otherwise
 932  *   @grab_window is %NULL.
 933  *
 934  * Generated when a pointer or keyboard grab is broken. On X11, this happens
 935  * when the grab window becomes unviewable (i.e. it or one of its ancestors
 936  * is unmapped), or if the same application grabs the pointer or keyboard
 937  * again. Note that implicit grabs (which are initiated by button presses)
 938  * can also cause #GdkEventGrabBroken events.
 939  *
 940  * Since: 2.8
 941  */
 942 struct _GdkEventGrabBroken {
 943   GdkEventType type;
 944   GdkWindow *window;
 945   gint8 send_event;
 946   gboolean keyboard;
 947   gboolean implicit;
 948   GdkWindow *grab_window;
 949 };
 950
 951 /**
 952  * GdkEventDND:
 953  * @type: the type of the event (%GDK_DRAG_ENTER, %GDK_DRAG_LEAVE,
 954  *   %GDK_DRAG_MOTION, %GDK_DRAG_STATUS, %GDK_DROP_START or
 955  *   %GDK_DROP_FINISHED).
 956  * @window: the window which received the event.
 957  * @send_event: %TRUE if the event was sent explicitly (e.g. using
 958  *   <function>XSendEvent</function>).
 959  * @context: the #GdkDragContext for the current DND operation.
 960  * @time: the time of the event in milliseconds.
 961  * @x_root: the x coordinate of the pointer relative to the root of the
 962  *   screen, only set for %GDK_DRAG_MOTION and %GDK_DROP_START.
 963  * @y_root: the y coordinate of the pointer relative to the root of the
 964  *   screen, only set for %GDK_DRAG_MOTION and %GDK_DROP_START.
 965  *
 966  * Generated during DND operations.
 967  */
 968 struct _GdkEventDND {
 969   GdkEventType type;
 970   GdkWindow *window;
 971   gint8 send_event;
 972   GdkDragContext *context;
 973
 974   guint32 time;
 975   gshort x_root, y_root;
 976 };
 977
 978 /**
 979  * GdkEvent:
 980  *
 981  * The #GdkEvent struct contains a union of all of the event structs,
 982  * and allows access to the data fields in a number of ways.
 983  *
 984  * The event type is always the first field in all of the event structs, and
 985  * can always be accessed with the following code, no matter what type of
 986  * event it is:
 987  * <informalexample>
 988  * <programlisting>
 989  *   GdkEvent *event;
 990  *   GdkEventType type;
 991  *
 992  *   type = event->type;
 993  * </programlisting>
 994  * </informalexample>
 995  *
 996  * To access other fields of the event structs, the pointer to the event
 997  * can be cast to the appropriate event struct pointer, or the union member
 998  * name can be used. For example if the event type is %GDK_BUTTON_PRESS
 999  * then the x coordinate of the button press can be accessed with:
1000  * <informalexample>
1001  * <programlisting>
1002  *   GdkEvent *event;
1003  *   gdouble x;
1004  *
1005  *   x = ((GdkEventButton*)event)->x;
1006  * </programlisting>
1007  * </informalexample>
1008  * or:
1009  * <informalexample>
1010  * <programlisting>
1011  *   GdkEvent *event;
1012  *   gdouble x;
1013  *
1014  *   x = event->button.x;
1015  * </programlisting>
1016  * </informalexample>
1017  */
1018 union _GdkEvent
1019 {
1020   GdkEventType              type;
1021   GdkEventAny               any;
1022   GdkEventExpose            expose;
1023   GdkEventVisibility        visibility;
1024   GdkEventMotion            motion;
1025   GdkEventButton            button;
1026   GdkEventScroll            scroll;
1027   GdkEventKey               key;
1028   GdkEventCrossing          crossing;
1029   GdkEventFocus             focus_change;
1030   GdkEventConfigure         configure;
1031   GdkEventProperty          property;
1032   GdkEventSelection         selection;
1033   GdkEventOwnerChange       owner_change;
1034   GdkEventProximity         proximity;
1035   GdkEventDND               dnd;
1036   GdkEventWindowState       window_state;
1037   GdkEventSetting           setting;
1038   GdkEventGrabBroken        grab_broken;
1039 };
1040
1041 GType     gdk_event_get_type            (void) G_GNUC_CONST;
1042
1043 gboolean  gdk_events_pending            (void);
1044 GdkEvent* gdk_event_get                 (void);
1045
1046 GdkEvent* gdk_event_peek                (void);
1047 void      gdk_event_put                 (const GdkEvent *event);
1048
1049 GdkEvent* gdk_event_new                 (GdkEventType    type);
1050 GdkEvent* gdk_event_copy                (const GdkEvent *event);
1051 void      gdk_event_free                (GdkEvent       *event);
1052
1053 guint32   gdk_event_get_time            (const GdkEvent  *event);
1054 gboolean  gdk_event_get_state           (const GdkEvent  *event,
1055                                          GdkModifierType *state);
1056 gboolean  gdk_event_get_coords          (const GdkEvent  *event,
1057                                          gdouble         *x_win,
1058                                          gdouble         *y_win);
1059 gboolean  gdk_event_get_root_coords     (const GdkEvent *event,
1060                                          gdouble        *x_root,
1061                                          gdouble        *y_root);
1062 gboolean  gdk_event_get_button          (const GdkEvent *event,
1063                                          guint          *button);
1064 gboolean  gdk_event_get_click_count     (const GdkEvent *event,
1065                                          guint          *click_count);
1066 gboolean  gdk_event_get_keyval          (const GdkEvent *event,
1067                                          guint          *keyval);
1068 gboolean  gdk_event_get_keycode         (const GdkEvent *event,
1069                                          guint16        *keycode);
1070 gboolean gdk_event_get_scroll_direction (const GdkEvent *event,
1071                                          GdkScrollDirection *direction);
1072 gboolean  gdk_event_get_axis            (const GdkEvent  *event,
1073                                          GdkAxisUse       axis_use,
1074                                          gdouble         *value);
1075 void       gdk_event_set_device         (GdkEvent        *event,
1076                                          GdkDevice       *device);
1077 GdkDevice* gdk_event_get_device         (const GdkEvent  *event);
1078 void       gdk_event_set_source_device  (GdkEvent        *event,
1079                                          GdkDevice       *device);
1080 GdkDevice* gdk_event_get_source_device  (const GdkEvent  *event);
1081 void       gdk_event_request_motions    (const GdkEventMotion *event);
1082 gboolean   gdk_event_triggers_context_menu (const GdkEvent *event);
1083
1084 gboolean  gdk_events_get_distance       (GdkEvent        *event1,
1085                                          GdkEvent        *event2,
1086                                          gdouble         *distance);
1087 gboolean  gdk_events_get_angle          (GdkEvent        *event1,
1088                                          GdkEvent        *event2,
1089                                          gdouble         *angle);
1090 gboolean  gdk_events_get_center         (GdkEvent        *event1,
1091                                          GdkEvent        *event2,
1092                                          gdouble         *x,
1093                                          gdouble         *y);
1094
1095 void      gdk_event_handler_set         (GdkEventFunc    func,
1096                                          gpointer        data,
1097                                          GDestroyNotify  notify);
1098
1099 void       gdk_event_set_screen         (GdkEvent        *event,
1100                                          GdkScreen       *screen);
1101 GdkScreen *gdk_event_get_screen         (const GdkEvent  *event);
1102
1103 void      gdk_set_show_events           (gboolean        show_events);
1104 gboolean  gdk_get_show_events           (void);
1105
1106 #ifndef GDK_MULTIHEAD_SAFE
1107
1108 gboolean gdk_setting_get                           (const gchar *name,
1109                                                     GValue          *value);
1110
1111 #endif /* GDK_MULTIHEAD_SAFE */
1112
1113 G_END_DECLS
1114
1115 #endif /* __GDK_EVENTS_H__ */