Older versions

This page describes Openbox 3.6. If you have an older config that doesn't work in 3.6, please let us know.

Introduction

Actions are used both in key and mouse bindings and in menus.

Action syntax

Actions are specified with the <action> tag as follows:

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

NAME is the name of the action as listed below, OPTIONS is a set of tags specific to each action also defined below.

Global actions

These actions are not used to manipulate windows. As such, they work whether a window is currently focused or not.

Execute

Runs a program.

Startup notification

You can use the startup notification protocol to tell everyone that an application is starting up. This can be used with most applications, but should not be used with old-style xterminals such as xterm, urxvt, aterm, etc, unless you include the command unset DESKTOP_STARTUP_ID in your shell's ~/.zshrc, ~/.bashrc or equivalent startup script.

Startup notification has these options, which are included inside the Execute action, in a <startupnotify> tag:

Example:

<keybind key="W-t">
  <action name="Execute">
    <command>urxvt</command>
  </action>
</keybind>

<keybind key="W-space">
  <action name="Execute">
    <startupnotify>
      <enabled>yes</enabled>
      <name>Terminal</name>
      <icon>konsole</icon>
    </startupnotify>
    <command>gnome-terminal</command>
  </action>
  <action name="Execute">
    <prompt>Are you sure you want to run a calculator!?</prompt>
    <startupnotify>
      <enabled>yes</enabled>
      <name>Calculator</name>
      <wmclass>xcalc</wmclass>
    </startupnotify>
    <command>xcalc</command>
  </action>
</keybind>

ShowMenu

Shows a menu by name.

The position tag has three sub-tags that are similar to how the per-application position tag works. <x> and <y> specify a position and take either a pixel value, the string "center" which will center the menu in that dimension, or a relative value specified either as a percentage or ratio. A relative value is interpreted in terms of the monitor the menu will be shown on, and will be relative to the left/top edge of the menu window and monitor for positive values, and to the right/bottom edge for negative values. The <monitor> tag can take one of the following values: default which is the default, this is also the same as specifying primary at present, and means the menu will show up on the primary monitor; mouse is the monitor containing the mouse pointer; active is the monitor containing the focused client, or the primary monitor if no client has focus; all will make the positions be relative to the full workspace area; any integer between 1 and the number of monitors you have will place the menu on the monitor with that number.

Openbox provides a number of built-in menus:

• client-list-combined-menu - A list of all windows, across all desktops
• client-list-menu - A list of all windows, separated into sub menus by desktop
• client-menu - A menu to control a window, such as to maximize or iconify it
  • This menu will only show with a key binding if an application window is focused, and for mouse bindings if the mouse event was on an application window (or its decorations).
• client-send-to-menu - A list of desktops. When one is selected, the window is sent to the desktop.
  • This menu will only show with a key binding if an application window is focused, and for mouse bindings if the mouse event was on an application window (or its decorations).
• client-layer-menu - A menu for selecting the stacking layer for a window, to put it "always on top" for example.
  • This menu will only show with a key binding if an application window is focused, and for mouse bindings if the mouse event was on an application window (or its decorations).

In addition, the default configuration provides this menu in the menu.xml file:

• root-menu - An example menu containing some applications and options for controlling Openbox

Example:

<keybind key="A-space">
  <action name="ShowMenu">
    <menu>client-menu</menu>
  </action>
</keybind>

<mousebind button="Right" action="Press">
  <action name="Activate"/>
  <action name="ShowMenu">
    <menu>client-menu</menu>
  </action>
</mousebind>

<mousebind button="Middle" action="Press">
  <action name="ShowMenu">
    <menu>client-list-combined-menu</menu>
  </action>
</mousebind>

<mousebind button="Right" action="Press">
  <action name="ShowMenu">
    <menu>root-menu</menu>
  </action>
</mousebind>

<keybind key="W-x">
  <action name="ShowMenu">
    <menu>programs</menu>
    <position>
      <x>center</x>
      <y>center</y>
      <monitor>1</monitor>
    </position>
  </action>
