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.

[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}
Inserts a command item into the menu. When you select the menu item from the menu, Blackbox runs 'shell command'.

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

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

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

[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] (directory name)
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) {directory name}
Creates a submenu entry with label (that is also the title of the new submenu), and inserts into that submenu all filenames in the specified directory, assuming that they are all valid style files (directories are ignored) 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).

[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.

[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) {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.

[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).

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


Here is a short example of a menu file:

# Blackbox menu file
[begin] (Blackbox)
  [exec] (cmd) {cmd.exe}
  [exec] (Internet Explorer) {iexplore.exe}
  [exec] (PhotoShop) {c:\Program files\Adobe\PhotoShop 5.5\photoshp.exe}
  [submenu] (Shell)
    [exec] (Edit menu.rc) {notepad c:\Blackbox\menu.rc}
    [submenu] (Style) {Select style...}
      [stylesdir] (c:\Blackbox\styles)
      [stylesmenu] (MyStyles) {c:\Blackbox\styles\mystyles}
    [end]
    [config] (Config Options)
    [reconfig] (Reconfigure)
    [restart] (Restart)
  [end]
  [exit] (Exit)
[end]
# end of menu file


(Please note that some parts of the Blackbox for Windows documentation was originally written for the Linux version by Wilbert Berendsen (wbsoft@xs4all.nl). It was modified for the Windows version by azathoth, and included into this easier-to-read HTML documentation by qwilk.)