.TH EVENT 2G
.SH NAME
event, einit, estart, etimer, eread, emouse, ekbd, ecanread, ecanmouse, ecankbd, ereshaped, getrect, menuhit, Event, Mouse, Menu \- graphics events
.SH SYNOPSIS
.nf
.PP
.B
#include	<u.h>
.B
#include	<libc.h>
.B
#include	<libg.h>
.ta \w'\fLRectangle 'u
.PP
.B
void	einit(ulong keys)
.PP
.B
ulong	event(Event *e)
.PP
.B
Mouse	emouse(void)
.PP
.B
int	ekbd(void)
.PP
.B
int	ecanmouse(void)
.PP
.B
int	ecankbd(void)
.PP
.B
ulong	estart(ulong key, int fd, int n)
.PP
.B
ulong	etimer(ulong key, int n)
.PP
.B
ulong	eread(ulong keys, Event *e)
.PP
.B
int	ecanread(ulong keys)
.PP
.B
void	ereshaped(Rectangle r)
.PP
.B
Rectangle	getrect(int but, Mouse *m)
.PP
.B
int	menuhit(int but, Mouse *m, Menu *menu)
.PP
.B
enum{
.B
	Emouse = 1,
.B
	Ekeyboard = 2,
.B
};
.fi
.SH DESCRIPTION
These routines provide an interface to multiple sources of input.
To use them,
.I einit
must be called.
If the argument to
.I einit
has the
.B Emouse
and
.B Ekeyboard
bits set,
the mouse and keyboard events will be enabled;
in this case,
.IR binit
(see
.IR graphics (2))
must have already been called.
The user must provide a function called
.IR ereshaped
to be called whenever the window in which the process
is running has been reshaped; the argument will be the
.B Rectangle
for the new window shape, including the border.
.PP
As characters are typed on the keyboard, they are read by the
event mechanism and put in a queue.
.I Ekbd
returns the next rune from the queue, blocking until the
queue is non-empty.
The characters are read in raw mode
(see
.IR cons (3)),
so they are available as soon as a complete rune is typed.
.PP
When the mouse moves or a mouse button is depressed or released,
a new mouse event is queued by the event mechanism.
.I Emouse
returns the next mouse event from the queue, blocking until the
queue is non-empty.
.I Emouse
returns a
.B Mouse
structure:
.IP
.EX
.ta 6n +\w'Point 'u
struct Mouse
{
	int	buttons;
	Point	xy;
	ulong	msec;
};
.EE
.PP
.B Buttons&1
is set when the left mouse button is depressed,
.B buttons&2
when the middle button is depressed,
and
.B buttons&4
when the right button is depressed.
The current mouse position is always returned in
.BR xy .
.B Msec
is a time stamp in units of milliseconds.
.PP
.I Ecankbd
and
.I ecanmouse
return non-zero when there are keyboard or mouse events available
to be read.
.PP
.I Estart
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, one will be allocated and returned.
.B
Ekeyboard
and
.B Emouse
are the mouse and keyboard event keys.
.PP
.I Etimer
starts a repeating timer with a period of
.I n
milliseconds.
Only one timer can be started.
Extra timer events are not queued and the timer channel has no associated data.
.PP
.I Eread
waits for the next event specified by the mask
.B keys
of event keys submitted to
.BR estart .
It fills in the appropriate field of the argument
.B Event
structure, which looks like:
.IP
.EX
struct Event
{
	int	kbdc;
	Mouse	mouse;
	int	n;
	uchar	data[EMAXMSG];
};
.EE
.PP
.B Data
is an array which is large enough to hold a 9P message.
.I Eread
returns the key for the event which was chosen.
For example, if a mouse event was read,
.I Emouse
will be returned.
.PP
.I Event
waits for the next event of any kind.
The return is the same as for
.IR eread .
.PP
As described in
.IR graphics (2),
the graphics functions are buffered.
.IR Event ,
.IR eread ,
.IR emouse ,
and
.I ekbd
all cause a buffer flush unless there is an event of the
appropriate type already queued.
.PP
.I Getrect
prompts the user to sweep a rectangle.
It should be called with
.I m
holding the mouse event that triggered the
.I getrect
(or, if none, a
.B Mouse
with
.B buttons
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
to be depressed, marking the initial corner.
If another button is depressed instead,
.I getrect
returns a rectangle
with zero for both corners, after
waiting for all the buttons to be released.
Otherwise,
.I getrect
continually draws the swept rectangle
until the button is released again, and returns the swept rectangle.
The mouse structure pointed to by
.I m
will contain the final mouse event.
.PP
.I Menuhit
displays a menu and returns a selected menu item number.
It should be called with
.I m
holding the mouse event that triggered the
.IR menuhit ;
it will call
.I emouse
to update it.
A
.B Menu
is a structure:
.IP
.EX
struct Menu
{
	char	**item;
	char	*(*gen)(int);
	int	lasthit;
};
.EE
.PP
If
.B item
is nonzero, it should be a null-terminated array of the character strings
to be displayed as menu items.
Otherwise,
.B 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.
.I Menuhit
waits until
.I but
is released, and then returns the number of the selection,
or \(mi1 for no selection.
The
.I m
argument is filled in with the final mouse event.
.SH "SEE ALSO"
.IR 8½ (1),
.IR graphics (2),
.IR cons (3),
.IR bit (3)
