input_devices.sgml 9.62 KB
Newer Older
Owen Taylor's avatar
Owen Taylor committed
1 2 3 4
<!-- ##### SECTION Title ##### -->
Input Devices

<!-- ##### SECTION Short_Description ##### -->
5
Functions for handling extended input devices
Owen Taylor's avatar
Owen Taylor committed
6 7 8

<!-- ##### SECTION Long_Description ##### -->
<para>
Owen Taylor's avatar
Owen Taylor committed
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
In addition to the normal keyboard and mouse input devices, GTK+ also
contains support for <firstterm>extended input devices</firstterm>. In
particular, this support is targeted at graphics tablets. Graphics
tablets typically return sub-pixel positioning information and possibly
information about the pressure and tilt of the stylus. Under
X, the support for extended devices is done through the 
<firstterm>XInput</firstterm> extension.
</para>
<para>
Because handling extended input devices may involve considerable
overhead, they need to be turned on for each #GdkWindow
individually using gdk_input_set_extension_events().
(Or, more typically, for GtkWidgets, using gtk_widget_set_extension_events()).
As an additional complication, depending on the support from
the windowing system, its possible that a normal mouse
cursor will not be displayed for a particular extension
device. If an application does not want to deal with displaying
a cursor itself, it can ask only to get extension events
from devices that will display a cursor, by passing the
%GDK_EXTENSION_EVENTS_CURSOR value to
gdk_input_set_extension_events(). Otherwise, the application
30
must retrieve the device information using gdk_devices_list(),
Owen Taylor's avatar
Owen Taylor committed
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45
check the <structfield>has_cursor</structfield> field, and, 
if it is %FALSE, draw a cursor itself when it receives 
motion events.
</para>
<para>
Each pointing device is assigned a unique integer ID; events from a
particular device can be identified by the
<structfield>deviceid</structfield> field in the event structure. The
events generated by pointer devices have also been extended to contain
<structfield>pressure</structfield>, <structfield>xtilt</structfield>
and <structfield>ytilt</structfield> fields which contain the extended
information reported as additional <firstterm>valuators</firstterm>
from the device. The <structfield>pressure</structfield> field is a 
a double value ranging from 0.0 to 1.0, while the tilt fields are
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
Owen Taylor's avatar
Owen Taylor committed
47 48 49 50 51 52
tilt to the right or down.)
</para>
<para>
One additional field in each event is the
<structfield>source</structfield> field, which contains an
enumeration value describing the type of device; this currently
Matthias Clasen's avatar
Matthias Clasen committed
53
can be one of %GDK_SOURCE_MOUSE, %GDK_SOURCE_PEN, %GDK_SOURCE_ERASER,
Owen Taylor's avatar
Owen Taylor committed
54 55 56 57 58 59
or %GDK_SOURCE_CURSOR. This field is present to allow simple
applications to (for instance) delete when they detect eraser
devices without having to keep track of complicated per-device
settings.
</para>
<para>
Christian Dywan's avatar
Christian Dywan committed
60
Various aspects of each device may be configured.
61 62
The configuration of devices is queried using gdk_devices_list().
Each device must be activated using gdk_device_set_mode(), which
Owen Taylor's avatar
Owen Taylor committed
63 64 65
also controls whether the device's range is mapped to the
entire screen or to a single window. The mapping of the valuators of
the device onto the predefined valuator types is set using
66 67
gdk_device_set_axis_use(). And the source type for each device
can be set with gdk_device_set_source().
Owen Taylor's avatar
Owen Taylor committed
68 69 70 71 72
</para>
<para>
Devices may also have associated <firstterm>keys</firstterm>
or macro buttons. Such keys can be globally set to map
into normal X keyboard events. The mapping is set using
73
gdk_device_set_key().
Owen Taylor's avatar
Owen Taylor committed
74 75 76 77
</para>
<para>
The interfaces in this section will most likely be considerably
modified in the future to accomodate devices that may have different
Matthias Clasen's avatar
Matthias Clasen committed
78 79
sets of additional valuators than the pressure <structfield>xtilt</structfield>
and <structfield>ytilt</structfield>.
Owen Taylor's avatar
Owen Taylor committed
80 81 82 83 84 85 86
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

Matthias Clasen's avatar
2.7.0  
Matthias Clasen committed
87 88 89
<!-- ##### SECTION Stability_Level ##### -->


90
<!-- ##### STRUCT GdkDevice ##### -->
Owen Taylor's avatar
Owen Taylor committed
91
<para>
Matthias Clasen's avatar
Matthias Clasen committed
92 93 94 95 96
A <structname>GdkDevice</structname> structure contains
a detailed description of an extended input device. All
fields are read-only; but you can use gdk_device_set_source(),
gdk_device_set_mode(), gdk_device_set_key() and gdk_device_set_axis_use()
to configure various aspects of the device.
97
</para>
Owen Taylor's avatar
Owen Taylor committed
98

