Blackbox uses configuration files called styles to control the look of its three main components: the toolbar, the menus and (in the future) the window decorations. These styles contain information about what colours, textures and fonts should be used for each element. Furthermore, third party plugins can read these style settings through the Blackbox API, making it possible to get the same look for all Blackbox user interface elements.

The default installation of Blackbox for Windows includes a few styles, located in the "styles" subfolder of the Blackbox folder (following the classic bb.themes.org naming scheme, used by most downloadable styles out there). We recommend that you study and/or edit these files to get a feeling of how the Blackbox style mechanism works (you can use the [style], [stylesdir] and [stylesmenu] commands in your menu file to be able to select between and change styles on the fly, and the [editstyle] command for quick access to the current style file).

Style resources consist of a key and a value. The key is constructed of several smaller keys (sometimes referred to as children), delimited by a period ('.'). Keys may also contain a star ('*') to serve as a wildcard, which means that one line of typed text will match several keys. This is useful for styles that are based on one or two colours. Here are some quick examples:

toolbar.clock.color: green
Sets the color resource of the toolbar clock to 'green.'
menu*color: rgb:3/4/5
Sets the color resource of the menu and all of its 'children' to 'rgb:3/4/5', ie. it also applies to "menu.title.color" and "menu.frame.color".
*font: verdana
Sets all Blackbox elements to use the same font. Font sizes are used with the settings "menu.frame.textHeight" and "menu.title.textHeight".

Now, what makes Blackbox so spectacular is its ability to render textures on the fly. Texture descriptions are specified directly to the key that they should apply to, e.g.:

toolbar.clock: Raised Gradient Diagonal Bevel1
toolbar.clock.color: rgb:8/6/4
toolbar.clock.colorTo: rgb:4/3/2

A texture description consists of up to five fields, which are as follows:

Flat / Raised / Sunken
Gives the component either a flat, raised or sunken appearance.
Gradient / Solid
Tells Blackbox to draw either a solid color or a gradient texture.
Horizontal / Vertical / Diagonal / Crossdiagonal / Pipecross / Elliptic / Rectangle / Pyramid
These only work when Gradient is also specified, and selects the type of gradient to use.
Interlaced
Tells Blackbox to interlace the texture (darken every other line).
Bevel1 / Bevel2
Tells Blackbox which type of bevel to use. Bevel1 is the default bevel, and sets the shading to be placed on the edge of the image. Bevel2 is an alternative, and sets the shading to be placed one pixel in from the edge of the image.

The option "ParentRelative" can be used instead of a texture description, which makes the component appear as a part of its parent, i.e. totally transparent.

All gradiented textures are composed of two colour values: the "color" and "colorTo" resources. The complete list of components and what kind of value they can contain can be found below. Any line in the style file that starts with an exclamation mark ('!') is considered a comment and ignored by Blackbox. Please note that not all of the settings in the list below (as specified by the *nix version) are used by Blackbox for Windows at this early stage, but eventually they will be... 8)


! The toolbar itself
toolbar: Texture
toolbar.color: Color
toolbar.colorTo: Color

! The buttons on the toolbar
toolbar.button: Texture or ParentRelative
toolbar.button.color: Color
toolbar.button.colorTo: Color

! Color of the button arrows
toolbar.button.picColor: Color

! Buttons in pressed state
toolbar.button.pressed: Texture or ParentRealtive
toolbar.button.pressed.color: Color
toolbar.button.pressed.colorTo: Color

! Color of pressed button arrows
toolbar.button.pressed.picColor: Color

! The toolbar workspace label
toolbar.label: Texture or ParentRelative
toolbar.label.color: Color
toolbar.label.colorTo: Color
toolbar.label.textColor: Color

! The toolbar window label
toolbar.windowLabel: Texture or ParentRelative
toolbar.windowLabel.color: Color
toolbar.windowLabel.colorTo: Color
toolbar.windowLabel.textColor: Color

