EVENT(2)EVENT(2)
NAME
event, einit, estart, estartfn, etimer, eread, emouse, ekbd, ecanread, ecanmouse, ecankbd, ereadmouse, eatomouse, eresized, egetrect, edrawgetrect, emenuhit, eenter, emoveto, esetcursor, Event, Mouse, Menu – graphics events
SYNOPSIS
#include <u.h>
#include <libc.h>
#include <draw.h>
#include <event.h>
#include <cursor.h>
void einit(ulong keys)
ulong event(Event *e)
Mouse emouse(void)
int ekbd(void)
int ecanmouse(void)
int ecankbd(void)
int ereadmouse(Mouse *m)
int eatomouse(Mouse *m, char *buf, int n)
ulong estart(ulong key, int fd, int n)
ulong estartfn(ulong key, int fd, int n,
int (*fn)(int, Event*, uchar*, int))
ulong etimer(ulong key, int n)
ulong eread(ulong keys, Event *e)
int ecanread(ulong keys)
void eresized(int new)
Rectangle egetrect(int but, Mouse *m)
void edrawgetrect(Rectangle r, int up)
int emenuhit(int but, Mouse *m, Menu *menu)
void emoveto(Point p)
void esetcursor(Cursor *c)
int eenter(char *ask, char *buf, int len, Mouse *m)
extern Mouse *mouse
enum{
Emouse = 1,
Ekeyboard = 2,
};
DESCRIPTION
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:
struct Mouse
{
int buttons;
Point xy;
ulong msec;
};
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 an error.
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
Event.v
can be used by
fn
to attach an arbitrary data item to the returned
Event
structure.
Ekeyboard
and
Emouse
are the keyboard and mouse event keys.
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:
struct Event
{
int kbdc;
Mouse mouse;
int n;
void *v;
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 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:
struct Menu
{
char **item;
char *(*gen)(int);
int lasthit;
};
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 arrow.
Eenter
provides a simple method of text input in graphical programs. It displays
a box at the current position of the mouse cursor (passed in the
Mouse *m
argument) in which text can be
typed and edited.
If the string argument
ask
is not
nil,
it is displayed as a static label before the input string.
The
buf
parameter contains the null-terminated input string to be edited. The
len
argument specifies the length of
buf
in bytes including the terminating null byte.
If
buf
or
len
is zero, no text can be entered.
On success,
eenter
returns the number of bytes in the edited string
buf
or -1 on error.
SOURCE
/sys/src/libdraw
SEE ALSO
rio(1),
graphics(2),
plumb(2),
cons(3),
draw(3)