</keybind>

NextWindow

Cycles focus to the next window.

Example:

<keybind key="A-Tab">
  <action name="NextWindow"/>
</keybind>
<keybind key="C-A-Tab">
  <action name="NextWindow">
    <panels>yes</panels>
    <desktop>yes</desktop>
  </action>
</keybind>
<keybind key="W-Tab">
  <action name="NextWindow">
    <finalactions>
      <action name="Focus"/>
      <action name="Raise"/>
      <action name="Unshade"/>
      <action name="MoveResizeTo">  <!-- center the window which we're focusing -->
        <x>center</x>
        <y>center</y>
      </action>
    </finalactions>
  </action>
</keybind>

PreviousWindow

Cycles focus to the previous window. Takes the same options as NextWindow.

DirectionalCycleWindows

Cycles focus to the window in the direction specified of the currently focused window.

Example:

<keybind key="W-Up">
  <action name="DirectionalalCycleWindows"><direction>north</direction><dialog>yes</dialog></action>
</keybind>
<keybind key="W-S-Down">
  <action name="DirectionalFocus">
    <direction>south</direction>
    <finalactions>
      <action name="Focus"> <!-- give focus without raising the window -->
      <action name="Unshade">
    </finalactions>
  </action>
</keybind>

DirectionalTargetWindow

Moves focus to the window in the direction specified of the currently focused window. This is similar to the DirectionalFocusCycle action, but it moves focus instantly instead of letting you interactively choose a window. Takes the same options except for <dialog> and <bar>.

Example:

<keybind key="W-Up">
  <action name="DirectionalTargetWindow"><direction>north</direction></action>
</keybind>
<keybind key="W-S-Down">
  <action name="DirectionalTargetWindow">
    <direction>south</direction>
    <finalactions>
      <action name="Focus"> <!-- give focus without raising the window -->
      <action name="Unshade">
    </finalactions>
  </action>
</keybind>

GoToDesktop

Changes the visible desktop.

The value "last" for the <to> option goes to the desktop you were on before the current one. Only one desktop is remembered, but there is a timeout so that if you go past a few desktops, you will go to the one you were really on before. This is useful if you switch between two desktops by going to the next or previous desktop several times, for example with the scroll wheel. The timeout is 750ms and cannot be configured currently.

Example:

<keybind key="W-F1">
  <action name="GoToDesktop"><to>1</to></action>
</keybind>
<keybind key="W-BackSpace">
  <action name="GoToDesktop"><to>last</to></action>
</keybind>
<keybind key="W-A">
  <action name="GoToDesktop"><to>next</to><wrap>no</wrap></action>
</keybind>

AddDesktop

Create a new desktop in the location specified.

Example

<keybind key="W-F12">
  <action name="AddDesktop">
     <where>current</where>
  </action
</keybind>

RemoveDesktop

Remove the a desktop in the location specified and move the windows on it to the one after it (or before if the removed desktop is the last one).

Example

<keybind key="W-F11">
  <action name="RemoveDesktop"/>
</keybind>

ToggleShowDesktop

Hides all windows so that the desktop is visible, and gives focus to the desktop window if one exists (such as in GNOME and KDE). You can also use the action again to show the windows again, if no windows have become visible yet.

Example:

<keybind key="W-d">
  <action name="ToggleShowDesktop"/>
</keybind>

ToggleDockAutohide

Toggles the autohide setting on the dock temporarily. This effectively means you can show/hide the dock with a keybinding.

Example:

<keybind key="C-A-d">
  <action name="ToggleDockAutohide"/>
</keybind>

Reconfigure

Prompts Openbox to reload its config file, menu and theme.

Example:

<keybind key="W-F11">
  <action name="Reconfigure"/>
</keybind>

Restart

Restarts Openbox. This starts a new copy of Openbox, and can be used to upgrade to a newly installed version without logging out of your X session. It can also be used to start another window manager.

Example:

<keybind key="W-F12">
  <action name="Restart"/>
