All themes should install by simply downloading them to ~/.blackbox/ then unzip it, and de-tar it.

On open Unixes this will be:

tar zxvf stylename.tar.gz

On commercial Unixes this will be something like:

gunzip stylename.tar.gz && tar xvf stylename.tar

Check your system manuals for specifics or check with your network administrator.

An entry should appear in the styles menu immediately.

Security Warning
Style files can execute shell scripts and other
executables. It would is wise to check the
rootCommand in the style file and make sure that
it is benign.

Things that go wrong.

1. The theme is pre Blackbox 0.51.

Style file syntax changed with version 0.51

2. The style tarball was formatted incorrectly.

Some styles use the directories ~/.blackbox/Backgrounds and ~/.blackbox/Styles

This can fixed by adding a [stylemenu] (~/.blackbox/Styles) to your menu file. To be a complete purist, hack the style file with the correct paths and move the files into the correct directories

3. The rootCommmand line is broken.

The rootCommand line in the style file will run an arbitrary executable. It is important that this executable be set to bsetbg to maintain portability between systems with different graphics software. In addition bsetbg can execute a shell script and do it in a portable fashion as well.

The documented method for creating styles is as follows:

1. Create or acquire the background for the style if

it will not be using bsetroot to draw a patterned background for the root window.

NOTE:
Blackbox runs on a wide variety
of systems ranging from PCs with 640x480 256 color
displays to ultra high speed workstations with 25"
screens and extreme resolution. For best results a
style graphic should be at least 1024x768.

2. Create a style file.

The best way to do this is to make a copy of a similar style and then edit it.

The style file is a list of X resources and other external variables. Manipulating these variables allows users to completely change the appearance of Blackbox. The user can also change the root window image by using the wrapper program bsetbg.

bsetbg knows how to use a number of programs to set the root window image. This makes styles much more portable since various platforms have different graphics software. For more info see bsetbg (1).

3. Background images should be placed in

~/.blackbox/backgrounds The style file should be placed in ~/.blackbox/styles any other information about the style should be placed in ~/.blackbox/about/STYLE_NAME/. This would include README files, licenses, etc.

Previous versions of Blackbox put backgrounds and styles in different directories. The directories listed above are the only officially supported directories. However you may put them whereever you like as long as you update your menu file so it knows where to find your styles.

4. To create a consistent experience and to ensure

portability between all systems it is important to use the following format to create your style archive.

first create a new directory named after your style NEW_STYLE

In this directory create the directories

backgrounds
styles
about/NEW_STYLE

Next put everything for the theme in these locations. Finally type

tar cvzf NEW_STYLE.tar.gz *

If you are using commercial Unix you may need to use gzip and tar separately.

Now when a user downloads a new style file she knows that all she has to do is put the tarball in her Blackbox directory, unzip->un-tar it and then click on it in her style menu.

By far the easiest way to create a new style is to use bbconf. bbconf allows complete control of every facet of style files and gives immediate updates of the current style as changes are made.

The style file format is not currently documented in a man page. There is a readme document included with the Blackbox source containing this information.

To create a personal menu copy the default menu to a file in your home directory. Then, open ~/.blackboxrc and add or modify the resource session.menuFile: ~/.blackbox/menu

Next, edit the new menu file. This can be done during a Blackbox session and the menu will automatically be updated when the code checks for file changes.

The default menu included with Blackbox has numerous comments describing the use of all menu commands. Menu commands follow this general form:

[command] (label|filename) {shell command|filename}

Blackbox menu commands:

# string...

Hash (or pound or number sign) is used as the comment delimiter. It can be used as a full line comment or as an end of line comment after a valid command statement.

[begin] (string)

This tag is used only once at the beginning of the menu file. "string" is the name or description used at the top of the menu.

[end]

This tag is used at the end of the menu file and at the end of a submenu block.

[exec] (label string) {command string}

This is a very flexible tag that allows the user to run an arbitrary shell command including shell scripts. If a command is too large to type on the command line by hand it is best to put it in a shell script.

[nop] (label string)

This tag is used to put a divider in the menu. label string is an optional description.

[submenu] (submenu name) {title string}

[submenu] (submenu name) {title string}

This creates a sub-menu with the name submenu name and if given, the string title string will be the title of the if given, the string title string will be the title of the pop up menu itself.

[include] (filename)

This command inserts filename into the menu file at the point at which it is called. filename should not contain a begin end pair. This feature can be used to include the system menu or include a piece of menu that is updated by a separate program.

[stylesdir] (description) (path)

Causes Blackbox to search path for style files. Blackbox lists styles in the menu by their file name as returned by the OS.

[stylesmenu] (description) {path}

This command creates a submenu with the name description with the contents of path. By creating a submenu and then populating it with stylesmenu entries the user can create an organized library of styles.

[workspaces] (description)

Inserts a link into the main menu to the workspace menu. If used, description is an optional description.

