| 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() |
