Configuring Openbox

File locations

When looking for its configuration files (rc.xml, menu.xml), Openbox follows the freedesktop.org base-dir specification. You can read the short specification for all the details. However, the end default result will be as follows.

First Openbox will try for your config files in $HOME/.config/openbox/. If it is unable to find them there, then it will try the system configuration dir (use ./configure --sysconfdir to modify this when configuring the Openbox build. If you installed Openbox from a distribution package, then it will most likely be looking in /etc/xdg/openbox/. If you built Openbox yourself and do not specify --sysconfdir, then it will be looking in /usr/local/etc/xdg/openbox.

Options

Most users will want to use the ObConf tool to configure Openbox. You can launch the tool by running:

% obconf

See the ObConf webpage to get this handy tool.

If you don't want/have ObConf, you can edit the configuration by hand. The recommended procedure for this is to copy the system config to $HOME/.config/openbox/ and edit that to your liking.

Menus

Menus are searched for in the directories given in the File locations section.

You can specify the names of the menu files to load in the rc.xml's menu section. Absolute paths can also be used to look outside of the default search paths. For example:

<menu>
  <file>mymenu.xml</file>
  <file>myothermenu.xml</file>
  <file>/etc/system/openboxmenu.xml</file>
</menu>

If no menus are specified in the rc.xml, Openbox will look for menu.xml.

Themes

First off, the theme format is not backwards compatible with Openbox2/Blackbox/Fluxbox themes. The themeupdate.py script included in the Openbox distribution can be used to aid in porting Openbox2/Blackbox/Fluxbox themes over.

Paths

Themes are searched for in the data directories specified in the base-dir spec mentioned in the File locations section. In addition to these paths, Openbox also looks in $HOME/.themes/ for backwards compatibility with existing applications. This means, by default, the following directories will be searched in order: $HOME/.themes/, $HOME/.local/share/themes/, $PREFIX/share/themes/. This means that Openbox themes can now be bundled with other themes (such as GTK+ themes).

Structure

Each theme is self-contained within its own directory. The theme file itself is a file named themerc inside the theme's openbox-3 directory. So for a theme named "Foo", its directory layout might look like this:

Foo/openbox-3/themerc
Foo/openbox-3/max.xbm
Foo/openbox-3/close.xbm

We'll get to the xbms later.

Fonts

Fonts are each specified through a single .font property. Different fonts can be specified for focused and unfocused windows. The available font properties are:

• window.label.focus.font
• window.label.unfocus.font
• menu.title.font
• menu.items.font

This property is an Xft/Fontconfig font string. It is highly recommended that when specifying this, you specify the size of the font by pixelsize, not by pointsize. Some details on building the required font string can be found in this Xft tutorial.

There are a couple extensions to the font string's options for openbox:

• shadow [boolean] (defaults to off)
• shadowoffset [integer] (defaults to 1)
• shadowtint [integer] (defaults to 25%)

Example:

window.focus.font: arial,sans:bold:pixelsize=12:shadow=y

Titlebar Button Bitmaps

A number of X Bitmap (xbm) files are used to specify the look of the titlebar buttons. These buttons are all found under the Theme/openbox-3/ directory. The following names are looked for:

• max.xbm - maximized button
• max_toggled.xbm - maximized button toggled
• max_disabled.xbm - maximized button disabled
• max_hover.xbm - maximized button while being hovered over
• max_pressed.xbm - maximized button while being pressed
• iconify.xbm - iconify button
• iconify_disabled.xbm - iconify button disabled
• iconify_hover.xbm - iconify button while being hovered over
• iconify_pressed.xbm - iconify button while being pressed
• desk.xbm - all-desktops button
• desk_toggled.xbm - all-desktops button toggled
• desk_disabled.xbm - all-desktops button disabled
• desk_hover.xbm - all-desktops button while being hovered over
• desk_pressed.xbm - all-desktops button while being pressed
• shade.xbm - shade button
• shade_toggled.xbm - shade button toggled
• shade_disabled.xbm - shade button disabled
• shade_hover.xbm - shade button while being hovered over
• shade_pressed.xbm - shade button while being pressed
• close.xbm - close button
• close_disabled.xbm - close button disabled
• close_hover.xbm - close button while being hovered over
• close_pressed.xbm - close button while being pressed
• bullet.xbm - submenu bullet in menus

Background

Themes do not provide a means for setting the background. There are many tools around for setting the root image (xsetroot, Esetroot, Rox, Gnome, Kde, etc!) so there is no point in rewriting those for Openbox.

Etc

A more detailed description and list of all the theme elements will be forthcoming. In the meantime, examples found in the distribution can be used for documentation.