! The toolbar clock
toolbar.clock: Texture or ParentRealtive
toolbar.clock.color: Color
toolbar.clock.colorTo: Color
toolbar.clock.textColor: Color

! How the toolbar's text should be justified
toolbar.justify: center, left, or right

! Font to be used for all toolbar components
toolbar.font: Font

! The menu titlebar
menu.title: Texture
menu.title.color: Color
menu.title.colorTo: Color
menu.title.textColor: Color
menu.title.font: Font
menu.title.justify: center, left, or right

! The menu frame
menu.frame: Texture
menu.frame.color: Color
menu.frame.colorTo: Color
menu.frame.textColor: Color
menu.frame.disableColor: Color
menu.frame.font: Font
menu.frame.justify: center, left, or right

! Bullets for submenu items
menu.bullet: empty, triangle, square, circle or diamond
menu.bullet.position: right or left

! The highlighted menu item
menu.hilite: Texture (e.g. Raised)
menu.hilite.color: Color
menu.hilite.colorTo: Color
menu.hilite.textColor: Color

! A focused window
window.title.focus: Texture
window.title.focus.color: Color
window.title.focus.colorTo: Color

! An unfocused window
window.title.unfocus: Texture
window.title.unfocus.color: Color
window.title.unfocus.colorTo: Color

! Window label
window.label.focus: Texture or ParentRelative
window.label.focus.color: Color
window.label.focus.colorTo: Color
window.label.focus.textColor: Color

window.label.unfocus: Texture or ParentRelative
window.label.unfocus.color: Color
window.label.unfocus.colorTo: Color
window.label.unfocus.textColor: Color

! Handle bar
window.handle.focus: Texture
window.handle.focus.color: Color
window.handle.focus.colorTo: Color

window.handle.unfocus: Texture
window.handle.unfocus.color: Color
window.handle.unfocus.colorTo: Color

! Resize grips
window.grip.focus: Texture
window.grip.focus.color: Color
window.grip.focus.colorTo: Color

window.grip.unfocus: Texture
window.grip.unfocus.color: Color
window.grip.unfocus.colorTo: Color

! Window buttons
window.button.focus: Texture or ParentRealtive
window.button.focus.color: Color
window.button.focus.colorTo: Color
window.button.focus.picColor: Color

window.button.unfocus: Texture or ParentRealtive
window.button.unfocus.color: Color
window.button.unfocus.colorTo: Color
window.button.unfocus.picColor: Color

window.button.pressed: Texture
window.button.pressed.color: Color
window.button.pressed.colorTo: Color

! Frame around window
window.frame.focusColor: Color
window.frame.unfocusColor: Color

! Font and justification for window labels
window.font: Font
window.justify: center, left, or right

! Miscellaneous resources

! A border can be drawn round all components
borderWidth: A number of pixels, e.g. 1
borderColor: Color

bevelWidth: A number of pixels > 0
handleWidth: A number of pixels > 0

! Width of the window frame (from Blackbox for *nix version 0.61 and later)
! When not specified, frameWidth defaults to the value of bevelWidth
frameWidth: A number of pixels >= 0

! This command is executed whenever this style is selected,
! and typically it sets the wallpaper to a nice picture or gradient
rootCommand: Shell command, e.g. bsetroot -gradient diagonalinterlaced -from 999999 -to 111111

! Some of the (*nix) bbtools read these old Blackbox for *nix version 0.51 resources...
menuFont: Font
titleFont: Font

Remember, when you create your own style, you can easily set several keys with a single "wildcard" command...

*color: slategrey
*colorTo: darkslategrey
*unfocus.color: darkslategrey
*unfocus.colorTo: black
*textColor: white
*unfocus.textColor: lightgrey
*font: verdana

...which will give you a nice set of defaults for several components. DISCLAIMER: Wildcards are not fully implemented yet, so if you want to be on the safe side please consider using the "normal" tags for each element.

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