data/README.menu

   1 -- data/README.menu for Blackbox - an X11 Window manager
   2
   3 Creating a user defined menu:
   4 -----------------------------
   5
   6 Creating a menu for Blackbox requires a text editor of some sort.
   7 Familiarity with your choice of text editor is assumed, since editor
   8 preference differs as much (if not more than) window manager
   9 preference.
  10
  11 First, we need to decide on a location for our custom menu.  Your home
  12 directory is the most logical solution, since you will most likely not
  13 have write access anywhere else.  You place the menu file in any
  14 directory, and give it any name you choose, as we will later tell
  15 Blackbox the path or location for this file.
  16
  17 As an example, let's assume that my home directory is
  18 `/usr/home/bhughes' (which it is).  I've decided to keep all my
  19 Blackbox related files in a directory named `.blackbox/'.  After
  20 creating the directory, I now have two options for creating my new
  21 menu.  I can either copy the system default (usually in
  22 `/usr/local/share/blackbox/menu') to this directory, or I can create a
  23 new one from scratch.  Let's do the latter, for the sake of
  24 completeness.
  25
  26 I've decided to name the file `rootmenu.'  I fire up my favorite text
  27 editor and now have a clean file.  So let's begin.
  28
  29
  30 Menu syntax:
  31 ------------
  32
  33 The menu syntax is very simple and very effective.  There are up to
  34 three fields in a menu line. They are of the form:
  35
  36     [tag] (label or filename) {command or filename}
  37
  38 The supported tags are as follows:
  39
  40 [begin] (label for root menu)
  41
  42     This tells Blackbox to start parsing the menu file.  This tag
  43     is required for Blackbox to parse your menu file.  If it
  44     cannot find it, the system default menu is used instead.
  45
  46 [end]
  47
  48     This tells Blackbox that it is at the end of a menu.  This can
  49     either be a submenu or the main root menu.  There must be at
  50     least one of these tags in your menu to correspond to the
  51     required [begin] tag.
  52
  53 [exec] (label for command) {shell command}
  54
  55     This tells Blackbox to insert a command item into the menu.
  56     When you select the menu item from the menu, Blackbox runs
  57     `shell command.'
  58
  59 [exit] (label for exit)
  60
  61     This tells Blackbox to insert an item that shuts down and
  62     exits Blackbox.  Any open applications are left running.
  63
  64 [include] (filename)
  65
  66     This tells Blackbox to parse the file specified by `filename'
  67     inline with the current menu.  `filename' can be the full path
  68     to a file (such as
  69     /usr/local/share/blackbox/brueghel/stylesmenu) or it can begin
  70     with `~/', which will be expanded into your home directory
  71     (e.g. [include] (~/.blackbox/stylesmenu) will include
  72     /usr/home/bhughes/blackbox/stylesmenu in my menu).
  73
  74 [nop] (label - optional)
  75
  76     This tells Blackbox to insert a non-operational item into the
  77     current menu.  This can be used to help format the menu into
  78     blocks or sections if so desired (e.g. you could put all your
  79     ssh accounts together, add a [nop] and then add all your
  80     telnet accounts together).  [nop] does accept a label, but it
  81     is not required, and a blank item will be used if none is
  82     supplied.
  83
  84 [sep]
  85
  86     Inserts a horizontal separator.  This can be used similar to
  87     [nop] to format and organize your menus.
  88
  89 [style] (label) {filename}
  90
  91     This tells Blackbox to read `filename' and apply the new
  92     textures, colors and fonts to the current running session.
  93     The filename is just like the [include] tag, it can be the
  94     full path to the file, or it can be of the form
  95     `~/path/from/home/dir.'  Blackbox also re-reads the entire
  96     menu structure from disk, in case the menu has changed.
  97
  98 [submenu] (label) {title for menu - optional}
  99
 100     This tells Blackbox to create and parse a new menu.  This menu
 101     is inserted as a submenu into the parent menu.  These menus
 102     are parsed recursively, so there is no limit to the number of
 103     levels or nested submenus you can have.  The title for the new
 104     menu is optional, if none is supplied, the new menu's title is
 105     the same as the item label.
 106
 107 [reconfig] (label)
 108
 109     This tells Blackbox to reread the current style and menu files
 110     and apply any changes.  This is useful for creating a new
 111     style or theme, as you don't have to constantly restart
 112     Blackbox every time you save your style.
 113
 114 [restart] (label) {shell command - optional}
 115
 116     This tells Blackbox to restart.  If `shell command' is
 117     supplied, it shuts down and runs the command (which is
 118     commonly the name of another window manager).  If the command
 119     is omitted, Blackbox restarts itself.
 120
 121 [workspaces] (label)
 122
 123     This tells Blackbox to insert a "link" to the workspaces menu
 124     directly into your menu.  This is handy for those users who
 125     can't access the workspace menu directly (e.g. if you don't
 126     have a 3 button mouse, it's rather hard to middle click to
 127     show the workspace menu).  This is a "link" to the systems
 128     workspace menu, so multiple [workspaces] tags will display the
 129     same workspace menu, so expect it to move around if you do
 130     so. ;)
 131
 132 [config] (label)
 133
 134     This tells Blackbox to insert the ConfigMenu into your menu.
 135     From this menu you can configure several options stored in
 136     your ~/.blackboxrc, and the changes take effect immediately.
 137
 138 Comments may be inserted on any line of the file, as long as the first
 139 character on the line is a `#.'
 140
 141 Also, in the labels/commands/filenames fields, you can escape any
 142 character like so:
 143
 144     [exec] (\(my cool\) \{XTERM\}) {\(xterm -T \\\"cool XTERM\\\"\)}
 145
 146 Using `\\' inserts a literal back-slash into the
 147 label/command/filename field.
 148
 149
 150 Putting it all together:
 151 ------------------------
 152
 153 So let's see if we can understand the arcane incantation above.  It
 154 says we have to have a [begin] and an [end] tag, which create our menu
 155 and give it a title.  Let's do that first:
 156
 157     [begin] (Example \[Menu\])
 158
 159     [end]
 160
 161 Simple enough. Now let's add some items to the list.  We always want
 162 to have access to a terminal emulator, be it a regular xterm or
 163 something else.  So we add the item to our menu, and it now looks like
 164 this:
 165
 166     [begin] (Example \[Menu\])
 167     [exec] (xterm) {xterm -ls}
 168     [end]
 169
 170 Great!  Now let's add us some items to run an irc client, a web
 171 browser and some other common programs.  This gives up this:
 172
 173     [begin] (Example \[Menu\])
 174     [exec] (xterm) {xterm -ls}
 175     [exec] (openprojects irc) {xterm -e irc fnord irc.openprojects.net}
 176     [exec] (Mozilla Navigator) {mozilla}
 177     [exec] (XEmacs) {xemacs}
 178     [exec] (The GIMP) {gimp}
 179     [exec] (Video Tune) {xvidtune}
 180     [end]
 181
 182 Whoa, wait a second.  This menu file is beginning to look a little
 183 cluttered.  Not a problem, just like programmers indent and space
 184 their code, we can do this with our menu file, so let's clean it up a
 185 bit:
 186
 187     [begin] (Example \[Menu\])
 188         [exec] (xterm) {xterm -ls}
 189         [exec] (openprojects irc) {xterm -e irc fnord irc.openprojects.net}
 190
 191         [exec] (Mozilla Navigator) {mozilla}
 192         [exec] (XEmacs) {xemacs}
 193
 194         [exec] (The GIMP) {gimp}
 195
 196         [exec] (Video Tune) {xvidtune}
 197     [end]
 198
 199 Ahh... now that looks a little better.  Now we decide that we kind of
 200 like the spacing in the file, and decide we want to apply it to the
 201 menu itself.  Now we take advantage of the [sep] tag:
 202
 203     [begin] (Example \[Menu\])
 204         [exec] (xterm) {xterm -ls}
 205         [exec] (openprojects irc) {xterm -e irc fnord irc.openprojects.net}
 206
 207         [sep]
 208
 209         [exec] (Mozilla Navigator) {mozilla}
 210         [exec] (XEmacs) {xemacs}
 211
 212         [sep]
 213
 214         [exec] (The GIMP) {gimp}
 215
 216         [sep]
 217
 218         [exec] (Video Tune) {xvidtune}
 219     [end]
 220
 221 Now, let's create a submenu to put some items to change between all
 222 these themes we downloaded from http://themes.freshmeat.net/.  Let's
 223 assume we untarred the themes into the ~/.blackbox directory like the
 224 documentation recommends.
 225
 226     [begin] (Example \[Menu\])
 227         [exec] (xterm) {xterm -ls}
 228         [exec] (openprojects irc) {xterm -e irc fnord irc.openprojects.net}
 229
 230         [sep]
 231
 232         [exec] (Mozilla Navigator) {mozilla}
 233         [exec] (XEmacs) {xemacs}
 234
 235         [sep]
 236
 237         [exec] (The GIMP) {gimp}
 238
 239         [sep]
 240
 241         [exec] (Video Tune) {xvidtune}
 242
 243         [submenu] (Themes) {Themes from themes.freshmeat.net}
 244             [style] (Blackbox) {~/.blackbox/styles/blackbox}
 245             [style] (Blackbox II) {~/.blackbox/styles/blackbox2}
 246             [style] (Hardware) {~/.blackbox/styles/hardware}
 247             [style] (Nova) {~/.blackbox/styles/nova}
 248             [style] (Orbital) {~/.blackbox/styles/orbital}
 249             [style] (Orbital II) {~/.blackbox/styles/orbital2}
 250             [style] (Seething) {~/.blackbox/styles/seething}
 251             [style] (Zero) {~/.blackbox/styles/zero}
 252             [style] (Cold Fusion) {~/.blackbox/styles/coldfusion}
 253         [end]
 254     [end]
 255
 256 Even better.  Now that we've gotten a feel for the menu syntax, we
 257 decide to finish off our menu.  In addition to the styles we
 258 downloaded, we decide we also want to keep a submenu for the default
 259 styles that came with Blackbox.  All we need to do is [include] the
 260 styles file from the share directory for Blackbox.  After putting
 261 everything together, we have:
 262
 263     # custom menu file for Blackbox
 264
 265     [begin] (Example \[Menu\])
 266         [exec] (xterm) {xterm -ls}
 267         [exec] (openprojects irc) {xterm -e irc fnord irc.openprojects.net}
 268
 269         [sep]
 270
 271         [exec] (Mozilla Browser) {mozilla}
 272         [exec] (XEmacs) {xemacs}
 273
 274         [sep]
 275
 276         [exec] (The GIMP) {gimp}
 277
 278         [sep]
 279
 280         [exec] (Video Tune) {xvidtune}
 281
 282         [sep]
 283
 284         [submenu] (Themes) {Themes from blackbox.themes.org}
 285             [style] (Blackbox) {~/.blackbox/styles/blackbox}
 286             [style] (Blackbox II) {~/.blackbox/styles/blackbox2}
 287             [style] (Hardware) {~/.blackbox/styles/hardware}
 288             [style] (Nova) {~/.blackbox/styles/nova}
 289             [style] (Orbital) {~/.blackbox/styles/orbital}
 290             [style] (Orbital II) {~/.blackbox/styles/orbital2}
 291             [style] (Seething) {~/.blackbox/styles/seething}
 292             [style] (Zero) {~/.blackbox/styles/zero}
 293             [style] (Cold Fusion) {~/.blackbox/styles/coldfusion}
 294
 295     # include the default style menu... this is assuming Blackbox was installed
 296     # into /usr/local
 297
 298             [sep]
 299
 300             [include] (/usr/local/share/blackbox/styles/stylesmenu)
 301         [end]
 302
 303         [workspaces] (Workspace list)
 304
 305         [submenu] (Restart) {Restart which?}
 306             [restart] (Blackbox)
 307
 308     # let's also give us access to some other window managers
 309
 310             [restart] (Window Maker) {wmaker}
 311             [restart] (Enlightenment) {enlightenment}
 312             [restart] (KWM) {kwm}
 313             [restart] (TWM) {twm}
 314         [end]
 315
 316         [sep]
 317
 318         [reconfig] (Reconfigure)
 319         [exit] (Quit!)
 320     [end]
 321
 322 And voila! our menu file is finished.  Now we need to tell Blackbox to
 323 read this menu file.  We do this by editing the file ~/.blackboxrc.
 324
 325 The format of ~/.blackboxrc is in the X resource database format (just
 326 like ~/.Xdefaults).  Since the file is updated automatically, it may
 327 be full of stuff or it may not even exist (especially if this is the
 328 first time we've ran Blackbox).  Don't worry if you have to create
 329 ~/.blackboxrc, Blackbox will see the file the next time it starts.
 330
 331 What we need to do is change the resource for the menu's filename.
 332 This is done by changing (or adding) the line that looks like so:
 333
 334     ...
 335     session.menuFile:    /path/to/some/file
 336     ...
 337
 338 If this resource exists, we change it.  If it does not, we add it.
 339 Depending on where we put the menu file, our new resource could look
 340 like this:
 341
 342     ...
 343     session.menuFile:    /usr/home/bhughes/.blackbox/rootmenu
 344     ...
 345
 346 We save ~/.blackboxrc and then restart Blackbox (reconfiguring doesn't
 347 work, we need Blackbox to completely shutdown and reread ALL of it's
 348 configuration files, not just the ones that control colors/fonts/etc.)
 349
 350 If we've done everything correctly, Blackbox restarts itself and our
 351 new menu is now ready for use.  If something doesn't work, read over
 352 the above example again to make sure you didn't forget a step or leave
 353 out the necessary tags.
 354
 355 Now that Blackbox has been told where to find it's menu, it does a
 356 little more.  Blackbox 0.51.x introduced automatic menu updates.  As
 357 long as you never change session.menuFile, you will never have to
 358 restart or reconfigure Blackbox whenever you change your menu.
 359 Blackbox watches the timestamps on all the files it reads to build
 360 your menu.  If any of them change, they are reread and your menu
 361 updated.  This check is done every time you open the root menu.  Like
 362 I said... it is a check, it doesn't reread the menu every time, it
 363 just looks at the modification time and rereads when it changes.