Home | Sitemap | Last changes RSS Feed | Wiki help | Wiki tools | SandBox
Preferences | Edit this page | View source | Page history | Referrers
Document last modified: Tue, 15 Jun 2010, 20:25 UTC
Parents: BlackboxDocumentation/

Blackbox Documentation/Blackbox Configuration

This section teaches you all there is to know about configuring Blackbox via menu, configuration file or 3rd party tools.

1 About the Blackbox configuration
1.1 Where and how is it stored?
1.2 How do I change the settings?
1.3 What are X resource files?
2 The configuration file
2.1 Where is the config file located?
2.2 Using the config file safely (IMPORTANT! READ THIS!)
2.2.1 When the config file is read
2.2.2 When the config file is overwritten
2.3 I don't have a config file, how do I get one?
2.3.1 Full default config example
2.3.2 How can I produce my own?
2.4 Configuration options
2.4.1 Window placement options
2.4.2 Window behaviour options
2.4.3 Window focus options
2.4.4 Workspace options
2.4.5 Color options
2.4.6 Toolbar options
2.4.7 Slit options
2.4.8 Other options
3 The configuration menu
4 Third-party configuration tools

1) About the Blackbox configuration

1.1) Where and how is it stored?

Blackbox uses various settings which decide how it handles the windows and the various other elements which make up the desktop, such as workspaces, toolbar, slit, and so on.

The settings are stored in a configuration file, which is a simple text file, usually located somewhere in your home directory. This file is also called a resource file. Read on for more details.

1.2) How do I change the settings?

There are various methods you can use to change configuration settings.

1.3) What are X resource files?

The config file is also called a resource file because that's what it is: an X resource file.

Resource files are plain text files using a standard syntax, and which can be accessed using standard functions from the X libraries. They are specifically designed to hold preferences for any X application which cares to use them. They are somewhat similar in concept to the .ini files under Microsoft Windows.

Describing the resource files themselves is beyond the scope of this site, but you can read the manual page for X* (section "RESOURCES") if you are interested. You won't need advanced resource knowledge in order to use the main Blackbox configuration file. You only need a text editor, and the resource keywords are fairly simple to understand.

Things to keep in mind about resources:
  • A line starting with a bang sign (!) will be ignored, so it can be used for comments.
    • Don't use sharp signs (#) for comments. They are meant for "include" statements. They appear to make good comments signs only because incorrect use renders those lines invalid.
  • Empty lines or lines which only contain whitespace will be ignored.
  • Invalid keywords will be ignored.
  • Values which don't have the expected type (ie. text where a number is expected) or which don't make sense (ie. a file which can't be found) will revert to the default value.
  • On/Off values (also called "boolean" values) can be spelled with their first letter either uppercase or lowercase (ie. both True and true are accepted, but not tRuE).

2) The configuration file

The configuration file is the file which holds the main Blackbox configuration.

2.1) Where is the config file located?

The default location of the config file is ~/.blackboxrc.

The location can be overwritten using the -rc command line option. You need to pass the option to the blackbox binary executable. Usually you do this in your ~/.xinitrc or ~/.Xsession file.

Some people prefer to use the -rc option and explicitly choose a config file placed under their ~/.blackbox/ directory. This way, they have all the Blackbox files in the same place.

2.2) Using the config file safely (IMPORTANT! READ THIS!)

2.2.1) When the config file is read

Blackbox re-reads the configuration file everytime it starts (or restarts).

It DOES NOT re-read it when you click on the reconfigure menu entry. That one is only for menus and styles.

If you modify your config file by hand, it's recommended that you restart Blackbox when you're done. You can safely do this even while using X (ie. you won't lose the open applications).

2.2.2) When the config file is overwritten

The configuration file is COMPLETELY overwritten each time you click on an option in the configuration menu.

This means it is useless to add bogus entries, whitespace, empty lines or comments to the config file. They will dissapear at the next overwrite.

Normally, you shouldn't have to care much about this. People either use the configuration menu, or edit the configuration file, but very seldom at the same time.

