Lots of man pages.
This commit is contained in:
rsc
parent
08df2a433e
commit
cfa37a7b11
152 changed files with 25407 additions and 148 deletions
384
man/man3/event.3
Normal file
384
man/man3/event.3
Normal file
|
|
@ -0,0 +1,384 @@
|
|||
.TH EVENT 3
|
||||
.SH NAME
|
||||
event, einit, estart, estartfn, etimer, eread, emouse, ekbd, ecanread, ecanmouse, ecankbd, ereadmouse, eatomouse, eresized, egetrect, edrawgetrect, emenuhit, 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(int id, ulong key, int fd, int n,
|
||||
.B
|
||||
int (*fn)(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
|
||||
.PP
|
||||
.B
|
||||
int emoveto(Point p)
|
||||
.PP
|
||||
.PP
|
||||
.B
|
||||
int esetcursor(Cursor *c)
|
||||
.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.
|
||||
.SH SOURCE
|
||||
.B /sys/src/libdraw
|
||||
.SH "SEE ALSO"
|
||||
.IR rio (1),
|
||||
.IR graphics (2),
|
||||
.IR plumb (2),
|
||||
.IR cons (3),
|
||||
.IR draw (3)
|
||||
Loading…
Add table
Add a link
Reference in a new issue