Home | Sitemap | Last changes RSS Feed | Wiki help | Wiki tools | SandBox
Preferences | Edit this page | View source | Page history | Referrers
Document last modified: Fri, 16 Nov 2007, 07:00 UTC
Parents: BlackboxDocumentation/

Blackbox Documentation/Blackbox Menus

The Blackbox menus are native menus produced by Blackbox to assist the user in handling various window manager widgets and settings. Since they are native, they follow the looks of the current Blackbox style.

It's worth noting that having these menus, toolbar and slit actually makes Blackbox sort of a minimal desktop environment rather than just a window manager.

1 Using menus
1.1 Main menu
1.2 Toolbar menu
1.3 Slit menu
1.4 Window menu
1.5 Workspaces menu
2 Configuring the main menu
2.1 The menu file
2.2 Main menu syntax
2.2.1 Basic definitions
2.2.2 Basic structure
2.2.3 Error handling
2.3 Main menu commands
2.3.1 nop
2.3.2 sep (starting with version 0.70)
2.3.3 begin
2.3.4 submenu
2.3.5 end
2.3.6 exec
2.3.7 exit
2.3.8 config
2.3.9 reconfig
2.3.10 restart
2.3.11 stylesdir
2.3.12 style
2.3.13 include Pipe menus
2.3.14 workspaces
2.4 Main menu example
2.5 Tips and tricks
2.5.1 Auto-generated distro submenus

1) Using menus

All menus behave the same way. Specifically, you hover the mouse pointer over entries to expand them, click your primary (left) mouse button to activate entries, or click your secondary (right) mouse button to make the menu go away. Sometimes the third (middle) mouse button also has a special function, depending on the particular menu.

Some menus have a small titlebar which you can use to drag them around to anywhere you want. If a menu has submenus, you can detach those submenus by dragging them by the title, then do the same for other submenus and so on. Detached submenus will stick around and always be on top (even after their parent disappears or the workspace changes) until you explicitly close them with the secondary (right) mouse button.

Note: Starting with version 0.70, Blackbox does not feature detachable submenus anymore. FIXME: Change this note if they ever come back.

Read on for information specific to various types of Blackbox menus, as well as some tips and tricks.

FIXME: The consistency of various mouse button effects in various menus could use some improvement. See BlackboxFeature:1187382 for a discussion.

1.1) Main menu

The main menu appears when you right-click on any empty portion of the desktop or on the window frames.

The main menu is often referred to as the root menu, because you obtain it by clicking on the root window a.k.a. the desktop.

Hint: screen corners are statistically the easiest places for people to reach with their mouse, followed by screen edges. So keep a corner or edge clear, even if it's just a couple of pixels, and when you need the main menu just fly the pointer in that general direction far enough to know you've reached it, then right-click.
Hint (how to keep a corner or edge clear at all times): set Blackbox to NOT do full maximization of windows (see the Blackbox config menu). This will reserve a space a few pixels wide along the edge you have the toolbar or the slit on, at all times. Now just make sure you clear a corner or an edge by not covering it with either slit or toolbar, and there you go.
Tip: Starting with Blackbox 0.70, when you click the secondary (right) mouse button on the window frames, Blackbox will still open the main menu. This is useful when a window covers the entire desktop; you no longer need to search for an empty desktop zone, you can just go to the sides of the screen.

The main menu gets its contents from the menu file. Typically, users want to place calls to various applications in the main menu and its various submenus, so as to have them within easy reach. The main menu can be split into submenus, and these can be further split into other submenus.

Clicking any mouse button on the insides of the main menu will activate the entry currently under the mouse cursor. In order to make the main menu dissapear you have to click the secondary (right) mouse button on any visible submenu heading. Or you can click any button anywhere outside the main menu.

Note: This used to be different before version 0.70. Right click inside the menus also made them disappear. Since 0.65 also featured detachable menus, right click on a detached menu only made that section disappear.

1.2) Toolbar menu

This menu appears when you right-click on the Blackbox toolbar. It offers access to various toolbar related settings, such as placement, position, autohide or on-top.

1.3) Slit menu

This menu appears when you right-click on the Blackbox slit. It offers access to various slit related settings, such as placement, position, orientation, autohide or on-top.

Note: Sometimes applications in the slit will cover the slit background. You need to click on the actual slit background in order to get the slit menu. It helps to have a slit marginWidth of 2-3 pixels or more.

1.4) Window menu

This menu appears when you right-click on a window's top bar. The entries in this menu allow you to do special things with that window or the application contained within it, such as: making the window always-on-top/bottom, making it present on all workspaces, iconify, maximize, close it, kill the application by force, send the window to another workspace, stickiness, raise/lower.

This menu is not detachable and depends on the window to exist (ie. window dissapears, menu goes away too). The reason for this menu is to allow you access to everything the window buttons do, and more.

1.5) Workspaces menu

The workspaces menu appears when middle-clicking on the desktop. It offers a list of all the workspaces, and under each one a list of all the windows on that workspace. There's also a submenu dedicated to iconified windows.

Clicking a window will teleport you to its workspace and focus that window.

