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