These routines provide an interface to multiple sources of input
for unthreaded programs. Threaded programs (see thread(2)) should
instead use the threaded mouse and keyboard interface described
in mouse(2) and keyboard(2).
Einit must be called first. If the argument to einit has the Emouse
and Ekeyboard bits set, the mouse and keyboard events will be
enabled; in this case, initdraw (see graphics(2)) must have already
been called. The user must provide a function called eresized
to be called whenever the window in which the process
is running has been resized; the argument new is a flag specifying
whether the program must call getwindow (see graphics(2)) to re–establish
a connection to its window. After resizing (and perhaps calling
getwindow), the global variable screen will be updated to point
to the new window's Image structure.
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 pressed 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:|
Buttons&1 is set when the left mouse button is pressed, buttons&2
when the middle button is pressed, and buttons&4 when the right
button is pressed. 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.
Ereadmouse reads the next mouse event from the file descriptor
connected to the mouse, converts the textual data into a Mouse
structure by calling eatomouse with the buffer and count from
the read call, and returns the number of bytes read, or –1 for
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, a key will be allocated and returned. Estartfn is
similar to estart, but processes the data received by calling
fn before returning the event to the user. The function fn is
called with the id of the event; it should return id if the event
is to be passed to the user, 0 if it is to be ignored. The variable
can be used by fn to attach an arbitrary data item to the returned
Event structure. Ekeyboard and Emouse are the keyboard and mouse
Etimer starts a repeating timer with a period of n 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.
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:
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 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 egetrect (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 pressed, marking the initial
corner. If another button is pressed instead, egetrect returns
a rectangle with zero for both corners, after waiting for all
the buttons to be released. Otherwise, egetrect 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.
Egetrect uses successive calls to edrawgetrect to maintain the
red rectangle showing the sweep–in–progress. The rectangle to be
drawn is specified by rc and the up parameter says whether to
draw (1) or erase (0) the rectangle.
Emenuhit displays a menu and returns a selected menu item number.
It should be called with m holding the mouse event that triggered
the emenuhit; it will call emouse to update it. A Menu is a structure:
If item is nonzero, it should be a null–terminated array of the
character 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.
Emoveto moves the mouse cursor to the position p on the screen.
Esetcursor changes the cursor image to that described by the Cursor
c (see mouse(2)). If c is nil, it restores the image to the default