1 |
COMMENT(-- $Id: rxvtRef-menubar.yo,v 1.1 2003/11/18 14:22:16 root Exp $ --) |
2 |
label(menuBar) |
3 |
nsect(menuBar) |
4 |
|
5 |
bf(The exact syntax used is em(almost) solidified.) nl()\ |
6 |
In the menus, bf(DON'T) try to use menuBar commands that add or remove a |
7 |
menuBar. |
8 |
|
9 |
Note that in all of the commands, the bf(em(/path/)) em(cannot) be omitted: |
10 |
use bf(./) to specify a menu relative to the current menu. |
11 |
|
12 |
nsubsect(Overview of menuBar operation) |
13 |
|
14 |
For the menuBar XTerm escape sequence tt(ESC ] 10 ; Pt ST), the |
15 |
syntax of tt(Pt) can be used for a variety of tasks: |
16 |
startit() |
17 |
it()link(Commands)(menuBarCommands) |
18 |
it()link(Adding and accessing menus)(menuBarAdd) |
19 |
it()link(Removing menus)(menuBarRemove) |
20 |
it()link(Quick Arrows)(menuBarArrows) |
21 |
it()link(Command Summary)(menuBarSummary) |
22 |
endit() |
23 |
|
24 |
At the top level is the current menuBar which is a member of a circular |
25 |
linked-list of other such menuBars. |
26 |
|
27 |
The menuBar acts as a parent for the various drop-down menus, which in turn, |
28 |
may have labels, separator lines, menuItems and subMenus. |
29 |
|
30 |
The menuItems are the useful bits: you can use them to mimic keyboard input |
31 |
or even to send text or escape sequences back to rxvt. |
32 |
|
33 |
The menuBar syntax is intended to provide a simple yet robust method of |
34 |
constructing and manipulating menus and navigating through the menuBars. |
35 |
|
36 |
The first step is to use the tag bf([menu:em(name)]) which creates the |
37 |
menuBar called em(name) and allows access. |
38 |
You may now link(add)(menuBarAdd) or link(remove)(menuBarRemove) menus, |
39 |
subMenus, and menuItems. Finally, use the tag bf([done]) to set the menuBar |
40 |
access as bf(readonly) to prevent accidental corruption of the menus. |
41 |
To re-access the current menuBar for alterations, use the tag bf([menu]), |
42 |
make the alterations and then use bf([done]) |
43 |
|
44 |
label(menuBarCommands) |
45 |
nsubsect(Commands) |
46 |
|
47 |
startdl() |
48 |
dl(bf([menu:+em(name)])) |
49 |
(access the named menuBar for creation or alteration. If a new menuBar |
50 |
is created, it is called em(name) (max of 15 chars) and the current |
51 |
menuBar is pushed onto the stack) |
52 |
P()\ |
53 |
dl(bf([menu])) |
54 |
(access the current menuBar for alteration) |
55 |
P()\ |
56 |
dl(bf([title:+em(string)])) |
57 |
(set the current menuBar's title to em(string), which may contain the |
58 |
following format specifiers: nl()\ |
59 |
bf(%%) : literal bf(%) character nl()\ |
60 |
bf(%n) : rxvt name (as per the bf(-name) command-line option) nl()\ |
61 |
bf(%v) : rxvt version) |
62 |
P()\ |
63 |
dl(bf([done])) |
64 |
(set menuBar access as bf(readonly). nl()\ |
65 |
End-of-file tag for bf([read:+em(file)]) operations.) |
66 |
P()\ |
67 |
dl(bf([read:+em(file)])) |
68 |
(read menu commands directly from em(file) (extension ".menu" will be |
69 |
appended if required.) Start reading at a line with bf([menu]) or |
70 |
bf([menu:+em(name)) and continuing until bf([done]) is encountered. |
71 |
|
72 |
Blank and comment lines (starting with bf(#)) are ignored. |
73 |
Actually, since any invalid menu commands are also ignored, almost |
74 |
anything could be construed as a comment line, but this may be |
75 |
tightened up in the future ... so don't count on it!.) |
76 |
P()\ |
77 |
dl(bf([read:+em(file);+em(name)])) |
78 |
(The same as bf([read:+em(file)]), but start reading at a line with |
79 |
bf([menu:+em(name)]) and continuing until bf([done:+em(name)]) or |
80 |
bf([done]) is encountered.) |
81 |
P()\ |
82 |
dl(bf([dump])) |
83 |
(dump all menuBars to the file bf(/tmp/rxvt-PID) in a format suitable |
84 |
for later rereading.) |
85 |
P()\ |
86 |
dl(bf([rm:name]nl()[rm] [rm:]nl()[rm*] [rm:*])) |
87 |
(remove the named menuBar nl()\ |
88 |
remove the current menuBar nl()\ |
89 |
remove all menuBars) |
90 |
P()\ |
91 |
dl(bf([swap])) |
92 |
(swap the top two menuBars) |
93 |
P()\ |
94 |
dl(bf([prev]nl()[next])) |
95 |
(access the previous or next menuBar) |
96 |
P()\ |
97 |
dl(bf([show]nl()[hide])) |
98 |
(control display of the menuBar ... just like |
99 |
link(ESC[?10 h/l)(Priv10)) |
100 |
P()\ |
101 |
dl(bf([pixmap:+em(name)]nl()[pixmap:+em(name);em(scaling)])) |
102 |
(set the background pixmap globally ... just like |
103 |
link(ESC ] 20 ; Pt ST)(XPM) |
104 |
|
105 |
bf(A Future implementation em(may) make this local to the menubar)) |
106 |
P()\ |
107 |
dl(bf([:+em(command):])) |
108 |
(ignore the menu readonly status and issue a em(command) to |
109 |
link(Add/Modify)(menuBarAdd) or link(Remove)(menuBarRemove) a menu or |
110 |
menuitem or change the link(Quick Arrows)(menuBarArrows); a useful |
111 |
shortcut for setting the quick arrows from a menuBar.) |
112 |
enddl() |
113 |
|
114 |
label(menuBarAdd) |
115 |
nsubsect(Adding and accessing menus) |
116 |
|
117 |
The following commands may also be bf(+) prefixed. |
118 |
startdl() |
119 |
dl(bf(/+nl()./+nl()../+nl()../../)) |
120 |
(access menuBar top level nl()\ |
121 |
access current menu level nl()\ |
122 |
access parent menu (1 level up) nl()\ |
123 |
access parent menu (multiple levels up)) |
124 |
dl(bf(em(/path/)menu)) |
125 |
(add/access menu) |
126 |
dl(bf(em(/path/)menu/*)) |
127 |
(add/access menu and clear it if it exists) |
128 |
dl(bf(em(/path/){-})) |
129 |
(add separator) |
130 |
dl(bf(em(/path/){item})) |
131 |
(add bf(item) as a label) |
132 |
dl(bf(em(/path/){item} action)) |
133 |
(add/alter em(menuitem) with an associated em(action)) |
134 |
dl(bf(em(/path/){item}{right-text})) |
135 |
(add/alter em(menuitem) with bf(right-text) as the right-justified |
136 |
text and as the associated em(action)) |
137 |
dl(bf(em(/path/){item}{rtext} action)) |
138 |
(add/alter em(menuitem) with an associated em(action) and with |
139 |
bf(rtext) as the right-justified text.) |
140 |
enddl() |
141 |
startdl() |
142 |
dl(Special characters in em(action) must be backslash-escaped:) |
143 |
(bf(\a \b \E \e \n \r \t \octal)) |
144 |
dl(or in control-character notation:) |
145 |
(bf(^@, ^A .. ^Z .. ^_, ^?)) |
146 |
enddl() |
147 |
|
148 |
To send a string starting with a bf(NUL) (bf(^@)) character to the program, |
149 |
start em(action) with a pair of bf(NUL) characters (bf(^@^@)), the first of |
150 |
which will be stripped off and the balance directed to the program. |
151 |
Otherwise if em(action) begins with bf(NUL) followed by non-+bf(NUL) |
152 |
characters, the leading bf(NUL) is stripped off and the balance is sent back |
153 |
to rxvt. |
154 |
|
155 |
As a convenience for the many Emacs-type editors, em(action) may start |
156 |
with bf(M-) (eg, bf(M-$) is equivalent to bf(\E$)) and a bf(CR) will be |
157 |
appended if missed from bf(M-x) commands. |
158 |
|
159 |
As a convenience for issuing XTerm bf(ESC]) sequences from a menubar |
160 |
(or quick arrow), a bf(BEL) (bf(^G)) will be appended if needed. |
161 |
|
162 |
startdl() |
163 |
dl(For example,) |
164 |
(bf(M-xapropos) is equivalent to bf(\Exapropos\r)) |
165 |
dl(and) |
166 |
(bf(\E]10;mona;100) is equivalent to bf(\E]10;mona;100\a)) |
167 |
enddl() |
168 |
|
169 |
The option bf({em(right-rtext)}) will be right-justified. In the absence of |
170 |
a specified action, this text will be used as the em(action) as well. |
171 |
|
172 |
startdl() |
173 |
dl(For example,) |
174 |
(bf(/File/{Open}{^X^F}) is equivalent to bf(/File/{Open}{^X^F} ^X^F)) |
175 |
enddl() |
176 |
|
177 |
The left label em(is) necessary, since it's used for matching, |
178 |
but implicitly hiding the left label (by using same name for both left |
179 |
and right labels), or explicitly hiding the left label (by preceeding |
180 |
it with a dot), makes it possible to have right-justified text only. |
181 |
startdl() |
182 |
dl(For example,) |
183 |
(bf(/File/{Open}{Open} Open-File-Action)) |
184 |
dl(or hiding it) |
185 |
(bf(/File/{.anylabel}{Open} Open-File-Action)) |
186 |
enddl() |
187 |
|
188 |
label(menuBarRemove) |
189 |
nsubsect(Removing menus) |
190 |
|
191 |
startdl() |
192 |
dl(bf(-/*+nl()-+em(/path)menu+nl()-+em(/path){item}+nl()-+em(/path){-})) |
193 |
(remove all menus from the menuBar, the same as bf([clear])nl()\ |
194 |
remove menu nl()\ |
195 |
remove item nl()\ |
196 |
remove separator) |
197 |
dl(bf(-/path/menu/*)) |
198 |
(remove all items, separators and submenus from menu) |
199 |
enddl() |
200 |
|
201 |
label(menuBarArrows) |
202 |
nsubsect(Quick Arrows) |
203 |
|
204 |
The menus also provide a hook for em(quick arrows) to provide easier user |
205 |
access. If nothing has been explicitly set, the default is to emulate the |
206 |
curror keys. The syntax permits each arrow to be altered individually or |
207 |
all four at once without re-entering their common beginning/end text. For |
208 |
example, to explicitly associate cursor actions with the arrows, any of |
209 |
the following forms could be used: |
210 |
|
211 |
startdl() |
212 |
dl(bf(<r>+em(Right)nl()<l>+em(Left)nl()<u>+em(Up)nl()<d>+em(Down))) |
213 |
(Define actions for the respective arrow buttons) |
214 |
dl(bf(<b>+em(Begin)nl()<e>+em(End))) |
215 |
(Define common beginning/end parts for em(quick arrows) which used |
216 |
in conjunction with the above <r> <l> <u> <d> constructs) |
217 |
enddl() |
218 |
|
219 |
startdl() |
220 |
dl(For example, define arrows individually,) |
221 |
(bf(<u>\E[A nl()\ |
222 |
<d>\E[B nl()\ |
223 |
<r>\E[C nl()\ |
224 |
<l>\E[D)) |
225 |
dl(or all at once) |
226 |
(bf(<u>\E[A<d>\E[B<r>\E[C<l>\E[D)) |
227 |
dl(or more compactly (factoring out common parts)) |
228 |
(bf(<b>\E[<u>A<d>B<r>C<l>D)) |
229 |
enddl() |
230 |
|
231 |
label(menuBarSummary) |
232 |
nsubsect(Command Summary) |
233 |
|
234 |
A short summary of the most em(common) commands: |
235 |
|
236 |
startdl() |
237 |
dl([menu:name]) |
238 |
(use an existing named menuBar or start a new one) |
239 |
dl([menu]) |
240 |
(use the current menuBar) |
241 |
dl([title:string]) |
242 |
(set menuBar title) |
243 |
dl([done]) |
244 |
(set menu access to readonly and, if reading from a file, signal EOF) |
245 |
dl([done:name]) |
246 |
(if reading from a file using [read:file;name] signal EOF) |
247 |
dl([rm:name]+nl()[rm] [rm:]+nl()[rm*] [rm:*]) |
248 |
(remove named, current, or all menuBar(s)) |
249 |
dl([swap]) |
250 |
(swap top two menuBars) |
251 |
dl([prev]+nl()[next]) |
252 |
(access the previous/next menuBar) |
253 |
dl([show]+nl()[hide]) |
254 |
(map/unmap menuBar) |
255 |
dl([pixmap;file]+nl()[pixmap;file;scaling]) |
256 |
(set a background pixmap) |
257 |
dl([read:file]+nl()[read:file;name]) |
258 |
(read in a menu from a file) |
259 |
dl([dump]) |
260 |
(dump out all menuBars to /tmp/rxvt-PID) |
261 |
dl(/) |
262 |
(access menuBar top level) |
263 |
dl(./+nl()../+nl()../../) |
264 |
(access current or parent menu level) |
265 |
dl(/path/menu) |
266 |
(add/access menu) |
267 |
dl(/path/{-}) |
268 |
(add separator) |
269 |
dl(/path/{item}{rtext} action) |
270 |
(add/alter menu item+nl()({rtext} and/or action, may be omitted)) |
271 |
dl(-/*) |
272 |
(remove all menus from the menuBar) |
273 |
dl(-/path/menu) |
274 |
(remove menu items, separators and submenus from menu) |
275 |
dl(-/path/menu) |
276 |
(remove menu) |
277 |
dl(-/path/{item}) |
278 |
(remove item) |
279 |
dl(-/path/{-}) |
280 |
(remove separator) |
281 |
dl(<b>Begin<r>Right<l>Left<u>Up<d>Down<e>End) |
282 |
(menu quick arrows) |
283 |
enddl() |