tevent.3 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tevent.3 (7533B)
---
1 .TH EVENT 3
2 .SH NAME
3 event, einit, estart, estartfn, etimer, eread, emouse, ekbd, ecanread, ecanmouse, ecankbd, ereadmouse, eatomouse, eresized, egetrect, edrawgetrect, emenuhit, emoveto, esetcursor, Event, Mouse, Menu \- graphics events
4 .SH SYNOPSIS
5 .nf
6 .PP
7 .B
8 #include <u.h>
9 .B
10 #include <libc.h>
11 .B
12 #include <draw.h>
13 .B
14 #include <event.h>
15 .B
16 #include <cursor.h>
17 .ta \w'\fLRectangle 'u
18 .PP
19 .B
20 void einit(ulong keys)
21 .PP
22 .B
23 ulong event(Event *e)
24 .PP
25 .B
26 Mouse emouse(void)
27 .PP
28 .B
29 int ekbd(void)
30 .PP
31 .B
32 int ecanmouse(void)
33 .PP
34 .B
35 int ecankbd(void)
36 .PP
37 .B
38 int ereadmouse(Mouse *m)
39 .PP
40 .B
41 int eatomouse(Mouse *m, char *buf, int n)
42 .PP
43 .B
44 ulong estart(ulong key, int fd, int n)
45 .PP
46 .B
47 ulong estartfn(int id, ulong key, int fd, int n,
48 .B
49 int (*fn)(Event*, uchar*, int))
50 .PP
51 .B
52 ulong etimer(ulong key, int n)
53 .PP
54 .B
55 ulong eread(ulong keys, Event *e)
56 .PP
57 .B
58 int ecanread(ulong keys)
59 .PP
60 .B
61 void eresized(int new)
62 .PP
63 .B
64 Rectangle egetrect(int but, Mouse *m)
65 .PP
66 .B
67 void edrawgetrect(Rectangle r, int up)
68 .PP
69 .B
70 int emenuhit(int but, Mouse *m, Menu *menu)
71 .PP
72 .PP
73 .B
74 int emoveto(Point p)
75 .PP
76 .PP
77 .B
78 int esetcursor(Cursor *c)
79 .PP
80 .B
81 extern Mouse *mouse
82 .PP
83 .B
84 enum{
85 .B
86 Emouse = 1,
87 .B
88 Ekeyboard = 2,
89 .B
90 };
91 .PP
92 .SH DESCRIPTION
93 These routines provide an interface to multiple sources of input for unthreaded
94 programs.
95 Threaded programs (see
96 .MR thread (3) )
97 should instead use the threaded mouse and keyboard interface described
98 in
99 .MR mouse (3)
100 and
101 .MR keyboard (3) .
102 .PP
103 .I Einit
104 must be called first.
105 If the argument to
106 .I einit
107 has the
108 .B Emouse
109 and
110 .B Ekeyboard
111 bits set,
112 the mouse and keyboard events will be enabled;
113 in this case,
114 .IR initdraw
115 (see
116 .MR graphics (3) )
117 must have already been called.
118 The user must provide a function called
119 .IR eresized
120 to be called whenever the window in which the process
121 is running has been resized; the argument
122 .I new
123 is a flag specifying whether the program must call
124 .I getwindow
125 (see
126 .MR graphics (3) )
127 to re-establish a connection to its window.
128 After resizing (and perhaps calling
129 .IR getwindow ),
130 the global variable
131 .B screen
132 will be updated to point to the new window's
133 .B Image
134 structure.
135 .PP
136 As characters are typed on the keyboard, they are read by the
137 event mechanism and put in a queue.
138 .I Ekbd
139 returns the next rune from the queue, blocking until the
140 queue is non-empty.
141 The characters are read in raw mode,
142 .\" (see
143 .\" .IR cons (3)),
144 so they are available as soon as a complete rune is typed.
145 .PP
146 When the mouse moves or a mouse button is pressed or released,
147 a new mouse event is queued by the event mechanism.
148 .I Emouse
149 returns the next mouse event from the queue, blocking until the
150 queue is non-empty.
151 .I Emouse
152 returns a
153 .B Mouse
154 structure:
155 .IP
156 .EX
157 .ta 6n +\w'Point 'u
158 struct Mouse
159 {
160 int buttons;
161 Point xy;
162 ulong msec;
163 };
164 .EE
165 .PP
166 .B Buttons&1
167 is set when the left mouse button is pressed,
168 .B buttons&2
169 when the middle button is pressed,
170 and
171 .B buttons&4
172 when the right button is pressed.
173 The current mouse position is always returned in
174 .BR xy .
175 .B Msec
176 is a time stamp in units of milliseconds.
177 .PP
178 .I Ecankbd
179 and
180 .I ecanmouse
181 return non-zero when there are keyboard or mouse events available
182 to be read.
183 .PP
184 .I Ereadmouse
185 reads the next mouse event from the file descriptor connected to the mouse,
186 converts the textual data into a
187 .B Mouse
188 structure by calling
189 .I eatomouse
190 with the buffer and count from the read call,
191 and returns the number of bytes read, or \-1 for an error.
192 .PP
193 .I Estart
194 can be used to register additional file descriptors to scan for input.
195 It takes as arguments the file descriptor to register,
196 the maximum length of an event message on that descriptor,
197 and a key to be used in accessing the event.
198 The key must be a power of 2 and must not conflict with any previous keys.
199 If a zero key is given, a key will be allocated and returned.
200 .I Estartfn
201 is similar to
202 .IR estart ,
203 but processes the data received by calling
204 .I fn
205 before returning the event to the user.
206 The function
207 .I fn
208 is called with the
209 .B id
210 of the event; it should return
211 .B id
212 if the event is to be passed to the user,
213 .B 0
214 if it is to be ignored.
215 The variable
216 .B Event.v
217 can be used by
218 .I fn
219 to attach an arbitrary data item to the returned
220 .B Event
221 structure.
222 .B
223 Ekeyboard
224 and
225 .B Emouse
226 are the keyboard and mouse event keys.
227 .PP
228 .I Etimer
229 starts a repeating timer with a period of
230 .I n
231 milliseconds; it returns the timer event key, or zero if it fails.
232 Only one timer can be started.
233 Extra timer events are not queued and the timer channel has no associated data.
234 .PP
235 .I Eread
236 waits for the next event specified by the mask
237 .I keys
238 of event keys submitted to
239 .IR estart .
240 It fills in the appropriate field of the argument
241 .B Event
242 structure, which looks like:
243 .IP
244 .EX
245 struct Event
246 {
247 int kbdc;
248 Mouse mouse;
249 int n;
250 void *v;
251 uchar data[EMAXMSG];
252 };
253 .EE
254 .PP
255 .B Data
256 is an array which is large enough to hold a 9P message.
257 .I Eread
258 returns the key for the event which was chosen.
259 For example, if a mouse event was read,
260 .B Emouse
261 will be returned.
262 .PP
263 .I Event
264 waits for the next event of any kind.
265 The return is the same as for
266 .IR eread .
267 .PP
268 As described in
269 .MR graphics (3) ,
270 the graphics functions are buffered.
271 .IR Event ,
272 .IR eread ,
273 .IR emouse ,
274 and
275 .I ekbd
276 all cause a buffer flush unless there is an event of the
277 appropriate type already queued.
278 .PP
279 .I Ecanread
280 checks whether a call to
281 .B eread(keys)
282 would block, returning 0 if it would, 1 if it would not.
283 .PP
284 .I Getrect
285 prompts the user to sweep a rectangle.
286 It should be called with
287 .I m
288 holding the mouse event that triggered the
289 .I egetrect
290 (or, if none, a
291 .B Mouse
292 with
293 .B buttons
294 set to 7).
295 It changes to the sweep cursor,
296 waits for the buttons all to be released,
297 and then waits for button number
298 .I but
299 to be pressed, marking the initial corner.
300 If another button is pressed instead,
301 .I egetrect
302 returns a rectangle
303 with zero for both corners, after
304 waiting for all the buttons to be released.
305 Otherwise,
306 .I egetrect
307 continually draws the swept rectangle
308 until the button is released again, and returns the swept rectangle.
309 The mouse structure pointed to by
310 .I m
311 will contain the final mouse event.
312 .PP
313 .I Egetrect
314 uses successive calls to
315 .I edrawgetrect
316 to maintain the red rectangle showing the sweep-in-progress.
317 The rectangle to be drawn is specified by
318 .I rc
319 and the
320 .I up
321 parameter says whether to draw (1) or erase (0) the rectangle.
322 .PP
323 .I Emenuhit
324 displays a menu and returns a selected menu item number.
325 It should be called with
326 .I m
327 holding the mouse event that triggered the
328 .IR emenuhit ;
329 it will call
330 .I emouse
331 to update it.
332 A
333 .B Menu
334 is a structure:
335 .IP
336 .EX
337 struct Menu
338 {
339 char **item;
340 char *(*gen)(int);
341 int lasthit;
342 };
343 .EE
344 .PP
345 If
346 .B item
347 is nonzero, it should be a null-terminated array of the character strings
348 to be displayed as menu items.
349 Otherwise,
350 .B gen
351 should be a function that, given an item number, returns the character
352 string for that item, or zero if the number is past the end of the list.
353 Items are numbered starting at zero.
354 .I Menuhit
355 waits until
356 .I but
357 is released, and then returns the number of the selection,
358 or \-1 for no selection.
359 The
360 .I m
361 argument is filled in with the final mouse event.
362 .PP
363 .I Emoveto
364 moves the mouse cursor to the position
365 .B p
366 on the screen.
367 .PP
368 .I Esetcursor
369 changes the cursor image to that described by the
370 .B Cursor
371 .I c
372 (see
373 .MR mouse (3) ).
374 If
375 .B c
376 is nil, it restores the image to the default arrow.
377 .SH SOURCE
378 .B \*9/src/libdraw
379 .SH "SEE ALSO"
380 .MR rio (1) ,
381 .MR graphics (3) ,
382 .MR plumb (3) ,
383 .\" .IR cons (3),
384 .MR draw (3)