diff options
Diffstat (limited to 'man/man3/event.html')
| -rw-r--r-- | man/man3/event.html | 390 |
1 files changed, 390 insertions, 0 deletions
diff --git a/man/man3/event.html b/man/man3/event.html new file mode 100644 index 00000000..87cff2fd --- /dev/null +++ b/man/man3/event.html @@ -0,0 +1,390 @@ +<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> |