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