Matthias Clasen's avatar
Updates  
Matthias Clasen committed
99
@parent_instance: the parent instance
Owen Taylor's avatar
Owen Taylor committed
100
@name: the name of this device.
Matthias Clasen's avatar
Matthias Clasen committed
101 102 103 104 105 106 107 108
@source: the type of this device.
@mode: the mode of this device
@has_cursor: %TRUE if the pointer follows device motion.
@num_axes: the length of the @axes array.
@axes: an array of #GdkDeviceAxis, describing the axes of this device.
@num_keys: the length of the @keys array.
@keys: an array of #GdkDeviceKey, describing the mapped macro buttons 
  of this device.
Owen Taylor's avatar
Owen Taylor committed
109

110
<!-- ##### ENUM GdkInputSource ##### -->
Owen Taylor's avatar
Owen Taylor committed
111
<para>
112 113
An enumeration describing the type of an input device
in general terms.
Owen Taylor's avatar
Owen Taylor committed
114 115
</para>

116 117 118 119 120 121
@GDK_SOURCE_MOUSE: the device is a mouse. (This will be reported for the core
                    pointer, even if it is something else, such as a trackball.)
@GDK_SOURCE_PEN: the device is a stylus of a graphics tablet or similar device.
@GDK_SOURCE_ERASER: the device is an eraser. Typically, this would be the other end
                    of a stylus on a graphics tablet.
@GDK_SOURCE_CURSOR: the device is a graphics tablet "puck" or similar device.
Owen Taylor's avatar
Owen Taylor committed
122

123
<!-- ##### ENUM GdkInputMode ##### -->
Owen Taylor's avatar
Owen Taylor committed
124
<para>
125
An enumeration that describes the mode of an input device.
Owen Taylor's avatar
Owen Taylor committed
126 127
</para>

128 129 130 131 132 133 134
@GDK_MODE_DISABLED: the device is disabled and will not report any events.
@GDK_MODE_SCREEN: the device is enabled. The device's coordinate space
                    maps to the entire screen.
@GDK_MODE_WINDOW: the device is enabled. The device's coordinate space
                    is mapped to a single window. The manner in which this window
                    is chosen is undefined, but it will typically be the same
                    way in which the focus window for key events is determined.
Owen Taylor's avatar
Owen Taylor committed
135

Owen Taylor's avatar
Owen Taylor committed
136
<!-- ##### STRUCT GdkDeviceKey ##### -->
Owen Taylor's avatar
Owen Taylor committed
137
<para>
Matthias Clasen's avatar
Matthias Clasen committed
138 139 140
The <structname>GdkDeviceKey</structname> structure contains information
about the mapping of one device macro button onto a normal X key event. 
It has the following fields:
Owen Taylor's avatar
Owen Taylor committed
141 142
</para>

Owen Taylor's avatar
Owen Taylor committed
143 144 145
@keyval: the keyval to generate when the macro button is pressed.
         If this is 0, no keypress will be generated.
@modifiers: the modifiers set for the generated key event.
Owen Taylor's avatar
Owen Taylor committed
146

147
<!-- ##### STRUCT GdkDeviceAxis ##### -->
Owen Taylor's avatar
Owen Taylor committed
148
<para>
Matthias Clasen's avatar
Matthias Clasen committed
149 150
The <structname>GdkDeviceAxis</structname> structure contains information
about the range and mapping of a device axis.
151
</para>
Owen Taylor's avatar
Owen Taylor committed
152

Matthias Clasen's avatar
Matthias Clasen committed
153
@use: specifies how the axis is used.
Owen Taylor's avatar
Owen Taylor committed
154
@min: the minimal value that will be reported by this axis.
Matthias Clasen's avatar
Matthias Clasen committed
155
@max: the maximal value that will be reported by this axis.
Owen Taylor's avatar
Owen Taylor committed
156

157
<!-- ##### ENUM GdkAxisUse ##### -->
Owen Taylor's avatar
Owen Taylor committed
158
<para>
159 160 161
An enumeration describing the way in which a device
axis (valuator) maps onto the predefined valuator
types that GTK+ understands.
Owen Taylor's avatar
Owen Taylor committed
162 163
</para>

164 165 166 167 168 169
@GDK_AXIS_IGNORE: the axis is ignored.
@GDK_AXIS_X: the axis is used as the x axis.
@GDK_AXIS_Y: the axis is used as the y axis.
@GDK_AXIS_PRESSURE: the axis is used for pressure information.
@GDK_AXIS_XTILT: the axis is used for x tilt information.
@GDK_AXIS_YTILT: the axis is used for x tilt information.
170
@GDK_AXIS_WHEEL: the axis is used for wheel information.
171
@GDK_AXIS_LAST: a constant equal to the numerically highest axis value.
Owen Taylor's avatar
Owen Taylor committed
172

173
<!-- ##### FUNCTION gdk_devices_list ##### -->
Owen Taylor's avatar
Owen Taylor committed
174 175 176
<para>
</para>