For example, one particular and highly unlikely case you could get bitten is if you started to edit the config file, using it without saving, then used the config menu (which overwrites the file) and then quit the editor without saving. And even then you would lose only what you changed, not the config file in its entirety.

2.3) I don't have a config file, how do I get one?

2.3.1) Full default config example

See below for a full example of a default configuration file. Copy and paste it to a file on your disk, using a text editor. Read the location suggestions to decide where to keep it in the future.

This default file was produced using the latest Blackbox version. Please remember to update your style and menu file paths before you use Blackbox with it!

session.styleFile:      /usr/share/blackbox/styles/Gray
session.menuFile:       /usr/share/blackbox/menu
session.screen0.slit.placement: CenterRight
session.screen0.slit.direction: Vertical
session.screen0.slit.onTop:     False
session.screen0.slit.autoHide:  False
session.screen0.toolbar.onTop:  False
session.screen0.toolbar.autoHide:       False
session.screen0.toolbar.placement:      BottomCenter
session.screen0.toolbar.widthPercent:   66
session.screen0.enableToolbar:  True
session.screen0.workspaces:     4
session.screen0.workspaceNames: Workspace 1,Workspace 2,Workspace 3,Workspace 4
session.screen0.strftimeFormat: %I:%M %p
session.windowSnapThreshold:    0
session.autoRaiseDelay: 400
session.placementIgnoresShaded: True
session.focusLastWindow:        True
session.opaqueMove:     True
session.changeWorkspaceWithMouseWheel:  True
session.imageDither:    OrderedDither
session.windowPlacement:        RowSmartPlacement
session.shadeWindowWithMouseWheel:      True
session.opaqueResize:   True
session.toolbarActionsWithMouseWheel:   True
session.rowPlacementDirection:  LeftToRight
session.maximumColors:  0
session.disableBindingsWithScrollLock:  False
session.fullMaximization:       False
session.colPlacementDirection:  TopToBottom
session.doubleClickInterval:    250
session.edgeSnapThreshold:      0
session.focusNewWindows:        True
session.focusModel:     ClickToFocus

2.3.2) How can I produce my own?

There is currently no easy way to force Blackbox to produce a default config file and write it to disk, if you don't have one. It only does this when you change something in the config menu, but if you ever start with an empty config file, the default menu won't give you a [config] entry. This issue is being discussed in BlackboxFeature:1409869 and will hopefully be fixed. (Also mentioned in BlackboxFeature:1181522).

A simple workaround is to change something in either the toolbar or the slit menu. Provided you have any of them enabled at the time, of course.

If you don't have those menus available either, here's how to make Blackbox produce a full default config file:

  1. Create a temporary menu file (let's say, ~/temp_menu).
  2. Enter this in the temporary menu file:
    [begin] (Temp)
    [config] (Config)
    [end]
    
  3. Create an empty config file somewhere, let's say ~/.blackboxrc.
  4. Enter this in the config file:
    session.menuFile: /full/path/to/temp_menu
    
  5. Start Blackbox. Open the main menu. Enter the configuration submenu and click on something, anything.
  6. The config file now contains a full set of options.
  7. Please note that the options are not all default. You probably changed something when you clicked in the config submenu!

2.4) Configuration options

The following list will attempt to list all the resource keywords used by the latest Blackbox, the version in which they appeared (if recent), the default values, and an explanation.

Note: The default values were determined by examining the contents of a new .blackboxrc file created by the latest version of Blackbox. The values mentioned in the man page may differ by being outdated, depending on whether you're using the latest Blackbox, or plain wrong, due to lack of updates.
Note: You will notice that some options contain screen0 in their name. This means that they are multi-screen-sensitive. If you use Blackbox with more than one screen, those options will be multiplied accordingly, one copy for each screen. This way, each screen can have specific options; for example, one screen can have the toolbar activated, while another won't.

2.4.1) Window placement options

