doc/yodl/rxvtRef-menubar.yo

   1 COMMENT(-- $Id: rxvtRef-menubar.yo,v 1.4 2004-04-24 05:52:44 pcg 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 ] 703 ; 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]703;mona;100) is equivalent to bf(\E]703;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()