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