Subversion Repositories planix.SVN

.TH MOUSE 3

.SH NAME

mouse, cursor \- kernel mouse interface

.SH SYNOPSIS

.nf

.B bind -a #m /dev

.B /dev/mouse

.B /dev/mousein

.B /dev/mousectl

.B /dev/cursor

.fi

.SH DESCRIPTION

The

.I mouse

device provides an interface to the mouse.

There is also a cursor associated with the screen;

it is always displayed at the current mouse position.

.PP

Reading the

.B mouse

file returns the mouse status: its position and button state.

The read blocks until the state has changed since the last read.

The read returns 49 bytes: the letter

.B m

followed by four decimal strings, each 11 characters

wide followed by a blank:

.I x

and

.IR y ,

coordinates of the mouse position in the screen image;

.IR buttons ,

a bitmask with the

1, 2, and 4 bits set when the

mouse's left, middle, and right buttons,

respectively, are down;

and

.IR msec ,

a time stamp, in units of milliseconds.

.PP

Writing the

.B mouse

file, in the same format,

causes the mouse cursor to move to the position specified by the

.I x

and

.I y

coordinates of the message.

The

.I buttons

and

.I msec

fields are ignored and may be omitted.

.PP

Writes to the

.B mousein

file are processed as if they were generated by the

mouse hardware itself,

as extra mouse events to be processed and passed back via

the

.B mouse

file.

The

.B mousein

file, which may be opened

only by the host owner, is intended for controlling devices, such as USB mice,

that are managed by user-level software.

Each event should consist of

the letter

.B m

followed by delta

.IR x ,

delta

.IR y ,

and

.IR buttons

as space-separated decimal numbers.

.PP

Writing to the

.B mousectl

file configures and controls the mouse.

The messages are:

.TF ps2intellimouse

.TP

.B "serial\fI n\fP"

sets serial port

.I n

to be the mouse port.

.TP

.B ps2

sets the PS2 port to be the mouse port.

.TP

.B intellimouse

uses the wheel on a Microsoft Intellimouse

as the middle button.

.TP

.B ps2intellimouse

is equivalent to a write of

.B ps2

followed by a write of

.BR intellimouse .

.TP

.B "accelerated\fI [n]\fP"

turns on mouse acceleration.

.I N

is an optional acceleration factor.

.TP

.B linear

turns off mouse acceleration.

.TP

.B "res\fI n\fR"

sets mouse resolution to a setting between 0 and

3 inclusive.

.TP

.B "hwaccel\fI on/off\fP"

sets whether acceleration is done in hardware or

software.

By default, PS2 mice use hardware and serial mice use

software.

Some laptops (notably the IBM Thinkpad T23) don't

implement hardware acceleration for external mice.

.TP

.B swap

swaps the left and right buttons on the mouse.

.TP

.B "buttonmap\fI xyz\fP"

numbers the left, middle, and right mouse buttons

.IR x ,

.IR y ,

and

.IR z ,

respectively.

If

.I xyz

is omitted, the default map, 123, is used.

Thus in the default state writing

.B "buttonmap 321

swaps left and right buttons

and writing

.B "buttonmap 123

or just

.B buttonmap

restores their usual meaning.

Note that

.B buttonmap

messages are idempotent,

unlike

.BR swap .

.TP

.B reset

clears the mouse

to its default state.

.PD

.PP

Not all mice interpret all messages; with some devices,

some of the messages may be no-ops.

.PP

Cursors are described in

.IR graphics (2).

When read or written from or to the

.B cursor

file, they are represented in a 72-byte binary format.

The first and second four bytes are little endian

32-bit numbers specifying the

.I x

and

.I y

coordinates of the cursor

.IR offset ;

the next 32 bytes are the

.B clr

bitmask,

and the last 32 bytes the

.B set

bitmask.

.PP

Reading from the

.B cursor

file returns the current cursor information.

Writing to the

.B cursor

file sets the current cursor information.

A write of fewer than 72 bytes sets the

cursor to the default, an arrow.

.PP

The

.B mouse

and

.B cursor

files are multiplexed by

.IR rio (1)

to give the illusion of a private mouse to each of its clients.

The semantics are otherwise the same except that notification

of a window resize is passed to the application using a

.B mouse

message beginning with

.B r

rather than

.BR m ;

see

.IR rio (4)

for details.

.PP

To cope with pointing devices with only two buttons, when the

shift key is pressed, the right mouse button generates middle-button events.

.SH SOURCE

.B /sys/src/9/port/devmouse.c

.SH "SEE ALSO

.IR rio (4)

.SH BUGS

The cursor format is big endian while the

rest of the graphics interface is little endian.