INPUT(7)INPUT(7)NAMEinput - input devices
DESCRIPTION
The IRIX operating system includes support for a number of input devices,
and support for additional devices can be added.
Standard input devices include the keyboard and mouse. Installing the
"Optional Input Devices" (eoe.sw.optinput) software adds support for the
following optional input devices:
o Calcomp tablets. (Module Name: calcomp, X Name: tablet)
o Hitachi HDG-J tablets. (Module Name: hitachi, X Name: hitachi)
o Other Hitachi tablets. (Module Name: tablet, X Name: tablet)
o Wacom tablets. (Module Name: wacom, X Name: wacom)
o The dial box. (Module Name: dialbox, X Name: dialbox)
o The dial and button box combination. (Module Name: dial, X Name:
dial+buttons)
o Imp infra-red presentation mouse. (Module Name: imp, X Name: imp)
o Logitech Magellan 3D controller. (Module Name: magellan, X Name:
magellan)
o Space ball. (Module Name: sball, X Name: spaceball)
Application programs access these devices using the X Input Extension.
The drivers for these devices are implemented as loadable STREAMS modules
(see ml(1m)). They handle device initialization and generate input
events in response to input from the devices. A driver will only be
loaded into the kernel when the corresponding device is opened for use.
CONFIGURING A DEVICE FOR USE
The easiest way to set up an optional input device is to use the visual
system adminstration tool SerialDeviceManager(1m) which is normally
accessed via the Toolchest(1)'s System section, through the System
Manager tool.
The X server looks for input devices by scanning the directory
/dev/input. Instead of using the SerialDeviceManager(1m), you can create
a link in this directory to the device special file associated with the
serial port the device is connected to. The name of the link must be the
same as the streams module name for the desired input device.
Page 1
INPUT(7)INPUT(7)
Note that the SerialDeviceManager will check various configuration files
and force you to remove other devices configured on a port before
allowing you to assign an input device to it. If you create the input
device file yourself, you must ensure that no other devices or programs
are associated with the port in question.
CUSTOM INPUT DEVICES
Support for custom X input devices can be added. First a STREAMS module
for the device must be written; the subsystem x_dev.src.examples installs
sample driver code in /usr/share/src/X/input/drivers. The device can then
be configured to work with the SerialDeviceManager by performing the
following actions.
An ftr file (see fftr(1)) for the device must be created in
/usr/lib/filetype/vadmin/ports. For example, an ftr file for the dial
and button box might appear as follows:
TYPE DialAndButton
MATCH false;
LEGEND DialAndButton
ICON {
include("iconlib/DialAndButton.fti");
}
"DialAndButton" should be replaced with a unique type name for the
device. The icon description may be included from the
/usr/lib/filetype/vadmin/ports/iconlib directory, as shown. After this
file is created, the following commands must be executed:
% cd /usr/lib/filetype
% make
A file must also be created in the /usr/lib/X11/input/installed
directory. This file must have the same name as the streams module for
the device. The first line in this file should be the string which will
identify the device for the user. The second line should be the type
name as given in the ftr file. Blank lines and lines that begin with the
character '#' are ignored.
For example, the file for the dial and button device might appear as
follows:
# Icon label
Dials & Buttons
# Icon type
DialAndButton
DEVICE CONTROLS
Device controls form an extensible mechanism for changing or querying
device characteristics. They fall into two categories: those
intercepted by the X server (x_init controls) and those handled by the
Page 2
INPUT(7)INPUT(7)
device drivers (device_init controls). The X server handles the x_init
controls, which change the way the server views devices. The device
drivers handle the device_init controls, which change device
characteristics.
Device controls can be permanently configured by storing them in files
which reside in the directory /usr/lib/X11/input/config.
The device_init controls must be placed in a file with the same name as
the streams module for the device (which is also the name of the link
created in /dev/input). The format is as follows:
device_init {
control "argument"
control "argument"
...
}
The x_init controls must be placed in a file with the X name of the
device (as supplied by the streams module). The format is as follows:
x_init {
control "argument"
control "argument"
...
}
If the streams module name and the X name are the same, device_init and
x_init controls may be placed in the same file. The device control
arguments must be enclosed in quotation marks.
You can also issue device controls dynamically by calling
XSGIDeviceControl(3X11) from within a program. The current setting of a
device control can be queried by using XSGIDeviceQuery(3X11).
The sample program devctrl can be used to issue or query device controls
from a command line prompt or script. The source for this program is
installed in /usr/share/src/X/input/clients by "X11 Source Code Examples"
(x_dev.src.examples).
DEVICE INITIALIZATION
The X server looks for new devices both at initialization time and when a
client requests a list of devices. When it finds a new device, it:
o opens the device and loads the streams module
o issues device_init controls
o asks the device to describe itself
Page 3
INPUT(7)INPUT(7)
o issues x_init controls
o closes the device unless autostart (see below) is on
When some program opens a device that is not autostarted nor open by some
other program, the X server:
o opens the device and loads the streams module
o issues device_init controls
o issues x_init controls
o starts reporting events from the device
X_INIT CONTROLS
The X server intercepts the following x_init controls:
autostart "on"/"off"
Specifies whether ("on") or not ("off") the device is opened
automatically by the X server. Extension devices are normally
ignored until some client explicitly opens them, but you can change
that using this directive. This allows you to use several devices
to control the cursor simultaneously without explicitly opening the
extension devices you wish to use.
keymap <keymap name>
Not implemented, but reserved (and intercepted).
motionhist <event count>
Specifies the maximum number of events to keep in a motion history
buffer for the device. This buffer is accessed using the X Input
Extension request XGetDeviceMotionEvents. The default size is 0.
The maximum size is 2048 events.
name <new name>
Renames the device. This changes the name of the device as
reported by the X Input Extension.
pushpointer "on"/"off"/"exclusive"
Controls whether or not the device generates core pointer events as
well as extension events. "on" means generate both, "off" means
generate extension events only and "exclusive" means generate core
events for two axes and extension events for the rest of them.
pushx <axis number>
Specifies the device axis which generates the X position in core
pointer events if pushpointer is "on" or "exclusive".
pushy <axis number>
Specifies the device axis which generates the Y position in core
pointer events if pushpointer is "on" or "exclusive".
Page 4
INPUT(7)INPUT(7)
scale "iso"/"fit"/"none"
Tells the X server how to scale the device the next time it is
opened. Scale "iso" uses the full range of either the X or Y axis
but preserves a 1 to 1 aspect ratio. Scale "fit" uses the full range
of both axes (aspect ratio may be skewed). Scale "none" uses raw
device data. Unless you're supporting a tablet, you probably want
scale "none".
scalewhich "allvals"/"novals"/"ptrvals"/"ptr"/"noptr"/"none"
Specifies the axes and events affected by the scale control.
Scalewhich "allvals" scales all extension device valuators
(meaningless for scale-to-fit). Scalewhich "novals" doesn't scale
any extension device valuators. Scalewhich "ptrvals" scales only
the extension valuators which correspond to the core pointer X and Y
axes. Scalewhich "ptr" means to scale the core pointer X and Y
values and "noptr" means no to. Scalewhich "none" means don't
scale anything. The effects of this control are cumulative, so you
can issue several.
screenchange "on"/"off"
For configurations where multiple screens are associated with a
single X server, specifies whether a change to a different screen
can be triggered by the device. The default is "on" (screen changes
enabled) for all devices. The device must be an active pointer
device (pushpointer "on" or "exclusive") in order to trigger a
screen change.
type <new type>
Changes the type of the device as reported by the X Input Extension.
DEVICE_INIT CONTROLS
Here are some of the more common device_init controls. Any control which
changes the observed characteristics of the device should be issued only
as a device_init control because the X server has already asked the
device to describe itself when it issues the x_init controls and it will
not notice the changes. "Observed chararcteristics" include number of
axes, buttons or keys or the range of the devices axes; they do not
include controls which change the way that physical device events are
mapped onto X events.
pressure "on"/"off"
For pressure sensitive tablets. Start/stop reporting pressure (and
tilt/height in some cases) information. This option adds axes (for
the pen pressure value) to a device, so it should be a device_init
option.
btnpressure <pressure>
For pressure sensitive tablets. Specifies the threshold above which
the tip pressure generates a button event. Note that this is a raw
8 bit integer, *not* an ascii decimal number. To set the tip button
pressure to '5', use '^E' (control-E), NOT '5'. This option
controls the mapping of physical pressure events on to X button
Page 5
INPUT(7)INPUT(7)
events, but it does not affect the observed characteristics of the
device. It can safely be used as either an x_init or a device_init
option.
invert <axes to invert>
Where <axes to invert> is a (case sensitive) string of characters
which specifies the axes to be inverted. An 'x' means invert the X
axis in core pointer events, a 'y' means invert the Y axis. A
single digit '0'-'9' means invert the corresponding axis in
extension events. A '!' in the string reverses the interpretation
of all following characters in the string. For example "y1" means:
invert the Y axis in core events and axis 1 in extension events
(leave all other axes alone). A "y!x" means: invert the Y axis in
core events but do not invert the X axis; in this case, extension
events are not affected. Affects mapping only, so it can be either
x_init or device_init.
left/right/top/bottom <offset>
Primarily for tablet devices. Specifies a dead margin (in raw
device coordinates) around the edges of the tablet. These requests
change the apparent size of the tablet surface so they should be
device_init options only.
max[xXyY0-9] <maximum value>
Changes the maximum value for the corresponding valuators. Note
that "maxx" and "maxy" change the axes that correspond to the core
pointer axes, not the core pointer events themselves. In other
words, you can't use this request to get illegal core pointer events
(core pointer events are always restricted to the screen).
device_init only.
model <vendor specific>
Specifies the model of the device so the driver can do model
specific things. Unfortunately, probing a device from the kernel
is pretty messy, so we use this control in a configuration file to
specify the type of device attached (for now). device_init only.
scale[xXyY0-9] <scale factor>
Control scaling on an axis by axis basis. To use this, first set
scalewhich none in the X server so the X server doesn't clobber your
values. For example:
scalex "1/5"
scales core pointer x events by one fifth.
scale4 "5"
scales extension valuator 4 events by 5.
Note that changing scaling does not affect the range of the valuator
- extension valuators are clamped to the range of the device. In
other words, if you scale a tablet axis by 5, you'll only be able to
use one-fifth of the tablets surface in the corresponding direction.
Page 6
INPUT(7)INPUT(7)
These affect mapping only, so they can be device_init or x_init.
EXAMPLES
The calcomp tablet uses a streams module named "calcomp" but reports an X
name of "tablet". The Drawing Pad II is 7" by 7" and has a resolution of
1000 points per inch. To scale raw tablet events to screen coordinates
(1280x1024) we create /usr/lib/X11/input/config/tablet (name of X device)
with the contents:
x_init {
scalewhich "none"
scalex "914/5000"
scaley "914/5000"
scale0 "914/5000"
scale1 "914/5000"
}
To make the calcomp tablet control the cursor automatically, we would add
the lines:
pushpointer "on"
autostart "on"
If we wanted a 1" margin around the tablet, we'd create a device_init
file (/usr/lib/X11/input/config/calcomp) with the contents:
device_init {
left "1000"
right "1000"
top "1000"
bottom "1000"
}
Of course, this reduces the tablet surface by 2000 units in each
direction, so we'd have to recalculate scale[xy01] values for the x_init
options to get the mapping right.
If we wanted to do the same thing for the Hitachi tablet, (streams module
== tablet, X name == tablet) we'd put both the x_init and device_init
sections in the same file (/usr/lib/X11/input/config/tablet).
FILES
/dev/input/*
/usr/lib/X11/input/config/*
SEE ALSOSerialDeviceManager(1m), sysmgr(1m), mknod(1m), ml(1m),
XSGIDeviceControl(3X11), XSGIDeviceQuery(3X11), imp(7), hitachi(7)
Page 7
