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 is exclusive-use and 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 30 minutes of inactivity.
 160 The screen can be unblanked by moving the mouse.
 161 .TP
 162 .BI blanktime " minutes"
 163 sets the timeout before the
 164 screen blanks; the default is 30 minutes.
 165 If
 166 .I minutes
 167 is zero, blanking is disabled.
 168 .TP
 169 .B twitch
 170 unblanks the screen and resets the idle timeout as if the
 171 mouse was twitched.
 172 .PD
 173 .PP
 174 Not all mice interpret all messages; with some devices,
 175 some of the messages may be no-ops.
 176 .PP
 177 Cursors are described in
 178 .IR graphics (2).
 179 When read or written from or to the
 180 .B cursor
 181 file, they are represented in a 72-byte binary format.
 182 The first and second four bytes are little endian
 183 32-bit numbers specifying the
 184 .I x
 185 and
 186 .I y
 187 coordinates of the cursor
 188 .IR offset ;
 189 the next 32 bytes are the
 190 .B clr
 191 bitmask,
 192 and the last 32 bytes the
 193 .B set
 194 bitmask.
 195 .PP
 196 Reading from the
 197 .B cursor
 198 file returns the current cursor information.
 199 Writing to the
 200 .B cursor
 201 file sets the current cursor information.
 202 A write of fewer than 72 bytes sets the
 203 cursor to the default, an arrow.
 204 .PP
 205 The
 206 .B mouse
 207 and
 208 .B cursor
 209 files are multiplexed by
 210 .IR rio (1)
 211 to give the illusion of a private mouse to each of its clients.
 212 The semantics are otherwise the same except that notification
 213 of a window resize is passed to the application using a
 214 .B mouse
 215 message beginning with
 216 .B r
 217 rather than
 218 .BR m ;
 219 see
 220 .IR rio (4)
 221 for details.
 222 .PP
 223 To cope with pointing devices with only two buttons, when the
 224 shift key is pressed, the right mouse button generates middle-button events.
 225 .SH SOURCE
 226 .B /sys/src/9/port/devmouse.c
 227 .SH "SEE ALSO
 228 .IR rio (4)
 229 .SH BUGS
 230 The cursor format is big endian while the
 231 rest of the graphics interface is little endian.