Owen Taylor's avatar
Owen Taylor committed
177
@Returns: 
Owen Taylor's avatar
Owen Taylor committed
178 179


180
<!-- ##### FUNCTION gdk_device_set_source ##### -->
Owen Taylor's avatar
Owen Taylor committed
181
<para>
182
Sets the source type for an input device.
Owen Taylor's avatar
Owen Taylor committed
183 184
</para>

185 186
@device: a #GdkDevice.
@source: the source type.
Owen Taylor's avatar
Owen Taylor committed
187 188


189
<!-- ##### FUNCTION gdk_device_set_mode ##### -->
Owen Taylor's avatar
Owen Taylor committed
190
<para>
191 192 193
Sets a the mode of an input device. The mode controls if the 
device is active and whether the device's range is mapped to the
entire screen or to a single window.
Owen Taylor's avatar
Owen Taylor committed
194 195
</para>

196
@device: a #GdkDevice.
197 198
@mode: the input mode.
@Returns: %TRUE if the mode was successfully changed.
Owen Taylor's avatar
Owen Taylor committed
199

200 201

<!-- ##### FUNCTION gdk_device_set_key ##### -->
Owen Taylor's avatar
Owen Taylor committed
202
<para>
203 204
Specifies the X key event to generate when a macro button of a device
is pressed.
Owen Taylor's avatar
Owen Taylor committed
205 206
</para>

207
@device: a #GdkDevice.
208
@index_: the index of the macro button to set.
209 210
@keyval: the keyval to generate.
@modifiers: the modifiers to set.
Owen Taylor's avatar
Owen Taylor committed
211 212


213
<!-- ##### FUNCTION gdk_device_set_axis_use ##### -->
Owen Taylor's avatar
Owen Taylor committed
214
<para>
215
Specifies how an axis of a device is used.
Owen Taylor's avatar
Owen Taylor committed
216 217
</para>

218
@device: a #GdkDevice.
219
@index_: the index of the axis.
220
@use: specifies how the axis is used.
Owen Taylor's avatar
Owen Taylor committed
221

222

Havoc Pennington's avatar
Havoc Pennington committed
223 224 225 226
<!-- ##### FUNCTION gdk_device_get_core_pointer ##### -->
<para>
</para>

227
@Returns: 
Havoc Pennington's avatar
Havoc Pennington committed
228 229


230
<!-- ##### FUNCTION gdk_device_get_state ##### -->
Owen Taylor's avatar
Owen Taylor committed
231

232 233 234 235
@device:
@window:
@axes:
@mask:
Owen Taylor's avatar
Owen Taylor committed
236 237


238
<!-- ##### FUNCTION gdk_device_get_history ##### -->
Owen Taylor's avatar
Owen Taylor committed
239
<para>
Matthias Clasen's avatar
Matthias Clasen committed
240

Owen Taylor's avatar
Owen Taylor committed
241 242
</para>

Matthias Clasen's avatar
Matthias Clasen committed
243 244 245 246 247 248 249
@device: 
@window: 
@start: 
@stop: 
@events: 
@n_events: 
@Returns: 
Owen Taylor's avatar
Owen Taylor committed
250 251


252
<!-- ##### FUNCTION gdk_device_free_history ##### -->
Owen Taylor's avatar
Owen Taylor committed
253
<para>
254
Frees an array of #GdkTimeCoord that was returned by gdk_device_get_history().
Owen Taylor's avatar
Owen Taylor committed
255 256
</para>

257 258
@events: an array of #GdkTimeCoord.
@n_events: the length of the array.
Owen Taylor's avatar
Owen Taylor committed
259 260 261 262


<!-- ##### STRUCT GdkTimeCoord ##### -->
<para>
Owen Taylor's avatar
Owen Taylor committed
263 264
The #GdkTimeCoord structure stores a single event in a
motion history. It contains the following fields:
Owen Taylor's avatar
Owen Taylor committed
265 266
</para>

Owen Taylor's avatar
Owen Taylor committed
267
@time: The timestamp for this event.
Matthias Clasen's avatar
Matthias Clasen committed
268
@axes: the values of the device's axes.
269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302

<!-- ##### FUNCTION gdk_device_get_axis ##### -->
<para>

</para>

@device: 
@axes: 
@use: 
@value: 
@Returns: 


<!-- ##### FUNCTION gdk_input_set_extension_events ##### -->
<para>
Turns extension events on or off for a particular window,
and specifies the event mask for extension events.
</para>

@window: a #GdkWindow.
@mask: the event mask
@mode: the type of extension events that are desired.


<!-- ##### ENUM GdkExtensionMode ##### -->
<para>
An enumeration used to specify which extension events
are desired for a particular widget.
</para>

@GDK_EXTENSION_EVENTS_NONE: no extension events are desired.
@GDK_EXTENSION_EVENTS_ALL: all extension events are desired.
@GDK_EXTENSION_EVENTS_CURSOR: extension events are desired only if a cursor
                              will be displayed for the device.
Owen Taylor's avatar
Owen Taylor committed
303