EVENT(2) EVENT(2)
NAME
event, einit, estart, etimer, eread, emouse, ekbd, ecanread,
ecanmouse, ecankbd, ereshaped, getrect, menuhit, Event,
Mouse, Menu - graphics events
SYNOPSIS
#include <u.h>
#include <libc.h>
#include <libg.h>
void einit(ulong keys)
ulong event(Event *e)
Mouse emouse(void)
int ekbd(void)
int ecanmouse(void)
int ecankbd(void)
ulong estart(ulong key, int fd, int n)
ulong etimer(ulong key, int n)
ulong eread(ulong keys, Event *e)
int ecanread(ulong keys)
void ereshaped(Rectangle r)
Rectangle getrect(int but, Mouse *m)
int menuhit(int but, Mouse *m, Menu *menu)
enum{
Emouse = 1,
Ekeyboard = 2,
};
/* Alef only */
adt Menu
{
/* ... */
(int, Mouse) hit(*Menu, int but, chan(Mouse), Mouse);
};
DESCRIPTION
Page 1 Plan 9 (printed 11/17/24)
EVENT(2) EVENT(2)
These routines provide an interface to multiple sources of
input. To use them, einit must be called. If the argument
to einit has the Emouse and Ekeyboard bits set, the mouse
and keyboard events will be enabled; in this case, binit
(see graphics(2)) must have already been called. The user
must provide a function called ereshaped to be called when-
ever the window in which the process is running has been
reshaped; the argument will be the Rectangle for the new
window shape, including the border.
As characters are typed on the keyboard, they are read by
the event mechanism and put in a queue. Ekbd returns the
next rune from the queue, blocking until the queue is non-
empty. The characters are read in raw mode (see cons(3)),
so they are available as soon as a complete rune is typed.
When the mouse moves or a mouse button is depressed or
released, a new mouse event is queued by the event mecha-
nism. Emouse returns the next mouse event from the queue,
blocking until the queue is non-empty. Emouse returns a
Mouse structure:
struct Mouse
{
int buttons;
Point xy;
ulong msec;
};
Buttons&1 is set when the left mouse button is depressed,
buttons&2 when the middle button is depressed, and buttons&4
when the right button is depressed. The current mouse posi-
tion is always returned in xy. Msec is a time stamp in
units of milliseconds.
Ecankbd and ecanmouse return non-zero when there are key-
board or mouse events available to be read.
Estart can be used to register additional file descriptors
to scan for input. It takes as arguments the file descrip-
tor 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, one will be
allocated and returned. Ekeyboard and Emouse are the mouse
and keyboard event keys.
Etimer starts a repeating timer with a period of n millisec-
onds; 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.
Page 2 Plan 9 (printed 11/17/24)
EVENT(2) EVENT(2)
Eread waits for the next event specified by the mask keys of
event keys submitted to estart. It fills in the appropriate
field of the argument Event structure, which looks like:
struct Event
{
int kbdc;
Mouse mouse;
int n;
uchar data[EMAXMSG];
};
Data is an array which is large enough to hold a 9P message.
Eread returns the key for the event which was chosen. For
example, if a mouse event was read, Emouse will be returned.
Event waits for the next event of any kind. The return is
the same as for eread.
As described in graphics(2), the graphics functions are buf-
fered. Event, eread, emouse, and ekbd all cause a buffer
flush unless there is an event of the appropriate type
already queued.
Ecanread checks whether a call to eread(keys) would block,
returning 0 if it would, 1 if it would not.
Getrect prompts the user to sweep a rectangle. It should be
called with m holding the mouse event that triggered the
getrect (or, if none, a Mouse with buttons set to 7). It
changes to the sweep cursor, waits for the buttons all to be
released, and then waits for button number but to be
depressed, marking the initial corner. If another button is
depressed instead, getrect returns a rectangle with zero for
both corners, after waiting for all the buttons to be
released. Otherwise, getrect continually draws the swept
rectangle until the button is released again, and returns
the swept rectangle. The mouse structure pointed to by m
will contain the final mouse event.
Menuhit displays a menu and returns a selected menu item
number. It should be called with m holding the mouse event
that triggered the menuhit; it will call emouse to update
it. A Menu is a structure:
struct Menu
{
char **item;
char *(*gen)(int);
int lasthit;
};
Page 3 Plan 9 (printed 11/17/24)
EVENT(2) EVENT(2)
If item is nonzero, it should be a null-terminated array of
the character strings to be displayed as menu items. Other-
wise, 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. Menuhit waits until but is released, and
then returns the number of the selection, or -1 for no
selection. The m argument is filled in with the final mouse
event.
Alef
Alef has none of the event software, since the language
encourages a different approach using processes to convert
mouse and keyboard activity into messages. In this vein, a
function called hit, analogous to menuhit, exists as a part
of the Menu adt; it takes as argument a chan of type Mouse
and a Mouse-valued argument reflecting the current state.
It returns the selection and the new state of the mouse.
SOURCE
/sys/src/libg
SEE ALSO
8½(1), graphics(2), cons(3), bit(3)
BUGS
There should be an official Alef interface to the mouse and
keyboard.
Page 4 Plan 9 (printed 11/17/24)