Details of the Config Files

Key Bindings

Introduction

Key bindings are used to bind actions to key combinations. Whenever the combination is pressed, the actions bound to it will be executed.

Key bindings are found in the keyboard section of the rc.xml file. Any key bindings outside of the keyboard section will be ignored.

Syntax

Key bindings are specified using the following:

<keybind key="KEY COMBO">
ACTIONS
</keybind>

Any number of actions may appear in a keybind.

KEY COMBO is the key combination to be bound. The key combo has the following syntax: Modifier-Modifier-Key. Any number of modifiers can be specified, following each one with a '-'. The available modifiers are:

S - the Shift key
C - the Control key
A - the Alt key
W - the Windows keys
M - Mod3, not set by default i think

Mod1 though Mod5 may also be used as modifiers. The xmodmap tool is used to set these up. The A and W modifiers are merely aliases for Mod1 and Mod4.

The Key is the name of the key, such as 'a' or 'F1' or '4'. You can find the name of a key by running xev in a terminal, pressing the key, and watching the output from xev in the terminal.

ACTIONS is any number of actions which will be executed when the key combination is pressed.

Chaining

Key-chains, as first seen in Emacs, are possible by simply nesting the key bindings. For example:

<keybind key="C-f">
  <keybind key="x">
    ACTIONS
  </keybind>
</keybind>

The actions bound in this example would be fired by first pressing "C-f" (Hold Control - Press f), and then releasing everything and pressing "x".

If you begin a key-chain, you will be unable to type in your applications until you complete the chain. After a short wait the chain will time out, and be cancelled. You may also cancel out of a chain by using the "C-g" (Hold Control - Press g) key sequence (the same as is used in Emacs). The cancelling key sequence is configurable if desired.

Mouse Bindings

Introduction

Mouse bindings are used to bind actions to mouse interactions. These control most of Openbox's behavior, from what happens when you click the Close button in a window's titlebar to how you drag windows to move them around the screen.

Mouse bindings are found in the mouse section of the rc.xml file. Any mouse bindings outside of the mouse section will be ignored.

Syntax

Mouse bindings are specified using the following:

<context name="CONTEXT">
  <mousebind button="BUTTON" action="INTERACTION">
    ACTIONS
  </mousebind>
</context>

Any number of mousebinds may appear in a context, and any number of actions may appear in a mousebind.

First, some definitions:

Decorations - The decorations drawn by Openbox around your applications. This includes the Titlebar displayed on the top of each window, with the title, and some buttons in it. It also includes the Handle displayed on the bottom of each window.
Client area - The applications themselves. This is the section of the window inside the Decorations.

CONTEXT is the context in which the mouse interaction is taking place. The possible contexts are:

Frame - Includes the entirety of all windows. This includes on their decorations and in their Client area. Note: When a button is bound in this context, the clicks will not be passed through to the application. Use with care.
Client - The Client area of all windows. Notes: When a button is bound in this context, the clicks will be passed through to the application. Because of how these are handled, Press interactions are the only useful interactions for this context.
Desktop - The desktop or background. This works even when you are running a file manager such as Nautilus.
Titlebar - The Decorations on the top of each window, containing the window's title.
Handle - The Decorations on the bottom of each window.
TLCorner - The top-left corner of the window's titlebar (the mouse cursor changes while over this). Generally this is only used for resizing windows.
TRCorner - The top-right corner of the window's titlebar (the mouse cursor changes while over this). Generally this is only used for resizing windows.
BLCorner - The bottom-left corner of the window's handle (the mouse cursor changes while over this). Generally this is only used for resizing windows.
BRCorner - The bottom-right corner of the window's handle (the mouse cursor changes while over this). Generally this is only used for resizing windows.
Icon - The window's icon in all window's titlebars.
AllDesktops - The All-Desktops (Omnipresent) button in all window's titlebars. This button is not visible in the default settings. It is called the All-Desktop button because its default bindings toggle omnipresence on the window.
Shade - The Shade button in all window's titlebars. This button is not visible in the default settings. It is called the Shade button because its default bindings toggle shading on the window.
Iconify - The Iconify button in all window's titlebars. It is called the Iconify button because its default bindings iconify the window.
Maximize - The Maximize button in all window's titlebars. It is called the Maximize button because its default bindings maximize the window.
Close - The Close button in all window's titlebars. It is called the Close button because its default bindings close the window.
MoveResize - Bindings under this context are available while moving or resizing a window.

BUTTON is the mouse button and keyboard modifiers being bound. The button has the following syntax: Modifier-Modifier-Button. Any number of modifiers can be specified, following each one with a '-'. The available modifiers are listed here

The Button can be the button's number, such as 1 or 3, or it can be a name. The available names are Left, Middle, Right, Up, and Down.

INTERACTION specifies what you are doing with your mouse for the binding. It can be one of the following:

