10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
385 lines
7.3 KiB
Groff
385 lines
7.3 KiB
Groff
.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
|
|
.MR thread 3 )
|
|
should instead use the threaded mouse and keyboard interface described
|
|
in
|
|
.MR mouse 3
|
|
and
|
|
.MR keyboard 3 .
|
|
.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
|
|
.MR graphics 3 )
|
|
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
|
|
.MR graphics 3 )
|
|
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
|
|
.MR graphics 3 ,
|
|
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
|
|
.MR mouse 3 ).
|
|
If
|
|
.B c
|
|
is nil, it restores the image to the default arrow.
|
|
.SH SOURCE
|
|
.B \*9/src/libdraw
|
|
.SH "SEE ALSO"
|
|
.MR rio 1 ,
|
|
.MR graphics 3 ,
|
|
.MR plumb 3 ,
|
|
.\" .IR cons (3),
|
|
.MR draw 3
|