The iconified windows submenu is the main Blackbox way to see those windows. Clicking on a window will de-iconify it to the current workspace. This submenu is an exception, in that it doesn't dissapear when you click on a window.

Tip: Together with the fact that Blackbox menus are always on top, this allows for a neat trick: detach it and leave it somewhere in a corner. It will effectively act as a sort of taskbar replacement, as long as you don't mind having windows from all workspaces on it and you don't mind it obscuring something else below.
No need to obscure. Try dragging it to the corner such that only a tiny bit of the frame is showing. Now whenever you move the mouse to this corner, the entire list will temporarily jump out and become visible and you can select the window you want.
Note: At the date of writing this, Blackbox 0.70 hasn't yet reimplemented menu detachment. Therefore the above trick doesn't work. Alternatives can be obtained via 3rd-party addon.

2) Configuring the main menu

Unlike the other Blackbox menus, which are predefined inside the program, the main menu is mostly defined by the user.

2.1) The menu file

The menu file is located in your home directory, at the following location: ~/.blackbox/menu. It is a simple text file, which you can edit using any text editor.

If the menu file is not there, please look in your configuration file for a line starting with session.menuFile, which will tell you where the menu is located. You can edit the config file and change that line to point to any file you want.

Blackbox rereads this file every time it has to produce the main menu, so changes are instantly incorporated.

2.2) Main menu syntax

2.2.1) Basic definitions

Each line is a separate menu definition. Definitions cannot span more than one line.

Empty (ie. containing only whitespace) and lines that start with # (comments) are ignored.

Everything from a comment mark to the end of the line is ignored. This makes it possible to have valid content at the beginning of a line and a comment later on on the same line.

Each definition looks like one of the following:

[command] (label) {data}
[command] (label)

As you can see, [command] is always mandatory. Sometimes {data} can be absent, sometimes both {data} and (label) can be absent. But you can never have a [command] and {data} without a (label) in between.

2.2.2) Basic structure

A valid menu must at the very least contain the following structure:

[begin] (Some label)
  ...at least one entry, no matter of what type...

2.2.3) Error handling

Usually Blackbox tries to recover as much of a faulty menu as it can. Sometimes only one broken line is affected and dissapears or it is rendered incorrectly. Other times, the mistake may affects submenus and larger menu areas can be affected, be rendered incompletely or incorrectly.

In the worst case scenario, if the mistakes are too extensive, Blackbox will ignore the entire menu and instead render the following barebone menu:

[begin] (Blackbox)
  [exec] (xterm) {xterm}
  [restart] (Restart)
  [exit] (Exit)

This also happens if the menu doesn't contain at least the basic structure.

2.3) Main menu commands

The following section describes each menu command in detail. The following terms are used:

2.3.1) nop

The [nop] command is used to create an inactive menu item, which can be clicked on but doesn't actually execute anything.

Tip: Version 0.65 and earlier didn't have separators, so [nop] could be used to fake them:
[nop] (------------)

It MAY have a label. If it doesn't, an empty one will be assumed. An empty label is also acceptable.

It SHOULD NOT have data.

2.3.2) sep (starting with version 0.70)

The [sep] command is used to create nice-looking, native menu separators, similar to the ones you might see in the window, config, or workspace menus.

A label and data SHOULD NOT be present.

2.3.3) begin

The [begin] command is used exclusively for marking the beginning of the menu commands. It MAY be preceeded by comment or empty lines, but SHOULD NOT be preceeded by any command lines.

It MUST have a label, which will be rendered as the heading title for the main root menu.

It SHOULD NOT have data.

2.3.4) submenu

The [submenu] command is used to open a new submenu. New submenus may be imbricated to any depth. Submenus MUST be nested properly.

It MUST have a label, which will be rendered as the heading title for the submenu.

It SHOULD NOT have data.

2.3.5) end

The [end] command closes the previously opened [submenu].

It is also used to mark the end of the commands in the menu, as a correspondent to the [begin] command. If used like this, it MAY be followed by empty or comment lines, but SHOULD NOT be followed by any command lines; any subsequent command lines will be ignored.

A label and data SHOULD NOT be present.

2.3.6) exec

The [exec] command allows you to execute a shell command. This is most widely used as a means to launch various applications.


[exec] (Firefox) {firefox}

It MUST have both label and data. Non-conforming lines will not be rendered at all.

For data, it's OK to use shell constructs such as pipes (ie. dmidecode|gless), background operators (ie. xterm & xterm), backtick operators (ie. xmessage `which xterm`), environment variables (ie. program --java-home $JAVA_HOME) and tilda expansion (ie. nedit ~/.blackbox/menu).

However, more complex scripts will fail due to the fact that Blackbox executes the command "quickly", so you can only have one single command unit. Anything that attempts to use two or more commands in the same data will fail. For instance, xterm ; xterm will only produce the first xterm, and you MUST NOT use logical separators (&&, ||), round brackets (for subprocesses), curly brackets (for blocks), test conditions (neither via test nor via square brackets), control structures (if, while, for), functions, and so on. If you need such advanced shell scripting then make a standalone script and execute that instead.

