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

   1 <!-- ##### SECTION Title ##### -->
   2 Events
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Functions for handling events from the window system
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 This section describes functions dealing with events from the window system.
  10 </para>
  11 <para>
  12 In GTK+ applications the events are handled automatically in
  13 gtk_main_do_event() and passed on to the appropriate widgets, so these
  14 functions are rarely needed. Though some of the fields in the
  15 <link linkend="gdk-Event-Structures">Event Structures</link> are useful.
  16 </para>
  17
  18 <!-- ##### SECTION See_Also ##### -->
  19 <para>
  20 <variablelist>
  21 <varlistentry>
  22 <term><link linkend="gdk-Event-Structures">Event Structures</link></term>
  23 <listitem><para>
  24 The structs used for each type of event.
  25 </para></listitem>
  26 </varlistentry>
  27 </variablelist>
  28 </para>
  29
  30 <!-- ##### SECTION Stability_Level ##### -->
  31
  32
  33 <!-- ##### SECTION Image ##### -->
  34
  35
  36 <!-- ##### ENUM GdkEventType ##### -->
  37 <para>
  38 Specifies the type of the event.
  39 </para>
  40 <para>
  41 Do not confuse these events with the signals that GTK+ widgets emit.
  42 Although many of these events result in corresponding signals being emitted,
  43 the events are often transformed or filtered along the way.
  44 </para>
  45
  46 @GDK_NOTHING: a special code to indicate a null event.
  47 @GDK_DELETE: the window manager has requested that the toplevel window be
  48 hidden or destroyed, usually when the user clicks on a special icon in the
  49 title bar.
  50 @GDK_DESTROY: the window has been destroyed.
  51 @GDK_EXPOSE: all or part of the window has become visible and needs to be
  52 redrawn.
  53 @GDK_MOTION_NOTIFY: the pointer (usually a mouse) has moved.
  54 @GDK_BUTTON_PRESS: a mouse button has been pressed.
  55 @GDK_2BUTTON_PRESS: a mouse button has been double-clicked (clicked twice
  56 within a short period of time). Note that each click also generates a
  57 %GDK_BUTTON_PRESS event.
  58 @GDK_3BUTTON_PRESS: a mouse button has been clicked 3 times in a short period
  59 of time. Note that each click also generates a %GDK_BUTTON_PRESS event.
  60 @GDK_BUTTON_RELEASE: a mouse button has been released.
  61 @GDK_KEY_PRESS: a key has been pressed.
  62 @GDK_KEY_RELEASE: a key has been released.
  63 @GDK_ENTER_NOTIFY: the pointer has entered the window.
  64 @GDK_LEAVE_NOTIFY: the pointer has left the window.
  65 @GDK_FOCUS_CHANGE: the keyboard focus has entered or left the window.
  66 @GDK_CONFIGURE: the size, position or stacking order of the window has changed.
  67 Note that GTK+ discards these events for %GDK_WINDOW_CHILD windows.
  68 @GDK_MAP: the window has been mapped.
  69 @GDK_UNMAP: the window has been unmapped.
  70 @GDK_PROPERTY_NOTIFY: a property on the window has been changed or deleted.
  71 @GDK_SELECTION_CLEAR: the application has lost ownership of a selection.
  72 @GDK_SELECTION_REQUEST: another application has requested a selection.
  73 @GDK_SELECTION_NOTIFY: a selection has been received.
  74 @GDK_PROXIMITY_IN: an input device has moved into contact with a sensing
  75 surface (e.g. a touchscreen or graphics tablet).
  76 @GDK_PROXIMITY_OUT: an input device has moved out of contact with a sensing
  77 surface.
  78 @GDK_DRAG_ENTER: the mouse has entered the window while a drag is in progress.
  79 @GDK_DRAG_LEAVE: the mouse has left the window while a drag is in progress.
  80 @GDK_DRAG_MOTION: the mouse has moved in the window while a drag is in
  81 progress.
  82 @GDK_DRAG_STATUS: the status of the drag operation initiated by the window
  83 has changed.
  84 @GDK_DROP_START: a drop operation onto the window has started.
  85 @GDK_DROP_FINISHED: the drop operation initiated by the window has completed.
  86 @GDK_CLIENT_EVENT: a message has been received from another application.
  87 @GDK_VISIBILITY_NOTIFY: the window visibility status has changed.
  88 @GDK_NO_EXPOSE: indicates that the source region was completely available
  89 when parts of a drawable were copied. This is not very useful.
  90 @GDK_SCROLL: the scroll wheel was turned
  91 @GDK_WINDOW_STATE: the state of a window has changed. See #GdkWindowState
  92 for the possible window states
  93 @GDK_SETTING: a setting has been modified.
  94 @GDK_OWNER_CHANGE: the owner of a selection has changed. This event type
  95   was added in 2.6
  96 @GDK_GRAB_BROKEN: a pointer or keyboard grab was broken. This event type
  97   was added in 2.8.
  98 @GDK_DAMAGE: the content of the window has been changed. This event type
  99   was added in 2.14.
 100 @GDK_EVENT_LAST: marks the end of the GdkEventType enumeration. Added in 2.18
 101
 102 <!-- ##### ENUM GdkEventMask ##### -->
 103 <para>
 104 A set of bit-flags to indicate which events a window is to receive.
 105 Most of these masks map onto one or more of the #GdkEventType event types
 106 above.
 107 </para>
 108 <para>
 109 %GDK_POINTER_MOTION_HINT_MASK is a special mask which is used to reduce the
 110 number of %GDK_MOTION_NOTIFY events received. Normally a %GDK_MOTION_NOTIFY
 111 event is received each time the mouse moves. However, if the application
 112 spends a lot of time processing the event (updating the display, for example),
 113 it can lag behind the position of the mouse. When using
 114 %GDK_POINTER_MOTION_HINT_MASK, fewer %GDK_MOTION_NOTIFY events will be sent,
 115 some of which are marked as a hint (the is_hint member is %TRUE).
 116 To receive more motion events after a motion hint event, the application
 117 needs to asks for more, by calling gdk_event_request_motions().
 118 </para>
 119
 120 @GDK_EXPOSURE_MASK: receive expose events
 121 @GDK_POINTER_MOTION_MASK: receive all pointer motion events
 122 @GDK_POINTER_MOTION_HINT_MASK: see the explanation above
 123 @GDK_BUTTON_MOTION_MASK: receive pointer motion events while any button is pressed
 124 @GDK_BUTTON1_MOTION_MASK: receive pointer motion events while 1 button is pressed
 125 @GDK_BUTTON2_MOTION_MASK: receive pointer motion events while 2 button is pressed
 126 @GDK_BUTTON3_MOTION_MASK: receive pointer motion events while 3 button is pressed
 127 @GDK_BUTTON_PRESS_MASK: receive button press events
 128 @GDK_BUTTON_RELEASE_MASK: receive button release events
 129 @GDK_KEY_PRESS_MASK: receive key press events
 130 @GDK_KEY_RELEASE_MASK: receive key release events
 131 @GDK_ENTER_NOTIFY_MASK: receive window enter events
 132 @GDK_LEAVE_NOTIFY_MASK: receive window leave events
 133 @GDK_FOCUS_CHANGE_MASK: receive focus change events
 134 @GDK_STRUCTURE_MASK: receive events about window configuration change
 135 @GDK_PROPERTY_CHANGE_MASK: receive property change events
 136 @GDK_VISIBILITY_NOTIFY_MASK: receive visibility change events
 137 @GDK_PROXIMITY_IN_MASK: receive proximity in events
 138 @GDK_PROXIMITY_OUT_MASK: receive proximity out events
 139 @GDK_SUBSTRUCTURE_MASK: receive events about window configuration changes of
 140   child windows
 141 @GDK_SCROLL_MASK: receive scroll events
 142 @GDK_ALL_EVENTS_MASK: the combination of all the above event masks.
 143
 144 <!-- ##### MACRO GDK_CURRENT_TIME ##### -->
 145 <para>
 146 Represents the current time, and can be used anywhere a time is expected.
 147 </para>
 148
 149
 150
 151 <!-- ##### MACRO GDK_PRIORITY_EVENTS ##### -->
 152 <para>
 153 This is the priority that events from the X server are given in the
 154 <link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link>.
 155 </para>
 156
 157
 158
 159 <!-- ##### MACRO GDK_PRIORITY_REDRAW ##### -->
 160 <para>
 161 This is the priority that the idle handler processing window updates
 162 is given in the <link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link>.
 163 </para>
 164
 165
 166
 167 <!-- ##### FUNCTION gdk_events_pending ##### -->
 168 <para>
 169 </para>
 170
 171 @void:
 172 @Returns:
 173
 174
 175 <!-- ##### FUNCTION gdk_event_peek ##### -->
 176 <para>
 177 </para>
 178
 179 @void:
 180 @Returns:
 181
 182
 183 <!-- ##### FUNCTION gdk_event_get ##### -->
 184 <para>
 185 </para>
 186
 187 @void:
 188 @Returns:
 189
 190
 191 <!-- ##### FUNCTION gdk_event_put ##### -->
 192 <para>
 193 </para>
 194
 195 @event:
 196
 197
 198 <!-- ##### FUNCTION gdk_event_new ##### -->
 199 <para>
 200
 201 </para>
 202
 203 @type:
 204 @Returns:
 205
 206
 207 <!-- ##### FUNCTION gdk_event_copy ##### -->
 208 <para>
 209 </para>
 210
 211 @event:
 212 @Returns:
 213
 214
 215 <!-- ##### FUNCTION gdk_event_free ##### -->
 216 <para>
 217 </para>
 218
 219 @event: a #GdkEvent.
 220
 221
 222 <!-- ##### FUNCTION gdk_event_get_time ##### -->
 223 <para>
 224 </para>
 225
 226 @event:
 227 @Returns:
 228
 229
 230 <!-- ##### FUNCTION gdk_event_get_state ##### -->
 231 <para>
 232
 233 </para>
 234
 235 @event:
 236 @state:
 237 @Returns:
 238
 239
 240 <!-- ##### FUNCTION gdk_event_get_axis ##### -->
 241 <para>
 242
 243 </para>
 244
 245 @event:
 246 @axis_use:
 247 @value:
 248 @Returns:
 249
 250
 251 <!-- ##### FUNCTION gdk_event_get_coords ##### -->
 252 <para>
 253
 254 </para>
 255
 256 @event:
 257 @x_win:
 258 @y_win:
 259 @Returns:
 260
 261
 262 <!-- ##### FUNCTION gdk_event_get_root_coords ##### -->
 263 <para>
 264
 265 </para>
 266
 267 @event:
 268 @x_root:
 269 @y_root:
 270 @Returns:
 271
 272
 273 <!-- ##### FUNCTION gdk_event_request_motions ##### -->
 274 <para>
 275
 276 </para>
 277
 278 @event:
 279
 280
 281 <!-- ##### FUNCTION gdk_event_handler_set ##### -->
 282 <para>
 283 </para>
 284
 285 @func:
 286 @data:
 287 @notify:
 288
 289
 290 <!-- ##### USER_FUNCTION GdkEventFunc ##### -->
 291 <para>
 292 Specifies the type of function passed to gdk_event_handler_set() to handle
 293 all GDK events.
 294 </para>
 295
 296 @event: the #GdkEvent to process.
 297 @data: user data set when the event handler was installed with
 298 gdk_event_handler_set().
 299
 300
 301 <!-- ##### FUNCTION gdk_event_send_client_message ##### -->
 302 <para>
 303 </para>
 304
 305 @event:
 306 @winid:
 307 @Returns:
 308
 309
 310 <!-- ##### FUNCTION gdk_event_send_client_message_for_display ##### -->
 311 <para>
 312
 313 </para>
 314
 315 @display:
 316 @event:
 317 @winid:
 318 @Returns:
 319
 320
 321 <!-- ##### FUNCTION gdk_event_send_clientmessage_toall ##### -->
 322 <para>
 323 </para>
 324
 325 @event:
 326
 327
 328 <!-- ##### FUNCTION gdk_add_client_message_filter ##### -->
 329 <para>
 330 </para>
 331
 332 @message_type:
 333 @func:
 334 @data:
 335
 336
 337 <!-- ##### FUNCTION gdk_get_show_events ##### -->
 338 <para>
 339 </para>
 340
 341 @void:
 342 @Returns:
 343
 344
 345 <!-- ##### FUNCTION gdk_set_show_events ##### -->
 346 <para>
 347 </para>
 348
 349 @show_events:
 350
 351
 352 <!-- ##### FUNCTION gdk_event_set_screen ##### -->
 353 <para>
 354
 355 </para>
 356
 357 @event:
 358 @screen:
 359
 360
 361 <!-- ##### FUNCTION gdk_event_get_screen ##### -->
 362 <para>
 363
 364 </para>
 365
 366 @event:
 367 @Returns:
 368
 369
 370 <!-- ##### FUNCTION gdk_setting_get ##### -->
 371 <para>
 372 </para>
 373
 374 @name:
 375 @value:
 376 @Returns:
 377
 378