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. (As of version 3.4.7)

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. (As of version 3.4.6)

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

DirectionalTargetSouth

Moves focus to the window south of the currently focused window. This is similar to the DirectionalFocusSouth action, but it moves focus instantly instead of letting you interactively choose a window.
Takes the same options as DirectionalTargetNorth.

DirectionalTargetEast

Moves focus to the window east of the currently focused window. This is similar to the DirectionalFocusEast action, but it moves focus instantly instead of letting you interactively choose a window.
Takes the same options as DirectionalTargetNorth.

DirectionalTargetWest

Moves focus to the window west of the currently focused window. This is similar to the DirectionalFocusWest action, but it moves focus instantly instead of letting you interactively choose a window.
Takes the same options as DirectionalTargetNorth.

DirectionalTargetNorthWest

Moves focus to the window north-west of the currently focused window. This is similar to the DirectionalFocusNorthWest action, but it moves focus instantly instead of letting you interactively choose a window.
Takes the same options as DirectionalTargetNorth.

DirectionalTargetNorthEast

Moves focus to the window north-east of the currently focused window. This is similar to the DirectionalFocusNorthEast action, but it moves focus instantly instead of letting you interactively choose a window.
Takes the same options as DirectionalTargetNorth.

DirectionalTargetSouthWest

Moves focus to the window south-west of the currently focused window. This is similar to the DirectionalFocusSouthWest action, but it moves focus instantly instead of letting you interactively choose a window.
Takes the same options as DirectionalTargetNorth.

DirectionalTargetSouthEast

Moves focus to the window south-east of the currently focused window. This is similar to the DirectionalFocusSouthEast action, but it moves focus instantly instead of letting you interactively choose a window.
Takes the same options as DirectionalTargetNorth.

GoToDesktop

Changes the visible desktop.

Option

Default Value

Description

<to>

current

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.

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. (As of version 3.4.7)

MaximizeHorz

Maximize the window to fill the entire screen horizontally, but not vertically.

Example:

<keybind key="A-F10">
<action name="MaximizeHorz"/>
</keybind>

UnmaximizeHorz

If the window is maximized horizontally, return the window to its pre-maximized dimensions.

Example:

<keybind key="A-F11">
<action name="UnmaximizeHorz"/>
</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.

MoveToCenter

Move the window to the center of the screen. MoveResizeTo can do this as well, and more.

Example:

<keybind key="W-m">
<action name="MoveToCenter"/>
</keybind>

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.

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

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

MoveToEdgeNorth

Moves the window to the nearest edge north of it. Edges are the outer edges of other windows, or the desktop boundaries.

Example:

<keybind key="W-Up">
<action name="MoveToEdgeNorth"/>
</keybind>

MoveToEdgeSouth

Moves the window to the nearest edge south of it. Edges are the outer edges of other windows, or the desktop boundaries.

Example:

<keybind key="W-Down">
<action name="MoveToEdgeSouth"/>
</keybind>

MoveToEdgeWest

Moves the window to the nearest edge west of it. Edges are the outer edges of other windows, or the desktop boundaries.

Example:

<keybind key="W-Left">
<action name="MoveToEdgeWest"/>
</keybind>

MoveToEdgeEast

Moves the window to the nearest edge east of it. Edges are the outer edges of other windows, or the desktop boundaries.

Example:

<keybind key="W-Right">
<action name="MoveToEdgeEast"/>
</keybind>

GrowToEdgeNorth

Resizes the window until it touches the nearest edge north of it. Edges are the outer edges of other windows, or the desktop boundaries.

Example:

<keybind key="C-Up">
<action name="GrowToEdgeNorth"/>
</keybind>

GrowToEdgeSouth

Resizes the window until it touches the nearest edge south of it. Edges are the outer edges of other windows, or the desktop boundaries.

Example:

<keybind key="C-Down">
<action name="GrowToEdgeSouth"/>
</keybind>

GrowToEdgeWest

Resizes the window until it touches the nearest edge west of it. Edges are the outer edges of other windows, or the desktop boundaries.

Example:

<keybind key="W-Left">
<action name="GrowToEdgeWest"/>
</keybind>

GrowToEdgeEast

Resizes the window until it touches the nearest edge east of it. Edges are the outer edges of other windows, or the desktop boundaries.

Example:

<keybind key="W-Right">
<action name="GrowToEdgeEast"/>
</keybind>

ShadeLower

If the window is unshaded, this shades (a.k.a. Rolls up) the window so only the titlebar is visible. If the window is already shaded, then this lowers the window below other windows in its layer.

Example:

<keybind key="W-l">
<action name="ShadeLower"/>
</keybind>

UnshadeRaise

If the window is shaded, this unshades (a.k.a. Rolls down) the window so it is fully visible. If the window is not shaded, then this raises the window above other windows in its layer.

Example:

<keybind key="W-r">
<action name="UnshadeRaise"/>
</keybind>

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>

SendToTopLayer

Makes the window always above other windows, in the "always on top" layer.

Example:

<keybind key="W-F7">
<action name="SendToTopLayer"/>
</keybind>

SendToBottomLayer

Makes the window always below other windows, in the "always on bottom" layer.

Example:

<keybind key="W-F6">
<action name="SendToBottomLayer"/>
</keybind>

SendToNormalLayer

Makes the window neither always above, nor always below other windows. This puts the window in the stacking order with other normal windows.