Openbox

Introduction
Screen Shots
Contributors
Platforms
Mailing Lists
Downloads
Bug Reports

Changelogs

Stable
Testing

Documentation

Whats new
Using Openbox

F.A.Q.
Openbox Features
Epist Features
Docker
The RC File
Menu File

Submitting a patch
What to do about a bug

Introduction

This document describes Openbox's rc file. The rc file is the file which Openbox uses to save and load your configuration and preferences.

The default location for the rc file is ~/.openbox/rc. If you do not have this file yet, then you can run Openbox to have it create the file with all of the default options in it.

Sections

Global Options
Screen Options
Toolbar Options
Slit Options

Global options

These options affect all of Openbox, they are the same across all screens.

session.styleFile
session.colorsPerChannel
session.titlebarLayout
session.doubleClickInterval
session.cacheMax
session.cacheLife
session.autoRaiseDelay
session.modifierMask
session.xineramaSupport.windowPlacement
session.xineramaSupport.windowMaximizing
session.xineramaSupport.windowSnapping

session.styleFile

The path to the openbox style you wish you use.

example: session.styleFile: /usr/share/openbox/styles/bluebox

session.colorsPerChannel

This tells Openbox how many colors to take from the X server on pseudo-color displays. A channel would be red, green, or blue. Openbox will allocate this variable ^ 3 colors and make them always available. A value less than 2 or greater than 6 is invalid. When you run Openbox on an 8-bit display, you must set this resource to 4.

example: session.colorsPerChannel: 4

session.titlebarLayout

The order of the elements of window titlebars. This is a string built of the following characters:

I: Iconify button
L: Label (window title)
M: Maximize button
S: Sticky button
C: Close button

The order in which these character appear in the string, is the order they will appear in window titlebars. You can also omit an item to not have it appear in the titlebar at all, except for the Label which will always appear.

example: session.titlebarLayout: ILMC

session.doubleClickInterval

The number of milliseconds that two clicks must be received within for them to be called a double-click instead of 2 single clicks.

example: session.doubleClickInterval: 250

session.cacheMax

This tells Openbox how much memory (in Kb) it may use to store cached pixmaps on the X server. If your machine runs short of memory, you may lower this value.

example: session.cacheMax: 200

session.cacheLife

This tells Openbox how long (in minutes) unused pixmaps may stay in the X server's memory.

example: session.cacheLife: 5

session.autoRaiseDelay

The number of milliseconds the mouse must be over a window before it is raised, if the session.screenX.focusModel is SloppyFocus with AutoRaise enabled.

example: session.autoRaiseDelay: 400

session.modifierMask

The modifiers you want to use for mouse events on windows. This is used for dragging windows to move/resize them, etc. The default is "Mod1". This property can be composed of the following options, separated however you wish:

Control, Shift, Mod1 (usually the Alt key), Mod2, Mod3, Mod4 (usually the "Windows" key), Mod5.

This property cannot be set to use no modifiers.

example: session.modifierMask: Control-Mod1

session.xineramaSupport.windowPlacement

When this is enabled, and xinerama is running, new windows will not be placed in dead zones (areas of the desktop which are not visible because of different screen resolutions), or across screen boundaries. Note: in order to you use, you must also use the --enable-xinerama configuration flag when compiling Openbox.

example: session.xineramaSupport.windowPlacement: True

session.xineramaSupport.windowMaximizing

When this is enabled, and xinerama is running, maximizing a window will only cause the window to fill a single screen instead of spanning across them all. Note: in order to you use, you must also use the --enable-xinerama configuration flag when compiling Openbox.

example: session.xineramaSupport.windowMaximizing: True

session.xineramaSupport.windowSnapping

When this is enabled, and xinerama is running, moving windows will snap to screen boundaries between screens the same way they snap to the edges that do not touch another screen. Note: in order to you use, you must also use the --enable-xinerama configuration flag when compiling Openbox.

example: session.xineramaSupport.windowSnapping: True

Screen options

These options are set for each screen. For most users, this doesn't mean anything, as they only have a single screen. But in the case when you have 2 screens, then these options are set for both screens (for example "session.screen0..." and "session.screen1...") so that you can have different behavior on each screen. For each of these, when it says "session.screenX", replace the X with the screen number (numbered starting at 0).

