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 <!-- ##### ENUM GdkEventType ##### -->
  31 <para>
  32 Specifies the type of the event.
  33 </para>
  34 <para>
  35 Do not confuse these events with the signals that GTK+ widgets emit.
  36 Although many of these events result in corresponding signals being emitted,
  37 the events are often transformed or filtered along the way.
  38 </para>
  39
  40 @GDK_NOTHING: a special code to indicate a null event.
  41 @GDK_DELETE: the window manager has requested that the toplevel window be
  42 hidden or destroyed, usually when the user clicks on a special icon in the
  43 title bar.
  44 @GDK_DESTROY: the window has been destroyed.
  45 @GDK_EXPOSE: all or part of the window has become visible and needs to be
  46 redrawn.
  47 @GDK_MOTION_NOTIFY: the pointer (usually a mouse) has moved.
  48 @GDK_BUTTON_PRESS: a mouse button has been pressed.
  49 @GDK_2BUTTON_PRESS: a mouse button has been double-clicked (clicked twice
  50 within a short period of time). Note that each click also generates a
  51 %GDK_BUTTON_PRESS event.
  52 @GDK_3BUTTON_PRESS: a mouse button has been clicked 3 times in a short period
  53 of time. Note that each click also generates a %GDK_BUTTON_PRESS event.
  54 @GDK_BUTTON_RELEASE: a mouse button has been released.
  55 @GDK_KEY_PRESS: a key has been pressed.
  56 @GDK_KEY_RELEASE: a key has been released.
  57 @GDK_ENTER_NOTIFY: the pointer has entered the window.
  58 @GDK_LEAVE_NOTIFY: the pointer has left the window.
  59 @GDK_FOCUS_CHANGE: the keyboard focus has entered or left the window.
  60 @GDK_CONFIGURE: the size, position or stacking order of the window has changed.
  61 Note that GTK+ discards these events for %GDK_WINDOW_CHILD windows.
  62 @GDK_MAP: the window has been mapped.
  63 @GDK_UNMAP: the window has been unmapped.
  64 @GDK_PROPERTY_NOTIFY: a property on the window has been changed or deleted.
  65 @GDK_SELECTION_CLEAR: the application has lost ownership of a selection.
  66 @GDK_SELECTION_REQUEST: another application has requested a selection.
  67 @GDK_SELECTION_NOTIFY: a selection has been received.
  68 @GDK_PROXIMITY_IN: an input device has moved into contact with a sensing
  69 surface (e.g. a touchscreen or graphics tablet).
  70 @GDK_PROXIMITY_OUT: an input device has moved out of contact with a sensing
  71 surface.
  72 @GDK_DRAG_ENTER: the mouse has entered the window while a drag is in progress.
  73 @GDK_DRAG_LEAVE: the mouse has left the window while a drag is in progress.
  74 @GDK_DRAG_MOTION: the mouse has moved in the window while a drag is in
  75 progress.
  76 @GDK_DRAG_STATUS: the status of the drag operation initiated by the window
  77 has changed.
  78 @GDK_DROP_START: a drop operation onto the window has started.
  79 @GDK_DROP_FINISHED: the drop operation initiated by the window has completed.
  80 @GDK_CLIENT_EVENT: a message has been received from another application.
  81 @GDK_VISIBILITY_NOTIFY: the window visibility status has changed.
  82 @GDK_NO_EXPOSE: indicates that the source region was completely available
  83 when parts of a drawable were copied. This is not very useful.
  84 @GDK_SCROLL:
  85 @GDK_WINDOW_STATE:
  86 @GDK_SETTING:
  87
  88 <!-- ##### ENUM GdkEventMask ##### -->
  89 <para>
  90 A set of bit-flags to indicate which events a window is to receive.
  91 Most of these masks map onto one or more of the #GdkEventType event types
  92 above.
  93 </para>
  94 <para>
  95 %GDK_POINTER_MOTION_HINT_MASK is a special mask which is used to reduce the
  96 number of %GDK_MOTION_NOTIFY events received. Normally a %GDK_MOTION_NOTIFY
  97 event is received each time the mouse moves. However, if the application
  98 spends a lot of time processing the event (updating the display, for example),
  99 it can easily lag behind the position of the mouse. When using the
 100 %GDK_POINTER_MOTION_HINT_MASK the server will only send %GDK_MOTION_NOTIFY
 101 events when the application asks for them, by calling gdk_window_get_pointer().
 102 </para>
 103
 104 @GDK_EXPOSURE_MASK:
 105 @GDK_POINTER_MOTION_MASK:
 106 @GDK_POINTER_MOTION_HINT_MASK:
 107 @GDK_BUTTON_MOTION_MASK:
 108 @GDK_BUTTON1_MOTION_MASK:
 109 @GDK_BUTTON2_MOTION_MASK:
 110 @GDK_BUTTON3_MOTION_MASK:
 111 @GDK_BUTTON_PRESS_MASK:
 112 @GDK_BUTTON_RELEASE_MASK:
 113 @GDK_KEY_PRESS_MASK:
 114 @GDK_KEY_RELEASE_MASK:
 115 @GDK_ENTER_NOTIFY_MASK:
 116 @GDK_LEAVE_NOTIFY_MASK:
 117 @GDK_FOCUS_CHANGE_MASK:
 118 @GDK_STRUCTURE_MASK:
 119 @GDK_PROPERTY_CHANGE_MASK:
 120 @GDK_VISIBILITY_NOTIFY_MASK:
 121 @GDK_PROXIMITY_IN_MASK:
 122 @GDK_PROXIMITY_OUT_MASK:
 123 @GDK_SUBSTRUCTURE_MASK:
 124 @GDK_SCROLL_MASK:
 125 @GDK_ALL_EVENTS_MASK: the combination of all the above event masks.
 126
 127 <!-- ##### MACRO GDK_CURRENT_TIME ##### -->
 128 <para>
 129 Represents the current time, and can be used anywhere a time is expected.
 130 </para>
 131
 132
 133
 134 <!-- ##### MACRO GDK_PRIORITY_EVENTS ##### -->
 135 <para>
 136 This is the priority that events from the X server are given in the
 137 <link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link>.
 138 </para>
 139
 140
 141
 142 <!-- ##### MACRO GDK_PRIORITY_REDRAW ##### -->
 143 <para>
 144 This is the priority that the idle handler processing window updates
 145 is given in the <link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link>.
 146 </para>
 147
 148
 149
 150 <!-- ##### FUNCTION gdk_events_pending ##### -->
 151 <para>
 152 Checks if any events are waiting to be processed.
 153 </para>
 154
 155 @Returns: %TRUE if any events are pending.
 156
 157
 158 <!-- ##### FUNCTION gdk_event_peek ##### -->
 159 <para>
 160 Gets a copy of the first #GdkEvent in the event queue.
 161 (Note that this function will not get more events from the X server.
 162 It only checks the events that have already been moved to the GDK event queue.)
 163 </para>
 164
 165 @Returns: a copy of the first #GdkEvent on the event queue, or %NULL if no
 166 events are in the queue. The returned #GdkEvent should be freed with
 167 gdk_event_free().
 168
 169
 170 <!-- ##### FUNCTION gdk_event_get ##### -->
 171 <para>
 172 Gets the next #GdkEvent to be processed, fetching events from the X server if
 173 necessary.
 174 </para>
 175
 176 @Returns: the next #GdkEvent to be processed, or %NULL if no events are pending.
 177 The returned #GdkEvent should be freed with gdk_event_free().
 178
 179
 180 <!-- ##### FUNCTION gdk_event_get_graphics_expose ##### -->
 181 <para>
 182 Waits for a GraphicsExpose or NoExpose event from the X server.
 183 This is used in the #GtkText and #GtkCList widgets in GTK+ to make sure any
 184 GraphicsExpose events are handled before the widget is scrolled.
 185 </para>
 186
 187 @window: the #GdkWindow to wait for the events for.
 188 @Returns: a #GdkEventExpose if a GraphicsExpose was received, or %NULL if a
 189 NoExpose event was received.
 190
 191
 192 <!-- ##### FUNCTION gdk_event_put ##### -->
 193 <para>
 194 Appends a copy of the given event onto the front of the event queue.
 195 </para>
 196
 197 @event: a #GdkEvent.
 198
 199
 200 <!-- ##### FUNCTION gdk_event_copy ##### -->
 201 <para>
 202 Copies a #GdkEvent, copying or incrementing the reference count of the
 203 resources associated with it (e.g. #GdkWindow's and strings).
 204 </para>
 205
 206 @event: a #GdkEvent.
 207 @Returns: a copy of @event. The returned #GdkEvent should be freed with
 208 gdk_event_free().
 209
 210
 211 <!-- ##### FUNCTION gdk_event_free ##### -->
 212 <para>
 213 Frees a #GdkEvent, freeing or decrementing any resources associated with it.
 214 Note that this function should only be called with events returned from
 215 gdk_event_peek(), gdk_event_get(), gdk_event_get_graphics_expose() and
 216 gdk_event_copy().
 217 </para>
 218
 219 @event: a #GdkEvent.
 220
 221
 222 <!-- ##### FUNCTION gdk_event_get_time ##### -->
 223 <para>
 224 Gets the timestamp from a #GdkEvent.
 225 </para>
 226
 227 @event: a #GdkEvent.
 228 @Returns: the timestamp from @event, or %GDK_CURRENT_TIME if the event has
 229 no timestamp.
 230
 231
 232 <!-- ##### FUNCTION gdk_event_get_state ##### -->
 233 <para>
 234
 235 </para>
 236
 237 @event:
 238 @state:
 239 @Returns:
 240
 241
 242 <!-- ##### FUNCTION gdk_event_get_axis ##### -->
 243 <para>
 244
 245 </para>
 246
 247 @event:
 248 @axis_use:
 249 @value:
 250 @Returns:
 251
 252
 253 <!-- ##### FUNCTION gdk_event_get_coords ##### -->
 254 <para>
 255
 256 </para>
 257
 258 @event:
 259 @x_win:
 260 @y_win:
 261 @Returns:
 262
 263
 264 <!-- ##### FUNCTION gdk_event_get_root_coords ##### -->
 265 <para>
 266
 267 </para>
 268
 269 @event:
 270 @x_root:
 271 @y_root:
 272 @Returns:
 273
 274
 275 <!-- ##### FUNCTION gdk_event_handler_set ##### -->
 276 <para>
 277 Sets the function to call to handle all events from GDK.
 278 </para>
 279 <para>
 280 Note that GTK+ uses this to install its own event handler, so it is probably
 281 not useful for GTK+ applications.
 282 </para>
 283
 284 @func: the function to call to handle events from GDK.
 285 @data: user data to pass to the function.
 286 @notify: the function to call when the handler function is removed, i.e. when
 287 gdk_event_handler_set() is called with another event handler.
 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 Sends an X ClientMessage event to a given window.
 304 </para>
 305 <para>
 306 This could be used for communicating between different applications,
 307 though the amount of data is limited to 20 bytes.
 308 </para>
 309
 310 @event: the #GdkEvent to send, which should be a #GdkEventClient.
 311 @xid: the window to send the X ClientMessage event to.
 312 @Returns: non-zero on success.
 313
 314
 315 <!-- ##### FUNCTION gdk_event_send_clientmessage_toall ##### -->
 316 <para>
 317 Sends an X ClientMessage event to all toplevel windows.
 318 </para>
 319 <para>
 320 Toplevel windows are determined by checking for the WM_STATE property, as
 321 described in the Inter-Client Communication Conventions Manual (ICCCM).
 322 If no windows are found with the WM_STATE property set, the message is sent
 323 to all children of the root window.
 324 </para>
 325
 326 @event: the #GdkEvent to send, which should be a #GdkEventClient.
 327
 328
 329 <!-- ##### FUNCTION gdk_add_client_message_filter ##### -->
 330 <para>
 331 Adds a filter to be called when X ClientMessage events are received.
 332 </para>
 333
 334 @message_type: the type of ClientMessage events to receive. This will be
 335 checked against the <structfield>message_type</structfield> field of the
 336 XClientMessage event struct.
 337 @func: the function to call to process the event.
 338 @data: user data to pass to @func.
 339
 340
 341 <!-- ##### FUNCTION gdk_get_show_events ##### -->
 342 <para>
 343 Returns non-zero if event debugging output is enabled.
 344 </para>
 345
 346 @Returns: non-zero if event debugging output is enabled.
 347
 348
 349 <!-- ##### FUNCTION gdk_set_show_events ##### -->
 350 <para>
 351 Sets whether event debugging information is output.
 352 Note that GTK+ must be compiled with debugging enabled, i.e. using the
 353 <option>--enable-debug</option> configure option.
 354 </para>
 355
 356 @show_events: %TRUE to output event debugging information.
 357
 358
 359 <!-- ##### FUNCTION gdk_setting_get ##### -->
 360 <para>
 361 Obtains a desktop-wide setting, such as the double-click time.
 362 </para>
 363 <para>
 364 FIXME needs a list of valid settings here, or a link to
 365 more information.
 366 </para>
 367
 368 @name: the name of the setting.
 369 @value: location to store the value of the setting.
 370 @Returns: %TRUE if the value has been successfully stored.
 371
 372