session.windowPlacement
  • Default Value: RowSmartPlacement. Value Type: text. Possible Values: RowSmartPlacement, ColSmartPlacement, CenterPlacement, CascadePlacement.
  • Description: Determines the window placement model for newly created windows.
    • "Smart" placement will attempt to position windows more or less in "rows" or "columns" ie. displace each new window slightly on the horizontal or vertical until a row or column is filled, then start again on the next row or column. Whether rows or columns are filled bottom-up, top-down, left-right or right-left is decided by session.colPlacementDirection and session.rowPlacementDirection.
    • Center placement will place all new windows at the center of the screen.
    • Cascade placement will displace new windows both vertically and horizontally by a small amount, relative to the last focused window. Cascade placement is always done from the top-left corner towards the bottom-right corner.
session.rowPlacementDirection
  • Default Value: LeftToRight. Value Type: text. Possible Values: LeftToRight, RightToLeft.
  • Description: Same as session.colPlacementDirection, except it deals with horizontal positioning.
session.colPlacementDirection
  • Default Value: TopToBottom. Value Type: text. Possible Values: TopToBottom, BottomToTop.
  • Description: Regards placement of new windows. Is only relevant when session.windowPlacement is set to a smart placement (ie. not with cascade placement). Determines whether vertical positioning is chosen from the bottom up or from the top down.
session.placementIgnoresShaded
  • Default Value: True. Value Type: on/off. Possible Values: True, False.
  • Description: Determines whether shaded windows are taken into consideration when calculating placement.

2.4.2) Window behaviour options

session.edgeSnapThreshold
  • Default Value: 0. Value Type: number. Possible Values: positive integers.
  • Description: Determines the minimum distance, in pixels, at which a window edge must be brought near the screen edge before snapping occurs. 0 (zero) means "disabled".
session.windowSnapThreshold
  • Default Value: 0. Value Type: number. Possible Values: positive integers.
  • Description: Determines the minimum distance, in pixels, at which a window edge must be brought near the edge of another window before snapping occurs. 0 (zero) means "disabled".
session.fullMaximization
  • Default Value: False. Value Type: on/off. Possible Values: True, False.
  • Description: Determines whether struts is respected. When enabled, this allows maximized windows to cover the slit, toolbar or other panels and such which otherwise normally reserve space at the edges of the screen.
session.opaqueMove
  • Default Value: True. Value Type: on/off. Possible Values: True, False.
  • Description: When enabled, this will attempt to keep windows fully drawn and the applications inside them working even during the move. Yes, you most likely want this. When disabled, moving a window draws a dotted rectangle which shows where the window will be moved to.
  • WARNING: There is a deeper meaning to opaque moving. When it is disabled, the application inside the window is effectively paralyzed for the duration of the move. Depending on the application, this may have negative effects, such as a download timing out, or a CD-burning application receiving a buffer underrun.
session.opaqueResize
  • Default Value: True. Value Type: on/off. Possible Values: True, False.
  • Description: Similar to session.opaqueMove, except it applies to resizing. Everything about moving applies, and yes, you most likely want this, too. The warning applies too!
session.shadeWindowWithMouseWheel
  • Default Value: True. Value Type: on/off. Possible Values: True, False.
  • Description: If enabled, you can shade or unshade windows by rolling the mouse wheel while the mouse cursor hovers over their titlebar.

2.4.3) Window focus options

session.focusLastWindow
  • Default Value: True. Value Type: on/off. Possible Values: True, False.
  • Description: The name of this option is a bit misleading. It determines whether Blackbox attempts to automatically give focus to a window when switching workspace. The "last" bit comes from the fact that, if enabled, Blackbox remembers which particular window last had focus on that workspace, and restores it.
session.focusModel
  • Default Value: ClickToFocus. Value Type: text. Possible Values: SloppyFocus, AutoRaise, ClickRaise, ClickToFocus.
  • Description: Determines the window focus model. ClickToFocus must be used by itself. If you use SloppyFocus you must also add either AutoRaise or ClickRaise in order to fully define the sloppy behaviour.
session.focusNewWindows
  • Default Value: True. Value Type: on/off. Possible Values: True, False.
  • Description: Determines whether newly created windows are automatically given focus.

2.4.4) Workspace options

session.changeWorkspaceWithMouseWheel
  • Default Value: True. Value Type: on/off. Possible Values: True, False.
  • Description: This determines whether rolling the mouse wheel over an empty portion of the desktop will cause the current workspace to change.
