aboutsummaryrefslogtreecommitdiff
path: root/man/man3/event.3
blob: e029981142b5673f7c690cc9d901750ba7752ebf (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
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 (3))
should instead use the threaded mouse and keyboard interface described
in
.IR mouse (3)
and
.IR 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
.IR 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
.IR 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
.IR 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
.IR mouse (3)).
If
.B c
is nil, it restores the image to the default arrow.
.SH SOURCE
.B /usr/local/plan9/src/libdraw
.SH "SEE ALSO"
.IR rio (1),
.IR graphics (3),
.IR plumb (3),
.\" .IR cons (3),
.IR draw (3)