Building The Menu

To build or change your main menu, open menu.rc in a text editor. See also the included default menu.rc as an example.


Each menu item consists of 1..3 fields:

[command]  (label)  {data}
Menu structure  
[begin] (label) indicates the begin of the menu, label is optional.
[end] indicates the end of the menu or submenu, required.
[submenu] (label) inserts a submenu into the menu, must be closed by [end]
[include] {filename} This will continue reading items from the indicated file.
[nop] (label) inserts an inactive item with an optional label
[sep] inserts a separator (same as [nop] with no label)

Inserting submenus  
[path] (label) {folder} inserts an submenu with a folder from your computer as specified
[path] (label) {folder1|folder2} merges two folders into a single menu
[insertpath] {folder} inserts items from a folder into the current menu
[stylesmenu] (label) {folder} insert a submenu with stylefiles from a folder
[stylesdir] {folder} insert style files from a folder into the current menu
[config] (label) inserts the configuration menu
[workspaces] (label) insert the workspaces menu
[tasks] (label) insert a menu with the current tasks
[icons] (label) insert a menu with the currently minimized tasks

In addition to normal paths like {c:/program files/...}, a number of items may be used to indicate a special shellfolder. See shellfolders.rc for examples.

Blackbox commands  
[style] (label) {filename} insert an item to apply a new style.
[toggleplugins] (label) show/hide plugins
[aboutplugins] (label) display 'about plugins' info
[aboutstyle] (label) display 'about style' info
[gather] (label) gather windows in current workspace
[reconfig] (label) re-read the configuration files
[restart] (label) reload plugins
[exit] (label) exit blackbox

Edit commands  
[edit] (label) {file} edit the specified 'file'
[editstyle] (label) edit the current style
[editmenu] (label) edit menu.rc
[editlugins] (label) edit plugins.rc
[editextensions] (label) edit extension.rc
[editblackbox] (label) edit blackbox.rc

The 'edit' commands use the 'blackbox.editor', which is specified in extensions.rc. For example:

blackbox.editor: bbnote.exe
Shutdown commands  
[logoff] (label) logoff (*)
[suspend] (label) suspend the computer (*)
[hibernate] (label) hibernate (*)
[reboot] (label) reboot the computer (*)
[shutdown] (label) shutdown the computer (*)
[lockworkstation] (label) lock workstation
[switchuser] (label) fast user switch
[exitwindows] (label) display standard shutdown dialog

(*) You can add -q(uiet) for no confirmation. For example

[logoff -q] (Log Out)
External commands  
[run] (label) show the windows 'run' dialog
[exec] (label) {command} run a program (*) or execute a broam.

(*) Optionally a working directory or a start workspace can be specified, or a (console-) program can be started in an hidden window:

[exec] (label) { -in "c:\working-dir" : program args ... }
[exec] (label) { -workspace2 : program args ... }
[exec] (label) { -hidden : program args ... }


Generally, the background can be an image or a dynamically generated gradient. The background is specified in the current style with a line that starts like:

rootCommand: bsetroot -full "backgrounds\your_image.jpg"

Click on bsetroot.exe to get some help with it. See also the documentation for bsetroot.exe.

bbLean uses bsetroot.exe to generate the background and then either displays it on its own or lets Windows set the wallpaper, depending on the setting of 'Smart Wallpaper' in 'Configuration->Graphics'.

Also any processing of the rootCommand may be disabled in 'Configuration->Graphics'.

Desktop Margins

Desktop Margins are the areas of the screen that aren't covered by maximized windows. They can be set to adjust automatically according to the placement of the bars or manually from the configuration menu.

Multiple monitors: Automatic adjustement is supposed to work independently on monitors. Margins for a 2nd monitor may be set manually in extensions.rc like:

blackbox.desktop.2.marginLeft: ...

Sticky Windows

