1 94b5e3ff 2005-01-04 devnull .TH ACMEEVENT 1
3 94b5e3ff 2005-01-04 devnull acmeevent, acme.rc \- shell script support for acme clients
4 94b5e3ff 2005-01-04 devnull .SH SYNOPSIS
7 94b5e3ff 2005-01-04 devnull .B acme/acme/$winid/event | acmeevent
10 94b5e3ff 2005-01-04 devnull \&. /usr/local/plan9/lib/acme.rc
12 94b5e3ff 2005-01-04 devnull .B newwindow
14 94b5e3ff 2005-01-04 devnull .B winread
17 94b5e3ff 2005-01-04 devnull .B winwrite
20 94b5e3ff 2005-01-04 devnull .B winctl
23 94b5e3ff 2005-01-04 devnull .B windump
25 94b5e3ff 2005-01-04 devnull .I dumpdir
30 94b5e3ff 2005-01-04 devnull .I dumpcmd
35 94b5e3ff 2005-01-04 devnull .B winname
38 94b5e3ff 2005-01-04 devnull .B windel
43 94b5e3ff 2005-01-04 devnull .B winwriteevent
52 94b5e3ff 2005-01-04 devnull .I textlen
54 94b5e3ff 2005-01-04 devnull .I chordarg
55 94b5e3ff 2005-01-04 devnull .I chordaddr
58 94b5e3ff 2005-01-04 devnull .B wineventloop
59 94b5e3ff 2005-01-04 devnull .SH DESCRIPTION
60 94b5e3ff 2005-01-04 devnull .I Acmeevent
62 94b5e3ff 2005-01-04 devnull .I acme.rc
63 94b5e3ff 2005-01-04 devnull make it easy to write simple
64 94b5e3ff 2005-01-04 devnull .IR acme (1)
65 94b5e3ff 2005-01-04 devnull client programs as shell scripts.
68 94b5e3ff 2005-01-04 devnull clients read the
72 94b5e3ff 2005-01-04 devnull .IR acme (4))
73 94b5e3ff 2005-01-04 devnull for the windows they control, reacting to the events.
74 94b5e3ff 2005-01-04 devnull The events are presented in a format that is easy to read with C programs
75 94b5e3ff 2005-01-04 devnull but hard to read with shell scripts.
77 94b5e3ff 2005-01-04 devnull .I Acmeevent
79 94b5e3ff 2005-01-04 devnull .IR acme (4)
80 94b5e3ff 2005-01-04 devnull event stream from standard input, printing a shell-friendly
81 94b5e3ff 2005-01-04 devnull version of the events, one per line, on standard output.
82 94b5e3ff 2005-01-04 devnull Each output line from
83 94b5e3ff 2005-01-04 devnull .I acmeevent
84 94b5e3ff 2005-01-04 devnull has the form:
94 94b5e3ff 2005-01-04 devnull .I textlen
96 94b5e3ff 2005-01-04 devnull .I chordarg
97 94b5e3ff 2005-01-04 devnull .I chordaddr
99 94b5e3ff 2005-01-04 devnull The fields are:
102 94b5e3ff 2005-01-04 devnull A character indicating the origin or cause of the action.
103 94b5e3ff 2005-01-04 devnull The possible causes are:
104 94b5e3ff 2005-01-04 devnull a write to the body or tag file
105 94b5e3ff 2005-01-04 devnull .RB ( E ),
106 94b5e3ff 2005-01-04 devnull a write to the window's other files
107 94b5e3ff 2005-01-04 devnull .RB ( F ),
108 94b5e3ff 2005-01-04 devnull input via the keyboard
109 94b5e3ff 2005-01-04 devnull .RB ( K ),
111 94b5e3ff 2005-01-04 devnull input via the mouse
112 94b5e3ff 2005-01-04 devnull .RB ( M ).
115 94b5e3ff 2005-01-04 devnull A character indicating the type of action.
116 94b5e3ff 2005-01-04 devnull The possible types are:
117 94b5e3ff 2005-01-04 devnull text deleted from the body
118 94b5e3ff 2005-01-04 devnull .RB ( D ),
119 94b5e3ff 2005-01-04 devnull text deleted from the tag
120 94b5e3ff 2005-01-04 devnull .RB ( d ),
121 94b5e3ff 2005-01-04 devnull text inserted in the body
122 94b5e3ff 2005-01-04 devnull .RB ( I ),
123 94b5e3ff 2005-01-04 devnull text inserted in the tag
124 94b5e3ff 2005-01-04 devnull .RB ( i ),
125 94b5e3ff 2005-01-04 devnull a button 3 action in the body
126 94b5e3ff 2005-01-04 devnull .RB ( L ),
127 94b5e3ff 2005-01-04 devnull a button 3 action in the tag
128 94b5e3ff 2005-01-04 devnull .RB ( l ),
129 94b5e3ff 2005-01-04 devnull a button 2 action in the body
130 94b5e3ff 2005-01-04 devnull .RB ( X ),
132 94b5e3ff 2005-01-04 devnull a button 2 action in the tag
133 94b5e3ff 2005-01-04 devnull .RB ( x ).
150 94b5e3ff 2005-01-04 devnull .I textlen
156 94b5e3ff 2005-01-04 devnull .I chordarg
159 94b5e3ff 2005-01-04 devnull .I chordorigin
162 94b5e3ff 2005-01-04 devnull .I Acme.rc
163 94b5e3ff 2005-01-04 devnull is a library of
164 94b5e3ff 2005-01-04 devnull .IR rc (1)
165 94b5e3ff 2005-01-04 devnull shell functions useful for writing acme clients.
167 94b5e3ff 2005-01-04 devnull .I Newwindow
168 94b5e3ff 2005-01-04 devnull creates a new acme window and sets
169 94b5e3ff 2005-01-04 devnull .B $winid
170 94b5e3ff 2005-01-04 devnull to the new window's id.
171 94b5e3ff 2005-01-04 devnull The other commands all use
172 94b5e3ff 2005-01-04 devnull .B $winid
173 94b5e3ff 2005-01-04 devnull to determine which window to operate on.
175 94b5e3ff 2005-01-04 devnull .I Winread
176 94b5e3ff 2005-01-04 devnull prints the current window's
178 94b5e3ff 2005-01-04 devnull to standard output.
179 94b5e3ff 2005-01-04 devnull It is equivalent to
181 94b5e3ff 2005-01-04 devnull .BI /mnt/acme/acme/$winid/ file
182 94b5e3ff 2005-01-04 devnull on Plan 9.
183 94b5e3ff 2005-01-04 devnull Similarly,
184 94b5e3ff 2005-01-04 devnull .I winwrite
185 94b5e3ff 2005-01-04 devnull writes standard input to the current window's
186 94b5e3ff 2005-01-04 devnull .IR file .
187 94b5e3ff 2005-01-04 devnull .I Winread
189 94b5e3ff 2005-01-04 devnull .I winwrite
190 94b5e3ff 2005-01-04 devnull are useful mainly in building more complex functions.
192 94b5e3ff 2005-01-04 devnull .I Winctl
195 94b5e3ff 2005-01-04 devnull to the window's
198 94b5e3ff 2005-01-04 devnull The most commonly-used command is
199 94b5e3ff 2005-01-04 devnull .BR clean ,
200 94b5e3ff 2005-01-04 devnull which marks the window as clean.
202 94b5e3ff 2005-01-04 devnull .IR acme (4)
203 94b5e3ff 2005-01-04 devnull for a full list of commands.
205 94b5e3ff 2005-01-04 devnull .I Windump
206 94b5e3ff 2005-01-04 devnull sets the window's dump directory
207 94b5e3ff 2005-01-04 devnull and dump command
209 94b5e3ff 2005-01-04 devnull .IR acme (4)).
210 94b5e3ff 2005-01-04 devnull If either argument is omitted or is
212 94b5e3ff 2005-01-04 devnull that argument is not set.
214 94b5e3ff 2005-01-04 devnull .I Winname
215 94b5e3ff 2005-01-04 devnull sets the name displayed in the window's tag.
217 94b5e3ff 2005-01-04 devnull .I Windel
218 94b5e3ff 2005-01-04 devnull simulates the
220 94b5e3ff 2005-01-04 devnull command. If the argument
222 94b5e3ff 2005-01-04 devnull is given, it simulates the
223 94b5e3ff 2005-01-04 devnull .B Delete
224 94b5e3ff 2005-01-04 devnull command.
226 94b5e3ff 2005-01-04 devnull .I Winwriteevent
227 94b5e3ff 2005-01-04 devnull writes an event to the window's event file.
228 94b5e3ff 2005-01-04 devnull The event is in the format produced by
229 94b5e3ff 2005-01-04 devnull .IR acmeevent .
230 94b5e3ff 2005-01-04 devnull Only the first four arguments are necessary:
231 94b5e3ff 2005-01-04 devnull the rest are ignored.
232 94b5e3ff 2005-01-04 devnull Event handlers should call
233 94b5e3ff 2005-01-04 devnull .I winwriteevent
234 94b5e3ff 2005-01-04 devnull to pass unhandled button 2 or button 3 events
237 94b5e3ff 2005-01-04 devnull for processing.
239 94b5e3ff 2005-01-04 devnull .I Wineventloop
240 94b5e3ff 2005-01-04 devnull executes the current window's event file, as output by
241 94b5e3ff 2005-01-04 devnull .IR acmeevent .
242 94b5e3ff 2005-01-04 devnull It returns when the window has been deleted.
243 94b5e3ff 2005-01-04 devnull Before running
244 94b5e3ff 2005-01-04 devnull .I wineventloop ,
245 94b5e3ff 2005-01-04 devnull clients must define a shell function named
246 94b5e3ff 2005-01-04 devnull .BR event ,
247 94b5e3ff 2005-01-04 devnull which will be run for each incoming event,
250 94b5e3ff 2005-01-04 devnull executes the output of
251 94b5e3ff 2005-01-04 devnull .IR acmeevent .
252 94b5e3ff 2005-01-04 devnull A typical event function need only worry about button 2 and button 3 events.
253 94b5e3ff 2005-01-04 devnull Those events not handled should be sent back to
256 94b5e3ff 2005-01-04 devnull .IR winwriteevent .
257 94b5e3ff 2005-01-04 devnull .SH EXAMPLE
258 94b5e3ff 2005-01-04 devnull .IR Adict ,
259 94b5e3ff 2005-01-04 devnull a dictionary browser,
260 94b5e3ff 2005-01-04 devnull is implemented using
261 94b5e3ff 2005-01-04 devnull .I acmeevent
263 94b5e3ff 2005-01-04 devnull .IR acme.rc .
265 94b5e3ff 2005-01-04 devnull .I event
266 94b5e3ff 2005-01-04 devnull handler is:
269 94b5e3ff 2005-01-04 devnull .ta +4n +4n +4n +4n +4n +4n
270 94b5e3ff 2005-01-04 devnull fn event {
271 94b5e3ff 2005-01-04 devnull switch($1$2){
272 94b5e3ff 2005-01-04 devnull case Mx MX # button 2 - pass back to acme
273 94b5e3ff 2005-01-04 devnull winwriteevent $*
274 94b5e3ff 2005-01-04 devnull case Ml ML # button 3 - open new window on dictionary or entry
276 94b5e3ff 2005-01-04 devnull if(~ $dict NONE)
277 94b5e3ff 2005-01-04 devnull dictwin /adict/$7/ $7
279 94b5e3ff 2005-01-04 devnull dictwin /adict/$dict/$7 $dict $7
285 94b5e3ff 2005-01-04 devnull Note that the button 3 handler starts a subshell in which to run
286 94b5e3ff 2005-01-04 devnull .IR dictwin .
287 94b5e3ff 2005-01-04 devnull That subshell will create a new window, set its name,
288 94b5e3ff 2005-01-04 devnull possibly fill the window with a dictionary list or dictionary entry,
289 94b5e3ff 2005-01-04 devnull mark the window as clean, and run the event loop:
292 94b5e3ff 2005-01-04 devnull fn dictwin {
293 94b5e3ff 2005-01-04 devnull newwindow
294 94b5e3ff 2005-01-04 devnull winname $1
296 94b5e3ff 2005-01-04 devnull if(~ $dict NONE)
297 94b5e3ff 2005-01-04 devnull dict -d '?' >[2=1] | sed 1d | winwrite body
298 94b5e3ff 2005-01-04 devnull if(~ $#* 3)
299 94b5e3ff 2005-01-04 devnull dict -d $dict $3 >[2=1] | winwrite body
300 94b5e3ff 2005-01-04 devnull winctl clean
301 94b5e3ff 2005-01-04 devnull wineventloop
305 94b5e3ff 2005-01-04 devnull The script starts with an initial window:
308 94b5e3ff 2005-01-04 devnull dictwin /adict/ NONE
311 94b5e3ff 2005-01-04 devnull Button 3 clicking on a dictionary name in the initial window
312 94b5e3ff 2005-01-04 devnull will create a new empty window for that dictionary.
313 94b5e3ff 2005-01-04 devnull Typing and button 3 clicking on a word in that window
314 94b5e3ff 2005-01-04 devnull will create a new window with the dictionary's entry for that word.
317 94b5e3ff 2005-01-04 devnull .B /usr/local/plan9/bin/adict
318 94b5e3ff 2005-01-04 devnull for the full implementation.
319 94b5e3ff 2005-01-04 devnull .SH SOURCE
320 94b5e3ff 2005-01-04 devnull .B /usr/local/plan9/src/cmd/acmeevent.c
322 94b5e3ff 2005-01-04 devnull .B /usr/local/plan9/lib/acme.rc
323 94b5e3ff 2005-01-04 devnull .SH SEE ALSO
324 94b5e3ff 2005-01-04 devnull .IR acme (1),
325 94b5e3ff 2005-01-04 devnull .IR acme (4),
326 94b5e3ff 2005-01-04 devnull .IR rc (1)
327 94b5e3ff 2005-01-04 devnull .SH BUGS
328 94b5e3ff 2005-01-04 devnull There is more that could be done to ease the writing
329 94b5e3ff 2005-01-04 devnull of complicated clients.