</keybind>
<keybind key="W-F11">
  <action name="Restart"><command>firebox</command></action>
</keybind>

Exit

Exits Openbox.

If Openbox is built with session support and is running inside a session manager (such as gnome-session, ksmserver), then Openbox will ask the session manager to log out. Otherwise, Openbox will simply exit, ending the current X session.

Example:

<keybind key="C-A-S-F12">
  <action name="Exit">
    <prompt>yes</prompt>
  </action>
</keybind>

SessionLogout

This is a synonym for the Exit action.

Debug

Prints out a string in Openbox's output for debugging purposes.

Example:

<keybind key="W-F10">
  <action name="Debug">
   <string>-------------------------------</string>
  </action>
</keybind>

Window actions

These actions are used to control windows. For key bindings, they operate on the currently focused window. For mouse bindings they operate on the window being clicked/dragged on.

Focus

Focuses a window.

Example:

<mousebind button="A-Left" action="Press">
  <action name="Focus"/>
  <action name="Raise"/>
</mousebind>

Raise

Raises a window above other windows in its layer.

Example:

<mousebind button="A-Left" action="Press">
  <action name="Focus"/>
  <action name="Raise"/>
</mousebind>

Lower

Lowers a window below other windows in its layer.

Example:

<mousebind button="A-Middle" action="Press">
  <action name="Lower"/>
  <action name="FocusToBottom"/>
  <action name="Unfocus"/>
</mousebind>

RaiseLower

Raises the window if it is currently behind any other windows in its layer. Lowers the window if it is above all other windows in its layer.

Example:

<keybind key="C-A-r">
  <action name="RaiseLower"/>
</keybind>

Unfocus

Move focus off of the window. Usually used in conjuction with FocusToBottom.

Example:

<mousebind button="A-Middle" action="Press">
  <action name="Lower"/>
  <action name="FocusToBottom"/>
  <action name="Unfocus"/>
</mousebind>

FocusToBottom

Move the window to the bottom of the recently-used-windows list. This means that other windows will be given preference when selecting which window to focus. Usually used in conjuction with Unfocus.

Example:

<keybind key="A-Escape">
  <action name="Lower"/>
  <action name="FocusToBottom"/>
  <action name="Unfocus"/>
</keybind>

Iconify

Iconify (a.k.a. minimize) the window.

Example:

<mousebind button="Left" action="Click">
  <action name="Iconify"/>
</mousebind>

Close

Close the window.

Example:

<keybind key="A-F4">
  <action name="Close"/>
</keybind>

ToggleShade

Shade (a.k.a. Roll up) the window, so only its titlebar is visible. If the window is already shaded, then Unshade (a.k.a. Roll down) the window.

Example:

<mousebind button="Left" action="Click">
  <action name="ToggleShade"/>
</mousebind>

Shade

Shade (a.k.a. Roll up) the window, so only its titlebar is visible.

Example:

<mousebind button="Up" action="Click">
  <action name="Shade"/>
  <action name="FocusToBottom"/>
  <action name="Unfocus"/>
</mousebind>

Unshade

Unshade (a.k.a. Roll down) the window, when it has been shaded.

Example:

<mousebind button="A-Left" action="Click">
  <action name="Unshade"/>
</mousebind>

ToggleOmnipresent

Make the window visible on all desktops, if it is not already. Otherwise, make it visible only on the current desktop.

Example:

<mousebind button="Left" action="Click">
  <action name="ToggleOmnipresent"/>
</mousebind>

ToggleMaximize

Maximize the window to fill the entire screen in the directions specified. If it is already maximized, return it to its original dimensions.

Example:

<mousebind button="Left" action="Click">
  <action name="ToggleMaximize"/>
</mousebind>
<mousebind button="Middle" action="DoubleClick">
  <action name="ToggleMaximize"><direction>horizontal</direction></action>
</mousebind>

Maximize

Maximize the window to fill the entire screen in the directions specifed.

Example:

<keybind key="A-F6">
  <action name="Maximize"/>
</keybind>

Unmaximize