session.screen0.workspaces
  • Default Value: 4. Value Type: number. Possible Values: positive integers.
  • Description: Determines the amount of workspaces aka virtual desktops you want to have. FIXME: what's the top limit?
session.screen0.workspaceNames
  • Default Value: Workspace 1,Workspace 2,Workspace 3,Workspace 4. Value Type: text. Possible Values: comma-separated list of names.
  • Description: This option provides a comma-separated list of names which will be used to name each of the workspaces. This serves to more easily identify the current workspace and is used, for instance, by the toolbar. If you provide fewer names then there are workspaces, the remaining ones will have a blank name.

2.4.5) Color options

session.imageDither
  • Default Value: OrderedDither. Value Type: text. Possible Values: NoDither, OrderedDither, FloydSteinbergDither.
  • Description: This is only used when Blackbox is running in a low-color X mode. It determines whether Blackbox should attempt to simulate colors which cannot be displayed by interpolating pixels from the available colors. NoDither disables this feature. OrderedDither and FloydSteinbergDither are the fast and the high-quality alternatives, respectively.
session.maximumColors:
  • Default Value: 0. Value Type: number. Possible Values: positive integers.
  • Description: FIXME: the purpose of this option is unknown.

2.4.6) Toolbar options

session.screen0.enableToolbar
  • Default Value: True. Value Type: on/off. Possible Values: True, False.
  • Description: Determines whether to enable the Blackbox toolbar.
session.screen0.strftimeFormat
  • Default Value: %I:%M %p. Value Type: text. Possible Values: valid date format.
  • Description: Determines what the toolbar clock shows. The format* is the one used by the UNIX date command.
session.screen0.toolbar.autoHide
  • Default Value: False. Value Type: on/off. Possible Values: True, False.
  • Description: When enabled, the toolbar will stay hidden when the mouse cursor is not hovering over it. This helps to save screen space.
session.screen0.toolbar.onTop
  • Default Value: False. Value Type: on/off. Possible Values: True, False.
  • Description: When enabled, the toolbar will always be shown in front of other windows, even when the windows are set to always on top.
session.screen0.toolbar.placement
  • Default Value: BottomCenter. Value Type: text. Possible Values: TopLeft, TopCenter, TopRight, BottomLeft, BottomCenter, BottomRight.
  • Description: This determines the toolbar position on screen. The values should be self-explanatory. Please note that "middle" values are missing. This happens because, unlike the slit, the toolbar is always horizontal, so placing it at the middle of the screen's side edges doesn't make sense.
session.screen0.toolbar.widthPercent
  • Default Value: 66. Value Type: number. Possible Values: positive integers in the range 1-100.
  • Description: Sets the width of the toolbar, expressed as a percentage of the screen width.
session.toolbarActionsWithMouseWheel
  • Default Value: True. Value Type: on/off. Possible Values: True, False.
  • Description: If enabled, certain actions become possible by rolling the mouse wheel over certain parts of the toolbar. Rolling it over the workspace name or over the clock will change workspace. Rolling the wheel over the window title will shade or unshade the window (but only if session.shadeWindowWithMouseWheel is also enabled).

2.4.7) Slit options

session.screen0.slit.autoHide
  • Default Value: False. Value Type: on/off. Possible Values: True, False.
  • Description: When enabled, the slit will stay hidden when the mouse cursor is not hovering over it. This helps to save screen space.
session.screen0.slit.direction
  • Default Value: Horizontal. Value Type: text. Possible Values: Horizontal, Vertical.
  • Description: The slit aligns the applications it holds along a single straight line. This option determines whether that line is horizontal or vertical.
session.screen0.slit.onTop
  • Default Value: False. Value Type: on/off. Possible Values: True, False.
  • Description: When enabled, the slit will always be shown in front of other windows, even when the windows are set to always on top.
session.screen0.slit.placement:
  • Default Value: CenterRight. Value Type: text. Possible Values: TopLeft, TopCenter, TopRight, CenterLeft, CenterRight, BottomLeft, BottomCenter, BottomRight.
  • Description: This determines the slit position on screen. The values should be self-explanatory.

2.4.8) Other options

