Help:Themes

From Openbox

Revision as of 12:20, 2 June 2007 by DanaJansens (Talk | contribs)

Jump to: navigation, search

Openbox 3 themes are written as an X resources database. The format is quite simple to learn. We'll start by going over the data types that are used for the various properties.

Contents

Data types

Integers

These are simply numbers like 1 or 42. They can be prime or composite.

Example:

window.handle.width: 3

Justification

These determines how to justify text. Valid options are Left, Center and Right.

Example:

menu.title.text.justify: Left

Textures

These determine the visual look of an element. They are the most complicated part of a theme file, but they are still not too tricky.

Textures are specified through a text string with a number of fields. Capitalization is not significant. The format is as follows (| stands for "or" and [] surround optional fields):

parentrelative | ((solid | gradient gradient-type) [border] [interlaced])

We'll dissect what that means exactly.

Parentrelative

Parentrelative means that the element inherits it's 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.

When a texture is parentrelative, that is the only field that should appear on the line.

Example:

window.active.label.bg: Parentrelative

Solid

Solid means that the background of the texture is filled with a single color. The texture must be accompanied by a single color field.

Example:

menu.items.bg:       Solid Flat
menu.items.bg.color: #f8f5f2

Gradients

When a gradient is specified, it must be followed by the gradient's type. Gradients all use two color fields: color and colorTo and must also be accompanied by these.

Valid gradient types are:

  • Diagonal - A gradient from the top left corner to the bottom right corner
  • CrossDiagonal - A gradient from the top right corner to the bottom left corner
  • Pyramid - A gradient that starts in all four corners and smooths to the center of the texture
  • Horizontal - A gradient from the left edge to the right
  • MirrorHorizontal - A gradient from the left edge to the middle, and then reversed to the right edge
  • Vertical - A gradient from the top edge to the bottom
  • SplitVertical - A gradient from the top to the bottom that is split in the middle

Example:

menu.title.bg:         Gradient Vertical Raised 
menu.title.bg.color:   #658fb5
menu.title.bg.colorTo: #4d6982

Border

Borders can be used on both solid and gradient textures. Valid options for the border are Flat, Raised and Sunken. When a border is not specified, Raised is assumed.

Flat, by default, means no border at all. To add a flat solid border, use Flat Border. When using a flat border, the texture must be accompanied by a border color.

Example:

window.active.button.unpressed.bg:              Gradient Vertical Flat Border
window.active.button.unpressed.bg.border.color: #3d4c5a

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.

Example:

window.inactive.button.disabled.bg:         Gradient Diagonal Raised
window.inactive.button.disabled.bg.color:   rgb:50/54/58
window.inactive.button.disabled.bg.colorTo: black

window.inactive.button.toggled.bg:          Gradient Diagonal Raised Bevel2
window.inactive.button.toggled.bg.color:    rgb:50/54/58
window.inactive.button.toggled.bg.colorTo:  black

Interlaced

Interlaced textures have a solid line drawn horizontally every second row. When you specify interlaced, the texture must be accompanied by an interlaced color.

Example:

window.inactive.title.bg: Solid Flat Interlaced
window.inactive.title.bg.color: #f5f5f5
window.inactive.title.bg.interlace.color: #f6f6f6

Colors

Colors can be specified by name or by their hexadecimal RGB value.

Color names

Wikipedia has a list of X11 color names, and further details here.

Example:

menu.items.active.text.color: white
window.active.grip.bg.color: grey40

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.

Example:

window.active.grip.bg.color: #658fb5
window.active.label.text.color: #fff
menu.items.active.bg.color: rgb:90/94/98
window.active.title.bg.color: rgb:6/9/c

Note that #fff is equivalent to #ffffff, not to #f0f0f0.

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.

We're going to use a table such as this to describe each element:

Type: integer
Default: 1
Valid: 0-100
Parentrelative: no

Type shows the type of the value for the element.

Default gives the default value for the element if it is not listed in the theme. When Default refers to another theme element, then it means that element's values are used.

Valid gives valid ranges for elements that this is applicable for, such as integer values.

Parentrelative specifies if a given texture may use the Parentrelative visual type, when applicable.

Geometry

border.width

Type: integer
Default: 1
Valid: 0 - 100

Specifies the size of the border drawn around window frames.

See also: window.active.border.color, window.inactive.border.color

menu.border.width

Type: integer
Default: border.width
Valid: 0 - 100

Specifies the size of the border drawn around menus.

See also: menu.border.color

window.client.padding.width

Type: integer
Default: padding.width
Valid: 0 - 100

Specifies the size of the inner border drawn around the window, but inside the other decorations.

See also: window.active.client.color, window.inactive.client.color

window.handle.width

Type: integer
Default: 6
Valid: 0 - 100

Specifies the size of the window handle. The window handle is the piece of decorations on the bottom of windows.

