):
def set_source(source
)
def set_mode(mode
)
def set_key(index
, keyval
, modifiers
)
def set_axis_use(index
, use
)
def get_state(window
)
def get_history(window
, start
, stop
)
def get_axis(axes
, use
)
Functions
def gtk.gdk.devices_list()
def gtk.gdk.device_get_core_pointer()
Description
In addition to the normal keyboard and mouse input devices,
PyGTK
also contains support for extended input devices.
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 XInput extension. Because handling
extended input devices may involve considerable overhead, they need to be
turned on for each gtk.gdk.Window
individually using gtk.gdk.Window.input_set_extension_events
().
(Or, more typically, for gtk.Widget
objects,
using the gtk.Widget.set_extension_events
()
method). 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
gtk.gdk.EXTENSION_EVENTS_CURSOR
value to the gtk.gdk.Window.input_set_extension_events
()
method. Otherwise, the application must retrieve the device information
using the gtk.gdk.devices_list
()
function, check the has_cursor field, and, if it is
False
, draw a cursor itself when it receives motion
events.
Each pointing device is assigned a unique integer ID; events from
a particular device can be identified by the deviceid
attribute in the event structure. The events generated by pointer devices
have also been extended to contain pressure
,
xtilt
and ytilt
attributes
which contain the extended information reported as additional valuators from
the device. The pressure
attribute ranges from 0.0 to
1.0, while the tilt attributes range 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.) One additional attribute in each event
is the source
attribute, which contains an
enumeration value describing the type of device; this currently can be one
of gtk.gdk.SOURCE_MOUSE
,
gtk.gdk.SOURCE_PEN
,
gtk.gdk.SOURCE_ERASER
, or
gtk.gdk.SOURCE_CURSOR
. This attribute 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.
Various aspects of each device may be configured. The easiest way
of creating a GUI to allow the user to configure such a device is to use the
gtk.InputDialog
widget in PyGTK
. 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 the gtk.gdk.devices_list
()
function. Each device must be activated using the set_mode
()
method, 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 the set_axis_use
()
method. And the source type for each device can be set with the set_source
()
method.
Devices may also have associated keys or macro buttons. Such keys
can be globally set to map into normal X keyboard events. The mapping is set
using the set_key
()
method. The interfaces in this section will most likely be considerably
modified in the future to accommodate devices that may have different sets of
additional valuators than the pressure xtilt and ytilt.
Methods
gtk.gdk.Device.set_source
def set_source(source
)
source :
| the source type of the
device |
The set_source
() method sets the source
type for the input device to the value specified by
source
. The value of source
must be one of:
gtk.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.) |
gtk.gdk.SOURCE_PEN
| the device is a stylus of a graphics tablet or similar
device. |
gtk.gdk.SOURCE_ERASER
| the device is an eraser. Typically, this would be the
other end of a stylus on a graphics tablet. |
gtk.gdk.SOURCE_CURSOR
| the device is a graphics tablet "puck" or similar
device. |
gtk.gdk.Device.set_mode
def set_mode(mode
)
mode :
| the input mode |
Returns : | True if the mode was
successfully changed. |
The set_mode
() method sets the input
device mode to the value specified by mode
. The value
of mode
must be one of:
gtk.gdk.MODE_DISABLED
| the device is disabled and will not report any
events. |
gtk.gdk.MODE_SCREEN
| the device is enabled. The device's coordinate space
maps to the entire screen. |
gtk.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. |
gtk.gdk.Device.set_key
def set_key(index
, keyval
, modifiers
)
index :
| the index of the macro button to
set. |
keyval :
| the key value to generate. |
modifiers :
| the modifiers to set. |
The set_key
() method sets the key event
to generate when a macro button of a device is pressed. The macro button is
specified by index
. The key value and modifiers
generated are specified by keyval
and
modifiers
respectively.
gtk.gdk.Device.set_axis_use
def set_axis_use(index
, use
)
index :
| the index of the axis. |
use :
| how the axis is used. |
The set_axis_use
() method sets the axis
(specified by index
) of the input device to be used
in the fashion specified by use
. The value of
use
must be one of:
gtk.gdk.AXIS_IGNORE
| the axis is ignored. |
gtk.gdk.AXIS_X
| the axis is used as the x axis. |
gtk.gdk.AXIS_Y
| the axis is used as the y axis. |
gtk.gdk.AXIS_PRESSURE
| the axis is used for pressure information. |
gtk.gdk.AXIS_XTILT
| the axis is used for x tilt information. |
gtk.gdk.AXIS_YTILT
| the axis is used for y tilt information. |
gtk.gdk.AXIS_WHEEL
| the axis is used for wheel information. |
gtk.gdk.AXIS_LAST
| a constant equal to the numerically highest axis
value. |
gtk.gdk.Device.get_state
def get_state(window
)
window :
| a gtk.gdk.Window |
Returns : | a tuple containing: a tuple containing the axes
data; and, the modifiers in effect. |
The get_state
() method returns a tuple
containing:
- a tuple containing the axes data
- the bitmask containing the set of key modifiers in
effect
The state information is relative to the gtk.gdk.Window
specified by window
.
gtk.gdk.Device.get_history
def get_history(window
, start
, stop
)
window :
| a gtk.gdk.Window |
start :
| the earliest event time
limit |
stop :
| the latest event time
limit |
Returns : | a tuple containing event tuples each with axes
data and a timestamp |
The get_history
() method returns a
tuple containing the motion history for the device with respect to the gtk.gdk.Window
specified by window between the time limits specified by
start
and stop
. The motion
history is a tuple containing event motion tuples that each contain a
timestamp for the event and a tuple with the axes data for the event.
gtk.gdk.Device.get_axis
def get_axis(axes
, use
)
axes :
| a sequence of axes values |
use :
| the axis use to match |
Returns : | the axis value from axes
that matches the use type or None if there is no
match. |
The get_axis
() method returns the value
in axes
whose axis matches the specified
use
.