The installation .zip in which Blackbox for Windows is distributed contains a default menu file called menu.rc. However, if this file is not found, one will be automatically generated for you in your Windows directory. This "default" menu contains only basic functionality and is a temporary feature until you can set up your own menu (for more information, see below). When you have finished your own menu file, you have to tell Blackbox to load that file instead of the default. This is accomplished by adding (or changing) a resource value in the blackbox.rc file:

session.menuFile: c:\Blackbox\menu.rc

For this change to take effect, Blackbox has to be restarted. Make sure that your menu is usable, then choose 'Restart' from the default Blackbox root menu.


The menu syntax is very simple and very effective. There are up to three fields in a menu line, 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 can not find it, the system default menu is used instead. If no label is specified (ie. [begin] () ) "Blackbox " + current version (e.g. "Blackbox 0.0.70") will be displayed instead.

[submenu] (label) {title for menu - optional}
This tells Blackbox to create and parse a new menu, which 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. An [end] tag is required to end the submenu.

[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) {"command" arguments}
Inserts a command item into the menu. When you select the menu item from the menu, Blackbox will execute 'command' with any optional 'arguments'. Please note that if the 'command' path contains spaces you have to put quotes around it, e.g. "c:\path with spaces\myapp.exe". If you do not specify an application for a document it will open in the default viewer for that filetype, e.g. a HTML file will open in your preferred browser (more examples can be found in the included menu.rc). Finally, as of Blackbox for Windows 0.0.60 the menu [exec] also supports bro@ms (broadcast messages).

[exit] (label for exit)
Inserts an item that exits Blackbox. Any open windows are sent to the first workspace before Blackbox exits.

[shutdown] (label for shutdown)
Inserts an item that shuts down your computer.

[reboot] (label for reboot)
Inserts an item that reboots your computer.

[logoff] (label for logoff)
Inserts an item that logs you off your computer.

[hibernate] (label for hibernate)
Inserts an item that puts your computer in hibernation.

[suspend] (label for suspend)
Inserts an item that puts your computer in suspended mode.

[lockworkstation] (label for lock workstation)
Inserts an item that locks your workstation (Windows 2000/XP only).

[run] (label for run)
Inserts an item that opens the run dialog.

[include] (filename)
Parses the file specified by 'filename' inline with the current menu. The filename can be the full path to a file or a path off of the program directory, e.g.: [include] (Blackbox\stylesmenu.rc) will include "c:\Blackbox\stylesmenu.rc" into your menu.

[nop] (label - optional)
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. [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 Blackbox to insert an item that, when selected, reads the style file named 'filename' and apply the new textures, colors and fonts to the current session.

[stylesdir] (path to directory)
Reads all filenames from the specified directory, assuming that they are all valid style files (directories are ignored), and creates menu items in the current menu for every filename, that (when selected by the user) apply the selected style to the current session. The labels that are created in the menu are the filenames of the style files.

[stylesmenu] (label) {path to directory}
Creates a submenu entry with label (that is also the title of the new submenu), and inserts into that submenu all files and subfolders of the specified directory, assuming that the files are all valid style files in the same way as the [stylesdir] command.

Both the [stylesdir] and [stylesmenu] commands make it possible to switch between style files without editing your menu file (the latest selected style will be saved to the blackbox.rc configuration file on restart or exit of Blackbox).

[path] (label) {path to directory}
Creates a submenu entry with label (that is also the title of the new submenu), and inserts into that submenu all files and subfolders of the specified directory. This can be used to e.g. insert the Windows Start Menu into the Blackbox menu.

[reconfig] (label)
When selected, this item rereads 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) {optional shell command}
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.

[config] (label)
Inserts a Blackbox native submenu item, containing numerous configuration options concerning window placement, focus style, window moving style etc.

[workspaces] (label)
This tells Blackbox to insert a link to the workspaces menu directly into your main menu. This is handy for those users who can't access the workspace menu directly (i.e. if you don't have a three button mouse).

[editstyle] (label)
This will open the current style in Notepad for editing (the reason it opens in Notepad is that since most styles do not have an extension, they do not have a default application).

[editmenu] (label)
This will open your menu.rc file in your preferred application.

[editplugins] (label)
This will open your plugins.rc file in your preferred application.

[aboutstyle] (label)
Displays information about the current style in a MessageBox (parses bbconf format style information tags).

[toggleplugins] (label)
This will show/hide any loaded
plugins (naturally, this functionality needs to be supported by the plugin).

Any line in the menu file that starts with a '#' is considered a comment and ignored by Blackbox.


Please study the included menu.rc file for more information and examples.


(Please note that some parts of the Blackbox for Windows documentation were originally written for the *nix version by Wilbert Berendsen. They were first modified for the Windows version by azathoth, then further modified and included into this easier-to-read HTML documentation by qwilk.)