event.3 (7533B)
1 .TH EVENT 3 2 .SH NAME 3 event, einit, estart, estartfn, etimer, eread, emouse, ekbd, ecanread, ecanmouse, ecankbd, ereadmouse, eatomouse, eresized, egetrect, edrawgetrect, emenuhit, emoveto, esetcursor, Event, Mouse, Menu \- graphics events 4 .SH SYNOPSIS 5 .nf 6 .PP 7 .B 8 #include <u.h> 9 .B 10 #include <libc.h> 11 .B 12 #include <draw.h> 13 .B 14 #include <event.h> 15 .B 16 #include <cursor.h> 17 .ta \w'\fLRectangle 'u 18 .PP 19 .B 20 void einit(ulong keys) 21 .PP 22 .B 23 ulong event(Event *e) 24 .PP 25 .B 26 Mouse emouse(void) 27 .PP 28 .B 29 int ekbd(void) 30 .PP 31 .B 32 int ecanmouse(void) 33 .PP 34 .B 35 int ecankbd(void) 36 .PP 37 .B 38 int ereadmouse(Mouse *m) 39 .PP 40 .B 41 int eatomouse(Mouse *m, char *buf, int n) 42 .PP 43 .B 44 ulong estart(ulong key, int fd, int n) 45 .PP 46 .B 47 ulong estartfn(int id, ulong key, int fd, int n, 48 .B 49 int (*fn)(Event*, uchar*, int)) 50 .PP 51 .B 52 ulong etimer(ulong key, int n) 53 .PP 54 .B 55 ulong eread(ulong keys, Event *e) 56 .PP 57 .B 58 int ecanread(ulong keys) 59 .PP 60 .B 61 void eresized(int new) 62 .PP 63 .B 64 Rectangle egetrect(int but, Mouse *m) 65 .PP 66 .B 67 void edrawgetrect(Rectangle r, int up) 68 .PP 69 .B 70 int emenuhit(int but, Mouse *m, Menu *menu) 71 .PP 72 .PP 73 .B 74 int emoveto(Point p) 75 .PP 76 .PP 77 .B 78 int esetcursor(Cursor *c) 79 .PP 80 .B 81 extern Mouse *mouse 82 .PP 83 .B 84 enum{ 85 .B 86 Emouse = 1, 87 .B 88 Ekeyboard = 2, 89 .B 90 }; 91 .PP 92 .SH DESCRIPTION 93 These routines provide an interface to multiple sources of input for unthreaded 94 programs. 95 Threaded programs (see 96 .MR thread (3) ) 97 should instead use the threaded mouse and keyboard interface described 98 in 99 .MR mouse (3) 100 and 101 .MR keyboard (3) . 102 .PP 103 .I Einit 104 must be called first. 105 If the argument to 106 .I einit 107 has the 108 .B Emouse 109 and 110 .B Ekeyboard 111 bits set, 112 the mouse and keyboard events will be enabled; 113 in this case, 114 .IR initdraw 115 (see 116 .MR graphics (3) ) 117 must have already been called. 118 The user must provide a function called 119 .IR eresized 120 to be called whenever the window in which the process 121 is running has been resized; the argument 122 .I new 123 is a flag specifying whether the program must call 124 .I getwindow 125 (see 126 .MR graphics (3) ) 127 to re-establish a connection to its window. 128 After resizing (and perhaps calling 129 .IR getwindow ), 130 the global variable 131 .B screen 132 will be updated to point to the new window's 133 .B Image 134 structure. 135 .PP 136 As characters are typed on the keyboard, they are read by the 137 event mechanism and put in a queue. 138 .I Ekbd 139 returns the next rune from the queue, blocking until the 140 queue is non-empty. 141 The characters are read in raw mode, 142 .\" (see 143 .\" .IR cons (3)), 144 so they are available as soon as a complete rune is typed. 145 .PP 146 When the mouse moves or a mouse button is pressed or released, 147 a new mouse event is queued by the event mechanism. 148 .I Emouse 149 returns the next mouse event from the queue, blocking until the 150 queue is non-empty. 151 .I Emouse 152 returns a 153 .B Mouse 154 structure: 155 .IP 156 .EX 157 .ta 6n +\w'Point 'u 158 struct Mouse 159 { 160 int buttons; 161 Point xy; 162 ulong msec; 163 }; 164 .EE 165 .PP 166 .B Buttons&1 167 is set when the left mouse button is pressed, 168 .B buttons&2 169 when the middle button is pressed, 170 and 171 .B buttons&4 172 when the right button is pressed. 173 The current mouse position is always returned in 174 .BR xy . 175 .B Msec 176 is a time stamp in units of milliseconds. 177 .PP 178 .I Ecankbd 179 and 180 .I ecanmouse 181 return non-zero when there are keyboard or mouse events available 182 to be read. 183 .PP 184 .I Ereadmouse 185 reads the next mouse event from the file descriptor connected to the mouse, 186 converts the textual data into a 187 .B Mouse 188 structure by calling 189 .I eatomouse 190 with the buffer and count from the read call, 191 and returns the number of bytes read, or \-1 for an error. 192 .PP 193 .I Estart 194 can be used to register additional file descriptors to scan for input. 195 It takes as arguments the file descriptor to register, 196 the maximum length of an event message on that descriptor, 197 and a key to be used in accessing the event. 198 The key must be a power of 2 and must not conflict with any previous keys. 199 If a zero key is given, a key will be allocated and returned. 200 .I Estartfn 201 is similar to 202 .IR estart , 203 but processes the data received by calling 204 .I fn 205 before returning the event to the user. 206 The function 207 .I fn 208 is called with the 209 .B id 210 of the event; it should return 211 .B id 212 if the event is to be passed to the user, 213 .B 0 214 if it is to be ignored. 215 The variable 216 .B Event.v 217 can be used by 218 .I fn 219 to attach an arbitrary data item to the returned 220 .B Event 221 structure. 222 .B 223 Ekeyboard 224 and 225 .B Emouse 226 are the keyboard and mouse event keys. 227 .PP 228 .I Etimer 229 starts a repeating timer with a period of 230 .I n 231 milliseconds; it returns the timer event key, or zero if it fails. 232 Only one timer can be started. 233 Extra timer events are not queued and the timer channel has no associated data. 234 .PP 235 .I Eread 236 waits for the next event specified by the mask 237 .I keys 238 of event keys submitted to 239 .IR estart . 240 It fills in the appropriate field of the argument 241 .B Event 242 structure, which looks like: 243 .IP 244 .EX 245 struct Event 246 { 247 int kbdc; 248 Mouse mouse; 249 int n; 250 void *v; 251 uchar data[EMAXMSG]; 252 }; 253 .EE 254 .PP 255 .B Data 256 is an array which is large enough to hold a 9P message. 257 .I Eread 258 returns the key for the event which was chosen. 259 For example, if a mouse event was read, 260 .B Emouse 261 will be returned. 262 .PP 263 .I Event 264 waits for the next event of any kind. 265 The return is the same as for 266 .IR eread . 267 .PP 268 As described in 269 .MR graphics (3) , 270 the graphics functions are buffered. 271 .IR Event , 272 .IR eread , 273 .IR emouse , 274 and 275 .I ekbd 276 all cause a buffer flush unless there is an event of the 277 appropriate type already queued. 278 .PP 279 .I Ecanread 280 checks whether a call to 281 .B eread(keys) 282 would block, returning 0 if it would, 1 if it would not. 283 .PP 284 .I Getrect 285 prompts the user to sweep a rectangle. 286 It should be called with 287 .I m 288 holding the mouse event that triggered the 289 .I egetrect 290 (or, if none, a 291 .B Mouse 292 with 293 .B buttons 294 set to 7). 295 It changes to the sweep cursor, 296 waits for the buttons all to be released, 297 and then waits for button number 298 .I but 299 to be pressed, marking the initial corner. 300 If another button is pressed instead, 301 .I egetrect 302 returns a rectangle 303 with zero for both corners, after 304 waiting for all the buttons to be released. 305 Otherwise, 306 .I egetrect 307 continually draws the swept rectangle 308 until the button is released again, and returns the swept rectangle. 309 The mouse structure pointed to by 310 .I m 311 will contain the final mouse event. 312 .PP 313 .I Egetrect 314 uses successive calls to 315 .I edrawgetrect 316 to maintain the red rectangle showing the sweep-in-progress. 317 The rectangle to be drawn is specified by 318 .I rc 319 and the 320 .I up 321 parameter says whether to draw (1) or erase (0) the rectangle. 322 .PP 323 .I Emenuhit 324 displays a menu and returns a selected menu item number. 325 It should be called with 326 .I m 327 holding the mouse event that triggered the 328 .IR emenuhit ; 329 it will call 330 .I emouse 331 to update it. 332 A 333 .B Menu 334 is a structure: 335 .IP 336 .EX 337 struct Menu 338 { 339 char **item; 340 char *(*gen)(int); 341 int lasthit; 342 }; 343 .EE 344 .PP 345 If 346 .B item 347 is nonzero, it should be a null-terminated array of the character strings 348 to be displayed as menu items. 349 Otherwise, 350 .B gen 351 should be a function that, given an item number, returns the character 352 string for that item, or zero if the number is past the end of the list. 353 Items are numbered starting at zero. 354 .I Menuhit 355 waits until 356 .I but 357 is released, and then returns the number of the selection, 358 or \-1 for no selection. 359 The 360 .I m 361 argument is filled in with the final mouse event. 362 .PP 363 .I Emoveto 364 moves the mouse cursor to the position 365 .B p 366 on the screen. 367 .PP 368 .I Esetcursor 369 changes the cursor image to that described by the 370 .B Cursor 371 .I c 372 (see 373 .MR mouse (3) ). 374 If 375 .B c 376 is nil, it restores the image to the default arrow. 377 .SH SOURCE 378 .B \*9/src/libdraw 379 .SH "SEE ALSO" 380 .MR rio (1) , 381 .MR graphics (3) , 382 .MR plumb (3) , 383 .\" .IR cons (3), 384 .MR draw (3)