Unmaximizes the window in the directions specified, and return it to its pre-maximized dimensions.

Example:

<keybind key="A-F7">
  <action name="Unmaximize"/>
</keybind>

ToggleFullscreen

Makes the window fullscreen, filling the entire monitor, without any decorations. If the window is already fullscreened, then it returns it to its pre-fullscreen dimensions.

Example:

<keybind key="A-F12">
  <action name="ToggleFullscreen"/>
</keybind>

ToggleDecorations

Removes the window's decorations. If the <keepBorder> configuration option is enabled (as in the default configuraton), then a border will be left as the only decorations around the window. If the window has already had its decorations removed, then this will restore them.

Example:

<keybind key="A-S-d">
  <action name="ToggleDecorations"/>
</keybind>

Decorate

Gives a window its normal decorations.

Example:

<keybind key="C-S-d">
  <action name="Decorate"/>
</keybind>

Undecorate

Removes decorations from a window. If the <keepBorder> configuration option is enabled (as in the default configuraton), then a border will be left as the only decorations around the window.

Example:

<keybind key="C-S-d">
  <action name="Undecorate"/>
</keybind>

SendToDesktop

Moves the window to another desktop.

Example:

<keybind key="W-S-F1">
  <action name="SendToDesktop"><to>1</to></action>
</keybind>
<keybind key="W-S-BackSpace">
  <action name="SendToDesktop"><to>last</to></action>
</keybind>
<!-- Cycle through all windows and focus the selected one on the current desktop -->
<keybind key="W-S-Tab">
  <action name="NextWindow">
    <allDesktops>yes</allDesktops>
    <finalactions>
      <action name="SendToDesktop"><to>current</to></action>
      <action name="focus"/>
      <action name="raise"/>
    </finalactions>
  </action
</keybind>

See also GoToDesktop.

Move

Begin interactively moving the window. Once a move has begun, you can move the window either by moving the mouse pointer, or by using the arrow keys. The move will complete when you release a mouse button, or press the Enter key. Pressing Escape will cancel the move.

Example:

<mousebind button="A-Left" action="Drag">
  <action name="Move"/>
</mousebind>

Resize

Begin interactively resizing the window. Once a resize has begun, you can resize the window either by moving the mouse pointer, or by using the arrow keys. The move will complete when you release a mouse button, or press the Enter key. Pressing Escape will cancel the move.

If the resize is bound to a mouse button, then the corner/edge of the window that is resized is chosen by which is nearest to the mouse pointer. You can use the <edge> option to override this and specify which corner/edge should be resized.

Example:

<mousebind button="A-Right" action="Drag">
  <action name="Resize"/>
</mousebind>

MoveResizeTo

Move and/or resize a window.

Example:

<keybind key="W-2">
  <action name="MoveResizeTo">
    <!-- move the window to the second monitor -->
    <monitor>2</monitor>
  </action>
</keybind>
<keybind key="W-F10">
  <action name="MoveResizeTo">
    <!-- put the window in the bottom right corner -->
    <x>-0</x>
    <y>-0</y>
  </action>
</keybind>
<keybind key="W-c">
  <action name="MoveResizeTo">
    <!-- center the window on the first monitor -->
    <x>center</x>
    <y>center</y>
    <monitor>1</monitor>
  </action>
</keybind>
<keybind key="C-A-1">
  <action name="MoveResizeTo">
    <!-- adjust a window's height -->
    <width client="yes">1/2</width>
    <height>300</height>
  </action>
</keybind>

MoveRelative

Move the window by an incremental amount, relative to its current position

Example:

<keybind key="W-Right">
  <action name="MoveRelative">
    <x>5</x>
    <y>0</y>
  </action>
</keybind>
<keybind key="W-Up">
  <action name="MoveRelative">
    <x>0</x>
    <y>-5</y>
  </action>
</keybind>

ResizeRelative

Resize the window by an incremental amount, relative to its current size.

Example:

<keybind key="W-Down">
  <action name="ResizeRelative">
    <bottom>5</bottom>
  </action>
