sys/man/2/event

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