Tip: If you need to launch an application which needs console support, such as top, you can launch it through a terminal, like this: xterm -e top. Most terminals allow you to use the -e parameter. Don't run such applications directly, because they will be executed on the X standard console, which is usually tty1, and will be invisible to the X user.

2.3.7) exit

The [exit] command creates a menu entry that will cause Blackbox to exit.

Note: Please observe that X uses a "control application" to determine its own lifetime. Usually, Blackbox (as the window manager) is that application. When Blackbox exits or crashes, X will too, and in turn kill all other applications started from under Blackbox or any applications which depend on that X session.

It MUST have a label.

It SHOULD NOT have data.

2.3.8) config

The [config] command will render a structure of submenus which will represent certain aspects of the current Blackbox configuration, dinamically. Only some aspects are included, because the Blackbox menus, by their nature, can only render simple on/off or multiple choice options.

Note: Changed options will take effect and will be saved to the current Blackbox preference file immediately.

Currently selected options are rendered with a check mark next to them.

The command MUST have a label.

It SHOULD NOT have data.

2.3.9) reconfig

The [reconfig] command will tell Blackbox to re-read its configuration files, except the configuration file (which is only re-read when Blackbox is restarted, see restart below).

It MUST have a label.

It MAY have data. If present, it will be assumed to be a shell command which will be executed before the reconfiguration is performed. This allows you to have, for instance, several configuration files and to switch between them on the fly.

2.3.10) restart

The [restart] command causes Blackbox to restart itself. This can be useful if some major configuration changes occured, or if the Blackbox binary was replaced.

It MUST have a label.

It MAY have data. If present, the data will be assumed to be a shell command which will be executed after Blackbox quits. This allows people to create entries that will be used for switching to another window manager.


[restart] (Switch to TWM) {twm}

If the shell command in data results in an error, Blackbox will revert to itself instead.

2.3.11) stylesdir

The [stylesdir] command will take a directory and produce a list of all the files in it (directories are ignored). It is assumed that those files are all Blackbox style files. When one of the files is clicked, Blackbox will attempt to load, parse and (if successful) use that style.

Note: A successfully loaded style will be saved to the current Blackbox preference file immediately.

It MUST have a label. This command is somewhat atypical, in that the label is the one that must indicate the target directory. If the target is not a directory, the command will be ignored.

Note: Tilda expansion is performed on the path.

It SHOULD NOT have data.

Tip: Remember that [stylesdir] doesn't produce a submenu of it's own, like [config] or [workspaces] do. It dumps the style files directly in the submenu where it was used. If you want it rendered nicely in its own submenu you'll have to construct that submenu manually, like this:
[submenu] (Styles) {Choose a style...} 
  [stylesdir] (/usr/local/share/blackbox/styles/)

2.3.12) style

The [style] command inserts a single entry pointing to a style file. When it is activated, the entry will make Blackbox attempt to load, parse and (if successfull) use the style.

It MUST have a label, which will be used as the text for the entry.

It MUST have data, which will indicate the file to use. Please use a full absolute path for best results.

Note: Tilda expansion is performed on the path.

2.3.13) include

The [include] command will attempt to load, parse and (if successful) render another menu file. If the file is not found, or its syntax is wrong, the command will be ignored.

Note: Tilda expansion is performed on the path.

The included menu MAY be enclosed with [begin]...[end] but it is not required. It will be rendered directly where it was included; a submenu will not be created automatically for it. If you want to place it in a submenu you'll have to construct one manually.

It MUST have a label. The label for this command is somewhat atypical, in that it contains a file name and path, and not a label.

It SHOULD NOT have data. Pipe menus

This is a special feature of the [include] command. If you prefix the label with the pipe character "|", the label will be assumed to represent not a filename, but a shell command. The standard output from the command will be parsed as a menu instead.

You would add something like the following to your blackbox menu file:

   [include] (|/path/to/my/script.sh)

You should click "Reconfigure" if you want a pipe menu to be regenerated.

FIXME: address the issues described in BlackboxBug:1187963.

2.3.14) workspaces

The [workspaces] command will cause Blackbox to render the workspace menu (the very same one you get by middle-clicking on the desktop) and include it as a submenu.

It MUST have a label.

It SHOULD not have data.

2.4) Main menu example

You can find the default main menu definition here: /BlackboxMenus/MainMenuExample. It also includes a short introduction to the syntax.

2.5) Tips and tricks

This section contains tips and tricks regarding the definition and organization of menu entries. Add them below and give each one a succint heading title.

2.5.1) Auto-generated distro submenus

It is possible to have a Blackbox submenu which is auto-generated from another menu system, and which gets updated automatically every time you install or remove packages on your machine.

Please see /BlackboxMenus/SystemIntegration for details.

eXTReMe Tracker Hosted by SourceForge.net
Document last modified: Fri, 16 Nov 2007, 07:00 UTC
Home | Sitemap | Last changes RSS Feed | Wiki help | Wiki tools | SandBox
Preferences | Edit this page | View source | Page history | Referrers
Hosted by SourceForge. Powered by Wikki Tikki Tavi. About the website. Terms of use.