mouse.3 (4987B)
1 .TH MOUSE 3 2 .SH NAME 3 initmouse, readmouse, closemouse, moveto, cursorswitch, getrect, drawgetrect, menuhit, setcursor \- 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 .fi 46 .SH DESCRIPTION 47 These functions access and control a mouse in a multi-threaded environment. 48 They use the message-passing 49 .B Channel 50 interface in the threads library 51 (see 52 .MR thread (3) ); 53 programs that wish a more event-driven, single-threaded approach should use 54 .MR event (3) . 55 .PP 56 The state of the mouse is recorded in a structure, 57 .BR Mouse , 58 defined in 59 .BR <mouse.h> : 60 .IP 61 .EX 62 .ta 6n +\w'Rectangle 'u +\w'buttons; 'u 63 typedef struct Mouse Mouse; 64 struct Mouse 65 { 66 int buttons; /* bit array: LMR=124 */ 67 Point xy; 68 ulong msec; 69 }; 70 .EE 71 .PP 72 The 73 .B Point 74 .B xy 75 records the position of the cursor, 76 .B buttons 77 the state of the buttons (three bits representing, from bit 0 up, the buttons from left to right, 78 0 if the button is released, 1 if it is pressed), 79 and 80 .BR msec , 81 a millisecond time stamp. 82 .PP 83 The routine 84 .B initmouse 85 returns a structure through which one may access the mouse: 86 .IP 87 .EX 88 typedef struct Mousectl Mousectl; 89 struct Mousectl 90 { 91 Mouse m; 92 Channel *c; /* chan(Mouse)[16] */ 93 Channel *resizec; /* chan(int)[2] */ 94 95 char *file; 96 int mfd; /* to mouse file */ 97 int cfd; /* to cursor file */ 98 int pid; /* of slave proc */ 99 Image* image; /* of associated window/display */ 100 }; 101 .EE 102 .PP 103 The arguments to 104 .I initmouse 105 are a 106 .I file 107 naming the device file connected to the mouse and an 108 .I Image 109 (see 110 .MR draw (3) ) 111 on which the mouse will be visible. 112 Typically the file is 113 nil, 114 which requests the default 115 .BR /dev/mouse ; 116 and the image is the window in which the program is running, held in the variable 117 .B screen 118 after a call to 119 .IR initdraw . 120 .PP 121 Once the 122 .B Mousectl 123 is set up, 124 mouse motion will be reported by messages of type 125 .B Mouse 126 sent on the 127 .B Channel 128 .BR Mousectl.c . 129 Typically, a message will be sent every time a read of 130 .B /dev/mouse 131 succeeds, which is every time the state of the mouse changes. 132 .PP 133 When the window is resized, a message is sent on 134 .BR Mousectl.resizec . 135 The actual value sent may be discarded; the receipt of the message 136 tells the program that it should call 137 .B getwindow 138 (see 139 .MR graphics (3) ) 140 to reconnect to the window. 141 .PP 142 .I Readmouse 143 updates the 144 .B Mouse 145 structure 146 .B m 147 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 .MR graphics (3) ) 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 .MR graphics (3) . 178 .PP 179 .I Getrect 180 returns the dimensions of a rectangle swept by the user, using the mouse, 181 in the manner 182 .MR rio (1) 183 or 184 .MR 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 .MR event (3) , 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 .MR window (3) ), 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 .SH SOURCE 245 .B \*9/src/libdraw 246 .SH SEE ALSO 247 .MR graphics (3) , 248 .MR draw (3) , 249 .MR event (3) , 250 .MR keyboard (3) , 251 .MR thread (3) .