sys/man/2/mouse

   1 .TH MOUSE 2
   2 .SH NAME
   3 initmouse, readmouse, closemouse, moveto, getrect, drawgetrect, menuhit, setcursor, enter \- mouse control
   4 .SH SYNOPSIS
   5 .nf
   6 .B
   7 #include <u.h>
   8 .B
   9 #include <libc.h>
  10 .B
  11 #include <draw.h>
  12 .B
  13 #include <thread.h>
  14 .B
  15 #include <mouse.h>
  16 .B
  17 #include <cursor.h>
  18 .PP
  19 .B
  20 Mousectl        *initmouse(char *file, Image *i)
  21 .PP
  22 .B
  23 int             readmouse(Mousectl *mc)
  24 .PP
  25 .B
  26 int             atomouse();
  27 .PP
  28 .B
  29 void            closemouse(Mousectl *mc)
  30 .PP
  31 .B
  32 void            moveto(Mousectl *mc, Point pt)
  33 .PP
  34 .B
  35 void            setcursor(Mousectl *mc, Cursor *c)
  36 .PP
  37 .B
  38 Rectangle       getrect(int but, Mousectl *mc)
  39 .PP
  40 .B
  41 void            drawgetrect(Rectangle r, int up)
  42 .PP
  43 .B
  44 int             menuhit(int but, Mousectl *mc, Menu *menu, Screen *scr)
  45 .PP
  46 .B
  47 int             enter(char *ask, char *buf, int len,
  48 .B
  49                         Mousectl *mc, Keyboardctl *kc, Screen *scr)
  50 .fi
  51 .SH DESCRIPTION
  52 These functions access and control a mouse in a multi-threaded environment.
  53 They use the message-passing
  54 .B Channel
  55 interface in the threads library
  56 (see
  57 .IR thread (2));
  58 programs that wish a more event-driven, single-threaded approach should use
  59 .IR event (2).
  60 .PP
  61 The state of the mouse is recorded in a structure,
  62 .BR Mouse ,
  63 defined in
  64 .BR <mouse.h> :
  65 .IP
  66 .EX
  67 .ta 6n +\w'Rectangle 'u +\w'buttons;   'u
  68 typedef struct Mouse Mouse;
  69 struct Mouse
  70 {
  71         int     buttons;        /* bit array: LMR=124 */
  72         Point   xy;
  73         ulong   msec;
  74 };
  75 .EE
  76 .PP
  77 The
  78 .B Point
  79 .B xy
  80 records the position of the cursor,
  81 .B buttons
  82 the state of the buttons (three bits representing, from bit 0 up, the buttons from left to right,
  83 0 if the button is released, 1 if it is pressed),
  84 and
  85 .BR msec ,
  86 a millisecond time stamp.
  87 .PP
  88 The routine
  89 .B initmouse
  90 returns a structure through which one may access the mouse:
  91 .IP
  92 .EX
  93 typedef struct Mousectl Mousectl;
  94 struct Mousectl
  95 {
  96         Mouse;
  97         Channel *c;     /* chan(Mouse)[16] */
  98         Channel *resizec;       /* chan(int)[2] */
  99
 100         char    *file;
 101         int     mfd;            /* to mouse file */
 102         int     cfd;            /* to cursor file */
 103         int     pid;            /* of slave proc */
 104         Image*  image;  /* of associated window/display */
 105 };
 106 .EE
 107 .PP
 108 The arguments to
 109 .I initmouse
 110 are a
 111 .I file
 112 naming the device file connected to the mouse and an
 113 .I Image
 114 (see
 115 .IR draw (2))
 116 on which the mouse will be visible.
 117 Typically the file is
 118 nil,
 119 which requests the default
 120 .BR /dev/mouse ;
 121 and the image is the window in which the program is running, held in the variable
 122 .B screen
 123 after a call to
 124 .IR initdraw .
 125 .PP
 126 Once the
 127 .B Mousectl
 128 is set up,
 129 mouse motion will be reported by messages of type
 130 .B Mouse
 131 sent on the
 132 .B Channel
 133 .BR Mousectl.c .
 134 Typically, a message will be sent every time a read of
 135 .B /dev/mouse
 136 succeeds, which is every time the state of the mouse changes.
 137 .PP
 138 When the window is resized, a message is sent on
 139 .BR Mousectl.resizec .
 140 The actual value sent may be discarded; the receipt of the message
 141 tells the program that it should call
 142 .B getwindow
 143 (see
 144 .IR graphics (2))
 145 to reconnect to the window.
 146 .PP
 147 .I Readmouse
 148 updates the
 149 .B Mouse
 150 structure held in the
 151 .BR Mousectl ,
 152 blocking if the state has not changed since the last
 153 .I readmouse
 154 or message sent on the channel.
 155 It calls
 156 .B flushimage
 157 (see
 158 .IR graphics (2))
 159 before blocking, so any buffered graphics requests are displayed.
 160 .PP
 161 .I Closemouse
 162 closes the file descriptors associated with the mouse, kills the slave processes,
 163 and frees the
 164 .B Mousectl
 165 structure.
 166 .PP
 167 .I Moveto
 168 moves the mouse cursor on the display to the position specified by
 169 .IR pt .
 170 .PP
 171 .I Setcursor
 172 sets the image of the cursor to that specified by
 173 .IR c .
 174 If
 175 .I c
 176 is nil, the cursor is set to the default.
 177 The format of the cursor data is spelled out in
 178 .B <cursor.h>
 179 and described in
 180 .IR graphics (2).
 181 .PP
 182 .I Getrect
 183 returns the dimensions of a rectangle swept by the user, using the mouse,
 184 in the manner
 185 .IR rio (1)
 186 or
 187 .IR sam (1)
 188 uses to create a new window.
 189 The
 190 .I but
 191 argument specifies which button the user must press to sweep the window;
 192 any other button press cancels the action.
 193 The returned rectangle is all zeros if the user cancels.
 194 .PP
 195 .I Getrect
 196 uses successive calls to
 197 .I drawgetrect
 198 to maintain the red rectangle showing the sweep-in-progress.
 199 The rectangle to be drawn is specified by
 200 .I rc
 201 and the
 202 .I up
 203 parameter says whether to draw (1) or erase (0) the rectangle.
 204 .PP
 205 .I Menuhit
 206 provides a simple menu mechanism.
 207 It uses a
 208 .B Menu
 209 structure defined in
 210 .BR <mouse.h> :
 211 .IP
 212 .EX
 213 typedef struct Menu Menu;
 214 struct Menu
 215 {
 216         char    **item;
 217         char    *(*gen)(int);
 218         int     lasthit;
 219 };
 220 .EE
 221 .PP
 222 .IR Menuhit
 223 behaves the same as its namesake
 224 .I emenuhit
 225 described in
 226 .IR event (2),
 227 with two exceptions.
 228 First, it uses a
 229 .B Mousectl
 230 to access the mouse rather than using the event interface;
 231 and second,
 232 it creates the menu as a true window on the
 233 .B Screen
 234 .I scr
 235 (see
 236 .IR window (2)),
 237 permitting the menu to be displayed in parallel with other activities on the display.
 238 If
 239 .I scr
 240 is null,
 241 .I menuhit
 242 behaves like
 243 .IR emenuhit ,
 244 creating backing store for the menu, writing the menu directly on the display, and
 245 restoring the display when the menu is removed.
 246 .PP
 247 .I Enter
 248 is a multithreded version of the
 249 .I eenter
 250 function described in
 251 .IR event (2).
 252 Like
 253 .I menuhit,
 254 it has a optional
 255 .B scr
 256 argument to create a window. Keyboard input is read from the channel in the
 257 .B Keyboardctl *kc
 258 argument (see
 259 .IR keyboard (2)).
 260 .PP
 261 .SH SOURCE
 262 .B /sys/src/libdraw
 263 .SH SEE ALSO
 264 .IR graphics (2),
 265 .IR draw (2),
 266 .IR event (2),
 267 .IR keyboard (2),
 268 .IR thread (2).