[config] (label)

This command causes Blackbox to insert a menu that gives the user control over focus models, dithering and other system preferences.

[reconfig] (label) {shell command}

The reconfig command causes Blackbox to reread its configuration files. This does not include ~/.blackboxrc which is only reread when Blackbox is restarted. If shell command is included Blackbox will run this command or shell script before rereading the files. This can be used to switch between multiple configurations

[restart] (label) {shell command}

This command is actually an exit command that defaults to restarting Blackbox. If provided shell command is run instead of Blackbox. This can be used to change versions of Blackbox. Not that you would ever want to do this but, it could also be used to start a different window manager.

[exit] (label)

Shuts down Blackbox. If Blackbox is the last command in your ~/.xinitrc file, this action will also shutdown X.

Here is a working example of a menu file:
[begin] (MenuName)
   [exec] (xterm) {xterm -ls -bg black -fg green}
   [submenu] (X utilities)
      [exec] (xcalc) {xcalc}
   [end]
   [submenu] (styles)
      [stylesmenu] (built-in styles) {/usr/share/blackbox/styles}
      [stylesmenu] (custom styles) {~/.blackbox/styles}
   [end]
   [workspaces] (workspace list)
   [config] (configure)
   [reconfig] (config play desktop) {play-config-blackbox}
   [reconfig] (config work desktop) {work-config-blackbox}
   [restart] (start Blackbox beta 7) {blackbox-beta7}
   [restart] (start Blackbox cvs) {blackbox-cvs}
   [restart] (restart)
   [exit] (exit)
[end]

NOTE: Blackbox only reads this file during start up. To make changes take effect during a Blackbox session the user must choose "restart" on the main menu. If you do not do so, your changes will be lost when Blackbox exits.

Some resources are named with a <num> after screen. This should be replaced with the number of the screen that is being configured. The default is 0 (zero).

Menu Configurable (Slit Menu):

Right click (button 3) on the slit border.

session.screen<num>.slit.placement SEE BELOW

Determines the position of the slit. Certain combinations of slit.placement with slit.direction are not terribly useful, i.e. TopCenter with Vertical direction puts the slit through the middle of your screen. Certainly some will think that is cool if only to be different...

Default is CenterLeft.
[  TopLeft  |   TopCenter  |   TopRight  |
 CenterLeft |              | CenterRight |
 BottomLeft | BottomCenter | BottomRight ]

session.screen<num>.slit.direction [Horizontal|Vertical]

Determines the direction of the slit.

Default is Vertical.

session.screen<num>.slit.onTop [True|False]

Determines whether the slit is always visible over windows or if the focused window can hide the slit.

Default is True.

session.screen<num>.slit.autoHide [True|False]

Determines whether the slit hides when not in use. The session.autoRaiseDelay time determines how long you must hover to get the slit to raise and how long it stays visible after mouse out.

Default is False.

Menu Configurable (Main Menu):

session.screen<num>.focusModel SEE BELOW

Sloppy focus (mouse focus) is the conventional X Window behavior and can be modified with AutoRaise or Click-Raise.

AutoRaise causes the window to automatically raise after session.autoRaiseDelay milliseconds.

ClickRaise causes the window to raise if you click anywhere inside the client area of the window.

Sloppy focus alone requires a click on the titlebar, border or

Sloppy focus alone requires a click on the titlebar, border or lower grip to raise the window.

ClickToFocus requires a click on a Blackbox decoration or in the client area to focus and raise the window. ClickToFocus cannot be modified by AutoRaise or ClickRaise.

Default is SloppyFocus
[SloppyFocus [[AutoRaise & ClickRaise]  |
              [AutoRaise | ClickRaise]] |
ClickToFocus]

session.screen<num>.windowPlacement SEE BELOW

RowSmartPlacement tries to fit new windows in empty space by making rows. Direction depends on session.screen<num>.rowPlacementDirection

ColSmartPlacement tries to fit new windows in empty space by making columns Direction depends on session.screen<num>.colPlacementDirection

CascadePlacement places the new window down and to the right of the most recently created window.

Default is RowSmartPlacement.
[RowSmartPlacement | ColSmartPlacement | CascadePlacement]

session.screen<num>.rowPlacementDirection [LeftToRight|RightToLeft]

Determines placement direction for new windows.

Default is LeftToRight.

session.screen<num>.colPlacementDirection [TopToBottom|BottomToTop]

Determines placement direction for new windows.

Default is TopToBottom.

session.imageDither [True|False]

This setting is only used when running in low color modes. Image Dithering helps to show an image properly even if there are not enough colors available in the system.

Default is False.

session.opaqueMove [True|False]

Determines whether the window's contents are drawn as it is moved. When False the behavior is to draw a box representing the window.

Default is False.

session.screen<num>.fullMaximization [True|False]

Determines if the maximize button will cause an application to maximize over the slit and toolbar.

