diff options
Diffstat (limited to 'man/man3/event.3')
| -rw-r--r-- | man/man3/event.3 | 384 |
1 files changed, 384 insertions, 0 deletions
diff --git a/man/man3/event.3 b/man/man3/event.3 new file mode 100644 index 00000000..9a71ddc3 --- /dev/null +++ b/man/man3/event.3 @@ -0,0 +1,384 @@ +.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 (2)) +should instead use the threaded mouse and keyboard interface described +in +.IR mouse (2) +and +.IR keyboard (2). +.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 (2)) +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 (2)) +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 (2), +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 (2)). +If +.B c +is nil, it restores the image to the default arrow. +.SH SOURCE +.B /sys/src/libdraw +.SH "SEE ALSO" +.IR rio (1), +.IR graphics (2), +.IR plumb (2), +.IR cons (3), +.IR draw (3) |