1 .TH ACMEEVENT 1
2 .SH NAME
3 acmeevent, acme.rc \- shell script support for acme clients
4 .SH SYNOPSIS
5 .B 9p
6 .B read
7 .B acme/acme/$winid/event | acmeevent
8 .PP
9 .B
10 \&. \*9/lib/acme.rc
11 .PP
12 .B newwindow
13 .PP
14 .B winread
15 .I file
16 .PP
17 .B winwrite
18 .I file
19 .PP
20 .B winctl
21 .I cmd
22 .PP
23 .B windump
24 [
25 .I dumpdir
26 |
27 .B -
28 ]
29 [
30 .I dumpcmd
31 |
32 .B -
33 ]
34 .PP
35 .B winname
36 .I name
37 .PP
38 .B windel
39 [
40 .B sure
41 ]
42 .PP
43 .B winwriteevent
44 .I c1
45 .I c2
46 .I q0
47 .I q1
48 [
49 .I eq0
50 .I eq1
51 .I flag
52 .I textlen
53 .I text
54 .I chordarg
55 .I chordaddr
56 ]
57 .PP
58 .B wineventloop
59 .SH DESCRIPTION
60 .I Acmeevent
61 and
62 .I acme.rc
63 make it easy to write simple
64 .MR acme (1)
65 client programs as shell scripts.
66 .PP
67 .I Acme
68 clients read the
69 .B event
70 files 
71 (see
72 .MR acme (4) )
73 for the windows they control, reacting to the events.
74 The events are presented in a format that is easy to read with C programs
75 but hard to read with shell scripts.
76 .PP
77 .I Acmeevent
78 reads an
79 .MR acme (4)
80 event stream from standard input, printing a shell-friendly
81 version of the events, one per line, on standard output.
82 Each output line from
83 .I acmeevent
84 has the form:
85 .IP
86 .B event
87 .I c1
88 .I c2
89 .I q0
90 .I q1
91 .I eq0
92 .I eq1
93 .I flag
94 .I textlen
95 .I text
96 .I chordarg
97 .I chordaddr
98 .PP
99 The fields are:
100 .TP
101 .I c1
102 A character indicating the origin or cause of the action.
103 The possible causes are:
104 a write to the body or tag file
105 .RB ( E ),
106 a write to the window's other files
107 .RB ( F ),
108 input via the keyboard
109 .RB ( K ),
110 and
111 input via the mouse
112 .RB ( M ).
113 .TP
114 .I c2
115 A character indicating the type of action.
116 The possible types are:
117 text deleted from the body
118 .RB ( D ),
119 text deleted from the tag
120 .RB ( d ),
121 text inserted in the body
122 .RB ( I ),
123 text inserted in the tag
124 .RB ( i ),
125 a button 3 action in the body
126 .RB ( L ),
127 a button 3 action in the tag
128 .RB ( l ),
129 a button 2 action in the body
130 .RB ( X ),
131 and 
132 a button 2 action in the tag
133 .RB ( x ).
134 .TP
135 .I q0\fR, \fPq1
136 The character addresses of the action.
137 .TP
138 .I eq0\fR, \fPq1
139 The expanded character addresses of the action.
140 If the text indicated by
141 .IR q0 ,
142 .I q1
143 is a null string that has a non-null expansion,
144 .IR eq0 ,
145 .I eq1
146 are the addresses of the expansion.
147 Otherwise they are the same as
148 .IR q0 ,
149 .IR q1 .
150 .TP
151 .I flag
152 .I Flag
153 is a bitwise OR (reported decimally) of the following:
154 1 if the text indicated is recognized as an
155 .I acme
156 built-in command;
157 2 if the text indicated is a null string that has a non-null expansion
158 (see
159 .IR eq0 ,
160 .I eq1
161 above);
162 8 if the command has an extra (chorded) argument
163 (see
164 .I chordarg
165 below).
166 .I Flag
167 remains from the
168 .MR acme (4)
169 event format.
170 Because
171 .IR eq0 ,
172 .IR eq1 ,
173 and
174 .I chordarg
175 are explicit in each event
176 (unlike in
177 .MR acme (4)
178 events),
179 .I flag
180 can usually be ignored.
181 .TP
182 .I textlen
183 The length of the action text (or its expansion) for button 2 and button 3 events in characters.
184 .TP
185 .I text
186 If
187 .I textlen
188 is less than 256 chracters,
189 .I text
190 is the action text itself.
191 Otherwise it is an empty string and must be read from the
192 .B data
193 file.
194 .TP
195 .I chordarg
196 The chorded argument for an action.
197 .TP
198 .I chordorigin
199 If the chord argument is in the body of a named window,
200 .I chordorigin
201 specifies the full address of the argument,
202 as in
203 .BR /etc/group:#123,#234 .
204 .PD
205 .PP
206 To experiment with
207 .IR acmeevent ,
208 create an empty window in
209 .I acme
210 (using
211 .IR New ), type
212 .IP
213 .EX
214 9p read acme/$winid/event | acmeevent
215 .EE
216 .LP
217 inside it, and execute it.
218 Actions performed on the window will be printed as events in the
219 .B +Errors
220 window.
221 .PP
222 .I Acme.rc
223 is a library of
224 .MR rc (1)
225 shell functions useful for writing acme clients.
226 .PP
227 .I Newwindow
228 creates a new acme window and sets
229 .B $winid
230 to the new window's id.
231 The other commands all use
232 .B $winid
233 to determine which window to operate on.
234 .PP
235 .I Winread
236 prints the current window's
237 .I file
238 to standard output.
239 It is equivalent to
240 .B cat
241 .BI /mnt/acme/acme/$winid/ file
242 on Plan 9.
243 Similarly,
244 .I winwrite
245 writes standard input to the current window's
246 .IR file .
247 .I Winread
248 and
249 .I winwrite
250 are useful mainly in building more complex functions.
251 .PP
252 .I Winctl
253 writes 
254 .I cmd
255 to the window's
256 .B ctl
257 file.
258 The most commonly-used command is
259 .BR clean ,
260 which marks the window as clean.
261 See
262 .MR acme (4)
263 for a full list of commands.
264 .PP
265 .I Windump
266 sets the window's dump directory
267 and dump command
268 (see
269 .MR acme (4) ).
270 If either argument is omitted or is
271 .BR - ,
272 that argument is not set.
273 .PP
274 .I Winname
275 sets the name displayed in the window's tag.
276 .PP
277 .I Windel
278 simulates the
279 .B Del
280 command.  If the argument
281 .B sure
282 is given, it simulates the
283 .B Delete
284 command.
285 .PP
286 .I Winwriteevent
287 writes an event to the window's event file.
288 The event is in the format produced by
289 .IR acmeevent .
290 Only the first four arguments are necessary:
291 the rest are ignored.
292 Event handlers should call
293 .I winwriteevent
294 to pass unhandled button 2 or button 3 events
295 back to
296 .I acme
297 for processing.
298 .PP
299 .I Wineventloop
300 executes the current window's event file, as output by
301 .IR acmeevent .
302 It returns when the window has been deleted.
303 Before running
304 .I wineventloop ,
305 clients must define a shell function named
306 .BR event ,
307 which will be run for each incoming event,
308 as
309 .I rc
310 executes the output of
311 .IR acmeevent .
312 A typical event function need only worry about button 2 and button 3 events.
313 Those events not handled should be sent back to 
314 .I acme
315 with
316 .IR winwriteevent .
317 .SH EXAMPLE
318 .IR Adict ,
319 a dictionary browser,
320 is implemented using 
321 .I acmeevent
322 and
323 .IR acme.rc .
324 The
325 .I event
326 handler is:
327 .IP
328 .EX
329 .ta +4n +4n +4n +4n +4n +4n
330 fn event {
331 	switch($1$2){
332 	case Mx MX    # button 2 - pass back to acme
333 		winwriteevent $*
334 	case Ml ML    # button 3 - open new window on dictionary or entry
335 		{
336 			if(~ $dict NONE)
337 				dictwin /adict/$7/ $7
338 			if not
339 				dictwin /adict/$dict/$7 $dict $7
340 		} &
341 	}
342 }
343 .EE
344 .LP
345 Note that the button 3 handler starts a subshell in which to run
346 .IR dictwin .
347 That subshell will create a new window, set its name,
348 possibly fill the window with a dictionary list or dictionary entry,
349 mark the window as clean, and run the event loop:
350 .IP
351 .EX
352 fn dictwin {
353 	newwindow
354 	winname $1
355 	dict=$2
356 	if(~ $dict NONE)
357 		dict -d '?' >[2=1] | sed 1d | winwrite body
358 	if(~ $#* 3)
359 		dict -d $dict $3 >[2=1] | winwrite body
360 	winctl clean
361 	wineventloop
362 }
363 .EE
364 .LP
365 The script starts with an initial window:
366 .IP
367 .EX
368 dictwin /adict/ NONE
369 .EE
370 .LP
371 Button 3 clicking on a dictionary name in the initial window
372 will create a new empty window for that dictionary.
373 Typing and button 3 clicking on a word in that window
374 will create a new window with the dictionary's entry for that word.
375 .PP
376 See
377 .B \*9/bin/adict
378 for the full implementation.
379 .SH SOURCE
380 .B \*9/src/cmd/acmeevent.c
381 .br
382 .B \*9/lib/acme.rc
383 .SH SEE ALSO
384 .MR acme (1) ,
385 .MR acme (4) ,
386 .MR rc (1)
387 .SH BUGS
388 There is more that could be done to ease the writing
389 of complicated clients.