INPUT(7) INPUT(7) NAME input - 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: + Calcomp tablets. (Module Name: calcomp, X Name: tablet) + Hitachi HDG-J tablets. (Module Name: hitachi, X Name: hitachi) + Other Hitachi tablets. (Module Name: tablet, X Name: tablet) + Wacom tablets. (Module Name: wacom, X Name: wacom) + The dial box. (Module Name: dialbox, X Name: dialbox) + The dial and button box combination. (Module Name: dial, X Name: dial+buttons) + Imp infra-red presentation mouse. (Module Name: imp, X Name: imp) + Logitech Magellan 3D controller. (Module Name: magellan, X Name: magellan) + 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. 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 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: + opens the device and loads the streams module + issues device_init controls + asks the device to describe itself + issues x_init controls + 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: + opens the device and loads the streams module + issues device_init controls + issues x_init controls + 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". 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 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. 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 ALSO SerialDeviceManager(1m), sysmgr(1m), mknod(1m), ml(1m), XSGIDeviceControl(3X11), XSGIDeviceQuery(3X11), imp(7), hitachi(7) Page 7