1 files changed, 213 insertions, 0 deletions
diff --git a/static/plan9-4e/man3/mouse.3 b/static/plan9-4e/man3/mouse.3
new file mode 100644
index 00000000..f2bd33d8
--- /dev/null
+++ b/static/plan9-4e/man3/mouse.3
@@ -0,0 +1,213 @@
+.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 is exclusive-use, 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\fR
+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
+turns on mouse acceleration.
+.TP
+.B linear
+turns off mouse acceleration
+.TP
+.B res \fIn\fR
+sets mouse resolution to a setting between 0 and
+3 inclusive.
+.TP
+.B hwaccel \fIon/off\fR
+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 \fIxyz\fR
+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.
+.PP
+The
+.B mousein
+file is disabled.