Default is False.

session.screen<num>.focusNewWindows [True|False]

Determines if newly created windows are given focus after they initially draw themselves.

Default is False. 

session.screen<num>.focusLastWindow [True|False]

This is actually "when moving between workspaces, remember which window has focus when leaving a workspace and return the focus to that window when I return to that workspace."

Default is False.

session.screen<num>.disableBindingsWithScrollLock [True|False]

When this resource is enabled, turning on scroll lock keeps Blackbox from grabbing the Alt and Ctrl keys that it normally uses for mouse controls. This feature allows users of drawing and modeling programs which use keystrokes to modify mouse actions to maintain their sanity. *NOTE* this has _no_ affect on bbkeys. If you need bbkeys to also behave this way it has a similar option in its config file. Refer to the bbkeys manpage for details.

Default is False.

Menu Configurable (Workspace Menu):

Middle click (button 2) on the root window (AKA Desktop) to reach this menu

session.screen<num>.workspaces [integer]

Workspaces may be created or deleted by middle clicking on the desktop and choosing "New Workspace" or "Remove Last". After creating a workspace, right click on the toolbar to name it.

Default is 1

Menu Configurable (Toolbar Menu):

session.screen<num>.workspaceNames [string[, string...]]

Workspaces are named in the order specified in this resource. Names should be delimited by commas. If there are more workspaces than explicit names, un-named workspaces will be named as "Workspace [number]".

Default is 
Workspace 1.

session.screen<num>.toolbar.placement SEE BELOW

Set toolbar screen position.

Default is BottomCenter
[  TopLeft  |   TopCenter  |   TopRight  |
 BottomLeft | BottomCenter | BottomRight ]

session.screen<num>.toolbar.onTop [True|False]

Determines whether the toolbar is always visible over windows or if the focused window can hide the toolbar.

Default is True.

session.screen<num>.toolbar.autoHide [True|False]

Determines whether the toolbar hides when not in use. The session.autoRaiseDelay time determines how long you must hover to get the toolbar to raise, and how long it stays visible after mouse out.

Default is False.

Configurable in ~/.Blackboxrc only:

session.screen<num>.toolbar.widthPercent [1-100]

Percentage of screen used by the toolbar. A number from 1-100 that sets the width of the toolbar. 0 (zero) does not cause the toolbar to disappear, instead the toolbar is set to the default. If you want to lose the toolbar there are patches that can remove it.

Default is 66.

session.screen<num>.strftimeFormat [string]

A C language date format string, any combination of specifiers can be used. The default is %I:%M %p which generates a 12 hour clock with minutes and an am/pm indicator appropriate to the locale.

24 hours and minutes    %H:%M
12 hours and minute     %I:%M %p
month/day/year          %m/%d/%y
day/month/year          %d/%m/%y

Default is hours:minutes am/pm
See
strftime 3
for more details.

session.screen<num>.dateFormat [American|European]

NOTE: Only used if the strftime() function is not available on your system.

Default is American, (mon/day/year).

session.screen<num>.clockFormat [12/24]

NOTE: Only used if the strftime() function is not available on your system.

Default is 12-hour format.

session.screen<num>.edgeSnapThreshold [integer]

When set to 0 this turns off edge snap. When set to one or greater edge snap will cause a window that is being moved to snap to the nearest screen edge, the slit, or or the toolbar. Windows will not snap to each other. The value represents a number in pixels which is the distance between the window and a screen edge which is required before the window is snapped to the screen edge. If you prefer this functionality values between 6 - 10 work nicely.

Default value is 0

session.menuFile [filepath]

Full path to the current menu file.

Default is /usr/share/blackbox/menu

session.colorsPerChannel [2-6]

The number of colors taken from the X server for use on pseudo color displays. This value must be set to 4 for 8 bit displays.

Default is 4.

session.doubleClickInterval [integer]

This is the maximum time that Blackbox will wait after one click to catch a double click. This only applies to Blackbox actions, such as double click shading, not to the X server in general.

Default is 250 milliseconds.

session.autoRaiseDelay [integer]

This is the time in milliseconds used for auto raise and auto hide behaviors. More than about 1000 ms is likely useless.

Default is 250 millisecond.

session.cacheLife [integer]

Determines the maximum number of minutes that the X server will cache unused decorations.

Default is 5 minutes

session.cacheMax [integer]

Determines how many kilobytes that Blackbox may take from the X server for storing decorations. Increasing this number may enhance your performance if you have plenty of memory and use lots of different windows.

Default is 200 Kilobytes

HOME

Blackbox uses $HOME to find its .blackboxrc rc file and its .blackbox directory for menus and style directories.

DISPLAY

If a display is not specified on the command line, Blackbox will use the value of $DISPLAY.

blackbox

Application binary

~/.blackboxrc

User's startup and resource file.

/usr/share/blackbox/menu

Default system wide menu