Press - A mouse button is pressed.
Release - A mouse button is released.
Click - A mouse button is pressed and released.
DoubleClick - A mouse button is pressed and released twice, quickly. The time delay in which both clicks must occur is configurable.
Drag - A mouse button is pressed, and the mouse is moved while holding the button down.

ACTIONS is any number of actions which will be executed when the mouse interaction occurs in the given context.

Examples

<context name="Close">
  <mousebind button="Left" action="Press">
    ACTIONS
  </mousebind>
</context>
<context name="Titlebar">
  <mousebind button="Left" action="Press">
    ACTIONS
  </mousebind>
  <mousebind button="Left" action="Click">
    ACTIONS
  </mousebind>
  <mousebind button="Left" action="Drag">
    ACTIONS
  </mousebind>
  <mousebind button="Right" action="Press">
    ACTIONS
  </mousebind>
</context>

Menus

Introduction

Menus are not read out of the rc.xml file, but rather out of files specified in the rc.xml. By default, the menu.xml file is read to build the menus.

Each menu is given an ID which is used in the bindings to specify which menu is being shown.

Openbox provides a few default menus:

client-menu - A menu for controlling a window.
client-send-to-menu - A menu for sending windows to desktops.
client-layer-menu - A menu for selecting stacking layers for windows (Always on top, etc).
client-list-menu - A menu for selecting a window or desktop to use.

Syntax

A menu file must be entirely enclosed within:

<openbox_menu>
...
</openbox_menu>

Inside these, menus are specified as follows:

<menu id="ID" label="TITLE">

  <item label="LABEL">
    ACTIONS
  </item>

  <separator />

  <menu id="ID" />

  <separator />

  <menu id="ID" label="TITLE" />
    <item label="LABEL">
      ACTIONS
    </item>
  </menu>

  <separator />

  <item label="LABEL">
    ACTIONS
  </item>

</menu>

The syntax example above shows how to put entries into a menu (items) and two methods to add submenus to a menu. It also shows how to put separators into the menu to group items visibly.

Submenus can be simply referenced, and defined outside the parent menu (as the first submenu in the example would be). Submenus can also be nested directly into the containing menu, and still be referenced elsewhere.

ID is a unique identifier used to reference the menu. The value of the ID can be used in a ShowMenu action to use the menu.

TITLE is the title displayed on the menu.

LABEL is the text displayed in the menu item

ACTIONS is any number of actions which will be executed when the menu item is selected.

Pipe menus

Openbox allows for dynamic menus, built on-the-fly from scripts. These are referred to as "Pipe menus" since the script's output is piped back to Openbox and used for the menu.

A Pipe menu can be created by placing the following into a menu file:

<menu id="ID" label="TITLE" execute="COMMAND" />

The generated Pipe menu can be referenced just like any other menu.

COMMAND is a command which is executed. The output from this command is parsed and turned into the menu. The output from the script should be a menu, something like:

<openbox_pipe_menu>
  <item label="LABEL">
    ACTIONS
  </item>
</openbox_pipe_menu>

Actions

Introduction

Actions are used to specify the behavior of Openbox. Any place where you can use actions, you can place more than one in a row to cause them all to execute one after the other.

Syntax

Basic Syntax

Actions are specified using the following:

<action name="NAME">PARAMETERS</action>

NAME is the name of the action, specifying which action to execute.

PARAMETERS is any possible inner tags to change how the action will behave. For example, the Execute action has an inner execute parameter specifying what will be run:

<action name="Execute"><execute>xterm</execute></action>

As another example, the DesktopRight action has an inner wrap parameter which specifies if the action should wrap around to the beginning when trying to go past the end:

<action name="DesktopRight"><wrap>no</wrap></action>

Syntax of Parameters

There are 3 types of parameters:

Strings
Numbers
Booleans (True/False)

The format of Strings and Numbers is pretty obvious. foo would be a valid String, and 23 would be a valid Number.

Booleans can be specied with one of: true, false, yes, no, on, or off.

Actions on Windows

Some actions will be performed globally, but some must be associated with a window, and cause the action to be applied to that window. When binding actions to mouse clicks, the window clicked on will have all the bound actions performed on it as applicable. When binding actions to keys, the actions will be associated with the currently focused window.

Available actions

Global Actions

