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