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 key-
board 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 connec-
tion 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 mechan-
ism. 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 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.
Ereadmouse reads the next mouse event from the file descrip-
tor 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 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, a key will
be allocated and returned. Estartfn is similar to estart,
but processes the data received by calling fn before return-
ing 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 vari-
able 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 mil-
liseconds; 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 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
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 rec-
tangle 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. 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.
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)
MOUSE(2) MOUSE(2)
NAME
initmouse, readmouse, closemouse, moveto, getrect,
drawgetrect, menuhit, setcursor, enter - mouse control
SYNOPSIS
#include <u.h>
#include <libc.h>
#include <draw.h>
#include <thread.h>
#include <mouse.h>
#include <cursor.h>
Mousectl *initmouse(char *file, Image *i)
int readmouse(Mousectl *mc)
void closemouse(Mousectl *mc)
void moveto(Mousectl *mc, Point pt)
void setcursor(Mousectl *mc, Cursor *c)
Rectangle getrect(int but, Mousectl *mc)
void drawgetrect(Rectangle r, int up)
int menuhit(int but, Mousectl *mc, Menu *menu, Screen *scr)
int enter(char *ask, char *buf, int len,
Mousectl *mc, Keyboardctl *kc, Screen *scr)
DESCRIPTION
These functions access and control a mouse in a multi-
threaded environment. They use the message-passing Channel
interface in the threads library (see thread(2)); programs
that wish a more event-driven, single-threaded approach
should use event(2).
The state of the mouse is recorded in a structure, Mouse,
defined in <mouse.h>:
typedef struct Mouse Mouse;
struct Mouse
{
int buttons; /* bit array: LMR=124 */
Point xy;
ulong msec;
};
The Point xy records the position of the cursor, buttons the
state of the buttons (three bits representing, from bit 0
up, the buttons from left to right, 0 if the button is
released, 1 if it is pressed), and msec, a millisecond time
stamp.
The routine initmouse returns a structure through which one
may access the mouse:
typedef struct Mousectl Mousectl;
struct Mousectl
{
Mouse;
Channel *c; /* chan(Mouse)[16] */
Channel *resizec; /* chan(int)[2] */
char *file;
int mfd; /* to mouse file */
int cfd; /* to cursor file */
int pid; /* of slave proc */
Image* image; /* of associated window/display */
};
The arguments to initmouse are a file naming the device file
connected to the mouse and an Image (see draw(2)) on which
the mouse will be visible. Typically the file is nil, which
requests the default /dev/mouse; and the image is the window
in which the program is running, held in the variable screen
after a call to initdraw.
Once the Mousectl is set up, mouse motion will be reported
by messages of type Mouse sent on the Channel Mousectl.c.
Typically, a message will be sent every time a read of
/dev/mouse succeeds, which is every time the state of the
mouse changes.
When the window is resized, a message is sent on
Mousectl.resizec. The actual value sent may be discarded;
the receipt of the message tells the program that it should
call getwindow (see graphics(2)) to reconnect to the window.
Readmouse updates the Mouse structure held in the Mousectl,
blocking if the state has not changed since the last
readmouse or message sent on the channel. It calls
flushimage (see graphics(2)) before blocking, so any buf-
fered graphics requests are displayed.
Closemouse closes the file descriptors associated with the
mouse, kills the slave processes, and frees the Mousectl
structure.
Moveto moves the mouse cursor on the display to the position
specified by pt.
Setcursor sets the image of the cursor to that specified by
c. If c is nil, the cursor is set to the default. The for-
mat of the cursor data is spelled out in <cursor.h> and
described in graphics(2).
Getrect returns the dimensions of a rectangle swept by the
user, using the mouse, in the manner rio(1) or sam(1) uses
to create a new window. The but argument specifies which
button the user must press to sweep the window; any other
button press cancels the action. The returned rectangle is
all zeros if the user cancels.
Getrect uses successive calls to drawgetrect 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.
Menuhit provides a simple menu mechanism. It uses a Menu
structure defined in <mouse.h>:
typedef struct Menu Menu;
struct Menu
{
char **item;
char *(*gen)(int);
int lasthit;
};
Menuhit behaves the same as its namesake emenuhit described
in event(2), with two exceptions. First, it uses a Mousectl
to access the mouse rather than using the event interface;
and second, it creates the menu as a true window on the
Screen scr (see window(2)), permitting the menu to be
displayed in parallel with other activities on the display.
If scr is null, menuhit behaves like emenuhit, creating
backing store for the menu, writing the menu directly on the
display, and restoring the display when the menu is removed.
Enter is a multithreaded version of the eenter function
described in event(2). Like menuhit, it has an optional scr
argument to create a window. Keyboard input is read from the
channel in the Keyboardctl *kc argument (see keyboard(2)).
SOURCE
/sys/src/libdraw
SEE ALSO
graphics(2), draw(2), event(2), keyboard(2), thread(2).
BUGS
Menuhit and enter are not re-entrant and will break when
used concurrently with an independent window whose Screen
changes during their execution (as is the case when receiv-
ing a resize event while using _screen). In such cases they
must be recreated after acquiring the new screen. When used
with a Screen that has an independent backing window (i.e.
not display->image/screen), this backing window must be
drawn periodically to the display->image/screen to be able
to see the changes induced by the input.
/plan9/man/2/