3 acmeevent, acme.rc \- shell script support for acme clients
7 .B acme/acme/$winid/event | acmeevent
63 make it easy to write simple
65 client programs as shell scripts.
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.
80 event stream from standard input, printing a shell-friendly
81 version of the events, one per line, on standard output.
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
106 a write to the window's other files
108 input via the keyboard
115 A character indicating the type of action.
116 The possible types are:
117 text deleted from the body
119 text deleted from the tag
121 text inserted in the body
123 text inserted in the tag
125 a button 3 action in the body
127 a button 3 action in the tag
129 a button 2 action in the body
132 a button 2 action in the tag
136 The character addresses of the action.
139 The expanded character addresses of the action.
140 If the text indicated by
143 is a null string that has a non-null expansion,
146 are the addresses of the expansion.
147 Otherwise they are the same as
153 is a bitwise OR (reported decimally) of the following:
154 1 if the text indicated is recognized as an
157 2 if the text indicated is a null string that has a non-null expansion
162 8 if the command has an extra (chorded) argument
175 are explicit in each event
180 can usually be ignored.
183 The length of the action text (or its expansion) for button 2 and button 3 events in characters.
188 is less than 256 chracters,
190 is the action text itself.
191 Otherwise it is an empty string and must be read from the
196 The chorded argument for an action.
199 If the chord argument is in the body of a named window,
201 specifies the full address of the argument,
203 .BR /etc/group:#123,#234 .
208 create an empty window in
214 9p read acme/$winid/event | acmeevent
217 inside it, and execute it.
218 Actions performed on the window will be printed as events in the
225 shell functions useful for writing acme clients.
228 creates a new acme window and sets
230 to the new window's id.
231 The other commands all use
233 to determine which window to operate on.
236 prints the current window's
241 .BI /mnt/acme/acme/$winid/ file
245 writes standard input to the current window's
250 are useful mainly in building more complex functions.
258 The most commonly-used command is
260 which marks the window as clean.
263 for a full list of commands.
266 sets the window's dump directory
270 If either argument is omitted or is
272 that argument is not set.
275 sets the name displayed in the window's tag.
280 command. If the argument
282 is given, it simulates the
287 writes an event to the window's event file.
288 The event is in the format produced by
290 Only the first four arguments are necessary:
291 the rest are ignored.
292 Event handlers should call
294 to pass unhandled button 2 or button 3 events
300 executes the current window's event file, as output by
302 It returns when the window has been deleted.
305 clients must define a shell function named
307 which will be run for each incoming event,
310 executes the output of
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
319 a dictionary browser,
329 .ta +4n +4n +4n +4n +4n +4n
332 case Mx MX # button 2 - pass back to acme
334 case Ml ML # button 3 - open new window on dictionary or entry
337 dictwin /adict/$7/ $7
339 dictwin /adict/$dict/$7 $dict $7
345 Note that the button 3 handler starts a subshell in which to run
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:
357 dict -d '?' >[2=1] | sed 1d | winwrite body
359 dict -d $dict $3 >[2=1] | winwrite body
365 The script starts with an initial window:
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.
378 for the full implementation.
380 .B \*9/src/cmd/acmeevent.c
388 There is more that could be done to ease the writing
389 of complicated clients.