Name	Parameters (default value in brackets)
Execute - run an executable	command () - specifies the executable to be run along with any arguments to pass it. The tilde ('~') character will be expanded in this string to your home directory, but no other shell expansions or scripting syntax can be used in the command.
DirectionalFocusNorth - cycles focus to the window north of the currently focused window.	dialog (yes) - display the focus cycling dialog while switching focus.
DirectionalFocusEast - cycles focus to the window east of the currently focused window.	dialog (yes) - display the focus cycling dialog while switching focus.
DirectionalFocusSouth - cycles focus to the window south of the currently focused window.	dialog (yes) - display the focus cycling dialog while switching focus.
DirectionalFocusWest - cycles focus to the window west of the currently focused window.	dialog (yes) - display the focus cycling dialog while switching focus.
DirectionalFocusNorthEast - cycles focus to the window northeast of the currently focused window.	dialog (yes) - display the focus cycling dialog while switching focus.
DirectionalFocusSouthEast - cycles focus to the window southeast of the currently focused window.	dialog (yes) - display the focus cycling dialog while switching focus.
DirectionalFocusSouthWest - cycles focus to the window southwest of the currently focused window.	dialog (yes) - display the focus cycling dialog while switching focus.
DirectionalFocusNorthWest - cycles focus to the window northwest of the currently focused window.	dialog (yes) - display the focus cycling dialog while switching focus.
NextWindow - cycles focus to the next window.	linear (no) - when true, windows are always cycled in the order in which they appeared; otherwise, they are cycled in order of recent use. dialog (yes) - display the focus cycling dialog while switching focus.
PreviousWindow - cycles focus to the previous window.	linear (no) - when true, windows are always cycled in the order in which they appeared; otherwise, they are cycled in order of recent use. dialog (yes) - display the focus cycling dialog while switching focus.
Desktop - changes the currently visible desktop.	desktop (1) - the number of the desktop (starting at 1) to make visible. dialog (no) - display the desktop dialog (with pager) while switching desktops. This will only work in keyboard bindings; otherwise, it is disabled.
AddDesktopLast - Adds a new desktop at the end of the list of current desktops.
RemoveDesktopLast - Removes the last of the current desktops.
AddDesktopCurrent - Adds a new desktop at the current location in the list of desktops.
RemoveDesktopCurrent - Removes the current desktop.
DesktopNext - makes the next desktop visible.	wrap (yes) - whether to wrap around to the first desktop when going past the last. dialog (yes) - display the desktop dialog (with pager) while switching desktops. This will only work in keyboard bindings; otherwise, it is disabled.
DesktopPrevious - makes the previous desktop visible.	wrap (yes) - whether to wrap around to the last desktop when going past the first. dialog (yes) - display the desktop dialog (with pager) while switching desktops. This will only work in keyboard bindings; otherwise, it is disabled.
DesktopRight - makes visible the desktop to the right of the currrently visible desktop.	wrap (yes) - whether to wrap around to the first desktop when going past the last. dialog (yes) - display the desktop dialog (with pager) while switching desktops. This will only work in keyboard bindings; otherwise, it is disabled.
DesktopLeft - makes visible the desktop to the left of the currently visible desktop.	wrap (yes) - whether to wrap around to the last desktop when going past the first. dialog (yes) - display the desktop dialog (with pager) while switching desktops. This will only work in keyboard bindings; otherwise, it is disabled.
DesktopDown - makes visible the desktop beneath the currently visible desktop.	wrap (yes) - whether to wrap around to the first desktop when going past the last. dialog (yes) - display the desktop dialog (with pager) while switching desktops. This will only work in keyboard bindings; otherwise, it is disabled.
DesktopUp - makes visible the desktop above the currently visible desktop.	wrap (yes) - whether to wrap around to the last desktop when going past the first. dialog (yes) - display the desktop dialog (with pager) while switching desktops. This will only work in keyboard bindings; otherwise, it is disabled.
ToggleShowDesktop - toggles between ShowDesktop and UnshowDesktop.
DesktopLast - makes the most recently visible desktop visible again. Only one desktop is remembered, so using this twice will simply flip between two desktops.
ShowMenu - shows a menu by name	menu () - the name of the menu to show. The names of menus are specified in the id attribute of their menu tag.
Reconfigure - reloads the config file, menu, and theme.
Restart - restarts Openbox. This starts a new copy of Openbox, and can be used to upgrade to a newly installed version.	command () - when this is used, the executable specified within will be run instead of Openbox. This can be used to switch to another window manager if desired.
Exit - exits Openbox.

Actions for Windows