session.autoRaiseDelay
  • Default Value: 400. Value Type: number. Possible Values: positive integers.
  • Description: The amount of time, in milliseconds, that the mouse needs to hover over a hidden slit or toolbar before they appear. Of course, this option is only relevant when ...autoHide is set to True for either of them.
session.disableBindingsWithScrollLock
  • Default Value: False. Value Type: on/off. Possible Values: True, False.
  • Description: If enabled, this will cause internal Blackbox keybindings to be ignored for as long as Scroll Lock is lit. This affects various modifier keys, such as using Alt with the left mouse button to drag windows. Disabling internal keybindings on the fly can be quite useful sometimes. One example is The Gimp* graphical editor, where Alt+LeftClick stands for the "subtract" mode of the various tools.
session.doubleClickInterval:
  • Default Value: 250. Value Type: number. Possible Values: positive integers.
  • Description: The time interval (in milliseconds) within which two mouse clicks must occur to be considered a double-click. This only affects Blackbox-specific actions, such as shading, not the X server, nor any application.
session.menuFile
  • Default Value: PREFIX/share/blackbox/menu. Value Type: text. Possible Values: valid file name.
  • Description: This indicates the file holding the definition for the Blackbox menu file. The PREFIX used for the default depends on the way Blackbox was configured at compilation time, but for most systems it is /usr. People usually set this to something like ~/.blackbox/menu.
session.styleFile
  • Default Value: PREFIX/share/blackbox/styles/Gray. Value Type: text. Possible Values: valid file name.
  • Description: This indicates the file holding the definition for the currently used style. The PREFIX used for the default depends on the way Blackbox was configured at compilation time, but for most systems it is /usr.

3) The configuration menu

Blackbox also allows you to configure certain options through a certain subsection of the main menu.

Not all the configuration options are available through this graphical menu. The Blackbox menus have limited interaction capabilities, for the sake of simplicity. They are unable to render things like text entries or number spinners, and are thus limited to representing on/off options or options that use predefined keywords.

Please also note that at any given time, some of the options may be disabled. This reflects the current option combinations and is intended to give you clues about how they relate to each other. For example, if you select "click to focus", then the sloppy focus -specific options (auto-raise and click-to-raise) will be disabled.

The following chart will emulate a complete configuration submenu. Each entry uses the name under which it appears in the actual menu, and links to the corresponding configuration file entry, defined above. We do this because there's no point in maintaining identical explanations in two different places.

Focus Model
Click to Focus
Sloppy Focus
Auto Raise
Click Raise
Window Placement
Smart Placement (Rows)
Smart Placement (Columns)
Center Placement
Cascade Placement
(separator)
Left to Right
Right to Left
Top to Bottom
Bottom to Top
(separator)
Ignore Shaded Windows
Image Dithering
Do not dither images
Use fast dither
Use high-quality dither
(separator)
Opaque Window Moving
Opaque Window Resizing
Full Maximization
Focus New Windows
Focus Last Window on Workspace
Change Workspace with Mouse Wheel
Shade Windows with Mouse Wheel
Toolbar Actions with Mouse Wheel
Disable Bindings with Scroll Lock
(separator)
Toolbar Options
Enable Toolbar
(separator)
Placement
Top Left
Top Center
Top Right
(separator)
Bottom Left
Bottom Center
Bottom Right
Always on top
Auto Hide
Slit Options
Direction
Horizontal
Vertical
Placement
Top Left
Center Left
Bottom Left
(separator)
Top Center
Bottom Center
(separator)
Top Right
Center Right
Bottom Right
(separator)
Always on top
Auto hide

4) Third-party configuration tools

You can also configure Blackbox by using configuration tools created by people other than the Blackbox developers. Please see the "configuration" section in the Blackbox add-ons listing.


eXTReMe Tracker Hosted by SourceForge.net
Document last modified: Tue, 15 Jun 2010, 20:25 UTC
Home | Sitemap | Last changes RSS Feed | Wiki help | Wiki tools | SandBox
Preferences | Edit this page | View source | Page history | Referrers
Hosted by SourceForge. Powered by Wikki Tikki Tavi. About the website. Terms of use.