session.screenX.focusModel
session.screenX.rootScrollDirection
session.screenX.rootMenuButton
session.screenX.workspaceMenuButton
session.screenX.strftimeFormat
session.screenX.windowPlacement
session.screenX.rowPlacementDirection
session.screenX.colPlacementDirection
session.screenX.placementIgnoreShaded
session.screenX.placementIgnoreMaximized
session.screenX.windowToWindowSnap
session.screenX.windowToEdgeSnap
session.screenX.windowCornerSnap
session.screenX.workspaceWarping
session.screenX.opaqueMove
session.screenX.raiseOnMoveResize
session.screenX.focusNewWindows
session.screenX.focusLastWindow
session.screenX.workspaces
session.screenX.workspaceNames
session.screenX.edgeSnapThreshold
session.screenX.resistanceSize
session.screenX.edgeSnapOffset
session.screenX.hideToolbar
session.screenX.antialiasFonts
session.screenX.dropShadowFonts
session.screenX.fullMaximization
session.screenX.resizeZones
session.screenX.imageDither
session.screenX.disableBindingsWithScrollLock

session.screenX.focusModel

This property determines how windows are given input focus. The two models to choose from are:

ClickToFocus: In this mode, windows do not receive focus until they are clicked on. Moving the mouse over a window does nothing. Clicking on the window will focus and raise it.

SloppyFocus: In this mode, windows receive focus when the mouse pointer enters the window. Focus does not follow the mouse pointer to the root window, however, so if you move it off the focused window, but not onto another window, focus will still stay on the last window. In the default behavior for this model, Clicking a window does not raise it, but clicking its decorations (for example the titlebar) does raise the window.

When using SloppyFocus, a number of other options can also be specified to modify its behavior.

AutoRaise: Raise the window when the mouse pointer is over it for an amount of time specified by session.autoRaiseDelay.

ClickRaise: Clicking in a window will raise the window as it does in the ClickToFocus model.

example: session.screen0.focusModel: ClickToFocus

example: session.screen0.focusModel: SloppyFocus ClickRaise

session.screenX.rootScrollDirection

This option determines what openbox does with mouse wheel clicks on the root window. The available options are:

Normal: This moves to the next workspace when the wheel is scrolled up, and the previous workspace when it is scrolled down.
Reverse: This is the opposite of normal. It moves to the next workspace when the wheel is scrolled down, and the previous workspace when it is scrolled up.
None: This causes no action to be taken when the mouse is scrolled on the root window.

example: session.screen0.rootScrollDirection: Normal

[only in 2.1]
session.screenX.rootMenuButton

This option determines which button, when clicked on the desktop, will pop up the Root Menu. The available options are:

Left: The left mouse button will pop up the Root Menu.
Middle: The middle mouse button will pop up the Root Menu.
Right: The right mouse button will pop up the Root Menu.
None: The Root Menu will not be popped up for any button.

example: session.screen0.rootMenuButton: Right

[only in 2.1]
session.screenX.workspaceMenuButton

This option determines which button, when clicked on the desktop, will pop up the Workspace Menu. The available options are:

Left: The left mouse button will pop up the Workspace Menu.
Middle: The middle mouse button will pop up the Workspace Menu.
Right: The right mouse button will pop up the Workspace Menu.
None: The Workspace Menu will not be popped up for any button.

example: session.screen0.workspaceMenuButton: Right

session.screenX.strftimeFormat

This is a string which is used to fill the time portion of the toolbar. For information on the format of this string, please see "man 3 strftime".

example: session.screen0.strftimeFormat: %I:%M %p

session.screenX.windowPlacement

This property determines how Openbox will place new windows which don't request a position for themselves. The possible options for this are:

RowSmartPlacement: places windows so they don't overlap while there is enough room, using horizontal space first, and then vertical, so that windows are placed in rows. (Also see session.screenX.rowPlacementDirection and session.screenX.colPlacementDirection.)
ColSmartPlacement: places windows so they don't overlap while there is enough room, using vertical space first, and then horizontal, so that windows are placed in columns. (Also see session.screenX.rowPlacementDirection and session.screenX.colPlacementDirection.)
UnderMousePlacement: places windows centered under the mouse pointer
ClickMousePlacement: lets you place the windows yourself, clicking a mouse button finalizes the placement.
CascadePlacement: places windows in a cascade from top-left to bottom-right.

