forked from AuroraMiddleware/gtk
0072dd5508
Mon Aug 16 6:60:53 1999 Owen Taylor <otaylor@redhat.com> * gdk/tmpl/properties.sgml gdk/tmpl/selections.sgml gdk/tmpl/input_devices.sgml: Documented * gdk/gdk-sections.txt: Moved around types for input devices properties and selections, marked a few functions as private.
302 lines
11 KiB
Plaintext
302 lines
11 KiB
Plaintext
<!-- ##### 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_input_list_devices(),
|
|
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 title 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 easiest way of
|
|
creating a GUI to allow the user to conifigure such a device
|
|
is to use to use the #GtkInputDialog widget in GTK+.
|
|
However, even when using this widget, application writers
|
|
will need to directly query and set the configuration parameters
|
|
in order to save the state between invocations of the application.
|
|
The configuration of devices is queried using gdk_input_list_devices.
|
|
Each device must is activated using gdk_input_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_input_set_axes. And the source type for each device
|
|
can be set with gdk_input_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_input_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 xtilt and ytilt.
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### MACRO GDK_CORE_POINTER ##### -->
|
|
<para>
|
|
This macro contains an integer value representing
|
|
the device ID for the core pointer device.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_input_list_devices ##### -->
|
|
<para>
|
|
Lists all available input devices, along with their
|
|
configuration information.
|
|
</para>
|
|
|
|
@Returns: A #GList of #GdkDeviceInfo structures. This list
|
|
is internal data of GTK+ and should not be modified
|
|
or freed.
|
|
|
|
|
|
<!-- ##### STRUCT GdkDeviceInfo ##### -->
|
|
<para>
|
|
The #GdkDeviceInfo structure contains information about a
|
|
device. It has the following fields:
|
|
</para>
|
|
|
|
@deviceid: a unique integer ID for this device.
|
|
@name: the human-readable name for the device.
|
|
@source: the type of device.
|
|
@mode: a value indicating whether the device is enabled and
|
|
how the device coordinates map to the screen.
|
|
@has_cursor: if %TRUE, a cursor will be displayed indicating
|
|
the current on-screen location to the user. Otherwise,
|
|
the application is responsible for drawing a cursor
|
|
itself.
|
|
@num_axes: the number of axes for this device.
|
|
@axes: a pointer to an array of GdkAxisUse values which
|
|
give the mapping of axes onto the possible valuators
|
|
for a GDK device.
|
|
@num_keys: the number of macro buttons.
|
|
@keys: a pointer to an array of #GdkDeviceKey structures
|
|
which describe what key press events are generated
|
|
for each macro button.
|
|
|
|
<!-- ##### STRUCT GdkDeviceKey ##### -->
|
|
<para>
|
|
The #GdkDeviceKey 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.
|
|
|
|
<!-- ##### 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.
|
|
|
|
<!-- ##### FUNCTION gdk_input_set_source ##### -->
|
|
<para>
|
|
Sets the source type for a device.
|
|
</para>
|
|
|
|
@deviceid: the device to configure
|
|
@source: the new source type.
|
|
|
|
|
|
<!-- ##### 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.
|
|
|
|
<!-- ##### FUNCTION gdk_input_set_mode ##### -->
|
|
<para>
|
|
Enables or disables a device, and determines how the
|
|
device maps onto the screen.
|
|
</para>
|
|
|
|
@deviceid: the device to configure.
|
|
@mode: the new mode.
|
|
@Returns: %TRUE if the device supports the given mode, otherwise
|
|
%FALSE and the device's mode is unchanged.
|
|
|
|
|
|
<!-- ##### 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.
|
|
|
|
<!-- ##### FUNCTION gdk_input_set_axes ##### -->
|
|
<para>
|
|
Sets the mapping of the axes (valuators) of a device
|
|
onto the predefined valuator types that GTK+ understands.
|
|
</para>
|
|
|
|
@deviceid: the device to configure.
|
|
@axes: an array of GdkAxisUse. This length of this array
|
|
must match the number of axes for the device.
|
|
|
|
|
|
<!-- ##### 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_LAST: a constant equal to the numerically highest axis value.
|
|
|
|
<!-- ##### FUNCTION gdk_input_set_key ##### -->
|
|
<para>
|
|
Sets the key event generated when a macro button is pressed.
|
|
</para>
|
|
|
|
@deviceid: the device to configure.
|
|
@index: the index of the macro button.
|
|
@keyval: the key value for the #GdkKeypressEvent to generate.
|
|
(a value of 0 means no event will be generated.)
|
|
@modifiers: the modifier field for the generated
|
|
#GdkKeyPressEvent.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_input_window_get_pointer ##### -->
|
|
<para>
|
|
Returns information about the current position of the pointer
|
|
within a window, including extended device information.
|
|
Any of the return parameters may be %NULL, in which case,
|
|
they will be ignored.
|
|
</para>
|
|
|
|
@window: a #GdkWindow.
|
|
@deviceid: a device ID.
|
|
@x: location to store current x postion.
|
|
@y: location to store current y postion.
|
|
@pressure: location to store current pressure.
|
|
@xtilt: location to store current tilt in the x direction.
|
|
@ytilt: location to store current tilt in the y direction.
|
|
@mask: location to store the current modifier state.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_input_motion_events ##### -->
|
|
<para>
|
|
Retrieves the motion history for a given device/window pair.
|
|
</para>
|
|
|
|
@window: a #GdkWindow.
|
|
@deviceid: the device for which to retrieve motion history.
|
|
@start: the start time.
|
|
@stop: the stop time.
|
|
@nevents_return: location to store the number of events returned.
|
|
@Returns: a newly allocated array containing all the events
|
|
from @start to @stop. This array should be freed
|
|
with g_free() when you are finished using it.
|
|
|
|
|
|
<!-- ##### 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.
|
|
@x: the x position.
|
|
@y: the y position.
|
|
@pressure: the pressure.
|
|
@xtilt: the tilt in the x direction.
|
|
@ytilt: the tilt in the y direction.
|
|
|