Revision as of 13:50, 25 January 2011

Openbox 3 themes are written as an X resource database, in a file named themerc. The format is quite simple to learn, but there are an enormous number of options available to you.

Each and every option has been documented, with details such as their default values, and which values are or are not valid for them. But to try make it a little more accessible, we'll start with an example theme, which uses every possible option within it. Each of the options can be clicked to read the details about it.

Theme installation

User-specific themes can be installed in ~/.local/share/themes or in ~/.themes.

Theme selection

Choosing a theme to use is simple with the ObConf tool. Alternatively, there are a number of Pipe menus which can perform this function for you.

If you wish to set the theme by hand, you need to edit the <name> key in the <theme> section of your rc.xml file. The Configuration guide is a good place to start.

Theme file structure

The file structure goes like this:

ThemesDirectory (such as /usr/share/themes)
|
+-> ThemeName (This is the name of the theme, such as Clearlooks)
|
+-> openbox-3 (This the type of the theme - it's for Openbox 3!)
|
|-> themerc (This is the main theme file, documented in this page)
|
|-> max.xbm (These are optional xbm masks for the titlebar buttons)
|-> close.xbm
...
+-> shade.xbm

ObConf can create a .obt Openbox Theme Archive file out of a theme for distribution, and can also install .obt files very easily.

Example

This is not a real theme, and if you used it, there is no guarantee it will look good in any way. It is just meant to show all of the options and how they relate to eachother.

Parentrelative

Parentrelative means that the element inherits its colors from the textures behind it. It is, in essence, completely transparent. Some theme elements can be parentrelative, and some can not. The documentation for each one will tell you if you can use parentrelative for it or not.

SplitVertical gradients

SplitVertical gradients have 2 optional, addition color fields: color.splitTo and colorTo.splitTo. These colors are the light colors used on the far top and bottom of the SplitVertical gradient. When these are omitted, then the default values for these are color * 5/4, and colorTo * 17/16.

Raised and Sunken have two bevel options available to them. By default, a bevel is drawn around the very outside of the texture. If Bevel2 is specified, then the bevel is drawn slightly in from the edge. This can be used to animate button presses/toggled states.

The strength of the bevel highlights can also be determined by the theme, by using the highlight and shadow fields:

The highlight field specifies the strength of the light bevel. It is a value above or equal to 0, where 0 makes no highlight at all, 256 makes the highlight color 100% brighter, 512 makes the highlight color 200% brighter, and so on. The default highlight is 128 (which is a 50% increase in brightness).

The shadow field specifies the strength of the dark bevel. It is a value between 0 and 256, where 0 makes no shadow at all, and 256 makes a completely black shadow (100% decreased brightness). The default shadow is 64 (which is a 25% decrease in brightness).

Color names

RGB values

Colors can be specified by hexadecimal RGB values in two ways. The most familiar is through syntax similar to HTML, #rrggbb. However you may also use the format rgb:rr/bb/gg. What goes inside them for the rr, gg and bb values is identical.

Text shadow strings

There are three properties that can be placed in the string: shadow, shadowtint and shadowoffset.

Shadow is a boolean value. It defaults to no. You can enable a shadow for text by using shadow=y.

Shadowtint specifies the alpha value for the shadow as well as its color (black or white). It defaults to black and 50% opacity. You can specify the shadowtint by using shadowtint=70. The tint can be any integer between -100 and 100. 0 means 0% opacity (invisible), 100 means 100% opacity and black, -100 means 100% opacity and white.

Shadowoffset specifies how far the shadow is should be offset from the text. It defaults to 1. It can be positive to move the shadow and and right from the text, or negative to move it up and left from the text. You can set the shadowoffset by using shadowoffset=2. A shadowoffset of 0 will place it exactly behind the text and it will not be visible.

The text shadow string used to be for choosing a font for the theme as well. Any other properties in the string, such as those for choosing a font, are ignored.

Example:

window.active.label.text.font:shadow=y:shadowtint=70:shadowoffset=1

Theme elements

Each theme element corresponds to one part of a window or a menu. We'll start be discussing the elements that let you change the size and placement of things, and then talk about how to change the textures used to render everything.

padding.width

Specifies the padding size, used for spacing out elements in the window decorations. This can be used to give a theme a more compact or a more relaxed feel. This specifies padding in the horizontal direction (and vertical direction if padding.height is not explicitly set).

padding.height

Specifies the padding size, used for spacing out elements in the window decorations. This can be used to give a theme a more compact or a more relaxed feel. This specifies padding in only the vertical direction.

menu.overlap.x

Specifies how sub menus should overlap their parents. A positive value moves the submenu over top of their parent by that amount. A negative value moves the submenu away from their parent by that amount. (As of version 3.4.7)

menu.overlap.y

Specifies how sub menus should be positioned relative to their parents. A positive value moves the submenu vertically down by that amount, a negative value moves it up by that amount. (As of version 3.4.7)

window.active.button.toggled.pressed.image.color

Specifies the color of the images in the titlebar buttons if they are pressed on with the mouse while they are in the toggled state - such as when a window is maximized. This element is for the focused window.

window.active.button.toggled.hover.image.color

Specifies the color of the images in the titlebar buttons when the mouse is hovered over them while they are in the toggled state - such as when a window is maximized. This element is for the focused window.

window.inactive.button.toggled.pressed.image.color

Specifies the color of the images in the titlebar buttons if they are pressed on with the mouse while they are in the toggled state - such as when a window is maximized. This element is for non-focused windows.

window.inactive.button.toggled.hover.image.color

Specifies the color of the images in the titlebar buttons when the mouse is hovered over them while they are in the toggled state - such as when a window is maximized. This element is for non-focused windows.

window.active.title.bg

window.active.label.bg

Specifies the background for the focused window's titlebar label. The label is the container for the window title. When it is parentrelative, then it uses the window.active.title.bg which is underneath it.

window.active.grip.bg

Specifies the background for the focused window's grips. The grips are located at the left and right sides of the window's handle. When it is parentrelative, then it uses the window.active.handle.bg which is underneath it.

window.inactive.title.bg

window.inactive.label.bg

Specifies the background for non-focused windows' titlebar labels. The label is the container for the window title. When it is parentrelative, then it uses the window.inactive.title.bg which is underneath it.

window.inactive.grip.bg

Specifies the background for non-focused windows' grips. The grips are located at the left and right sides of the window's handle. When it is parentrelative, then it uses the window.inactive.handle.bg which is underneath it.

Active window button textures

window.active.button.unpressed.bg

Specifies the background for titlebar buttons in their default, unpressed, state. This element is for the focused window. When it is parentrelative, then it uses the window.active.title.bg which is underneath it.

window.active.button.pressed.bg

Specifies the background for titlebar buttons when they are being pressed by the user. This element is for the focused window. When it is parentrelative, then it uses the window.active.title.bg which is underneath it.

window.active.button.hover.bg

Specifies the background for titlebar buttons when the mouse is over them. This element is for the focused window. When it is parentrelative, then it uses the window.active.title.bg which is underneath it.

window.active.button.disabled.bg

Specifies the background for titlebar buttons when they are disabled for the window. This element is for the focused window. When it is parentrelative, then it uses the window.active.title.bg which is underneath it.

window.active.button.toggled.unpressed.bg

Specifies the default background for titlebar buttons when they are toggled - such as when a window is maximized. This element is for the focused window. When it is parentrelative, then it uses the window.inactive.title.bg which is underneath it.

window.active.button.toggled.pressed.bg

Specifies the default background for titlebar buttons if the user is pressing them with the mouse while they are toggled - such as when a window is maximized. This element is for the focused window. When it is parentrelative, then it uses the window.inactive.title.bg which is underneath it.

window.active.button.toggled.hover.bg

Specifies the default background for titlebar buttons if the user is pressing them with the mouse while they are toggled - such as when a window is maximized. This element is for the focused window. When it is parentrelative, then it uses the window.inactive.title.bg which is underneath it.

Inactive window button textures

window.inactive.button.unpressed.bg

Specifies the background for titlebar buttons in their default, unpressed, state. This element is for non-focused windows. When it is parentrelative, then it uses the window.inactive.title.bg which is underneath it.

window.inactive.button.pressed.bg

Specifies the background for titlebar buttons when they are being pressed by the user. This element is for non-focused windows. When it is parentrelative, then it uses the window.inactive.title.bg which is underneath it.

window.inactive.button.hover.bg

Specifies the background for titlebar buttons when the mouse is over them. This element is for non-focused windows. When it is parentrelative, then it uses the window.inactive.title.bg which is underneath it.

window.inactive.button.disabled.bg

Specifies the background for titlebar buttons when they are disabled for the window. This element is for non-focused windows. When it is parentrelative, then it uses the window.inactive.title.bg which is underneath it.

window.inactive.button.toggled.unpressed.bg

Specifies the default background for titlebar buttons when they are toggled - such as when a window is maximized. This element is for non-focused windows. When it is parentrelative, then it uses the window.inactive.title.bg which is underneath it.

window.inactive.button.toggled.pressed.bg

Specifies the default background for titlebar buttons if the user is pressing them with the mouse while they are toggled - such as when a window is maximized. This element is for non-focused windows. When it is parentrelative, then it uses the window.inactive.title.bg which is underneath it.

window.inactive.button.toggled.hover.bg

Specifies the default background for titlebar buttons if the user is pressing them with the mouse while they are toggled - such as when a window is maximized. This element is for non-focused windows. When it is parentrelative, then it uses the window.inactive.title.bg which is underneath it.