From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man1/acmeevent.html | 332 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 332 insertions(+) create mode 100644 man/man1/acmeevent.html (limited to 'man/man1/acmeevent.html') diff --git a/man/man1/acmeevent.html b/man/man1/acmeevent.html new file mode 100644 index 00000000..230145ce --- /dev/null +++ b/man/man1/acmeevent.html @@ -0,0 +1,332 @@ + +acmeevent(1) - Plan 9 from User Space + + + + +
+
+
ACMEEVENT(1)ACMEEVENT(1) +
+
+

NAME
+ +
+ + acmeevent, acme.rc – shell script support for acme clients
+ +
+

SYNOPSIS
+ +
+ + 9p read acme/acme/$winid/event | acmeevent +
+ + . /usr/local/plan9/lib/acme.rc +
+ + newwindow +
+ + winread file +
+ + winwrite file +
+ + winctl cmd +
+ + windump [ dumpdir | − ] [ dumpcmd | − ] +
+ + winname name +
+ + windel [ sure ] +
+ + winwriteevent c1 c2 q0 q1 [ eq0 eq1 flag textlen text chordarg + chordaddr ] +
+ + wineventloop
+ +
+

DESCRIPTION
+ +
+ + Acmeevent and acme.rc make it easy to write simple acme(1) client + programs as shell scripts. +
+ + Acme clients read the event files (see acme(4)) for the windows + they control, reacting to the events. The events are presented + in a format that is easy to read with C programs but hard to read + with shell scripts. +
+ + Acmeevent reads an acme(4) event stream from standard input, printing + a shell-friendly version of the events, one per line, on standard + output. Each output line from acmeevent has the form:
+ +
+ + event c1 c2 q0 q1 eq0 eq1 flag textlen text chordarg chordaddr + +
+ + +
+ The fields are:
+ c1    A character indicating the origin or cause of the action. The + possible causes are: a write to the body or tag file (E), a write + to the window’s other files (F), input via the keyboard (K), and + input via the mouse (M).
+ c2    A character indicating the type of action. The possible types + are: text deleted from the body (D), text deleted from the tag + (d), text inserted in the body (I), text inserted in the tag (i), + a button 3 action in the body (L), a button 3 action in the tag + (l), a button 2 action in the body (X), and a button 2 action + in the + +
+ + tag (x).
+ +
+ q0, q1The character addresses of the action.
+ eq0, q1
+ +
+ + The expanded character addresses of the action. If the text indicated + by q0, q1 is a null string that has a non-null expansion, eq0, + eq1 are the addresses of the expansion. Otherwise they are the + same as q0, q1.
+ +
+ flag   Flag is a bitwise OR (reported decimally) of the following: + 1 if the text indicated is recognized as an acme built-in command; + 2 if the text indicated is a null string that has a non-null expansion + (see eq0, eq1 above); 8 if the command has an extra (chorded) + argument (see chordarg below). Flag remains from the + +
+ + acme(4) event format. Because eq0, eq1, and chordarg are explicit + in each event (unlike in acme(4) events), flag can usually be + ignored.
+ +
+ textlen
+ +
+ + The length of the action text (or its expansion) for button 2 + and button 3 events in characters.
+ +
+ text   If textlen is less than 256 chracters, text is the action + text itself. Otherwise it is an empty string and must be read + from the data file.
+ chordarg
+ +
+ + The chorded argument for an action.
+ +
+ chordorigin
+ +
+ + If the chord argument is in the body of a named window, chordorigin + specifies the full address of the argument, as in /etc/group:#123,#234. + +
+ + +
+ To experiment with acmeevent, create an empty window in acme (using + New),type
+ +
+ + 9p read acme/$winid/event | acmeevent
+ +
+ + +
+ inside it, and execute it. Actions performed on the window will + be printed as events in the +Errors window. +
+ + Acme.rc is a library of rc(1) shell functions useful for writing + acme clients. +
+ + Newwindow creates a new acme window and sets $winid to the new + window’s id. The other commands all use $winid to determine which + window to operate on. +
+ + Winread prints the current window’s file to standard output. It + is equivalent to cat /mnt/acme/acme/$winid/file on Plan 9. Similarly, + winwrite writes standard input to the current window’s file. Winread + and winwrite are useful mainly in building more complex functions. + +
+ + Winctl writes cmd to the window’s ctl file. The most commonly-used + command is clean, which marks the window as clean. See acme(4) + for a full list of commands. +
+ + Windump sets the window’s dump directory and dump command (see + acme(4)). If either argument is omitted or is −, that argument + is not set. +
+ + Winname sets the name displayed in the window’s tag. +
+ + Windel simulates the Del command. If the argument sure is given, + it simulates the Delete command. +
+ + Winwriteevent writes an event to the window’s event file. The + event is in the format produced by acmeevent. Only the first four + arguments are necessary: the rest are ignored. Event handlers + should call winwriteevent to pass unhandled button 2 or button + 3 events back to acme for processing. +
+ + Wineventloop executes the current window’s event file, as output + by acmeevent. It returns when the window has been deleted. Before + running wineventloop , clients must define a shell function named + event, which will be run for each incoming event, as rc executes + the output of acmeevent. A typical event function + need only worry about button 2 and button 3 events. Those events + not handled should be sent back to acme with winwriteevent.
+ +
+

EXAMPLE
+ +
+ + Adict, a dictionary browser, is implemented using acmeevent and + acme.rc. The event handler is:
+ +
+ + fn event {
+ +
+ + switch($1$2){
+ case Mx MX      # button 2 − pass back to acme
+ winwriteevent $*
+ case Ml ML      # button 3 − open new window on dictionary or entry
+ {
+ if(~ $dict NONE)
+ dictwin /adict/$7/ $7
+ if not
+ dictwin /adict/$dict/$7 $dict $7
+ } &
+ }
+ +
+ }
+ +
+ + +
+ Note that the button 3 handler starts a subshell in which to run + dictwin. That subshell will create a new window, set its name, + possibly fill the window with a dictionary list or dictionary + entry, mark the window as clean, and run the event loop:
+ +
+ + fn dictwin {
+ +
+ + newwindow
+ winname $1
+ dict=$2
+ if(~ $dict NONE)
+ dict −d '?' >[2=1] | sed 1d | winwrite body
+ if(~ $#* 3)
+ dict −d $dict $3 >[2=1] | winwrite body
+ winctl clean
+ wineventloop
+ +
+ }
+ +
+ + +
+ The script starts with an initial window:
+ +
+ + dictwin /adict/ NONE
+ +
+ + +
+ Button 3 clicking on a dictionary name in the initial window will + create a new empty window for that dictionary. Typing and button + 3 clicking on a word in that window will create a new window with + the dictionary’s entry for that word. +
+ + See /usr/local/plan9/bin/adict for the full implementation.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/acmeevent.c
+ /usr/local/plan9/lib/acme.rc
+ +
+

SEE ALSO
+ +
+ + acme(1), acme(4), rc(1)
+ +
+

BUGS
+ +
+ + There is more that could be done to ease the writing of complicated + clients.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + -- cgit v1.2.3