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

   1 <!-- ##### SECTION Title ##### -->
   2 Input Devices
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Functions for handling extended input devices
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 In addition to the normal keyboard and mouse input devices, GTK+ also
  10 contains support for <firstterm>extended input devices</firstterm>. In
  11 particular, this support is targeted at graphics tablets. Graphics
  12 tablets typically return sub-pixel positioning information and possibly
  13 information about the pressure and tilt of the stylus. Under
  14 X, the support for extended devices is done through the
  15 <firstterm>XInput</firstterm> extension.
  16 </para>
  17 <para>
  18 Because handling extended input devices may involve considerable
  19 overhead, they need to be turned on for each #GdkWindow
  20 individually using gdk_input_set_extension_events().
  21 (Or, more typically, for GtkWidgets, using gtk_widget_set_extension_events()).
  22 As an additional complication, depending on the support from
  23 the windowing system, its possible that a normal mouse
  24 cursor will not be displayed for a particular extension
  25 device. If an application does not want to deal with displaying
  26 a cursor itself, it can ask only to get extension events
  27 from devices that will display a cursor, by passing the
  28 %GDK_EXTENSION_EVENTS_CURSOR value to
  29 gdk_input_set_extension_events(). Otherwise, the application
  30 must retrieve the device information using gdk_devices_list(),
  31 check the <structfield>has_cursor</structfield> field, and,
  32 if it is %FALSE, draw a cursor itself when it receives
  33 motion events.
  34 </para>
  35 <para>
  36 Each pointing device is assigned a unique integer ID; events from a
  37 particular device can be identified by the
  38 <structfield>deviceid</structfield> field in the event structure. The
  39 events generated by pointer devices have also been extended to contain
  40 <structfield>pressure</structfield>, <structfield>xtilt</structfield>
  41 and <structfield>ytilt</structfield> fields which contain the extended
  42 information reported as additional <firstterm>valuators</firstterm>
  43 from the device. The <structfield>pressure</structfield> field is a
  44 a double value ranging from 0.0 to 1.0, while the tilt fields are
  45 double values ranging from -1.0 to 1.0. (With -1.0 representing the
  46 maximum tilt to the left or up, and 1.0 representing the maximum
  47 tilt to the right or down.)
  48 </para>
  49 <para>
  50 One additional field in each event is the
  51 <structfield>source</structfield> field, which contains an
  52 enumeration value describing the type of device; this currently
  53 can be one of %GDK_SOURCE_MOUSE, %GDK_SOURCE_PEN, %GDK_SOURCE_ERASER,
  54 or %GDK_SOURCE_CURSOR. This field is present to allow simple
  55 applications to (for instance) delete when they detect eraser
  56 devices without having to keep track of complicated per-device
  57 settings.
  58 </para>
  59 <para>
  60 Various aspects of each device may be configured. The easiest way of
  61 creating a GUI to allow the user to configure such a device
  62 is to use the #GtkInputDialog widget in GTK+.
  63 However, even when using this widget, application writers
  64 will need to directly query and set the configuration parameters
  65 in order to save the state between invocations of the application.
  66 The configuration of devices is queried using gdk_devices_list().
  67 Each device must be activated using gdk_device_set_mode(), which
  68 also controls whether the device's range is mapped to the
  69 entire screen or to a single window. The mapping of the valuators of
  70 the device onto the predefined valuator types is set using
  71 gdk_device_set_axis_use(). And the source type for each device
  72 can be set with gdk_device_set_source().
  73 </para>
  74 <para>
  75 Devices may also have associated <firstterm>keys</firstterm>
  76 or macro buttons. Such keys can be globally set to map
  77 into normal X keyboard events. The mapping is set using
  78 gdk_device_set_key().
  79 </para>
  80 <para>
  81 The interfaces in this section will most likely be considerably
  82 modified in the future to accomodate devices that may have different
  83 sets of additional valuators than the pressure <structfield>xtilt</structfield>
  84 and <structfield>ytilt</structfield>.
  85 </para>
  86
  87 <!-- ##### SECTION See_Also ##### -->
  88 <para>
  89
  90 </para>
  91
  92 <!-- ##### SECTION Stability_Level ##### -->
  93
  94
  95 <!-- ##### STRUCT GdkDevice ##### -->
  96 <para>
  97 A <structname>GdkDevice</structname> structure contains
  98 a detailed description of an extended input device. All
  99 fields are read-only; but you can use gdk_device_set_source(),
 100 gdk_device_set_mode(), gdk_device_set_key() and gdk_device_set_axis_use()
 101 to configure various aspects of the device.
 102 </para>
 103
 104 @parent_instance:
 105 @name: the name of this device.
 106 @source: the type of this device.
 107 @mode: the mode of this device
 108 @has_cursor: %TRUE if the pointer follows device motion.
 109 @num_axes: the length of the @axes array.
 110 @axes: an array of #GdkDeviceAxis, describing the axes of this device.
 111 @num_keys: the length of the @keys array.
 112 @keys: an array of #GdkDeviceKey, describing the mapped macro buttons
 113   of this device.
 114
 115 <!-- ##### ENUM GdkInputSource ##### -->
 116 <para>
 117 An enumeration describing the type of an input device
 118 in general terms.
 119 </para>
 120
 121 @GDK_SOURCE_MOUSE: the device is a mouse. (This will be reported for the core
 122                     pointer, even if it is something else, such as a trackball.)
 123 @GDK_SOURCE_PEN: the device is a stylus of a graphics tablet or similar device.
 124 @GDK_SOURCE_ERASER: the device is an eraser. Typically, this would be the other end
 125                     of a stylus on a graphics tablet.
 126 @GDK_SOURCE_CURSOR: the device is a graphics tablet "puck" or similar device.
 127
 128 <!-- ##### ENUM GdkInputMode ##### -->
 129 <para>
 130 An enumeration that describes the mode of an input device.
 131 </para>
 132
 133 @GDK_MODE_DISABLED: the device is disabled and will not report any events.
 134 @GDK_MODE_SCREEN: the device is enabled. The device's coordinate space
 135                     maps to the entire screen.
 136 @GDK_MODE_WINDOW: the device is enabled. The device's coordinate space
 137                     is mapped to a single window. The manner in which this window
 138                     is chosen is undefined, but it will typically be the same
 139                     way in which the focus window for key events is determined.
 140
 141 <!-- ##### STRUCT GdkDeviceKey ##### -->
 142 <para>
 143 The <structname>GdkDeviceKey</structname> structure contains information
 144 about the mapping of one device macro button onto a normal X key event.
 145 It has the following fields:
 146 </para>
 147
 148 @keyval: the keyval to generate when the macro button is pressed.
 149          If this is 0, no keypress will be generated.
 150 @modifiers: the modifiers set for the generated key event.
 151
 152 <!-- ##### STRUCT GdkDeviceAxis ##### -->
 153 <para>
 154 The <structname>GdkDeviceAxis</structname> structure contains information
 155 about the range and mapping of a device axis.
 156 </para>
 157
 158 @use: specifies how the axis is used.
 159 @min: the minimal value that will be reported by this axis.
 160 @max: the maximal value that will be reported by this axis.
 161
 162 <!-- ##### ENUM GdkAxisUse ##### -->
 163 <para>
 164 An enumeration describing the way in which a device
 165 axis (valuator) maps onto the predefined valuator
 166 types that GTK+ understands.
 167 </para>
 168
 169 @GDK_AXIS_IGNORE: the axis is ignored.
 170 @GDK_AXIS_X: the axis is used as the x axis.
 171 @GDK_AXIS_Y: the axis is used as the y axis.
 172 @GDK_AXIS_PRESSURE: the axis is used for pressure information.
 173 @GDK_AXIS_XTILT: the axis is used for x tilt information.
 174 @GDK_AXIS_YTILT: the axis is used for x tilt information.
 175 @GDK_AXIS_WHEEL: the axis is used for wheel information.
 176 @GDK_AXIS_LAST: a constant equal to the numerically highest axis value.
 177
 178 <!-- ##### FUNCTION gdk_devices_list ##### -->
 179 <para>
 180 </para>
 181
 182 @Returns:
 183
 184
 185 <!-- ##### FUNCTION gdk_device_set_source ##### -->
 186 <para>
 187 Sets the source type for an input device.
 188 </para>
 189
 190 @device: a #GdkDevice.
 191 @source: the source type.
 192
 193
 194 <!-- ##### FUNCTION gdk_device_set_mode ##### -->
 195 <para>
 196 Sets a the mode of an input device. The mode controls if the
 197 device is active and whether the device's range is mapped to the
 198 entire screen or to a single window.
 199 </para>
 200
 201 @device: a #GdkDevice.
 202 @mode: the input mode.
 203 @Returns: %TRUE if the mode was successfully changed.
 204
 205
 206 <!-- ##### FUNCTION gdk_device_set_key ##### -->
 207 <para>
 208 Specifies the X key event to generate when a macro button of a device
 209 is pressed.
 210 </para>
 211
 212 @device: a #GdkDevice.
 213 @index_: the index of the macro button to set.
 214 @keyval: the keyval to generate.
 215 @modifiers: the modifiers to set.
 216
 217
 218 <!-- ##### FUNCTION gdk_device_set_axis_use ##### -->
 219 <para>
 220 Specifies how an axis of a device is used.
 221 </para>
 222
 223 @device: a #GdkDevice.
 224 @index_: the index of the axis.
 225 @use: specifies how the axis is used.
 226
 227
 228 <!-- ##### FUNCTION gdk_device_get_core_pointer ##### -->
 229 <para>
 230 </para>
 231
 232 @Returns:
 233
 234
 235 <!-- ##### FUNCTION gdk_device_get_state ##### -->
 236 <para>
 237 Gets the current state of a device.
 238 </para>
 239
 240 @device: a #GdkDevice.
 241 @window: a #GdkWindow.
 242 @axes: an array of doubles to store the values of the axes of @device in,
 243   or %NULL.
 244 @mask: location to store the modifiers, or %NULL.
 245
 246
 247 <!-- ##### FUNCTION gdk_device_get_history ##### -->
 248 <para>
 249
 250 </para>
 251
 252 @device:
 253 @window:
 254 @start:
 255 @stop:
 256 @events:
 257 @n_events:
 258 @Returns:
 259
 260
 261 <!-- ##### FUNCTION gdk_device_free_history ##### -->
 262 <para>
 263 Frees an array of #GdkTimeCoord that was returned by gdk_device_get_history().
 264 </para>
 265
 266 @events: an array of #GdkTimeCoord.
 267 @n_events: the length of the array.
 268
 269
 270 <!-- ##### STRUCT GdkTimeCoord ##### -->
 271 <para>
 272 The #GdkTimeCoord structure stores a single event in a
 273 motion history. It contains the following fields:
 274 </para>
 275
 276 @time: The timestamp for this event.
 277 @axes: the values of the device's axes.
 278
 279 <!-- ##### FUNCTION gdk_device_get_axis ##### -->
 280 <para>
 281
 282 </para>
 283
 284 @device:
 285 @axes:
 286 @use:
 287 @value:
 288 @Returns:
 289
 290
 291 <!-- ##### FUNCTION gdk_input_set_extension_events ##### -->
 292 <para>
 293 Turns extension events on or off for a particular window,
 294 and specifies the event mask for extension events.
 295 </para>
 296
 297 @window: a #GdkWindow.
 298 @mask: the event mask
 299 @mode: the type of extension events that are desired.
 300
 301
 302 <!-- ##### ENUM GdkExtensionMode ##### -->
 303 <para>
 304 An enumeration used to specify which extension events
 305 are desired for a particular widget.
 306 </para>
 307
 308 @GDK_EXTENSION_EVENTS_NONE: no extension events are desired.
 309 @GDK_EXTENSION_EVENTS_ALL: all extension events are desired.
 310 @GDK_EXTENSION_EVENTS_CURSOR: extension events are desired only if a cursor
 311                               will be displayed for the device.
 312