blackbox - Man Page

a window manager for X11

Synopsis

blackbox -help | -version
blackbox [ -rc rcfile ] [ -display display ]

Description

Blackbox is a window manager for the Open Group's X Window System, Version 11 Release 6 and above. Its design is meant to be visually minimalist and fast.

Blackbox is similar to the NeXT interface and Windowmaker. Applications are launched using a menu which is accessed by right clicking on the root window. Workspaces, a system of virtual  desktops are controlled via a menu which is accessed  by middle clicking on the root window and by using  the toolbar. Individual windows can be controlled by  buttons on the title bar and more options are available  by right clicking on the title bar.

Blackbox is able to generate beautiful window decorations on the fly at high speed. Themes, called styles in Blackbox terminology, are very flexible but the use of pixmaps has been  purposefully avoided to eliminate dependencies  and excess memory usage.

Blackbox itself does not directly handle key bindings like most other window managers. This task is handled by a separate utility called bbkeys. Although Blackbox has a built-in workspace (paging) system, bbpager, which provides a graphical pager, is popular with many users. bbkeys, bbpager and several other bbtools can be found by going to

http://bbtools.thelinuxcommunity.org/

The slit is an edge of the screen which can hold specially designed programs called dock apps (from Windowmaker). In addition, the  popular program gkrellm will also run in the slit.  There is a huge selection of dockapps available  and they run the gamut from must-have gadgets  to utterly useless (but cute and/or funny) eye candy.

http://www.bensinclair.com/dockapp/
http://dockapps.org/

Options

Blackbox supports the following command line options:

-help

Display command line options, compiled-in features, and exit.

-version

Display version and exit.

-rc rcfile

Use an alternate resource file.

-display display

Start Blackbox on the specified display, and set the DISPLAY environment variable to this value for programs  started by Blackbox.

Starting and Exiting Blackbox

The most common method for starting Blackbox  is to place the the command "blackbox" (no quotes) at the end of your ~/.xinitrc or ~/.xsession file.  The advantage of putting Blackbox at the end of the file is that the X Server will shutdown when you exit  Blackbox. Blackbox can also be started from  the command line of a terminal program like xterm in an X session that does not already have a window manager running.

On startup, Blackbox will look for ~/.blackboxrc and use the resource session.menuFile to determine where to get the menu for the session.  If this file is not found Blackbox will use /usr/share/blackbox/menu as the menu file. If that fails as well Blackbox  will use a default menu that contains commands  to start an xterm as well as restart and exit the window manager. The other resources available in the ~/.blackboxrc file are discussed later in this manual under  the heading Resource File.

On exit, Blackbox writes its current configuration to ~/.blackboxrc.

NOTE:
If ~/.blackboxrc is modified during a Blackbox 
session, Blackbox must be restarted with the 
"restart" command on the main menu or the changes 
will be lost on exit. Restart causes Blackbox to 
re-read ~/.blackboxrc and apply the changes immediately.

Blackbox can be exited by selecting "exit" on the main menu (discussed shortly), killing it gently from a terminal or by the X Window System  shutdown hot key combo Ctrl+Alt+BackSpace.

Using Blackbox

A three button mouse has the following functions  when clicking on the root window:

Button Two  (Middle Button)

Open workspace menu

Button Three  (Right Button)

Open main menu

Note that Button One (Left Button) is not used.
Main Menu

The default installation assumes you have a number  of common X Window System programs in their typical locations. The default menu is defined by a plain text file named 'menu'. It is heavily commented and covers a number of details of menu file syntax. This file can also be edited graphically by using the extension program bbconf which makes menu creation very easy. Menu file syntax is discussed later in this manual.

Caveat:
Menus can run arbitrary command lines, but
if you wish to use a complex command line 
it is best to place it in a shell script. 
Remember to put #!/bin/bash on the first 
line and chmod 755 on the file to make it 
executable.
Workspace Menu

This menu gives the user control of the workspace  system. The user can create a new workspace, remove the last workspace or go to an application via either the icon menu or a workspace entry. Workspaces are listed by name. Clicking on the  workspace name will take you to that workspace with focus on the program under the mouse. If  there are programs already running in the  workspace, they will appear in a pop-out menu.  Clicking on the application name will jump to  the workspace and focus that application. If a middle click is used the window will be brought to the current workspace.

Blackbox uses an external program, bbpager, to provide a traditional, graphical paging interface to the workspace system. Many Blackbox users run another extension program - bbkeys - to provide keyboard shortcuts for workspace control.

Caveat:
To name a workspace the user must right
click on the toolbar, select "Edit current 
workspace name," type the workspace name, 
And_Press_Enter to finish.

Workspaces can also be named in the .blackboxrc file as described in RESOURCES.

The Slit

The Slit provides a user positionable window for  running utility programs called "dockapps". To  learn more about dockapps refer to the web sites mentioned in the Description. Dockapps  automatically run in the slit in most cases, but may require a special command switch.   Often, -w is used for "withdrawn" into the slit.

gkrellm is a very useful and modern dockapp that gives the user near real time information on  machine performance. Other dockapps include clocks, notepads, pagers, key grabbers, fishbowls, fire places and many, many others.

