sys/man/3/mouse

   1 .TH MOUSE 3
   2 .SH NAME
   3 mouse, cursor \- kernel mouse interface
   4 .SH SYNOPSIS
   5 .nf
   6 .B bind -a #m /dev
   7
   8 .B /dev/mouse
   9 .B /dev/mousein
  10 .B /dev/mousectl
  11 .B /dev/cursor
  12 .fi
  13 .SH DESCRIPTION
  14 The
  15 .I mouse
  16 device provides an interface to the mouse.
  17 There is also a cursor associated with the screen;
  18 it is always displayed at the current mouse position.
  19 .PP
  20 Reading the
  21 .B mouse
  22 file returns the mouse status: its position and button state.
  23 The read blocks until the state has changed since the last read.
  24 The read returns 49 bytes: the letter
  25 .B m
  26 followed by four decimal strings, each 11 characters
  27 wide followed by a blank:
  28 .I x
  29 and
  30 .IR y ,
  31 coordinates of the mouse position in the screen image;
  32 .IR buttons ,
  33 a bitmask with the
  34 1, 2, and 4 bits set when the
  35 mouse's left, middle, and right buttons,
  36 respectively, are down;
  37 and
  38 .IR msec ,
  39 a time stamp, in units of milliseconds.
  40 .PP
  41 Writing the
  42 .B mouse
  43 file, in the same format,
  44 causes the mouse cursor to move to the position specified by the
  45 .I x
  46 and
  47 .I y
  48 coordinates of the message.
  49 The
  50 .I buttons
  51 and
  52 .I msec
  53 fields are ignored and may be omitted.
  54 .PP
  55 Writes to the
  56 .B mousein
  57 file are processed as if they were generated by the
  58 mouse hardware itself,
  59 as extra mouse events to be processed and passed back via
  60 the
  61 .B mouse
  62 file.
  63 The
  64 .B mousein
  65 file, which may be opened
  66 only by the host owner, is intended for controlling devices, such as USB mice,
  67 that are managed by user-level software.
  68 Each event should consist of
  69 the letter
  70 .B m
  71 followed by delta
  72 .IR x ,
  73 delta
  74 .IR y ,
  75 and
  76 .IR buttons
  77 as space-separated decimal numbers.
  78 .PP
  79 Writing to the
  80 .B mousectl
  81 file configures and controls the mouse.
  82 The messages are:
  83 .TF ps2intellimouse
  84 .TP
  85 .B "serial\fI n\fP"
  86 sets serial port
  87 .I n
  88 to be the mouse port.
  89 .TP
  90 .B ps2
  91 sets the PS2 port to be the mouse port.
  92 .TP
  93 .B intellimouse
  94 uses the wheel on a Microsoft Intellimouse
  95 as the middle button.
  96 .TP
  97 .B ps2intellimouse
  98 is equivalent to a write of
  99 .B ps2
 100 followed by a write of
 101 .BR intellimouse .
 102 .TP
 103 .B "accelerated\fI [n]\fP"
 104 turns on mouse acceleration.
 105 .I N
 106 is an optional acceleration factor.
 107 .TP
 108 .B linear
 109 turns off mouse acceleration.
 110 .TP
 111 .B "res\fI n\fR"
 112 sets mouse resolution to a setting between 0 and
 113 3 inclusive.
 114 .TP
 115 .B "hwaccel\fI on/off\fP"
 116 sets whether acceleration is done in hardware or
 117 software.
 118 By default, PS2 mice use hardware and serial mice use
 119 software.
 120 Some laptops (notably the IBM Thinkpad T23) don't
 121 implement hardware acceleration for external mice.
 122 .TP
 123 .B swap
 124 swaps the left and right buttons on the mouse.
 125 .TP
 126 .B "buttonmap\fI xyz\fP"
 127 numbers the left, middle, and right mouse buttons
 128 .IR x ,
 129 .IR y ,
 130 and
 131 .IR z ,
 132 respectively.
 133 If
 134 .I xyz
 135 is omitted, the default map, 123, is used.
 136 Thus in the default state writing
 137 .B "buttonmap 321
 138 swaps left and right buttons
 139 and writing
 140 .B "buttonmap 123
 141 or just
 142 .B buttonmap
 143 restores their usual meaning.
 144 Note that
 145 .B buttonmap
 146 messages are idempotent,
 147 unlike
 148 .BR swap .
 149 .TP
 150 .B scrollswap
 151 inverts the scroll wheel.
 152 .TP
 153 .B reset
 154 clears the mouse
 155 to its default state.
 156 .TP
 157 .B blank
 158 blanks the screen.
 159 The screen also blanks after
 160 .I blanktime
 161 minutes of inactivity.
 162 The screen can be unblanked by moving the mouse.
 163 .TP
 164 .BI blanktime " minutes"
 165 sets the timeout before the
 166 screen blanks.
 167 If
 168 .I minutes
 169 is zero, blanking is disabled (this is the default).
 170 .TP
 171 .B twitch
 172 unblanks the screen and resets the idle timeout as if the
 173 mouse was twitched.
 174 .PD
 175 .PP
 176 Not all mice interpret all messages; with some devices,
 177 some of the messages may be no-ops.
 178 .PP
 179 Cursors are described in
 180 .IR graphics (2).
 181 When read or written from or to the
 182 .B cursor
 183 file, they are represented in a 72-byte binary format.
 184 The first and second four bytes are little endian
 185 32-bit numbers specifying the
 186 .I x
 187 and
 188 .I y
 189 coordinates of the cursor
 190 .IR offset ;
 191 the next 32 bytes are the
 192 .B clr
 193 bitmask,
 194 and the last 32 bytes the
 195 .B set
 196 bitmask.
 197 .PP
 198 Reading from the
 199 .B cursor
 200 file returns the current cursor information.
 201 Writing to the
 202 .B cursor
 203 file sets the current cursor information.
 204 A write of fewer than 72 bytes sets the
 205 cursor to the default, an arrow.
 206 .PP
 207 The
 208 .B mouse
 209 and
 210 .B cursor
 211 files are multiplexed by
 212 .IR rio (1)
 213 to give the illusion of a private mouse to each of its clients.
 214 The semantics are otherwise the same except that notification
 215 of a window resize is passed to the application using a
 216 .B mouse
 217 message beginning with
 218 .B r
 219 rather than
 220 .BR m ;
 221 see
 222 .IR rio (4)
 223 for details.
 224 .PP
 225 To cope with pointing devices with only two buttons, when the
 226 shift key is pressed, the right mouse button generates middle-button events.
 227 .SH SOURCE
 228 .B /sys/src/9/port/devmouse.c
 229 .SH "SEE ALSO
 230 .IR rio (4)
 231 .SH BUGS
 232 The cursor format is big endian while the
 233 rest of the graphics interface is little endian.