| 1 |
pcg |
1.4 |
COMMENT(-- $Id: rxvtRef-menubar.yo,v 1.3 2004/04/02 00:51:09 pcg Exp $ --) |
| 2 |
pcg |
1.1 |
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 |
pcg |
1.3 |
For the menuBar XTerm escape sequence tt(ESC ] 703 ; Pt ST), the |
| 15 |
pcg |
1.1 |
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 |
pcg |
1.4 |
link(ESC[ ? 10 h/l)(Priv10)) |
| 100 |
pcg |
1.1 |
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 |
pcg |
1.3 |
(bf(\E]703;mona;100) is equivalent to bf(\E]703;mona;100\a)) |
| 167 |
pcg |
1.1 |
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() |
