390 lines
18 KiB
HTML
390 lines
18 KiB
HTML
<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>
|