example: session.screen0.windowPlacement: RowSmartPlacement

session.screenX.rowPlacementDirection

This sets the horizontal direction to use to place windows in RowSmartPlacement and ColSmartPlacement window placement modes (see session.screenX.windowPlacement. The possible options for this are:

LeftToRight
RightToLeft

example: session.screen0.rowPlacementDirection: LeftToRight

session.screenX.colPlacementDirection

This sets the vertical direction to use to place windows in RowSmartPlacement and ColSmartPlacement window placement modes (see session.screenX.windowPlacement. The possible options for this are:

TopToBottom
BottomToTop

example: session.screen0.colPlacementDirection: TopToBottom

session.screenX.placementIgnoreShaded

When this is enabled, window placement will ignore shaded windows, and will place over top of them as if they aren't there.

example: session.screen0.placementIgnoreShaded: True

session.screenX.placementIgnoreMaximized

When this is enabled, window placement will ignore fully-maximized windows, and will place over top of them as if they aren't there.

example: session.screen0.placementIgnoreMaximized: True

session.screenX.windowToWindowSnap

This option specifies how windows should be snapped to each other. The available options are:

NoSnap: In this mode, windows do not snap to each other at all.
Snap: In this mode, windows snap to each other when they are within session.screenX.edgeSnapThreshold pixels from each other. Windows snap from both sides of the snap edge.
Resistance: In this mode, windows do no snap from a distance, rather, the edge of the window provides resistance to the moving window. The amount of the resistance is controlled by the session.screenX.resistanceSize option. Resistance only works from one direction, where snapping works from both.

example: session.screen0.windowToWindowSnap: Resistance

session.screenX.windowToEdgeSnap

This option specifies how windows should snap to the screen's boundaries. The available options are:

NoSnap: In this mode, windows do not snap to the screen boundaries at all.
Snap: In this mode, windows snap to the screen boundaries when they are within session.screenX.edgeSnapThreshold pixels of them. Windows snap from both sides of the snap edge.
Resistance: In this mode, windows do no snap from a distance, rather, the screen boundaries provide resistance to the moving window. The amount of the resistance is controlled by the session.screenX.resistanceSize option. Resistance only works from one direction, where snapping works from both.

example: session.screen0.windowToEdgeSnap: Resistance

session.screenX.windowCornerSnap

When this is enabled, and a moving window has snapped to another window's edge, the moving window will also snap to the other window's corners so that they align with each other.

example: session.screenX.windowCornerSnap: True

session.screenX.workspaceWarping

When this is enabled, and you are moving a window, if the pointer touches the left or right edge of the screen, Openbox will warp the window to the next/previous workspace.

example: session.screenX.workspaceWarping: True

session.screenX.opaqueMove

When this is enabled, moving a window moves the entire window in real-time. This is sometimes referred to as "Show window contents while moving". When this is disabled, a rectangular box is drawn where the window will be placed, and the window is moved after the operation is completed.

example: session.screen0.opaqueMove: False

session.screenX.raiseOnMoveResize

When this is enabled, windows will be raised when they are clicked on with the modifierMask to initiate a move or a resize. When disabled, windows can not be raised by a mouse click with the modifierMask.

example: session.screen0.raiseOnMoveResize: True

session.screenX.focusNewWindows

When this is enabled, new windows will automatically be given the input focus. Hint: this property is more suited to the ClickToFocus session.screenX.focusModel than to SloppyFocus.

example: session.screen0.focusNewWindows: True

session.screenX.focusLastWindow

When this is enabled, the last focused window on a hidden workspace will be re-focused when the workspace becomes visible again. Hint: this property is more suited to the ClickToFocus session.screenX.focusModel than to SloppyFocus.

example: session.screen0.focusLastWindow: True

session.screenX.workspaces

This property specifies the number of workspaces to use in Openbox. A value less than 1 is invalid and will be ignored.

example: session.screen0.workspaces: 3

session.screenX.workspaceNames

This property contains the names of each of the workspaces. If fewer names than workspaces are specified, default names will be used to the remaining workspaces. Each workspace name is separated by a comma.

example: session.screen0.workspaceNames: one,two,three

session.screenX.edgeSnapThreshold

This is the number of pixels away from a snap edge (another window, or a screen boundary) that a window will snap to the edge.

example: session.screen0.edgeSnapThreshold: 8

session.screenX.resistanceSize

This is the number of pixels of resistance a snap edge (another window, or a screen boundary) will provide against moving a window over the edge.

example: session.screen0.resistanceSize: 18

session.screenX.edgeSnapOffset

This is the number of pixels of margin to keep between a moving window and all snap edges. So when this is set to a value greater than 0, windows will snap that far away from each other, and away from the screen boundaries. This affects both Snap mode and Resistance mode.

example: session.screen0.edgeSnapOffset: 4

session.screenX.hideToolbar

When this is enabled, the toolbar is removed from the desktop entirely.

example: session.screen0.hideToolbar: True

session.screenX.antialiasFonts

When this is enabled, Xft fonts will be anti-aliased. Note: In order to use Xft fonts, you must have some Xft font directives specified.

example: session.screen0.antialiasFonts: True

session.screenX.dropShadowFonts

When this is enabled, Xft fonts will be given a drop shadow. This option cannot be used when session.screenX.antialiasFonts is off. Note: In order to use Xft fonts, you must have some Xft font directives specified.

example: session.screen0.dropShadowFonts: True

session.screenX.fullMaximization

When this is enabled, maximizing a window will allow the window to cover the toolbar and slit, and windows such as KDE's kicker (panels). When this is not enabled, maximizing a window will not cover these things.

example: session.screen0.fullMaximization: False

session.screenX.resizeZones

This specifies the number of zones to break a window into for resizing. Possible values are:

1: No matter where in the window you click, the bottom right corner is always resized (old Blackbox behavior).
2: The window is broken in half vertically. The bottom corners are always resized, but the left one is used if you click in the left half of the window to resize.
4: The window is broken into four quarters. The corner nearest to where you click to resize is the corner that is resized.

example: session.screen0.resizeZones: 4

session.screenX.imageDither

When this is enabled, gradients are dithered to give a smoother appearance. This does make rendering them slower (maybe not so good on really low end machines) but improves appearance dramatically.

example: session.screen0.imageDither: True

session.screenX.disableBindingsWithScrollLock

When this is enabled, the ScrollLock key will disable Openbox's mouse bindings. This is useful for applications which use "Alt-RightClick" since openbox usually steals it. With this option enabled, and ScrollLock on, the "Alt-RightClick" is ignored by Openbox and gets to the application.

example: session.screen0.disableBindingsWithScrollLock: False

Toolbar options

These options affect how the toolbar appears and behaves.

session.screenX.toolbar.onTop
session.screenX.toolbar.autoHide
session.screenX.toolbar.widthPercent
session.screenX.toolbar.placement

session.screenX.toolbar.onTop

When this is enabled, the toolbar will stay on top of all other windows.

example: session.screen0.toolbar.onTop: False

session.screenX.toolbar.autoHide

When this is enabled, the toolbar will move itself to a hidden position, where it will only have a few pixels showing. When the mouse is moved over it, the toolbar will make itself fully visible, and remain so until the mouse leaves the toolbar. This hiding uses the session.autoRaiseDelay to determine how long to wait before showing itself or hiding.

example: session.screen0.toolbar.autoHide: False

session.screenX.toolbar.widthPercent

The percentage of the screens width that the toolbar should size itself to. A value less than 1 or greater than 100 is invalid and ignored.

example: session.screen0.toolbar.widthPercent: 66

session.screenX.toolbar.placement

This property specifies where to place the toolbar. Possible options are:

TopLeft
TopCenter
TopRight
BottomLeft
BottomCenter
BottomRight

example: session.screen0.toolbar.placement: BottomCenter

Slit options

These options affect how the slit appears and behaves.

session.screenX.slit.onTop
session.screenX.slit.autoHide
session.screenX.slit.placement
session.screenX.slit.direction

session.screenX.slit.onTop

When this is enabled, the slit will stay on top of all other windows.

example: session.screen0.slit.onTop: False

session.screenX.slit.autoHide

When this is enabled, the slit will move itself to a hidden position, where it will only have a few pixels showing. When the mouse is moved over it, the slit will make itself fully visible, and remain so until the mouse leaves the slit. This hiding uses the session.autoRaiseDelay to determine how long to wait before showing itself or hiding.