Key and mouse bindings are created in your ~/.config/openbox/rc.xml file. You should copy the file from /etc/xdg/openbox/rc.xml to ~/.config/openbox/rc.xml to edit it, if that file does not already exist.

Key bindings and mouse bindings both use Actions to specify what they will do. There are a lot of actions available to you. First we'll talk about how to write a generic key binding, or mouse binding. Then we'll discuss all the actions that are available.

Key bindings

Key bindings are found in the <keyboard> section of your rc.xml configuration file. Any bindings outside of that section are not valid and will be ignored.

Here's a few example key bindings from the default configuration file:

<keyboard>
  <keybind key="A-F4">
    <action name="Close"/>
  </keybind>
  <keybind key="A-Escape">
    <action name="Lower"/>
    <action name="FocusToBottom"/>
    <action name="Unfocus"/>
  </keybind>
  <keybind key="A-space">
    <action name="ShowMenu"><menu>client-menu</menu></action>
  </keybind>
</keyboard>

Syntax

A key binding is specified as follows:

<keyboard>
  ...
  <keybind key="KEY-COMBO">
    ...ACTIONS...
  </keybind>
  ...
</keyboard>

Key combinations

KEY-COMBO is the key combination which you want to bind to the actions. The format for the KEY-COMBO is: Modifier-Modifier-Key. Any number of modifiers (0 or more) can be used together, and they are each separated by a "-".

The Key is the name of the key, such as "a", "space", "Escape", or "F1". You can find the name of any key by using the xev command in a terminal, pressing the desired key, and watching the output from xev in the terminal.

Actions

The ACTIONS can be any number of actions. They will generally be executed in order from the first to the last.

Key chains

You can create Emacs-style key chains simply by nesting key bindings inside each other. Here's an example:

  <keybind key="C-f">
    <keybind key="x">
      <action name="ToggleMaximizeFull"/>
    </keybind>
    <keybind key="s">
      <action name="ToggleShade"/>
    </keybind>
  </keybind>

In order to maximize a window using this key binding you would press the Control key and the "f" key together (which is written as C-f), then you would release everything and press the "x" key.

To shade a window, you would press Control and the "f" key together, and then release everything and press the "s" key.

You can create key chains within key chains, with as many levels as you want, if you wish to.

The key chain dialog

When you start a key chain, after a short delay, a small dialog will appear in the top left corner of the screen to show you where you are in the key chain.

As long as you are in a key chain, other key bindings will not work except the ones found inside the key chain.

Cancelling key chains

If you leave Openbox in a key chain state for too long without completing it, Openbox will cancel the key chain and restore your normal key bindings.

You can also use the "C-g" (Control key and "g" key together), in the default configuration, to cancel any key chain which you are in. The choice of this key is controlled by the <chainQuitKey> in the <keyboard> section of the rc.xml configuration file.

The default <chainQuitKey> is defined as this:

<keyboard>
  <chainQuitKey>C-g</chainQuitKey>
  ...
</keyboard>

Chrooting key chains

By default, once you get to the terminal end of a key chain, and run some actions with it, Openbox will exit the key chain and return to the normal key bindings. You can use "chroots" if you want to prevent this behavior.

You can use a chroot in a key chain such as this:

  <keybind key="C-A-d" chroot="true">                                           
    <keybind key="Up"><action name="DesktopUp"><dialog>no</dialog></action></keybind>                 
    <keybind key="Down"><action name="DesktopDown"><dialog>no</dialog></action></keybind>                 
    <keybind key="Left"><action name="DesktopLeft"><dialog>no</dialog></action></keybind>                 
    <keybind key="Right"><action name="DesktopRight"><dialog>no</dialog></action></keybind>                 
    <keybind key="Escape"><action name="BreakChroot"/></keybind>              
  </keybind>

Once you enter a chrooted key chain, Openbox will not time out and leave the chain. You will remain inside the key chain until you use a BreakChroot action, as shown here, or press the <chainQuitKey>.