| <head> |
| <title>event(3) - Plan 9 from User Space</title> |
| <meta content="text/html; charset=utf-8" http-equiv=Content-Type> |
| </head> |
| <body bgcolor=#ffffff> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=10><td> |
| <tr><td width=20><td> |
| <tr><td width=20><td><b>EVENT(3)</b><td align=right><b>EVENT(3)</b> |
| <tr><td width=20><td colspan=2> |
| <br> |
| <p><font size=+1><b>NAME </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| event, einit, estart, estartfn, etimer, eread, emouse, ekbd, ecanread, |
| ecanmouse, ecankbd, ereadmouse, eatomouse, eresized, egetrect, |
| edrawgetrect, emenuhit, emoveto, esetcursor, Event, Mouse, Menu |
| – graphics events<br> |
| |
| </table> |
| <p><font size=+1><b>SYNOPSIS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>#include <u.h><br> |
| #include <libc.h><br> |
| #include <draw.h><br> |
| #include <event.h><br> |
| #include <cursor.h><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>void einit(ulong keys)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>ulong event(Event *e)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>Mouse emouse(void)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int ekbd(void)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int ecanmouse(void)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int ecankbd(void)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int ereadmouse(Mouse *m)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int eatomouse(Mouse *m, char *buf, int n)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>ulong estart(ulong key, int fd, int n)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>ulong estartfn(int id, ulong key, int fd, int n,<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| int (*fn)(Event*, uchar*, int))<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| </table> |
| |
| </table> |
| </font></tt> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| |
| |
| </table> |
| |
| </table> |
| <tt><font size=+1>ulong etimer(ulong key, int n)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>ulong eread(ulong keys, Event *e)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int ecanread(ulong keys)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>void eresized(int new)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>Rectangle egetrect(int but, Mouse *m)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>void edrawgetrect(Rectangle r, int up)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int emenuhit(int but, Mouse *m, Menu *menu)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <tt><font size=+1>int emoveto(Point p)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <tt><font size=+1>int esetcursor(Cursor *c)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>extern Mouse *mouse<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>enum{<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| Emouse = 1,<br> |
| Ekeyboard = 2,<br> |
| |
| </table> |
| |
| </table> |
| };<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| |
| </table> |
| <p><font size=+1><b>DESCRIPTION </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| These routines provide an interface to multiple sources of input |
| for unthreaded programs. Threaded programs (see <a href="../man3/thread.html"><i>thread</i>(3)</a>) should |
| instead use the threaded mouse and keyboard interface described |
| in <a href="../man3/mouse.html"><i>mouse</i>(3)</a> and <a href="../man3/keyboard.html"><i>keyboard</i>(3)</a>. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Einit</i> must be called first. If the argument to <i>einit</i> has the <tt><font size=+1>Emouse</font></tt> |
| and <tt><font size=+1>Ekeyboard</font></tt> bits set, the mouse and keyboard events will be |
| enabled; in this case, <i>initdraw</i> (see <a href="../man3/graphics.html"><i>graphics</i>(3)</a>) must have already |
| been called. The user must provide a function called <i>eresized</i> |
| to be called whenever the window in which the process |
| is running has been resized; the argument <i>new</i> is a flag specifying |
| whether the program must call <i>getwindow</i> (see <a href="../man3/graphics.html"><i>graphics</i>(3)</a>) to re-establish |
| a connection to its window. After resizing (and perhaps calling |
| <i>getwindow</i>), the global variable <tt><font size=+1>screen</font></tt> will be updated to point |
| to the new window’s <tt><font size=+1>Image</font></tt> structure. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| As characters are typed on the keyboard, they are read by the |
| event mechanism and put in a queue. <i>Ekbd</i> returns the next rune |
| from the queue, blocking until the queue is non-empty. The characters |
| are read in raw mode, so they are available as soon as a complete |
| rune is typed. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| When the mouse moves or a mouse button is pressed or released, |
| a new mouse event is queued by the event mechanism. <i>Emouse</i> returns |
| the next mouse event from the queue, blocking until the queue |
| is non-empty. <i>Emouse</i> returns a <tt><font size=+1>Mouse</font></tt> structure:<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>struct Mouse<br> |
| {<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| int buttons;<br> |
| Point xy;<br> |
| ulong msec;<br> |
| |
| </table> |
| };<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| |
| </table> |
| <tt><font size=+1>Buttons&1</font></tt> is set when the left mouse button is pressed, <tt><font size=+1>buttons&2</font></tt> |
| when the middle button is pressed, and <tt><font size=+1>buttons&4</font></tt> when the right |
| button is pressed. The current mouse position is always returned |
| in <tt><font size=+1>xy</font></tt>. <tt><font size=+1>Msec</font></tt> is a time stamp in units of milliseconds. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Ecankbd</i> and <i>ecanmouse</i> return non-zero when there are keyboard |
| or mouse events available to be read. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Ereadmouse</i> reads the next mouse event from the file descriptor |
| connected to the mouse, converts the textual data into a <tt><font size=+1>Mouse</font></tt> |
| structure by calling <i>eatomouse</i> with the buffer and count from |
| the read call, and returns the number of bytes read, or –1 for |
| an error. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Estart</i> 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</i> is |
| similar to <i>estart</i>, but processes the data received by calling |
| <i>fn</i> before returning the event to the user. The function <i>fn</i> is |
| called with the <tt><font size=+1>id</font></tt> of the event; it should return <tt><font size=+1>id</font></tt> if the event |
| is to be passed to the user, <tt><font size=+1>0</font></tt> if it is to be ignored. The variable |
| <tt><font size=+1>Event.v |
| </font></tt>can be used by <i>fn</i> to attach an arbitrary data item to the returned |
| <tt><font size=+1>Event</font></tt> structure. <tt><font size=+1> Ekeyboard</font></tt> and <tt><font size=+1>Emouse</font></tt> are the keyboard and mouse |
| event keys. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Etimer</i> starts a repeating timer with a period of <i>n</i> 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. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Eread</i> waits for the next event specified by the mask <i>keys</i> of event |
| keys submitted to <i>estart</i>. It fills in the appropriate field of |
| the argument <tt><font size=+1>Event</font></tt> structure, which looks like:<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>struct Event<br> |
| {<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| int kbdc;<br> |
| Mouse mouse;<br> |
| int n;<br> |
| void *v;<br> |
| uchar data[EMAXMSG];<br> |
| |
| </table> |
| };<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| |
| </table> |
| <tt><font size=+1>Data</font></tt> is an array which is large enough to hold a 9P message. <i>Eread</i> |
| returns the key for the event which was chosen. For example, if |
| a mouse event was read, <tt><font size=+1>Emouse</font></tt> will be returned. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Event</i> waits for the next event of any kind. The return is the |
| same as for <i>eread</i>. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| As described in <a href="../man3/graphics.html"><i>graphics</i>(3)</a>, the graphics functions are buffered. |
| <i>Event</i>, <i>eread</i>, <i>emouse</i>, and <i>ekbd</i> all cause a buffer flush unless |
| there is an event of the appropriate type already queued. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Ecanread</i> checks whether a call to <tt><font size=+1>eread(keys)</font></tt> would block, returning |
| 0 if it would, 1 if it would not. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Getrect</i> prompts the user to sweep a rectangle. It should be called |
| with <i>m</i> holding the mouse event that triggered the <i>egetrect</i> (or, |
| if none, a <tt><font size=+1>Mouse</font></tt> with <tt><font size=+1>buttons</font></tt> 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</i> to be pressed, marking the initial |
| corner. If another button is pressed instead, <i>egetrect</i> returns |
| a rectangle with zero for both corners, after waiting for all |
| the buttons to be released. Otherwise, <i>egetrect</i> continually draws |
| the swept rectangle until the button is released again, and returns |
| the swept rectangle. The mouse structure pointed to by <i>m</i> will |
| contain the final mouse event. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Egetrect</i> uses successive calls to <i>edrawgetrect</i> to maintain the |
| red rectangle showing the sweep-in-progress. The rectangle to |
| be drawn is specified by <i>rc</i> and the <i>up</i> parameter says whether |
| to draw (1) or erase (0) the rectangle. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Emenuhit</i> displays a menu and returns a selected menu item number. |
| It should be called with <i>m</i> holding the mouse event that triggered |
| the <i>emenuhit</i>; it will call <i>emouse</i> to update it. A <tt><font size=+1>Menu</font></tt> is a structure:<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>struct Menu<br> |
| {<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| char **item;<br> |
| char *(*gen)(int);<br> |
| int lasthit;<br> |
| |
| </table> |
| };<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| |
| </table> |
| If <tt><font size=+1>item</font></tt> is nonzero, it should be a null-terminated array of the |
| character strings to be displayed as menu items. Otherwise, <tt><font size=+1>gen</font></tt> |
| 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 |
| </i>waits until <i>but</i> is released, and then returns the number of the |
| selection, or –1 for no selection. The <i>m</i> argument is filled in |
| with the final mouse event. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Emoveto</i> moves the mouse cursor to the position <tt><font size=+1>p</font></tt> on the screen. |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Esetcursor</i> changes the cursor image to that described by the <tt><font size=+1>Cursor</font></tt> |
| <i>c</i> (see <a href="../man3/mouse.html"><i>mouse</i>(3)</a>). If <tt><font size=+1>c</font></tt> is nil, it restores the image to the default |
| arrow.<br> |
| |
| </table> |
| <p><font size=+1><b>SOURCE </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>/usr/local/plan9/src/libdraw<br> |
| </font></tt> |
| </table> |
| <p><font size=+1><b>SEE ALSO </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <a href="../man1/rio.html"><i>rio</i>(1)</a>, <a href="../man3/graphics.html"><i>graphics</i>(3)</a>, <a href="../man3/plumb.html"><i>plumb</i>(3)</a>, <a href="../man3/draw.html"><i>draw</i>(3)</a><br> |
| |
| </table> |
| <p><font size=+1><b>BUGS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <i>Etimer</i> and <i>estart</i> are unimplemented.<br> |
| |
| </table> |
| |
| <td width=20> |
| <tr height=20><td> |
| </table> |
| <!-- TRAILER --> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=15><td width=10><td><td width=10> |
| <tr><td><td> |
| <center> |
| <a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> |
| </center> |
| </table> |
| <!-- TRAILER --> |
| </body></html> |
