term% cat index.txt EVENT(2) System Calls Manual 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
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
whenever 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 mechanism. 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 but‐
ton is depressed. The current mouse position is always returned in xy.
Msec is a time stamp in units of milliseconds.
Ecankbd and ecanmouse return non-zero when there are keyboard 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 descriptor to register, the max‐
imum 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 key‐
board event keys.
Etimer starts a repeating timer with a period of n milliseconds; it re‐
turns 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.
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 re‐
turns 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 buffered.
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 cor‐
ners, after waiting for all the buttons to be released. Otherwise, ge‐
trect continually draws the swept rectangle until the button is re‐
leased 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;
};
If item is nonzero, it should be a null-terminated array of the charac‐
ter strings to be displayed as menu items. Otherwise, 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 activ‐
ity 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.
EVENT(2)