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 ho