Name	Parameters (default value in brackets)
Activate - activates the window. This is the same process that occurs when focus cycling to a window, or selecting it in the client-list-menu.
Focus - give focus to the window.
Unfocus - remove focus from the window.
Iconify - iconify the window. This causes the window to not be shown on screen. The window can be found again with focus cycling or with the client-list-menu.
RaiseLower - raise the window to the forefront if it is obscured behind anything; lower it to the back if it is already at the front.
Raise - raise the window to the forefront.
Lower - lower the window to the back.
Close - request the window to close.
Kill - forcibly disconnect the window's application from the X server.
ShadeLower - Shade the window; if the window is already shaded, then Lower it.
UnshadeRaise - Unshade the window; if the window is already unshaded, then Raise it.
Shade - shade the window. This hides everything of the window except the titlebar. This concept has also been known as "rolling up" the window into the titlebar.
Unshade - unshade the window. This shows the entire window if it was previously shaded.
ToggleShade - toggles the shaded state of the window, firing the Shade and Unshade actions appropriately.
ToggleOmnipresent - toggles between moving the client to all desktops (omnipresent) and to the currently visible desktop.
MoveRelative - moves the window	x (0) - the number of pixels to move the window horizontally. A positive value moves to the right, a negative value moves to the left. y (0) - the number of pixels to move the window vertically. A positive value moves down, a negative value moves up.
ResizeRelative - resizes the window	top or up (0) - the amount to move the top edge of the window. A positive value makes the window taller, a negative value makes it shorter. bottom or down (0) - the amount to move the bottom edge of the window. A positive value makes the window taller, a negative value makes it shorter. left (0) - the amount to move the left edge of the window. A positive value makes the window wider, a negative value makes it narrower. right (0) - the amount to move the right edge of the window. A positive value makes the window wider, a negative value makes it narrower.
MaximizeFull - maximizes a window to fill the entire screen.
UnmaximizeFull - restores a window to its original size.
ToggleMaximizeFull - toggles between MaximizeFull and UnmaximizeFull.
MaximizeHorz - maximizes a window to fill the entire screen horizontally, but not vertically.
UnmaximizeHorz - restores a window to its original size.
ToggleMaximizeHorz - toggles between MaximizeHorz and UnmaximizeHorz.
MaximizeVert - maximizes a window to fill the entire screen vertically, but not horizontally.
UnmaximizeVert - restores a window to its original size.
ToggleMaximizeVert - toggles between MaximizeHorz and UnmaximizeVert.
SendToDesktop - sends the window to the specified desktop	desktop (1) - the number of the desktop (starting at 1) to send the window to. follow (yes) - whether to change to the desktop while moving the window.
SendToDesktopNext - sends the window to the next desktop.	wrap (yes) - whether to wrap around to the first desktop when going past the last. follow (yes) - whether to change to the desktop while moving the window.
SendToDesktopPrevious - sends the window to the previous desktop.	wrap (yes) - whether to wrap around to the last desktop when going past the first. follow (yes) - whether to change to the desktop while moving the window.
SendToDesktopRight - sends the window to the desktop to the right of the currently visible desktop.	wrap (yes) - whether to wrap around to the first desktop when going past the last. follow (yes) - whether to change to the desktop while moving the window.
SendToDesktopLeft - sends the window to the desktop to the left of the currently visible desktop.	wrap (yes) - whether to wrap around to the last desktop when going past the first. follow (yes) - whether to change to the desktop while moving the window.
SendToDesktopDown - sends the window to the desktop beneath the currently visible desktop.	wrap (yes) - whether to wrap around to the first desktop when going past the last. follow (yes) - whether to change to the desktop while moving the window.
SendToDesktopUp - sends the window to the desktop above the currently visible desktops.	wrap (yes) - whether to wrap around to the last desktop when going past the first. follow (yes) - whether to change to the desktop while moving the window.
ToggleDecorations - toggles if the window is given decorations. Decorations are the the titlebar and handle that are shown around most windows.
Move - begins an interactive move. The move will complete when the mouse button is released, if it is bound to one. The Enter key will also complete the move, and the Escape key will cancel it.
Resize - begins an interactive resize. The resize will complete when the mouse button is released, if it is bound to one. The Enter key will also complete the resize, and the Escape key will cancel it.
SendToTopLayer - makes the window always-on-top.
SendToNormalLayer - make the window not always-on-top or always-on-bottom.
SendToBottomLayer - makes the window always-on-bottom.
ToggleAlwaysOnTop - toggles between SendToTopLayer and SendToNormalLayer.
ToggleAlwaysOnBottom - toggles between SendToBottomLayer and SendToNormalLayer.
MoveToEdgeNorth - moves the window to the nearest edge to the north of it.
MoveToEdgeSouth - moves the window to the nearest edge to the south of it.
MoveToEdgeEast - moves the window to the nearest edge to the east of it.
MoveToEdgeWest - moves the window to the nearest edge to the west of it.
GrowToEdgeNorth - resizes the window up to the nearest edge to the north of it.
GrowToEdgeSouth - resizes the window up to the nearest edge to the south of it.
GrowToEdgeEast - resizes the window up to the nearest edge to the east of it.
GrowToEdgeWest - resizes the window up to the nearest edge to the west of it.

Examples

<action name="Raise"/>
<action name="Focus"/>

<action name="ShowMenu"><menu>root-menu</menu></action>

<action name="MoveRelativeVert"><delta>5</delta></action>

<action name="SendToDesktopNext">
<wrap>no</wrap>
<follow>no</follow>
</action>

Table of Contents