usemouse(1)

usemouse -- map mouse input to keystrokes

Synopsis

usemouse [-f conffile | -t type] [-h horiz_sens] [-v vert_sens] [-c cmd] [-b] parameters

Description

The usemouse command merges data from a mouse into the input stream of a tty. The mouse data is translated to arrow keys or any other arbitrary ASCII strings. Mouse movements up, down, left, right, up-left, up-right, down-left, and down-right, as well as individual up and down button transitions, are programmable. This permits the mouse to be used with programs that are not designed to accept mouse input.

usemouse with no arguments sets the mouse for use with the default map /etc/default/usemouse. A new shell is invoked. To terminate usemouse, exit the shell with <Ctrl>d.

Alternate map files can be found in the directory /usr/lib/mouse. Users can create their own map files based on the default file. Quoted strings may be used in a map file, as well as the octal sequences found in the ascii(5) manual page. Map files can be located anywhere on the system and accessed with the -f option (see below).

The default map file has the following values:

Mouse Keystroke

Left Button vi top of file (1G) command

Middle Button vi delete character (x) command

Right Button vi bottom of file (G) command

Up Up arrow key

Down Down arrow key

Left Left arrow key

Right Right arrow key

Up and Left Not defined

Up and Right Not defined

Down and Left Not defined

Down and Right Not defined

Bells No

usemouse takes the following options:

Mouse	Keystroke
Left Button	vi top of file (1G) command
Middle Button	vi delete character (x) command
Right Button	vi bottom of file (G) command
Up	Up arrow key
Down	Down arrow key
Left	Left arrow key
Right	Right arrow key
Up and Left	Not defined
Up and Right	Not defined
Down and Left	Not defined
Down and Right	Not defined
Bells	No

-b: Suppress bell (<Ctrl>g) for the duration of mouse usage. Useful with vi(1).
-c cmd: Run cmd with usemouse. cmd defaults to the shell specified in the SHELL environment variable. If SHELL is unspecified, /bin/sh is used. Note that the command given with this flag can contain blank spaces if the entire command is placed within double quotes. For example:

usemouse -c "vi /etc/termcap"
is valid. When cmd terminates, usemouse terminates as well.
-f conffile: Select an alternate configuration file, conffile. conffile should use the format of /etc/default/usemouse.
-h horiz_sens: Define the horizontal sensitivity. Horizontal mouse movements smaller than this threshold are ignored. Mouse movements that are multiples of this value generate multiple strings. The sensitivity defaults to 5 units. The minimum value is 1 unit, and the maximum is 100 units. The lower the value, the more sensitive your mouse is to motion. Note that setting a high value may cause your mouse to behave as though it is not functioning, due to the large motion required to generate a signal.
-t type: Select a predefined configuration file. type can be any file in /usr/lib/mouse, such as vi, or rogue. These files are identical in format to /etc/default/usemouse.
The vi-specific map maps the traditional h-j-k-l direction keys to the mouse movements. The terminal bell is automatically silenced by the vi map entry bells=no. This is done to prevent the bell being activated continuously when the user generates a spurious command with the mouse.
-v vert_sens: Define the vertical sensitivity. Vertical mouse movements smaller than this threshold are ignored. Mouse movements that are multiples of this value generate multiple strings. The sensitivity defaults to 5 units. The minimum value is 1 unit, and the maximum is 100 units. The lower the value, the more sensitive your mouse is to motion. Note that setting a high value may cause your mouse to behave as though it is not functioning, due to the large motion required to generate a signal.

The parameters are name=value pairs indicating what ASCII string to insert into the tty input stream when the given event is received.

Valid parameters include:

rbu=string: String to generate on right button up.
rbd=string: String to generate on right button down.
mbu=string: String to generate on middle button up.
mbd=string: String to generate on middle button down.
lbu=string: String to generate on left button up.
lbd=string: String to generate on left button down.
rt=string: String to generate on mouse right.
lt=string: String to generate on mouse left.
up=string: String to generate on mouse up.
dn=string: String to generate on mouse down.
ul=string: String to generate on mouse up-left.
ur=string: String to generate on mouse up-right.
dr=string: String to generate on mouse down-right.
dl=string: String to generate on mouse down-left.
hsens=num: Sensitivity to horizontal motion.
vsens=num: Sensitivity to vertical motion.
bells=yes|no: Whether to remove <Ctrl>g characters.

Parameters may be specified in any order. They may contain octal escapes. They should be quoted with single or double quotes if they contain blank spaces. Any parameter may be omitted; its value is then taken from the configuration file.

Files

/dev/mouse: directory for mouse-related special device files
/etc/default/usemouse: default map file for mouse-generated characters
/usr/lib/event/devices: file containing device information for mice
/usr/lib/event/ttys: file listing ttys eligible to use mice
/usr/lib/mouse/: alternate map files for mice

References

ascii(5), vi(1)

Examples

To set up the mouse for use with vi, enter:

usemouse -t vi

This will not start vi.

To start up the mouse for use with vi, and start vi, enter:

usemouse -t vi -c vi

This invokes the vi map along with the command; when you quit out of vi the mouse disengages.

To start up vi using the default mouse map, but redefining the middle button (mbd) to be insert in vi, enter:

usemouse -c vi mbd=i

To start the mouse in vi using the customized map mine, enter:

usemouse -f mine -c vi

Standards compliance

usemouse is not part of any currently supported standard; it is an extension of AT&T System V provided by The Santa Cruz Operation, Inc.