blackbox(1) | General Commands Manual | blackbox(1) |
blackbox - a window manager for X11
blackbox -help | -version
blackbox [ -rc rcfile ] [ -display display ]
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
0 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.
0 http://www.bensinclair.com/dockapp/ http://dockapps.org/
Blackbox supports the following command line options:
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 /etc/X11/blackbox/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.
0 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.
A three button mouse has the following functions when clicking on the root window:
0 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/sh on the first line and chmod 755 on the file to make it executable.
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.
0 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.
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.
3 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.
8 i.e. #!/bin/sh speyes -w & sleep 2 gkrellm -w & sleep 2
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.
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.
This is the same action as Double-Click with Button One.
Hide the window. It can be accessed with the icon menu.
Toggle window maximization.
Bring window to the front above the other windows and focus it.
Drop the window below the other ones.
Stick this window to the glass on the inside of the monitor so it does not hide when you change workspaces.
This kills the client program with -SIGKILL (-9) Only use this as a last resort.
Send a close signal to the client application.
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.
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
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.
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).
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.
first create a new directory named after your style NEW_STYLE
In this directory create the directories
backgrounds styles about/NEW_STYLENext 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.
The default menu file is installed in /etc/X11/blackbox/blackbox-menu. This menu can be customized as a system default menu or the user can create a personal menu.
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}
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]
$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).
Default is CenterLeft. [ TopLeft | TopCenter | TopRight |
CenterLeft | | CenterRight |
BottomLeft | BottomCenter | BottomRight ]
Default is Vertical.
Default is True.
Default is False.
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]
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]
Default is LeftToRight.
Default is TopToBottom.
Default is False.
Default is False.
Default is False.
Default is False.
Default is False.
Default is False.
Default is 1
Default is Workspace 1.
Default is BottomCenter [ TopLeft | TopCenter | TopRight |
BottomLeft | BottomCenter | BottomRight ]
Default is True.
Default is False.
Default is 66.
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.
Default is American, (mon/day/year).
0 Default is 12-hour format.
Default value is 0
Default is /etc/X11/blackbox/blackbox-menu
Default is 4.
Default is 250 milliseconds.
Default is 250 millisecond.
Default is 5 minutes
Default is 200 Kilobytes
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.
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.
bsetbg(1), bsetroot(1), bbkeys(1), bbconf(1)
September 18, 2002 | 0.65.0 |