</keybind>
<keybind key="W-S-Down">
  <action name="ResizeRelative">
    <bottom>-5</bottom>
  </action>
</keybind>

MoveToEdge

Moves the window to the nearest edge in the direction specified. Edges are the outer edges of other windows, monitor edges in multi-monitor setups, or the desktop boundaries.

Example:

<keybind key="W-Left">
  <action name="MoveToEdge"><direction>west</direction></action>
</keybind>

GrowToEdge

Grows the window until it touches the nearest edge in the direction specified. Edges are the outer edges of other windows, monitor edges in multi-monitor setups, or the desktop boundaries. If the window edge is at the screen edge already, it is shrunk instead.

Example:

<keybind key="C-Right">
  <action name="GrowToEdge"><direction>west</direction></action>
</keybind>

GrowToFill

Grows the window in every direction but doesn't go across any edges until all edges touch something else.

ShrinkToEdge

Shrinks the window until it touches the nearest edge in the direction specified. Edges are the outer edges of other windows, monitor edges in multi-monitor setups, or the desktop boundaries. If no edge is found, the window is halved in size.

Example:

<keybind key="C-Right">
  <action name="GrowToEdge"><direction>west</direction></action>
</keybind>

If

This action allows you to do different things depending on various conditions. The basic structure is:

<action name="If">
  <query target="default">
    <somecondition>value of condition</somecondition>
    <someothercondition>value of condition</someothercondition>
  </query>
  <then>
    ... list of <action>s to run when true
  </then>
  <else>
    ... list of <action>s to run when false
  </else>
</action>

The query tag's target can be either "default" or "focus", and multiple query tags can be present in one If action. "default" means to check the conditions against whatever window the actions would normally act on, while "focus" always checks against the window that currently has focus. These differ for example during focus cycling actions, or when the ForEach action is being used.

The list of conditions is:

Example:

<!-- this corresponds to the ShadeLower and UnshadeRaise actions from 3.4 -->
<mousebind button="Up" action="Click">
  <action name="If">
    <query>
      <shaded>yes</shaded>
    </query>
    <then>
      <action name="Lower"/>
    </then>
    <else>
      <action name="Shade"/>
    </else>
  </action>
</mousebind>
<mousebind button="Down" action="Click">
  <action name="If">
    <query>
      <shaded>no</shaded>
    </query>
    <then>
      <action name="Raise"/>
    </then>
    <else>
      <action name="Unshade"/>
    </else>
  </action>
</mousebind>

ForEach

This action has the same syntax as the If action, but runs for every client window on every desktop, not just the current window.

Stop

As of Openbox 3.6.1: Stop will end execution only of the parent element that directly contains the Stop. If a grandparent element exists (via hierarchical nesting via If or ForEach), execution of that grandparent element will (surprisingly!) continue. Additionally, if a ForEach contains an If (or several nested Ifs), and if one of those Ifs contains a Stop, then that Stop will cause that ForEach to exit once the current iteration completes.

As of Openbox 3.6.1: If a parent ForEach contains a child ForEach that contains a Stop, Openbox may permanently lock up and freeze. This is a bug.

Stop takes no arguments.

One pattern is to use a Stop at the end of a ForEach. In this pattern, the actions in the ForEach will be applied only to the first client that matches the ForEach's query.

ToggleAlwaysOnTop

Makes the window always above other windows, in the "always on top" layer. If the window is already set to be above other windows, this puts the window back in the stacking order with normal windows.

Example:

<keybind key="W-F8">
  <action name="ToggleAlwaysOnTop"/>
</keybind>

ToggleAlwaysOnBottom

Makes the window always below other windows, in the "always on bottom" layer. If the window is already set to be below other windows, this puts the window back in the stacking order with normal windows.

Example:

<keybind key="W-F5">
  <action name="ToggleAlwaysOnBottom"/>
</keybind>

SendToLayer

Moves the window to the specified layer.

Example:

<keybind key="W-F7">
  <action name="SendToLayer"><layer>top</layer></action>
</keybind>