414 lines
8 KiB
Text
414 lines
8 KiB
Text
.TH EVENT 2
|
|
.SH 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
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.PP
|
|
.B
|
|
#include <u.h>
|
|
.B
|
|
#include <libc.h>
|
|
.B
|
|
#include <draw.h>
|
|
.B
|
|
#include <event.h>
|
|
.B
|
|
#include <cursor.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
|
|
int ereadmouse(Mouse *m)
|
|
.PP
|
|
.B
|
|
int eatomouse(Mouse *m, char *buf, int n)
|
|
.PP
|
|
.B
|
|
ulong estart(ulong key, int fd, int n)
|
|
.PP
|
|
.B
|
|
ulong estartfn(ulong key, int fd, int n,
|
|
.B
|
|
int (*fn)(int, Event*, uchar*, int))
|
|
.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 eresized(int new)
|
|
.PP
|
|
.B
|
|
Rectangle egetrect(int but, Mouse *m)
|
|
.PP
|
|
.B
|
|
void edrawgetrect(Rectangle r, int up)
|
|
.PP
|
|
.B
|
|
int emenuhit(int but, Mouse *m, Menu *menu)
|
|
.PP
|
|
.B
|
|
void emoveto(Point p)
|
|
.PP
|
|
.B
|
|
void esetcursor(Cursor *c)
|
|
.PP
|
|
.B
|
|
int eenter(char *ask, char *buf, int len, Mouse *m)
|
|
.PP
|
|
.B
|
|
extern Mouse *mouse
|
|
.PP
|
|
.B
|
|
enum{
|
|
.B
|
|
Emouse = 1,
|
|
.B
|
|
Ekeyboard = 2,
|
|
.B
|
|
};
|
|
.PP
|
|
.SH DESCRIPTION
|
|
These routines provide an interface to multiple sources of input for unthreaded
|
|
programs.
|
|
Threaded programs (see
|
|
.IR thread (2))
|
|
should instead use the threaded mouse and keyboard interface described
|
|
in
|
|
.IR mouse (2)
|
|
and
|
|
.IR keyboard (2).
|
|
.PP
|
|
.I Einit
|
|
must be called first.
|
|
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 initdraw
|
|
(see
|
|
.IR graphics (2))
|
|
must have already been called.
|
|
The user must provide a function called
|
|
.IR eresized
|
|
to be called whenever the window in which the process
|
|
is running has been resized; the argument
|
|
.I new
|
|
is a flag specifying whether the program must call
|
|
.I getwindow
|
|
(see
|
|
.IR graphics (2))
|
|
to re-establish a connection to its window.
|
|
After resizing (and perhaps calling
|
|
.IR getwindow ),
|
|
the global variable
|
|
.B screen
|
|
will be updated to point to the new window's
|
|
.B Image
|
|
structure.
|
|
.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 pressed 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 pressed,
|
|
.B buttons&2
|
|
when the middle button is pressed,
|
|
and
|
|
.B buttons&4
|
|
when the right button is pressed.
|
|
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 Ereadmouse
|
|
reads the next mouse event from the file descriptor connected to the mouse,
|
|
converts the textual data into a
|
|
.B Mouse
|
|
structure by calling
|
|
.I eatomouse
|
|
with the buffer and count from the read call,
|
|
and returns the number of bytes read, or \-1 for an error.
|
|
.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, a key will be allocated and returned.
|
|
.I Estartfn
|
|
is similar to
|
|
.IR estart ,
|
|
but processes the data received by calling
|
|
.I fn
|
|
before returning the event to the user.
|
|
The function
|
|
.I fn
|
|
is called with the
|
|
.B id
|
|
of the event; it should return
|
|
.B id
|
|
if the event is to be passed to the user,
|
|
.B 0
|
|
if it is to be ignored.
|
|
The variable
|
|
.B Event.v
|
|
can be used by
|
|
.I fn
|
|
to attach an arbitrary data item to the returned
|
|
.B Event
|
|
structure.
|
|
.B
|
|
Ekeyboard
|
|
and
|
|
.B Emouse
|
|
are the keyboard and mouse event keys.
|
|
.PP
|
|
.I Etimer
|
|
starts a repeating timer with a period of
|
|
.I 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.
|
|
.PP
|
|
.I Eread
|
|
waits for the next event specified by the mask
|
|
.I keys
|
|
of event keys submitted to
|
|
.IR 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;
|
|
void *v;
|
|
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,
|
|
.B 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 Ecanread
|
|
checks whether a call to
|
|
.B eread(keys)
|
|
would block, returning 0 if it would, 1 if it would not.
|
|
.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 egetrect
|
|
(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 pressed, marking the initial corner.
|
|
If another button is pressed instead,
|
|
.I egetrect
|
|
returns a rectangle
|
|
with zero for both corners, after
|
|
waiting for all the buttons to be released.
|
|
Otherwise,
|
|
.I egetrect
|
|
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 Egetrect
|
|
uses successive calls to
|
|
.I edrawgetrect
|
|
to maintain the red rectangle showing the sweep-in-progress.
|
|
The rectangle to be drawn is specified by
|
|
.I rc
|
|
and the
|
|
.I up
|
|
parameter says whether to draw (1) or erase (0) the rectangle.
|
|
.PP
|
|
.I Emenuhit
|
|
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 emenuhit ;
|
|
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 \-1 for no selection.
|
|
The
|
|
.I m
|
|
argument is filled in with the final mouse event.
|
|
.PP
|
|
.I Emoveto
|
|
moves the mouse cursor to the position
|
|
.B p
|
|
on the screen.
|
|
.PP
|
|
.I Esetcursor
|
|
changes the cursor image to that described by the
|
|
.B Cursor
|
|
.I c
|
|
(see
|
|
.IR mouse (2)).
|
|
If
|
|
.B c
|
|
is nil, it restores the image to the default arrow.
|
|
.PP
|
|
.I 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
|
|
.B Mouse *m
|
|
argument) in which text can be
|
|
typed and edited.
|
|
If the string argument
|
|
.B ask
|
|
is not
|
|
.B nil,
|
|
it is displayed as a static label before the input string.
|
|
The
|
|
.B buf
|
|
parameter contains the null-terminated input string to be edited. The
|
|
.B len
|
|
argument specifies the length of
|
|
.B buf
|
|
in bytes including the terminating null byte.
|
|
If
|
|
.B buf
|
|
or
|
|
.B len
|
|
is zero, no text can be entered.
|
|
On success,
|
|
.I eenter
|
|
returns the number of bytes in the edited string
|
|
.B buf
|
|
or -1 on error.
|
|
.SH SOURCE
|
|
.B /sys/src/libdraw
|
|
.SH "SEE ALSO"
|
|
.IR rio (1),
|
|
.IR graphics (2),
|
|
.IR plumb (2),
|
|
.IR cons (3),
|
|
.IR draw (3)
|