| .TH EVENT 3 |
| .SH NAME |
| event, einit, estart, estartfn, etimer, eread, emouse, ekbd, ecanread, ecanmouse, ecankbd, ereadmouse, eatomouse, eresized, egetrect, edrawgetrect, emenuhit, emoveto, esetcursor, Event, Mouse, Menu \- graphics events |
| .SH SYNOPSIS |
| .nf |
| .PP |
| .B |
| #include <u.h> |
| .B |
| #include <libc.h> |
| .B |
| #include <draw.h> |
| .B |
| #include <event.h> |
| .B |
| #include <cursor.h> |
| .ta \w'\fLRectangle 'u |
| .PP |
| .B |
| void einit(ulong keys) |
| .PP |
| .B |
| ulong event(Event *e) |
| .PP |
| .B |
| Mouse emouse(void) |
| .PP |
| .B |
| int ekbd(void) |
| .PP |
| .B |
| int ecanmouse(void) |
| .PP |
| .B |
| int ecankbd(void) |
| .PP |
| .B |
| int ereadmouse(Mouse *m) |
| .PP |
| .B |
| int eatomouse(Mouse *m, char *buf, int n) |
| .PP |
| .B |
| ulong estart(ulong key, int fd, int n) |
| .PP |
| .B |
| ulong estartfn(int id, ulong key, int fd, int n, |
| .B |
| int (*fn)(Event*, uchar*, int)) |
| .PP |
| .B |
| ulong etimer(ulong key, int n) |
| .PP |
| .B |
| ulong eread(ulong keys, Event *e) |
| .PP |
| .B |
| int ecanread(ulong keys) |
| .PP |
| .B |
| void eresized(int new) |
| .PP |
| .B |
| Rectangle egetrect(int but, Mouse *m) |
| .PP |
| .B |
| void edrawgetrect(Rectangle r, int up) |
| .PP |
| .B |
| int emenuhit(int but, Mouse *m, Menu *menu) |
| .PP |
| .PP |
| .B |
| int emoveto(Point p) |
| .PP |
| .PP |
| .B |
| int esetcursor(Cursor *c) |
| .PP |
| .B |
| extern Mouse *mouse |
| .PP |
| .B |
| enum{ |
| .B |
| Emouse = 1, |
| .B |
| Ekeyboard = 2, |
| .B |
| }; |
| .PP |
| .SH DESCRIPTION |
| These routines provide an interface to multiple sources of input for unthreaded |
| programs. |
| Threaded programs (see |
| .IR thread (3)) |
| should instead use the threaded mouse and keyboard interface described |
| in |
| .IR mouse (3) |
| and |
| .IR keyboard (3). |
| .PP |
| .I Einit |
| must be called first. |
| If the argument to |
| .I einit |
| has the |
| .B Emouse |
| and |
| .B Ekeyboard |
| bits set, |
| the mouse and keyboard events will be enabled; |
| in this case, |
| .IR initdraw |
| (see |
| .IR graphics (3)) |
| must have already been called. |
| The user must provide a function called |
| .IR eresized |
| to be called whenever the window in which the process |
| is running has been resized; the argument |
| .I new |
| is a flag specifying whether the program must call |
| .I getwindow |
| (see |
| .IR graphics (3)) |
| to re-establish a connection to its window. |
| After resizing (and perhaps calling |
| .IR getwindow ), |
| the global variable |
| .B screen |
| will be updated to point to the new window's |
| .B Image |
| structure. |
| .PP |
| As characters are typed on the keyboard, they are read by the |
| event mechanism and put in a queue. |
| .I Ekbd |
| returns the next rune from the queue, blocking until the |
| queue is non-empty. |
| The characters are read in raw mode, |
| .\" (see |
| .\" .IR cons (3)), |
| so they are available as soon as a complete rune is typed. |
| .PP |
| When the mouse moves or a mouse button is pressed or released, |
| a new mouse event is queued by the event mechanism. |
| .I Emouse |
| returns the next mouse event from the queue, blocking until the |
| queue is non-empty. |
| .I Emouse |
| returns a |
| .B Mouse |
| structure: |
| .IP |
| .EX |
| .ta 6n +\w'Point 'u |
| struct Mouse |
| { |
| int buttons; |
| Point xy; |
| ulong msec; |
| }; |
| .EE |
| .PP |
| .B Buttons&1 |
| is set when the left mouse button is pressed, |
| .B buttons&2 |
| when the middle button is pressed, |
| and |
| .B buttons&4 |
| when the right button is pressed. |
| The current mouse position is always returned in |
| .BR xy . |
| .B Msec |
| is a time stamp in units of milliseconds. |
| .PP |
| .I Ecankbd |
| and |
| .I ecanmouse |
| return non-zero when there are keyboard or mouse events available |
| to be read. |
| .PP |
| .I Ereadmouse |
| reads the next mouse event from the file descriptor connected to the mouse, |
| converts the textual data into a |
| .B Mouse |
| structure by calling |
| .I eatomouse |
| with the buffer and count from the read call, |
| and returns the number of bytes read, or \-1 for an error. |
| .PP |
| .I Estart |
| can be used to register additional file descriptors to scan for input. |
| It takes as arguments the file descriptor to register, |
| the maximum length of an event message on that descriptor, |
| and a key to be used in accessing the event. |
| The key must be a power of 2 and must not conflict with any previous keys. |
| If a zero key is given, a key will be allocated and returned. |
| .I Estartfn |
| is similar to |
| .IR estart , |
| but processes the data received by calling |
| .I fn |
| before returning the event to the user. |
| The function |
| .I fn |
| is called with the |
| .B id |
| of the event; it should return |
| .B id |
| if the event is to be passed to the user, |
| .B 0 |
| if it is to be ignored. |
| The variable |
| .B Event.v |
| can be used by |
| .I fn |
| to attach an arbitrary data item to the returned |
| .B Event |
| structure. |
| .B |
| Ekeyboard |
| and |
| .B Emouse |
| are the keyboard and mouse event keys. |
| .PP |
| .I Etimer |
| starts a repeating timer with a period of |
| .I n |
| milliseconds; it returns the timer event key, or zero if it fails. |
| Only one timer can be started. |
| Extra timer events are not queued and the timer channel has no associated data. |
| .PP |
| .I Eread |
| waits for the next event specified by the mask |
| .I keys |
| of event keys submitted to |
| .IR estart . |
| It fills in the appropriate field of the argument |
| .B Event |
| structure, which looks like: |
| .IP |
| .EX |
| struct Event |
| { |
| int kbdc; |
| Mouse mouse; |
| int n; |
| void *v; |
| uchar data[EMAXMSG]; |
| }; |
| .EE |
| .PP |
| .B Data |
| is an array which is large enough to hold a 9P message. |
| .I Eread |
| returns the key for the event which was chosen. |
| For example, if a mouse event was read, |
| .B Emouse |
| will be returned. |
| .PP |
| .I Event |
| waits for the next event of any kind. |
| The return is the same as for |
| .IR eread . |
| .PP |
| As described in |
| .IR graphics (3), |
| the graphics functions are buffered. |
| .IR Event , |
| .IR eread , |
| .IR emouse , |
| and |
| .I ekbd |
| all cause a buffer flush unless there is an event of the |
| appropriate type already queued. |
| .PP |
| .I Ecanread |
| checks whether a call to |
| .B eread(keys) |
| would block, returning 0 if it would, 1 if it would not. |
| .PP |
| .I Getrect |
| prompts the user to sweep a rectangle. |
| It should be called with |
| .I m |
| holding the mouse event that triggered the |
| .I egetrect |
| (or, if none, a |
| .B Mouse |
| with |
| .B buttons |
| set to 7). |
| It changes to the sweep cursor, |
| waits for the buttons all to be released, |
| and then waits for button number |
| .I but |
| to be pressed, marking the initial corner. |
| If another button is pressed instead, |
| .I egetrect |
| returns a rectangle |
| with zero for both corners, after |
| waiting for all the buttons to be released. |
| Otherwise, |
| .I egetrect |
| continually draws the swept rectangle |
| until the button is released again, and returns the swept rectangle. |
| The mouse structure pointed to by |
| .I m |
| will contain the final mouse event. |
| .PP |
| .I Egetrect |
| uses successive calls to |
| .I edrawgetrect |
| to maintain the red rectangle showing the sweep-in-progress. |
| The rectangle to be drawn is specified by |
| .I rc |
| and the |
| .I up |
| parameter says whether to draw (1) or erase (0) the rectangle. |
| .PP |
| .I Emenuhit |
| displays a menu and returns a selected menu item number. |
| It should be called with |
| .I m |
| holding the mouse event that triggered the |
| .IR emenuhit ; |
| it will call |
| .I emouse |
| to update it. |
| A |
| .B Menu |
| is a structure: |
| .IP |
| .EX |
| struct Menu |
| { |
| char **item; |
| char *(*gen)(int); |
| int lasthit; |
| }; |
| .EE |
| .PP |
| If |
| .B item |
| is nonzero, it should be a null-terminated array of the character strings |
| to be displayed as menu items. |
| Otherwise, |
| .B gen |
| should be a function that, given an item number, returns the character |
| string for that item, or zero if the number is past the end of the list. |
| Items are numbered starting at zero. |
| .I Menuhit |
| waits until |
| .I but |
| is released, and then returns the number of the selection, |
| or \-1 for no selection. |
| The |
| .I m |
| argument is filled in with the final mouse event. |
| .PP |
| .I Emoveto |
| moves the mouse cursor to the position |
| .B p |
| on the screen. |
| .PP |
| .I Esetcursor |
| changes the cursor image to that described by the |
| .B Cursor |
| .I c |
| (see |
| .IR mouse (3)). |
| If |
| .B c |
| is nil, it restores the image to the default arrow. |
| .SH SOURCE |
| .B \*9/src/libdraw |
| .SH "SEE ALSO" |
| .IR rio (1), |
| .IR graphics (3), |
| .IR plumb (3), |
| .\" .IR cons (3), |
| .IR draw (3) |