List each application to be common among all workspaces on a separate line in 'StickyWindows.ini' (located in the blackbox.exe's folder), save the changes, and 'reconfigure.'

Click 'Show Appnames' from 'Configuration->Misc.' to get a list of the currently running tasks and their internal names.

Install as Shell

bbLean can be run on top of explorer or installed as default shell. To install bbLean as default shell, use the included bsetshell tool.

On Win2k/XP/Vista you can install bbLean for all users or for certain users only. To install bbLean for certain users only you first need to run bsetshell as administrator (right-click -> "Run as ...") and enable "per-user" shell setting. Then from the user account set blackbox as shell for that user.



-help Show version and commandline info
-install Install Blackbox as default shell
-uninstall Reset Explorer as default shell
-nostartup Do not run startup programs
-rc <file> Specify alternate blackbox.rc
-exec <@broam> Send broadcast message to running shell

Broadcast Messages

Broadcast messages (Broams) are messages sent to Blackbox and plugins to trigger some actions.

They may be sent

[exec] (label) {@BroadcastMessage}
..., WithAction(@BBCore.ShowMenu)

Broadcast messages recognized by the core:

@BBCore.ShowMenu show pinned menu, or main menu as default
@BBCore.ShowMenu Root show the main menu
@BBCore.ShowMenu Workspaces show workspaces menu
@BBCore.ShowMenu Tasks show menu with all tasks
@BBCore.ShowMenu Icons show menu with minimized tasks
@BBCore.ShowMenu Configuration show configuration menu
@BBCore.ShowMenu <path> show folder as specified
@BBCore.ShowMenu <menu.rc> display alternative menu as specified
@BBCore.HideMenu hide all menus that are not 'pinned'

ShowMenu Options  
@BBCore.ShowMenu -at x,y ... show menu at position x,y as specified
@BBCore.ShowMenu -at rb x,y ... align at position with right and/or bottom edge
@BBCore.ShowMenu -key ... show menu at position as in blackbox.rc
@BBCore.ShowMenu -toggle hide menu if it currently has focus
@BBCore.ShowMenu -pinned ... make menu stay permanently
@BBCore.ShowMenu -ontop ... make menu stay on top
@BBCore.ShowMenu -notitle ... show title-less menu

@BBCore.PrevWindow activate previous window
@BBCore.NextWindow activate next window
@BBCore.PrevWindowAllWorkspaces activate previous window (all workspaces)
@BBCore.NextWindowAllWorkspaces activate next window (all workspaces)
@BBCore.RaiseWindow bring bottom window on top
@BBCore.LowerWindow send top window to bottom
@BBCore.ShadeWindow shade window
@BBCore.StickWindow make window appear on all workspaces
@BBCore.OnTopWindow make window always on top
@BBCore.MinimizeWindow minimize window
@BBCore.MaximizeWindow maximize window
@BBCore.MaximizeVertical maximize window vertically
@BBCore.MaximizeHorizontal maximize window horizontally
@BBCore.RestoreWindow restore window
@BBCore.MoveWindow move the window
@BBCore.ResizeWindow resize the window
@BBCore.CloseWindow close window
@BBCore.ActivateWindow activate the window in the foreground

All Windows  
@BBCore.MinimizeAll minimize all windows
@BBCore.RestoreAll restore all windows
@BBCore.Cascade cascade windows
@BBCore.TileVertical tile windows vertically
@BBCore.TileHorizontal tile windows horizontally

@BBCore.PrevWorkspace previous workspace
@BBCore.NextWorkspace next workspace
@BBCore.SwitchToWorkspace #n switch to workspace number #n
@BBCore.LastWorkspace switch to last used workspace
@BBCore.MoveWindowLeft move window to previous workspace
@BBCore.MoveWindowRight move window to next workspace
@BBCore.MoveWindowToWS #n move window to workspace number #n and switch WS
@BBCore.SendWindowToWS #n send window to workspace number #n and don't switch
@BBCore.GatherWindows gather all windows in the current workspace
@BBCore.AddWorkspace add another workspace
@BBCore.DelWorkspace remove the last workspace
@BBCore.EditWorkspaceNames edit the names of workspaces

@BBCore.toggleplugins toggle plugins (if configured to 'toggle with plugins')
@BBCore.toggleplugins true/false show/hide plugins (if configured to 'toggle with plugins')
@BBCore.aboutstyle display style info
@BBCore.aboutplugins display plugin info
@BBCore.about display core info
@BBCore.reconfig reload style-settings and rc-settings
@BBCore.restart [-p] unload and reload all plugins. (*) -p(ause) = paused restart.
@BBCore.exit [-q] exit the blackbox shell. -q(uiet) = no confirmation.

@BBCore.editstyle run the 'blackbox editor' on the current style
@BBCore.editmenu run the 'blackbox editor' on menu.rc
@BBCore.editplugins run the 'blackbox editor' on plugins.rc
@BBCore.editextensions run the 'blackbox editor' on extensions.rc
@BBCore.editblackbox run the 'blackbox editor' on blackbox.rc
@BBCore.edit <file> run the 'blackbox editor' on the specified file

The 'blackbox editor' is specified in extensions.rc.

@BBCore.shutdown [-q] shutdown the computer. -q(uiet) = no confirmation.
@BBCore.reboot [-q] reboot the computer
@BBCore.logoff [-q] logoff
@BBCore.hibernate [-q] hibernate
@BBCore.suspend [-q] suspend the computer
@BBCore.lockworkstation lock workstation
@BBCore.switchuser fast user switch
@BBCore.exitwindows display standard shutdown dialog

@BBCore.exec <command> execute command <stylefile> apply the specified style
@BBCore.rootCommand <command> set wallpaper, command is any line, 'style' or 'none'. display the windows 'run' dialog
@BBCore.message <message> popup a message box for confirmation
@BBCore.label <message> display message on the toolbar label for 2 seconds
@BBCore.pause #n pause for #n milliseconds
@BBCore.nop do nothing <command> execute command slightly later. Useful to unload a plugin from itself.
@BBCore.showAppnames display module information of running tasks.
@BBCore.showRecoverMenu display a menu that can be used to recover hidden windows after a crash while alternate workspace method was enabled. Use with care.

@BBCfg.plugin.load <plugin> load/unload a plugin
@BBCfg.plugin.inslit <plugin> toggle slit mode for plugin
@BBCfg.plugin.add <pathToPlugin> add a plugin to the list and load it

Any '@BBCfg...' command that toggles a setting, can have an optional argument 'true' or 'false' to specify the new state. For example to unload bbLeanBar if loaded and do nothing otherwise:

@BBCfg.plugin.load bbLeanBar false

Use the Show Bro@ms option in Configuration->Menus to view other broadcast messages for core configuration and plugins.


This is to execute multiple commands on one broadcast message. The command list must be enclosed into '[ ]'s, and single commands are separated by '|'s and may be broams or external executables.

@Script [@SomeBroam | some_prog arguments | @AnotherBroam]


Hotkeys are done with the 'bbKeys' plugin and its configuration file 'bbKeys.rc'. The line-format in bbkeys.rc is like this:

KeyToGrab(<hotkey>), WithModifier(<modifiers>), WithAction(<action>)

Available hotkeys:

Available modifiers:

Available actions:

Default Hotkey Bindings:

Clock Formatting

These codes are used for formatting the clock displays, for ...

session.screen0.strftimeFormat: %#I:%M:%S %p
bbleanbar.strftimeFormat: %d %a %#H:%M
Label Value
%a Abbreviated weekday name
%A Full weekday name
%b Abbreviated month name
%B Full month name
%c Date and time representation appropriate for locale
%d Day of month as decimal number (01 - 31)
%H Hour in 24-hour format (00 - 23)
%I Hour in 12-hour format (01 - 12)
%j Day of year as decimal number (001 - 366)
%m Month as decimal number (01 - 12)
%M Minute as decimal number (00 - 59)
%p Current locale's A.M./P.M. indicator for 12-hour clock
%S Second as decimal number (00 - 59)
%U Week of year as decimal number, with Sunday as first day of week (00 - 53)
%w Weekday as decimal number (0 - 6; Sunday is 0)
%W Week of year as decimal number, with Monday as first day of week (00 - 53)
%x Date representation for current locale
%X Time representation for current locale
%y Year without century, as decimal number (00 - 99)
%Y Year with century, as decimal number
%z Either the time-zone name or time zone abbreviation, depending on registry settings; no characters if time zone is unknown
%Z same as above
%% Percent sign
%K Special extension with bbLeanBar: Two letter abbreviation for the active keyboard layout

The # flag modifies some of the above as follows:

Format Effect
%#c Long date and time representation, appropriate for current locale.
%#x Long date representation, appropriate to current locale.
%#d,H,I,j,m,M,S,U,w,W,y,Y Remove leading zeros (if any).
%#a,A,b,B,p,X,z,Z,% # flag is ignored


You can set another language for the clock display in extensions.rc.

blackbox.options.locale: <locale-id>

For locale-id's see


Experimental options in extensions.rc

Some options are supported to disable parts of the bbLean shell for special purposes:

Option Default Description
blackbox.options.hideExplorer true hide desktop icons when run under explorer (Q)
blackbox.options.hideTaskbar true hide explorer taskbar when run under explorer (Q)
blackbox.options.disableTray false do not receive tray events (Q)
blackbox.options.disableMargins false do not set desktop margins (Q)
blackbox.options.disableVWM false disable workspaces (Q)
blackbox.options.disableDDE false do not initialize DDE in shdocvw.dll (Q)
blackbox.options.shellContextMenu false use plain grey context menu (right-click)
blackbox.options.disableDesk false do not create an own desktop window (Q)
blackbox.options.desktopHook false use deskhook.dll to receive desktop clicks (Q) (D)

(R) Restart the shell to apply - (Q) Quit and restart the shell to apply - (L) Logout and login again to apply

(D) deskhook.dll can be used in combination with no own desktop window to receive mouse clicks on the explore desktop background. deskhook.dll is not part of the binary package, but is included in the source code.


Other options for extensions.rc:

Option Default Description
blackbox.options.openFolderCommand explorer for menu double-click, e.g. explorer.exe /e,"%1" (R)
blackbox.options.locale C locale identifier for clock and date strings (R)
blackbox.options.UTF8Encoding false use unicode and read menu.rc etc. as UTF-8 files (R)
blackbox.options.OldTray false Vista Support with older Taskbars (e.g. SystembarEx) (Q)
blackbox.options.translation   translation file for messages and menus. See "docs/nls-c.txt" (R)
blackbox.options.log   enable blackbox.log. Possible options: Startup, Tray (L)
blackbox.editor notepad editor to edit styles and rc files (R)   program or script to run after system startup (L)
blackbox.contextmenu.itemAdjust 28/28 left adjust for contextmenus/sendto. (R)
blackbox.appearance.bullet.bitmap   bitmap for menu bullets. See "docs/menu-bullets.bmp" (R)

(R) Restart the shell to apply - (Q) Quit and restart the shell to apply - (L) Logout and login again to apply


bbLean runs on windows versions 95/98/me/2000/xp/vista. Still there may be potential problems:

Systray icons missing:
You need to install blackbox as shell to get all systray icons. See -> Install as Shell
Shell crashes, hangs, does not start, etc.:
Unload all plugins first, then try again. Also some anti-virus/spyware programs cah cause problems with bbLeanSkin and/or blackbox itself.
Drawing issues with applications, unresponsive applications:
May be caused by bbLeanSkin. See bbLeanSkin/readme.txt for details on how to exclude applications from being skinned. Also, on XP/Vista it is recommended to use the 'Windows Classic' design option (in 'Display Properties').
Titlebars flickers:
May happen with bbLeanSkin when the caption text is frequently updated. Can't be fixed.
Find files:
Does not work from the context menu. Hit F3 or Ctrl-F in an explorer window instead. Or use an alternate tool like Agent Ransack...
Network Places and Recent Documents folder don't update:
This also does not seem to work without the explorer shell. On a blackbox menu you can press F5 to refresh.
'SendTo' or 'Open With' menus empty or scrambled:
Turn off 'ClearType' fonts (XP/Vista).
Plugins conflict with gaming:
Disable 'Always On Top' and 'AutoHide' with plugins. Or hit Win+Ctrl+P to toggle plugin visibility.
Lost Windows, other issues with workspaces:
Hit Win-G to 'Gather Windows' in the current workspace. If the problem continues, try 'Alternate Workspace Method' off or on, respectively. With Winamp, checkout its 'LiteStep Virtual Desktop' options, or add it to StickyWindows.ini.
Browse long menus:
Drag the scroll button (under the menu titlebar) or use the mouse wheel or the arrow keys.
Show file extensions in menus:
Uncheck "Hide Extensions for Known File Types" in windows explorer options.
Memory usage:
bbLean itself uses about 1..2MB. However as it is the shell, bbLean is also responsible to load other things into its own process. For example on Vista just loading the systray applets causes something like 15MB additional memory usage. Of course if you don't need the network and volume icons, you could always compile your own bb-super-lean version.
Unknow procedure DrawShadowText in comctl32.dll:
This is a problem in the Microsoft products. See It means basically that some application has an old comctl32.dll installed, most likely in its own directory. Try to remove that dll or rename it to something else.
Windows 95:
You might need to install msvcrt.dll.