[~andy/gtk] / docs / reference / gdk / tmpl / input_devices.sgml

<!-- ##### SECTION Title ##### -->
Input Devices

<!-- ##### SECTION Short_Description ##### -->
Functions for handling extended input devices

<!-- ##### SECTION Long_Description ##### -->
<para>
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
must retrieve the device information using gdk_devices_list(),
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
maximum tilt to the left or up, and 1.0 representing the maximum
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
can be one of %GDK_SOURCE_MOUSE, %GDK_SOURCE_PEN, %GDK_SOURCE_ERASER,
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>
Various aspects of each device may be configured.
The configuration of devices is queried using gdk_devices_list().
Each device must be activated using gdk_device_set_mode(), which
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
gdk_device_set_axis_use(). And the source type for each device
can be set with gdk_device_set_source().
</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
gdk_device_set_key().
</para>
<para>
The interfaces in this section will most likely be considerably
modified in the future to accomodate devices that may have different
sets of additional valuators than the pressure <structfield>xtilt</structfield>
and <structfield>ytilt</structfield>.
</para>

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

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### SECTION Image ##### -->


<!-- ##### STRUCT GdkDevice ##### -->
<para>
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.
</para>

@parent_instance: the parent instance
@name: the name of this device.
@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.

<!-- ##### ENUM GdkInputSource ##### -->
<para>
An enumeration describing the type of an input device
in general terms.
</para>

@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.

<!-- ##### ENUM GdkInputMode ##### -->
<para>
An enumeration that describes the mode of an input device.
</para>

@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.

<!-- ##### STRUCT GdkDeviceKey ##### -->
<para>
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:
</para>

@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.

<!-- ##### STRUCT GdkDeviceAxis ##### -->
<para>
The <structname>GdkDeviceAxis</structname> structure contains information
about the range and mapping of a device axis.
</para>

@use: specifies how the axis is used.
@min: the minimal value that will be reported by this axis.
@max: the maximal value that will be reported by this axis.

<!-- ##### ENUM GdkAxisUse ##### -->
<para>
An enumeration describing the way in which a device
axis (valuator) maps onto the predefined valuator
types that GTK+ understands.
</para>

@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.
@GDK_AXIS_WHEEL: the axis is used for wheel information.
@GDK_AXIS_LAST: a constant equal to the numerically highest axis value.

<!-- ##### FUNCTION gdk_devices_list ##### -->
<para>
</para>

@void: 
@Returns: 


<!-- ##### FUNCTION gdk_device_set_source ##### -->
<para>
Sets the source type for an input device.
</para>

@device: a #GdkDevice.
@source: the source type.


<!-- ##### FUNCTION gdk_device_set_mode ##### -->
<para>
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.
</para>

@device: a #GdkDevice.
@mode: the input mode.
@Returns: %TRUE if the mode was successfully changed.


<!-- ##### FUNCTION gdk_device_set_key ##### -->
<para>
Specifies the X key event to generate when a macro button of a device
is pressed.
</para>

@device: a #GdkDevice.
@index_: the index of the macro button to set.
@keyval: the keyval to generate.
@modifiers: the modifiers to set.


<!-- ##### FUNCTION gdk_device_set_axis_use ##### -->
<para>
Specifies how an axis of a device is used.
</para>

@device: a #GdkDevice.
@index_: the index of the axis.
@use: specifies how the axis is used.


<!-- ##### FUNCTION gdk_device_get_core_pointer ##### -->
<para>
</para>

@void: 
@Returns: 


<!-- ##### FUNCTION gdk_device_get_state ##### -->


@device: 
@window: 
@axes: 
@mask: 


<!-- ##### FUNCTION gdk_device_get_history ##### -->
<para>

</para>

@device: 
@window: 
@start: 
@stop: 
@events: 
@n_events: 
@Returns: 


<!-- ##### FUNCTION gdk_device_free_history ##### -->
<para>
Frees an array of #GdkTimeCoord that was returned by gdk_device_get_history().
</para>

@events: an array of #GdkTimeCoord.
@n_events: the length of the array.


<!-- ##### STRUCT GdkTimeCoord ##### -->
<para>
The #GdkTimeCoord structure stores a single event in a
motion history. It contains the following fields:
</para>

@time: The timestamp for this event.
@axes: the values of the device's axes.

<!-- ##### 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.