1 94b5e3ff 2005-01-04 devnull .TH ACMEEVENT 1
  2 94b5e3ff 2005-01-04 devnull .SH NAME
  3 94b5e3ff 2005-01-04 devnull acmeevent, acme.rc \- shell script support for acme clients
  4 94b5e3ff 2005-01-04 devnull .SH SYNOPSIS
  5 94b5e3ff 2005-01-04 devnull .B 9p
  6 94b5e3ff 2005-01-04 devnull .B read
  7 94b5e3ff 2005-01-04 devnull .B acme/acme/$winid/event | acmeevent
  8 94b5e3ff 2005-01-04 devnull .PP
  9 94b5e3ff 2005-01-04 devnull .B
 10 94b5e3ff 2005-01-04 devnull \&. /usr/local/plan9/lib/acme.rc
 11 94b5e3ff 2005-01-04 devnull .PP
 12 94b5e3ff 2005-01-04 devnull .B newwindow
 13 94b5e3ff 2005-01-04 devnull .PP
 14 94b5e3ff 2005-01-04 devnull .B winread
 15 94b5e3ff 2005-01-04 devnull .I file
 16 94b5e3ff 2005-01-04 devnull .PP
 17 94b5e3ff 2005-01-04 devnull .B winwrite
 18 94b5e3ff 2005-01-04 devnull .I file
 19 94b5e3ff 2005-01-04 devnull .PP
 20 94b5e3ff 2005-01-04 devnull .B winctl
 21 94b5e3ff 2005-01-04 devnull .I cmd
 22 94b5e3ff 2005-01-04 devnull .PP
 23 94b5e3ff 2005-01-04 devnull .B windump
 24 94b5e3ff 2005-01-04 devnull [
 25 94b5e3ff 2005-01-04 devnull .I dumpdir
 26 94b5e3ff 2005-01-04 devnull |
 27 94b5e3ff 2005-01-04 devnull .B -
 28 94b5e3ff 2005-01-04 devnull ]
 29 94b5e3ff 2005-01-04 devnull [
 30 94b5e3ff 2005-01-04 devnull .I dumpcmd
 31 94b5e3ff 2005-01-04 devnull |
 32 94b5e3ff 2005-01-04 devnull .B -
 33 94b5e3ff 2005-01-04 devnull ]
 34 94b5e3ff 2005-01-04 devnull .PP
 35 94b5e3ff 2005-01-04 devnull .B winname
 36 94b5e3ff 2005-01-04 devnull .I name
 37 94b5e3ff 2005-01-04 devnull .PP
 38 94b5e3ff 2005-01-04 devnull .B windel
 39 94b5e3ff 2005-01-04 devnull [
 40 94b5e3ff 2005-01-04 devnull .B sure
 41 94b5e3ff 2005-01-04 devnull ]
 42 94b5e3ff 2005-01-04 devnull .PP
 43 94b5e3ff 2005-01-04 devnull .B winwriteevent
 44 94b5e3ff 2005-01-04 devnull .I c1
 45 94b5e3ff 2005-01-04 devnull .I c2
 46 94b5e3ff 2005-01-04 devnull .I q0
 47 94b5e3ff 2005-01-04 devnull .I q1
 48 94b5e3ff 2005-01-04 devnull [
 49 94b5e3ff 2005-01-04 devnull .I eq0
 50 94b5e3ff 2005-01-04 devnull .I eq1
 51 94b5e3ff 2005-01-04 devnull .I flag
 52 94b5e3ff 2005-01-04 devnull .I textlen
 53 94b5e3ff 2005-01-04 devnull .I text
 54 94b5e3ff 2005-01-04 devnull .I chordarg
 55 94b5e3ff 2005-01-04 devnull .I chordaddr
 56 94b5e3ff 2005-01-04 devnull ]
 57 94b5e3ff 2005-01-04 devnull .PP
 58 94b5e3ff 2005-01-04 devnull .B wineventloop
 59 94b5e3ff 2005-01-04 devnull .SH DESCRIPTION
 60 94b5e3ff 2005-01-04 devnull .I Acmeevent
 61 94b5e3ff 2005-01-04 devnull and
 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.
 66 94b5e3ff 2005-01-04 devnull .PP
 67 94b5e3ff 2005-01-04 devnull .I Acme
 68 94b5e3ff 2005-01-04 devnull clients read the
 69 94b5e3ff 2005-01-04 devnull .B event
 70 94b5e3ff 2005-01-04 devnull files 
 71 94b5e3ff 2005-01-04 devnull (see
 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.
 76 94b5e3ff 2005-01-04 devnull .PP
 77 94b5e3ff 2005-01-04 devnull .I Acmeevent
 78 94b5e3ff 2005-01-04 devnull reads an
 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:
 85 94b5e3ff 2005-01-04 devnull .IP
 86 94b5e3ff 2005-01-04 devnull .B event
 87 94b5e3ff 2005-01-04 devnull .I c1
 88 94b5e3ff 2005-01-04 devnull .I c2
 89 94b5e3ff 2005-01-04 devnull .I q0
 90 94b5e3ff 2005-01-04 devnull .I q1
 91 94b5e3ff 2005-01-04 devnull .I eq0
 92 94b5e3ff 2005-01-04 devnull .I eq1
 93 94b5e3ff 2005-01-04 devnull .I flag
 94 94b5e3ff 2005-01-04 devnull .I textlen
 95 94b5e3ff 2005-01-04 devnull .I text
 96 94b5e3ff 2005-01-04 devnull .I chordarg
 97 94b5e3ff 2005-01-04 devnull .I chordaddr
 98 94b5e3ff 2005-01-04 devnull .PP
 99 94b5e3ff 2005-01-04 devnull The fields are:
100 94b5e3ff 2005-01-04 devnull .TP
101 94b5e3ff 2005-01-04 devnull .I c1
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 ),
110 94b5e3ff 2005-01-04 devnull and
111 94b5e3ff 2005-01-04 devnull input via the mouse
112 94b5e3ff 2005-01-04 devnull .RB ( M ).
113 94b5e3ff 2005-01-04 devnull .TP
114 94b5e3ff 2005-01-04 devnull .I c2
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 ),
131 94b5e3ff 2005-01-04 devnull and 
132 94b5e3ff 2005-01-04 devnull a button 2 action in the tag
133 94b5e3ff 2005-01-04 devnull .RB ( x ).
134 94b5e3ff 2005-01-04 devnull .TP
135 94b5e3ff 2005-01-04 devnull .I q0
136 94b5e3ff 2005-01-04 devnull 
137 94b5e3ff 2005-01-04 devnull .TP
138 94b5e3ff 2005-01-04 devnull .I q1
139 94b5e3ff 2005-01-04 devnull 
140 94b5e3ff 2005-01-04 devnull .TP
141 94b5e3ff 2005-01-04 devnull .I eq0
142 94b5e3ff 2005-01-04 devnull 
143 94b5e3ff 2005-01-04 devnull .TP
144 94b5e3ff 2005-01-04 devnull .I eq1
145 94b5e3ff 2005-01-04 devnull 
146 94b5e3ff 2005-01-04 devnull .TP
147 94b5e3ff 2005-01-04 devnull .I flag
148 94b5e3ff 2005-01-04 devnull 
149 94b5e3ff 2005-01-04 devnull .TP
150 94b5e3ff 2005-01-04 devnull .I textlen
151 94b5e3ff 2005-01-04 devnull 
152 94b5e3ff 2005-01-04 devnull .TP
153 94b5e3ff 2005-01-04 devnull .I text
154 94b5e3ff 2005-01-04 devnull 
155 94b5e3ff 2005-01-04 devnull .TP
156 94b5e3ff 2005-01-04 devnull .I chordarg
157 94b5e3ff 2005-01-04 devnull 
158 94b5e3ff 2005-01-04 devnull .TP
159 94b5e3ff 2005-01-04 devnull .I chordorigin
160 94b5e3ff 2005-01-04 devnull 
161 94b5e3ff 2005-01-04 devnull .PP
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.
166 94b5e3ff 2005-01-04 devnull .PP
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.
174 94b5e3ff 2005-01-04 devnull .PP
175 94b5e3ff 2005-01-04 devnull .I Winread
176 94b5e3ff 2005-01-04 devnull prints the current window's
177 94b5e3ff 2005-01-04 devnull .I file
178 94b5e3ff 2005-01-04 devnull to standard output.
179 94b5e3ff 2005-01-04 devnull It is equivalent to
180 94b5e3ff 2005-01-04 devnull .B cat
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
188 94b5e3ff 2005-01-04 devnull and
189 94b5e3ff 2005-01-04 devnull .I winwrite
190 94b5e3ff 2005-01-04 devnull are useful mainly in building more complex functions.
191 94b5e3ff 2005-01-04 devnull .PP
192 94b5e3ff 2005-01-04 devnull .I Winctl
193 94b5e3ff 2005-01-04 devnull writes 
194 94b5e3ff 2005-01-04 devnull .I cmd
195 94b5e3ff 2005-01-04 devnull to the window's
196 94b5e3ff 2005-01-04 devnull .B ctl
197 94b5e3ff 2005-01-04 devnull file.
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.
201 94b5e3ff 2005-01-04 devnull See
202 94b5e3ff 2005-01-04 devnull .IR acme (4)
203 94b5e3ff 2005-01-04 devnull for a full list of commands.
204 94b5e3ff 2005-01-04 devnull .PP
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
208 94b5e3ff 2005-01-04 devnull (see
209 94b5e3ff 2005-01-04 devnull .IR acme (4)).
210 94b5e3ff 2005-01-04 devnull If either argument is omitted or is
211 94b5e3ff 2005-01-04 devnull .BR - ,
212 94b5e3ff 2005-01-04 devnull that argument is not set.
213 94b5e3ff 2005-01-04 devnull .PP
214 94b5e3ff 2005-01-04 devnull .I Winname
215 94b5e3ff 2005-01-04 devnull sets the name displayed in the window's tag.
216 94b5e3ff 2005-01-04 devnull .PP
217 94b5e3ff 2005-01-04 devnull .I Windel
218 94b5e3ff 2005-01-04 devnull simulates the
219 94b5e3ff 2005-01-04 devnull .B Del
220 94b5e3ff 2005-01-04 devnull command.  If the argument
221 94b5e3ff 2005-01-04 devnull .B sure
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.
225 94b5e3ff 2005-01-04 devnull .PP
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
235 94b5e3ff 2005-01-04 devnull back to
236 94b5e3ff 2005-01-04 devnull .I acme
237 94b5e3ff 2005-01-04 devnull for processing.
238 94b5e3ff 2005-01-04 devnull .PP
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,
248 94b5e3ff 2005-01-04 devnull as
249 94b5e3ff 2005-01-04 devnull .I rc
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 
254 94b5e3ff 2005-01-04 devnull .I acme
255 94b5e3ff 2005-01-04 devnull with
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
262 94b5e3ff 2005-01-04 devnull and
263 94b5e3ff 2005-01-04 devnull .IR acme.rc .
264 94b5e3ff 2005-01-04 devnull The
265 94b5e3ff 2005-01-04 devnull .I event
266 94b5e3ff 2005-01-04 devnull handler is:
267 94b5e3ff 2005-01-04 devnull .IP
268 94b5e3ff 2005-01-04 devnull .EX
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
275 94b5e3ff 2005-01-04 devnull 		{
276 94b5e3ff 2005-01-04 devnull 			if(~ $dict NONE)
277 94b5e3ff 2005-01-04 devnull 				dictwin /adict/$7/ $7
278 94b5e3ff 2005-01-04 devnull 			if not
279 94b5e3ff 2005-01-04 devnull 				dictwin /adict/$dict/$7 $dict $7
280 94b5e3ff 2005-01-04 devnull 		} &
281 94b5e3ff 2005-01-04 devnull 	}
282 94b5e3ff 2005-01-04 devnull }
283 94b5e3ff 2005-01-04 devnull .EE
284 94b5e3ff 2005-01-04 devnull .LP
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:
290 94b5e3ff 2005-01-04 devnull .IP
291 94b5e3ff 2005-01-04 devnull .EX
292 94b5e3ff 2005-01-04 devnull fn dictwin {
293 94b5e3ff 2005-01-04 devnull 	newwindow
294 94b5e3ff 2005-01-04 devnull 	winname $1
295 94b5e3ff 2005-01-04 devnull 	dict=$2
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
302 94b5e3ff 2005-01-04 devnull }
303 94b5e3ff 2005-01-04 devnull .EE
304 94b5e3ff 2005-01-04 devnull .LP
305 94b5e3ff 2005-01-04 devnull The script starts with an initial window:
306 94b5e3ff 2005-01-04 devnull .IP
307 94b5e3ff 2005-01-04 devnull .EX
308 94b5e3ff 2005-01-04 devnull dictwin /adict/ NONE
309 94b5e3ff 2005-01-04 devnull .EE
310 94b5e3ff 2005-01-04 devnull .LP
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.
315 94b5e3ff 2005-01-04 devnull .PP
316 94b5e3ff 2005-01-04 devnull See
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
321 94b5e3ff 2005-01-04 devnull .br
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.