-- data/README.menu for Blackbox - an X11 Window manager Creating a user defined menu: ----------------------------- Creating a menu for Blackbox 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 Blackbox the path or location for this file. As an example, let's assume that my home directory is `/usr/home/bhughes' (which it is). I've decided to keep all my Blackbox related files in a directory named `.blackbox/'. 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/blackbox/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 up to 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 Blackbox to start parsing the menu file. This tag is required for Blackbox to parse your menu file. If it cannot find it, the system default menu is used instead. [end] This tells Blackbox 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 Blackbox to insert a command item into the menu. When you select the menu item from the menu, Blackbox runs `shell command.' [exit] (label for exit) This tells Blackbox to insert an item that shuts down and exits Blackbox. Any open applications are left running. [include] (filename) This tells Blackbox 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/blackbox/brueghel/stylesmenu) or it can begin with `~/', which will be expanded into your home directory (e.g. [include] (~/.blackbox/stylesmenu) will include /usr/home/bhughes/blackbox/stylesmenu in my menu). [nop] (label - optional) This tells Blackbox 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. [sep] Inserts a horizontal separator. This can be used similar to [nop] to format and organize your menus. [style] (label) {filename} This tells Blackbox 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.' Blackbox also re-reads the entire menu structure from disk, in case the menu has changed. [stylesdir] (directory) This tells Blackbox to create a [style] entry in the menu for every file in the specified directory. If you put all of your styles into a single directory, this saves you having to create [style] entries for each one manually. [submenu] (label) {title for menu - optional} This tells Blackbox 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 Blackbox 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 Blackbox every time you save your style. [restart] (label) {shell command - optional} This tells Blackbox 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, Blackbox restarts itself. [workspaces] (label) This tells Blackbox 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 Blackbox to insert the ConfigMenu into your menu. From this menu you can configure several options stored in your ~/.blackboxrc, 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: ------------------------ 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] (openprojects irc) {xterm -e irc fnord irc.openprojects.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] (openprojects irc) {xterm -e irc fnord irc.openprojects.net} [exec] (Mozilla Navigator) {mozilla} [exec] (XEmacs) {xemacs} [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 [sep] tag: [begin] (Example \[Menu\]) [exec] (xterm) {xterm -ls} [exec] (openprojects irc) {xterm -e irc fnord irc.openprojects.net} [sep] [exec] (Mozilla Navigator) {mozilla} [exec] (XEmacs) {xemacs} [sep] [exec] (The GIMP) {gimp} [sep] [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://themes.freshmeat.net/. Let's assume we untarred the themes into the ~/.blackbox directory like the documentation recommends. [begin] (Example \[Menu\]) [exec] (xterm) {xterm -ls} [exec] (openprojects irc) {xterm -e irc fnord irc.openprojects.net} [sep] [exec] (Mozilla Navigator) {mozilla} [exec] (XEmacs) {xemacs} [sep] [exec] (The GIMP) {gimp} [sep] [exec] (Video Tune) {xvidtune} [submenu] (Themes) {Themes from themes.freshmeat.net} [style] (Blackbox) {~/.blackbox/styles/blackbox} [style] (Blackbox II) {~/.blackbox/styles/blackbox2} [style] (Hardware) {~/.blackbox/styles/hardware} [style] (Nova) {~/.blackbox/styles/nova} [style] (Orbital) {~/.blackbox/styles/orbital} [style] (Orbital II) {~/.blackbox/styles/orbital2} [style] (Seething) {~/.blackbox/styles/seething} [style] (Zero) {~/.blackbox/styles/zero} [style] (Cold Fusion) {~/.blackbox/styles/coldfusion} [end] [end] An advantage of keeping styles in a directory of their own, is that you can use the [stylesdir] menu command to avoid having to add [style] entries manually. If you put your styles into ~/.blackbox/styles, the above style menu can be made like this: [submenu] (Themes) {Themes from themes.freshmeat.net} [stylesdir] (~/.blackbox/styles) [end] Even better. 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 Blackbox. All we need to do is [include] the styles file from the share directory for Blackbox. After putting everything together, we have: # custom menu file for Blackbox [begin] (Example \[Menu\]) [exec] (xterm) {xterm -ls} [exec] (openprojects irc) {xterm -e irc fnord irc.openprojects.net} [sep] [exec] (Mozilla Browser) {mozilla} [exec] (XEmacs) {xemacs} [sep] [exec] (The GIMP) {gimp} [sep] [exec] (Video Tune) {xvidtune} [sep] [submenu] (Themes) {Themes from blackbox.themes.org} [style] (Blackbox) {~/.blackbox/styles/blackbox} [style] (Blackbox II) {~/.blackbox/styles/blackbox2} [style] (Hardware) {~/.blackbox/styles/hardware} [style] (Nova) {~/.blackbox/styles/nova} [style] (Orbital) {~/.blackbox/styles/orbital} [style] (Orbital II) {~/.blackbox/styles/orbital2} [style] (Seething) {~/.blackbox/styles/seething} [style] (Zero) {~/.blackbox/styles/zero} [style] (Cold Fusion) {~/.blackbox/styles/coldfusion} # include the default style menu... this is assuming Blackbox was installed # into /usr/local [sep] [include] (/usr/local/share/blackbox/styles/stylesmenu) # or, we could use # [stylesdir] (/usr/local/share/blackbox/styles) [end] [workspaces] (Workspace list) [submenu] (Restart) {Restart which?} [restart] (Blackbox) # 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] [sep] [reconfig] (Reconfigure) [exit] (Quit!) [end] And voila! our menu file is finished. Now we need to tell Blackbox to read this menu file. We do this by editing the file ~/.blackboxrc. The format of ~/.blackboxrc 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 Blackbox). Don't worry if you have to create ~/.blackboxrc, Blackbox 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: /usr/home/bhughes/.blackbox/rootmenu ... We save ~/.blackboxrc and then restart Blackbox (reconfiguring doesn't work, we need Blackbox 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, Blackbox 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 Blackbox has been told where to find it's menu, it does a little more. Blackbox 0.51.x introduced automatic menu updates. As long as you never change session.menuFile, you will never have to restart or reconfigure Blackbox whenever you change your menu. Blackbox 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 every time you open the root menu. Like I said... it is a check, it doesn't reread the menu every time, it just looks at the modification time and rereads when it changes.
Generated by dwww version 1.15 on Sat Jun 15 20:21:47 CEST 2024.