| 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 |
[stylesdir] (directory) |
| 99 |
|
| 100 |
This tells Blackbox to create a [style] entry in the menu for every |
| 101 |
file in the specified directory. If you put all of your styles |
| 102 |
into a single directory, this saves you having to create [style] |
| 103 |
entries for each one manually. |
| 104 |
|
| 105 |
[submenu] (label) {title for menu - optional} |
| 106 |
|
| 107 |
This tells Blackbox to create and parse a new menu. This menu |
| 108 |
is inserted as a submenu into the parent menu. These menus |
| 109 |
are parsed recursively, so there is no limit to the number of |
| 110 |
levels or nested submenus you can have. The title for the new |
| 111 |
menu is optional, if none is supplied, the new menu's title is |
| 112 |
the same as the item label. |
| 113 |
|
| 114 |
[reconfig] (label) |
| 115 |
|
| 116 |
This tells Blackbox to reread the current style and menu files |
| 117 |
and apply any changes. This is useful for creating a new |
| 118 |
style or theme, as you don't have to constantly restart |
| 119 |
Blackbox every time you save your style. |
| 120 |
|
| 121 |
[restart] (label) {shell command - optional} |
| 122 |
|
| 123 |
This tells Blackbox to restart. If `shell command' is |
| 124 |
supplied, it shuts down and runs the command (which is |
| 125 |
commonly the name of another window manager). If the command |
| 126 |
is omitted, Blackbox restarts itself. |
| 127 |
|
| 128 |
[workspaces] (label) |
| 129 |
|
| 130 |
This tells Blackbox to insert a "link" to the workspaces menu |
| 131 |
directly into your menu. This is handy for those users who |
| 132 |
can't access the workspace menu directly (e.g. if you don't |
| 133 |
have a 3 button mouse, it's rather hard to middle click to |
| 134 |
show the workspace menu). This is a "link" to the systems |
| 135 |
workspace menu, so multiple [workspaces] tags will display the |
| 136 |
same workspace menu, so expect it to move around if you do |
| 137 |
so. ;) |
| 138 |
|
| 139 |
[config] (label) |
| 140 |
|
| 141 |
This tells Blackbox to insert the ConfigMenu into your menu. |
| 142 |
From this menu you can configure several options stored in |
| 143 |
your ~/.blackboxrc, and the changes take effect immediately. |
| 144 |
|
| 145 |
Comments may be inserted on any line of the file, as long as the first |
| 146 |
character on the line is a `#.' |
| 147 |
|
| 148 |
Also, in the labels/commands/filenames fields, you can escape any |
| 149 |
character like so: |
| 150 |
|
| 151 |
[exec] (\(my cool\) \{XTERM\}) {\(xterm -T \\\"cool XTERM\\\"\)} |
| 152 |
|
| 153 |
Using `\\' inserts a literal back-slash into the |
| 154 |
label/command/filename field. |
| 155 |
|
| 156 |
|
| 157 |
Putting it all together: |
| 158 |
------------------------ |
| 159 |
|
| 160 |
So let's see if we can understand the arcane incantation above. It |
| 161 |
says we have to have a [begin] and an [end] tag, which create our menu |
| 162 |
and give it a title. Let's do that first: |
| 163 |
|
| 164 |
[begin] (Example \[Menu\]) |
| 165 |
|
| 166 |
[end] |
| 167 |
|
| 168 |
Simple enough. Now let's add some items to the list. We always want |
| 169 |
to have access to a terminal emulator, be it a regular xterm or |
| 170 |
something else. So we add the item to our menu, and it now looks like |
| 171 |
this: |
| 172 |
|
| 173 |
[begin] (Example \[Menu\]) |
| 174 |
[exec] (xterm) {xterm -ls} |
| 175 |
[end] |
| 176 |
|
| 177 |
Great! Now let's add us some items to run an irc client, a web |
| 178 |
browser and some other common programs. This gives up this: |
| 179 |
|
| 180 |
[begin] (Example \[Menu\]) |
| 181 |
[exec] (xterm) {xterm -ls} |
| 182 |
[exec] (openprojects irc) {xterm -e irc fnord irc.openprojects.net} |
| 183 |
[exec] (Mozilla Navigator) {mozilla} |
| 184 |
[exec] (XEmacs) {xemacs} |
| 185 |
[exec] (The GIMP) {gimp} |
| 186 |
[exec] (Video Tune) {xvidtune} |
| 187 |
[end] |
| 188 |
|
| 189 |
Whoa, wait a second. This menu file is beginning to look a little |
| 190 |
cluttered. Not a problem, just like programmers indent and space |
| 191 |
their code, we can do this with our menu file, so let's clean it up a |
| 192 |
bit: |
| 193 |
|
| 194 |
[begin] (Example \[Menu\]) |
| 195 |
[exec] (xterm) {xterm -ls} |
| 196 |
[exec] (openprojects irc) {xterm -e irc fnord irc.openprojects.net} |
| 197 |
|
| 198 |
[exec] (Mozilla Navigator) {mozilla} |
| 199 |
[exec] (XEmacs) {xemacs} |
| 200 |
|
| 201 |
[exec] (The GIMP) {gimp} |
| 202 |
|
| 203 |
[exec] (Video Tune) {xvidtune} |
| 204 |
[end] |
| 205 |
|
| 206 |
Ahh... now that looks a little better. Now we decide that we kind of |
| 207 |
like the spacing in the file, and decide we want to apply it to the |
| 208 |
menu itself. Now we take advantage of the [sep] tag: |
| 209 |
|
| 210 |
[begin] (Example \[Menu\]) |
| 211 |
[exec] (xterm) {xterm -ls} |
| 212 |
[exec] (openprojects irc) {xterm -e irc fnord irc.openprojects.net} |
| 213 |
|
| 214 |
[sep] |
| 215 |
|
| 216 |
[exec] (Mozilla Navigator) {mozilla} |
| 217 |
[exec] (XEmacs) {xemacs} |
| 218 |
|
| 219 |
[sep] |
| 220 |
|
| 221 |
[exec] (The GIMP) {gimp} |
| 222 |
|
| 223 |
[sep] |
| 224 |
|
| 225 |
[exec] (Video Tune) {xvidtune} |
| 226 |
[end] |
| 227 |
|
| 228 |
Now, let's create a submenu to put some items to change between all |
| 229 |
these themes we downloaded from http://themes.freshmeat.net/. Let's |
| 230 |
assume we untarred the themes into the ~/.blackbox directory like the |
| 231 |
documentation recommends. |
| 232 |
|
| 233 |
[begin] (Example \[Menu\]) |
| 234 |
[exec] (xterm) {xterm -ls} |
| 235 |
[exec] (openprojects irc) {xterm -e irc fnord irc.openprojects.net} |
| 236 |
|
| 237 |
[sep] |
| 238 |
|
| 239 |
[exec] (Mozilla Navigator) {mozilla} |
| 240 |
[exec] (XEmacs) {xemacs} |
| 241 |
|
| 242 |
[sep] |
| 243 |
|
| 244 |
[exec] (The GIMP) {gimp} |
| 245 |
|
| 246 |
[sep] |
| 247 |
|
| 248 |
[exec] (Video Tune) {xvidtune} |
| 249 |
|
| 250 |
[submenu] (Themes) {Themes from themes.freshmeat.net} |
| 251 |
[style] (Blackbox) {~/.blackbox/styles/blackbox} |
| 252 |
[style] (Blackbox II) {~/.blackbox/styles/blackbox2} |
| 253 |
[style] (Hardware) {~/.blackbox/styles/hardware} |
| 254 |
[style] (Nova) {~/.blackbox/styles/nova} |
| 255 |
[style] (Orbital) {~/.blackbox/styles/orbital} |
| 256 |
[style] (Orbital II) {~/.blackbox/styles/orbital2} |
| 257 |
[style] (Seething) {~/.blackbox/styles/seething} |
| 258 |
[style] (Zero) {~/.blackbox/styles/zero} |
| 259 |
[style] (Cold Fusion) {~/.blackbox/styles/coldfusion} |
| 260 |
[end] |
| 261 |
[end] |
| 262 |
|
| 263 |
An advantage of keeping styles in a directory of their own, is that you can |
| 264 |
use the [stylesdir] menu command to avoid having to add [style] entries |
| 265 |
manually. If you put your styles into ~/.blackbox/styles, the above style |
| 266 |
menu can be made like this: |
| 267 |
|
| 268 |
[submenu] (Themes) {Themes from themes.freshmeat.net} |
| 269 |
[stylesdir] (~/.blackbox/styles) |
| 270 |
[end] |
| 271 |
|
| 272 |
Even better. Now that we've gotten a feel for the menu syntax, we |
| 273 |
decide to finish off our menu. In addition to the styles we |
| 274 |
downloaded, we decide we also want to keep a submenu for the default |
| 275 |
styles that came with Blackbox. All we need to do is [include] the |
| 276 |
styles file from the share directory for Blackbox. After putting |
| 277 |
everything together, we have: |
| 278 |
|
| 279 |
# custom menu file for Blackbox |
| 280 |
|
| 281 |
[begin] (Example \[Menu\]) |
| 282 |
[exec] (xterm) {xterm -ls} |
| 283 |
[exec] (openprojects irc) {xterm -e irc fnord irc.openprojects.net} |
| 284 |
|
| 285 |
[sep] |
| 286 |
|
| 287 |
[exec] (Mozilla Browser) {mozilla} |
| 288 |
[exec] (XEmacs) {xemacs} |
| 289 |
|
| 290 |
[sep] |
| 291 |
|
| 292 |
[exec] (The GIMP) {gimp} |
| 293 |
|
| 294 |
[sep] |
| 295 |
|
| 296 |
[exec] (Video Tune) {xvidtune} |
| 297 |
|
| 298 |
[sep] |
| 299 |
|
| 300 |
[submenu] (Themes) {Themes from blackbox.themes.org} |
| 301 |
[style] (Blackbox) {~/.blackbox/styles/blackbox} |
| 302 |
[style] (Blackbox II) {~/.blackbox/styles/blackbox2} |
| 303 |
[style] (Hardware) {~/.blackbox/styles/hardware} |
| 304 |
[style] (Nova) {~/.blackbox/styles/nova} |
| 305 |
[style] (Orbital) {~/.blackbox/styles/orbital} |
| 306 |
[style] (Orbital II) {~/.blackbox/styles/orbital2} |
| 307 |
[style] (Seething) {~/.blackbox/styles/seething} |
| 308 |
[style] (Zero) {~/.blackbox/styles/zero} |
| 309 |
[style] (Cold Fusion) {~/.blackbox/styles/coldfusion} |
| 310 |
|
| 311 |
# include the default style menu... this is assuming Blackbox was installed |
| 312 |
# into /usr/local |
| 313 |
|
| 314 |
[sep] |
| 315 |
|
| 316 |
[include] (/usr/local/share/blackbox/styles/stylesmenu) |
| 317 |
|
| 318 |
# or, we could use |
| 319 |
# [stylesdir] (/usr/local/share/blackbox/styles) |
| 320 |
|
| 321 |
[end] |
| 322 |
|
| 323 |
[workspaces] (Workspace list) |
| 324 |
|
| 325 |
[submenu] (Restart) {Restart which?} |
| 326 |
[restart] (Blackbox) |
| 327 |
|
| 328 |
# let's also give us access to some other window managers |
| 329 |
|
| 330 |
[restart] (Window Maker) {wmaker} |
| 331 |
[restart] (Enlightenment) {enlightenment} |
| 332 |
[restart] (KWM) {kwm} |
| 333 |
[restart] (TWM) {twm} |
| 334 |
[end] |
| 335 |
|
| 336 |
[sep] |
| 337 |
|
| 338 |
[reconfig] (Reconfigure) |
| 339 |
[exit] (Quit!) |
| 340 |
[end] |
| 341 |
|
| 342 |
And voila! our menu file is finished. Now we need to tell Blackbox to |
| 343 |
read this menu file. We do this by editing the file ~/.blackboxrc. |
| 344 |
|
| 345 |
The format of ~/.blackboxrc is in the X resource database format (just |
| 346 |
like ~/.Xdefaults). Since the file is updated automatically, it may |
| 347 |
be full of stuff or it may not even exist (especially if this is the |
| 348 |
first time we've ran Blackbox). Don't worry if you have to create |
| 349 |
~/.blackboxrc, Blackbox will see the file the next time it starts. |
| 350 |
|
| 351 |
What we need to do is change the resource for the menu's filename. |
| 352 |
This is done by changing (or adding) the line that looks like so: |
| 353 |
|
| 354 |
... |
| 355 |
session.menuFile: /path/to/some/file |
| 356 |
... |
| 357 |
|
| 358 |
If this resource exists, we change it. If it does not, we add it. |
| 359 |
Depending on where we put the menu file, our new resource could look |
| 360 |
like this: |
| 361 |
|
| 362 |
... |
| 363 |
session.menuFile: /usr/home/bhughes/.blackbox/rootmenu |
| 364 |
... |
| 365 |
|
| 366 |
We save ~/.blackboxrc and then restart Blackbox (reconfiguring doesn't |
| 367 |
work, we need Blackbox to completely shutdown and reread ALL of it's |
| 368 |
configuration files, not just the ones that control colors/fonts/etc.) |
| 369 |
|
| 370 |
If we've done everything correctly, Blackbox restarts itself and our |
| 371 |
new menu is now ready for use. If something doesn't work, read over |
| 372 |
the above example again to make sure you didn't forget a step or leave |
| 373 |
out the necessary tags. |
| 374 |
|
| 375 |
Now that Blackbox has been told where to find it's menu, it does a |
| 376 |
little more. Blackbox 0.51.x introduced automatic menu updates. As |
| 377 |
long as you never change session.menuFile, you will never have to |
| 378 |
restart or reconfigure Blackbox whenever you change your menu. |
| 379 |
Blackbox watches the timestamps on all the files it reads to build |
| 380 |
your menu. If any of them change, they are reread and your menu |
| 381 |
updated. This check is done every time you open the root menu. Like |
| 382 |
I said... it is a check, it doesn't reread the menu every time, it |
| 383 |
just looks at the modification time and rereads when it changes. |