Only mouse button three is captured by the  Blackbox slit. This menu allows the user to change  the position of the slit, and sets the state of  Always on top, and Auto hide. These all do what  the user expects.

Caveat:
When starting Dockapps from an external script
a race condition can take place where the shell
rapidly forks all of the dockapps, which then
take varied and random times to draw themselves 
for the first time. To get the dockapps to start 
in a given order, follow each dockapp with 
sleep 2; This ensures that each dockapp is placed 
in the correct order by the slit.
i.e.
#!/bin/bash
speyes -w & sleep 2
gkrellm -w & sleep 2
The Toolbar

The toolbar provides an alternate method for  cycling through multiple workspaces and  applications. The left side of the toolbar is  the workspace control, the center is the  application control, and the right side is a clock. The format of the clock can be controlled as described under RESOURCES.

Mouse button 3 raises a menu that allows  configuration of the toolbar. It can be  positioned either at the top or the bottom  of the screen and can be set to auto hide  and/or to always be on top.

Caveat:
The toolbar is a permanent fixture. It 
can only be removed by modifying the source and 
rebuilding, which is beyond the scope of this 
document. Setting the toolbar to auto hide is
the next best thing.
Window Decorations

Window decorations include handles at the bottom of each window, a title bar, and three control buttons. The handles at the bottom of the window are divided  into three sections.  The two corner sections are  resizing handles The center section is a window  moving handle. The bottom center handle and the  title bar respond to a number of mouse clicks and  key + mouse click combinations. The three buttons in the title bar, left to right, are iconify, maximize, and close. The resize button has special behavior  detailed below.

Button One  (Left Button)

Click and drag on titlebar to move or resize from bottom corners. Click the iconify button to move the window to the icon list. Click the maximize button to fully maximize the window. Click the close button to close the window and application. Double-Click the title bar to shade the window.

Alt + Button One

Click anywhere on client window and drag to move the window.

Button Two  (Middle Button)

Click the titlebar to lower the window. Click the maximize button to maximize the window vertically.

Button Three  (Right Button)

Click on title bar or bottom center handle pulls down a control menu. Click the maximize button to maximize the window horizontally.

Alt + Button Three

Click anywhere on client window and drag to resize the window.

The control menu contains:
Send To ...
Button One  (Left Button)
Click to send this window to another workspace.
Button Two  (Middle Button)
Click to send this window to another workspace, change 
to that workspace and keep the application focused.
as well.
    Shade
    This is the same action as Double-Click with Button One.
    Iconify
    Hide the window.  It can be accessed with the icon menu.
    Maximize
    Toggle window maximization.
    Raise
    Bring window to the front above the other windows and
    focus it.
    Lower
    Drop the window below the other ones.
    Stick
    Stick this window to the glass on the inside of
    the monitor so it does not hide when you change 
    workspaces.
    Kill Client
    This kills the client program with -SIGKILL (-9)
    Only use this as a last resort.
    Close
    Send a close signal to the client application.

Styles

Styles are a collection of colors, fonts, and textures that control the appearance of Blackbox. These characteristics are recorded in style files. The default system style files are located in /usr/share/blackbox/styles. The menu system will identify the style by  its filename, and styles can be sorted into different directories at the user's discretion.

There are over 700 styles available for  Blackbox. The official distribution point for  Blackbox styles is

    http://blackbox.themes.org/

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.

Style File Syntax and Details

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.

Resource File

$HOME/.blackboxrc These options are stored in the ~/.blackboxrc file. They control various features of Blackbox and most can be set from menus. Some of these can only be set by editing .blackboxrc directly.

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

Environment

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.

Files

blackbox

Application binary

~/.blackboxrc

User's startup and resource file.

/usr/share/blackbox/menu

Default system wide menu

Web Sites

General info website:

http://blackboxwm.sourceforge.net/

Development website:

http://sourceforge.net/projects/blackboxwm/

Bugs

If you think you have found a bug, please help by going to the development website and select "Bugs" in the upper menu. Check the bug list to see if your problem has already been reported. If it has please read the summary and add any information that you believe would help. If your bug has not been  submitted select "Submit New" and fill out the form.

Authors and History

Sean Shaleh Perry <shaleh@debian.org> is the current maintainer and is actively working  together with Brad to keep Blackbox up-to-date and  stable as a rock.

Brad Hughes  <bhughes@trolltech.com> originally designed and coded Blackbox in 1997 with  the intent of creating a memory efficient window  manager with no dependencies on external libraries.  Brad's original idea has become a popular alternative  to other window managers.

Jeff Raven  <jraven@psu.edu> then picked up the torch for the 0.61.x series after  Brad took a full time job at TrollTech.

This manual page was written by: R.B. Brig Young <secretsaregood@yahoo.com> he is solely responsible for errors or omissions.  Comments, corrections, and suggestions are welcomed.

See Also

bsetbg(1), bsetroot(1), 
bbkeys(1), bbconf(1)

Referenced By

bbkeysrc(5), bsetbg(1), bsetroot(1), xde-menu(1).

September 18, 2002 0.65.0