Older versions

This page describes Openbox 3.6. For older documentation, see 3.5 and 3.4. The syntax described there should still work in 3.6. If you have an older config that doesn't work in 3.6, please let us know.

Introduction

Action syntax

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.

Option

Default Value

Description

<command>

""

A string which is the command to be executed, along with any arguments to be passed to it. The "~" tilde character will be expanded to your home directory, but no other shell expansions or scripting syntax may be used in the command unless they are passed to the sh command. Also, the & character must be written as &amp; in order to be parsed correctly. <execute> is a deprecated name for <command>.

<prompt>

none

A string which Openbox will display in a popup dialog, along with "Yes" and "No" buttons. The execute action will only be run if you choose the "Yes" button in the dialog.

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:

Option

Default Value

Description

<enabled>

no

A boolean (yes/no) which says if the startup notification protocol should be used to notify other programs that an application is launching. This is disabled by default to avoid it being used for old-style xterminals.

<wmclass>

none

A string specifying one of the values that will be in the application window's WM_CLASS property when the window appears. This is not needed for applications that support the startup-notification protocol.

<name>

none

The name of the application which is launching. If this option is not used, then the command itself will be used for the name.

<icon>

none

The icon of the application which is launching. If this option is not used, then the command itself will be used to pick the icon.

ShowMenu

The name of the menu to be shown. Names of menus are specified in the menu file, in the id attribute of the <menu> tag.

<position>

Show the menu in the specified position on the specified monitor, see below.

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

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>.

GoToDesktop

The desktop to switch to, starting from 1, or one of the following special values: "current", "next", "previous", "last", "north" or "up", "south" or "down", "west" or "left", "east" or "right".

<wrap>

yes

A boolean (yes/no) which when enabled lets you wrap around from the last desktop to the first, west to east, north to south, etc, and vice versa.

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.

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).

Option

Default Value

Description

<where>

last

Can be "current" (remove the current desktop and shuffle the desktops after it over) or "last" (remove the last desktop).

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.

Option

Default Value

Description

<strict>

"no"

A boolean (yes/no) which specifies if windows are allowed to show themselves while in Show Desktop mode. In strict mode, they cannot.

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.

Option

Default Value

Description

<command>

""

A string which is the command to be executed as the new window manager, along with any arguments to be passed to it.

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.

Option

Default Value

Description

<prompt>

true

A boolean (yes/no) which specifies if Openbox should display a prompt dialog asking if you really want to exit before it actually exits.

Maximize

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

Option

Default Value

Description

<direction>

both

The direction to maximize the window, can be "both", "horizontal" or "vertical".

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.

Option

Default Value

Description

<direction>

both

The direction to maximize the window, can be "both", "horizontal" or "vertical".

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.

Option

Default Value

Description

<to>

current

The desktop to send the window to, starting from 1, or one of the following special values: "current", "next", "previous", "last", "north" or "up", "south" or "down", "west" or "left", "east" or "right".

<wrap>

yes

A boolean (yes/no) which when enabled lets you wrap around from the last desktop to the first, west to east, north to south, etc, and vice versa.

<follow>

yes

A boolean (yes/no) which when enabled will also switch to the specified desktop.

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.

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.

Option

Default Value

Description

<edge>

none

One of: "top", "left", "right", "bottom", "topleft", "topright", "bottomleft", "bottomright". This specifies which corner/edge should be resized, and overrides having the edge determined dynamically by which is closest to the mouse pointer.

MoveResizeTo

Move and/or resize a window.

Option

Default Value

Description

<x>

current

The position to move the window to. current specifies the window's current x-position. center moves the window to the center of the screen, horizontally. A number gives the absolute position to move the window to. A negative value specifies the distance from the right edge of the screen (e.g. -2 is 2 pixels in from the right edge). Use +- to specify a negative position relative to the left edge (e.g. +-10 is 10 pixels off the screen on the left side), and -- to specify a negative position relative to the right edge (e.g. --5 is 5 pixels off the screen on the right side).

<y>

current

The position to move the window to. current specifies the window's current y-position. center moves the window to the center of the screen, vertically. A number gives the absolute position to move the window to. A negative value specifies the distance from the bottom edge of the screen (e.g. -2 is 2 pixels in from the bottom edge). Use +- to specify a negative position relative to the top edge (e.g. +-10 is 10 pixels off the top of the screen), and -- to specify a negative position relative to the bottom edge (e.g. --5 is 5 pixels off the bottom of the screen).

<width>

current

The width to resize the window to. current specifies the window's current width. A number specifies the desired width of the window. You may also specify the width as a fraction or a percentage, eg 50% or 7/8. If client="yes" is specified as an attribute, then the size determines the size of the application window inside the decorations. The default includes the decorations in the size.

<height>

current

The height to resize the window to. current specifies the window's current height. A number specifies the desired height of the window. You may also specify the width as a fraction or a percentage, eg 50% or 7/8. If client="yes" is specified as an attribute, then the size determines the size of the application window inside the decorations. The default includes the decorations in the size.

<monitor>

current

The monitor to move the window to (in Xinerama/TwinView setups with multiple monitors). current specifies the window's current monitor. all specifies to use all monitors together. next specifies to move the window to the next monitor relative to the one it is currently on. prev specifies to move the window to the previous monitor relative to the one it is currently on. A number specifies the desired monitor (starting from 1).

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.

Option

Default Value

Description

<direction>

north

The direction to grow the window, can be "north", "south", "west" or "east".

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.

Option

Default Value

Description

<direction>

north

The direction to shrink the window, can be "north", "south", "west" or "east".

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:

Condition

Description

<shaded>

yes/no: if the window is rolled up or not.

<maximized>

yes/no

<maximizedhorizontal>

yes/no

<maximizedvertical>

yes/no

<iconified>

yes/no: if the window is minimized or not.

<focused>

yes/no: the window is the focused window. This may not be true while focus cycling or in the finalactions of focus cycling.

<urgent>

yes/no: the window has the urgent flag set (also known as DEMANDS_ATTENTION).

<undecorated>

yes/no: if the window decorations are hidden or not.

<omnipresent>

yes/no: if the window is visible on all desktops or not

<activedesktop>

The desktop that is currently active. This can only be a number.

<desktop>

The desktop the client is currently on. This can be the number of a desktop or the special values "current" or "other".

<monitor>

Matches the monitor the client is currently on (most area wins if spanning several).

<title> or <title type="pattern">

A wildcard pattern to match against the window title, like "* - Mozilla Firefox".

<title type="regex">

As above, but use regex instead of wildcard pattern, eg "- Mozilla Firefox$".

<title type="exact">

As above, but the string must match exactly (case sensitive).

<class>, <name>, <role>, <type>

Works like the <title> tag and takes the type parameter, but matches against the window class, name, role and type respectively.

ForEach

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

Stop

This action can be used to stop execution of the ForEach action, for example to search all clients for a given set of conditions, but then only run the actions on the first one. It takes no arguments. It will both stop the current list of actions from being run and break out of one level of ForEach.

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.

Option

Default Value

Description

<layer>

normal

The layer to put the window in. It can be the "top" layer, which appears over all other windows except fullscreen windows, the "normal" layer, or the "bottom" layer, which appears below all other windows.