See also: window.active.handle.bg, window.inactive.handle.bg, window.active.grip.bg, window.inactive.grip.bg

padding.width

Type: integer
Default: 3
Valid: 0 - 100

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.

menu.overlap

Type: integer
Default: 0
Valid:

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.

Border colors

window.active.border.color

Type: color
Default: border.color

Specifies the border color for the focused window.

See also: border.width, window.inactive.border.color

window.inactive.border.color

Type: color
Default: window.active.border.color

Specifies the border color for all non-focused windows.

See also: border.width, window.active.border.color

menu.border.color

Type: color
Default: window.active.border.color

Specifies the border color for menus.

See also: menu.border.width

border.color

Type: color
Default: black

This property is obsolete and only present for backwards compatibility.

See also: window.active.border.color, window.inactive.border.color, menu.border.color

window.active.client.color

Type: color
Default: white

Specifies the color of the inner border for the focused window, drawn around the window but inside the other decorations.

See also: window.client.padding.width, window.inactive.client.color

window.inactive.client.color

Type: color
Default: white

Specifies the color of the inner border for non-focused windows, drawn around the window but inside the other decorations.

See also: window.client.padding.width, window.active.client.color

Titlebar colors

window.active.label.text.color

Type: color
Default: black

Specifies the color of the titlebar text for the focused window.

See also: window.inactive.label.text.color

window.inactive.label.text.color

Type: color
Default: white

Specifies the color of the titlebar text for non-focused windows.

See also: window.active.label.text.color

window.active.button.unpressed.image.color

Type: color
Default: black

Specifies the color of the images in titlebar buttons in their default, unpressed, state. This element is for the focused window.

See also: window.active.button.pressed.image.color, window.active.button.disabled.image.color, window.active.button.hover.image.color, window.active.button.toggled.image.color

window.active.button.pressed.image.color

Type: color
Default: window.active.button.unpressed.image.color

Specifies the color of the images in titlebar buttons when they are being pressed by the user. This element is for the focused window.

See also: window.active.button.unpressed.image.color, window.active.button.disabled.image.color, window.active.button.hover.image.color, window.active.button.toggled.image.color

window.active.button.disabled.image.color

Type: color
Default: white

Specifies the color of the images in titlebar buttons when they are disabled for the window. This element is for the focused window.

See also: window.active.button.unpressed.image.color, window.active.button.pressed.image.color, window.active.button.hover.image.color, window.active.button.toggled.image.color

window.active.button.hover.image.color

Type: color
Default: window.active.button.unpressed.image.color

Specifies the color of the images in titlebar buttons when the mouse is over top of the button. This element is for the focused window.

See also: window.active.button.unpressed.image.color, window.active.button.pressed.image.color, window.active.button.disabled.image.color, window.active.button.toggled.image.color

window.active.button.toggled.image.color

Type: color
Default: window.active.button.pressed.image.color

Specifies the color of the images in titlebar buttons when the button is toggled - such as when a window is maximized. This element is for the focused window.

See also: window.active.button.unpressed.image.color, window.active.button.pressed.image.color, window.active.button.disabled.image.color, window.active.button.hover.image.color

window.inactive.button.unpressed.image.color

Type: color
Default: white

Specifies the color of the images in titlebar buttons in their default, unpressed, state. This element is for non-focused windows.

See also: window.inactive.button.pressed.image.color, window.inactive.button.disabled.image.color, window.inactive.button.hover.image.color, window.inactive.button.toggled.image.color

window.inactive.button.pressed.image.color

Type: color
Default: window.inactive.button.unpressed.image.color

Specifies the color of the images in titlebar buttons when they are being pressed by the user. This element is for non-focused windows.

See also: window.inactive.button.unpressed.image.color, window.inactive.button.disabled.image.color, window.inactive.button.hover.image.color, window.inactive.button.toggled.image.color

window.inactive.button.disabled.image.color

Type: color
Default: black

Specifies the color of the images in titlebar buttons when they are disabled for the window. This element is for non-focused windows.

See also: window.inactive.button.unpressed.image.color, window.inactive.button.pressed.image.color, window.inactive.button.hover.image.color, window.inactive.button.toggled.image.color

window.inactive.button.hover.image.color

Type: color
Default: window.inactive.button.unpressed.image.color

Specifies the color of the images in titlebar buttons when the mouse is over top of the button. This element is for non-focused windows.

See also: window.inactive.button.unpressed.image.color, window.inactive.button.pressed.image.color, window.inactive.button.disabled.image.color, window.inactive.button.toggled.image.color

window.inactive.button.toggled.image.color

Type: color
Default: window.inactive.button.pressed.image.color

Specifies the color of the images in titlebar buttons when the button is toggled - such as when a window is maximized. This element is for non-focused windows.

See also: window.inactive.button.unpressed.image.color, window.inactive.button.pressed.image.color, window.inactive.button.disabled.image.color, window.inactive.button.hover.image.color

Personal tools