Revision as of 20:02, 6 November 2007

Template:I18n links start Template:I18n entry Template:I18n entry Template:I18n links end

Introduction

Openbox is a lightweight and highly configurable window manager with extensive standards support. Its features are well-documented at the official website. This article will pertain to running Openbox under Arch Linux.

Installation

Openbox is available from the standard repositories:

# pacman -S openbox

Once installed, pacman will direct you to copy the default menu.xml & rc.xml configuration files to ~/.config/openbox/, for exmaple:

$ mkdir -p ~/.config/openbox/
$ cp /etc/xdg/openbox/rc.xml ~/.config/openbox/
$ cp /etc/xdg/openbox/menu.xml ~/.config/openbox/

Note: do this as a regular user, not as root.

The rc.xml file is the core configuration file for Openbox. It is used to manage keyboard shortcuts, themes, virtual desktops and other features.

The menu.xml file controls the Openbox application menu that appears when you right-click on your desktop. The default items are pretty sparse (if not entirely useless), but it's very easy to modify the menu structure to suit your needs. See the menu section below for more details, or visit the Openbox website.

Getting Started

Using Openbox

To run Openbox on its own, simply add the following to the bottom of ~/.xinitrc:

exec openbox-session

Using Openbox with GNOME

1. If you use GDM, select the "GNOME/Openbox" login option
2. If you use startx, add exec openbox-gnome-session to ~/.xinitrc

Using Openbox with KDE

1. If you use KDM, select the "KDE/Openbox" login option
2. If you use startx, add exec openbox-kde-session to ~/.xinitrc

Configuration

Preferences

Currently, there are two options for configuring the core Openbox preferences; manually edit the rc.xml, or use the ObConf tool.

Setting Preferences Manually

To configure Openbox manually, simply edit ~/.config/openbox/rc.xml with your favourite text editor.

Setting Preferences with ObConf

ObConf is GUI-based Openbox configuration tool, which can be used to set most preferences, including themes, virtual desktops, window properties and desktop margins.

To install ObConf, run:

# pacman -S obconf

Currently, ObConf cannot be used to manage keyboard shortcuts and a few other advanced features. For these modifications, the user must resort to editing the rc.xml manually.

Menu Management

The default Openbox menu is pretty basic and if you don't have any of the listed programs installed, it is downright useless. There are a number of ways to customize your menu.

MenuMaker

MenuMaker is a powerful tool that creates xml-based menus for a variety of Window Managers, including Openbox. MenuMaker will search your computer for executable programs and create an xml menu based on the results. It can be configured to exclude Legacy X, GNOME, KDE, or Xfce applications if the user desires.

MenuMaker is available from the AUR.

Once installed, you can generate a complete menu by running:

$ mmaker -v OpenBox3

By default, MenuMaker will not overwrite an existing menu.xml. To do so, run it with the -f argument:

$ mmaker -vf OpenBox3

To see a full list of options, run mmaker --help

This will give you a pretty thorough menu. Now you can modify the menu.xml by hand, or simply regenerate the list whenever you install new software.

Obmenu

Obmenu is a GUI-based menu editor for Openbox. For those who don't enjoy mucking about in XML source code, this is probably the best option for you.

It's available in the standard repositories:

# pacman -S obmenu

Once installed, simply run obmenu and add or remove the desired applications.

obm-xdg

obm-xdg is a command-line tool that comes with Obmenu. It can generate a categorized sub-menu of installed GTK/GNOME applications.

To use obm-xdg, add the following line to ~/.config/openbox/menu.xml:

<menu execute="obm-xdg" id="xdg-menu" label="xdg"/>

Then run openbox --reconfigure to refresh the Openbox menu. You should now see a sub-menu labeled xdg in your menu.

Startup Programs

Openbox 3.4+ features support for running programs at startup. This is provided by the "openbox-session" command.

There are two ways to enable autostart:

1. If you use startx to log into your X session, change the line that executes openbox to execute openbox-session instead.
2. If you log in with GDM/KDM, then select the Openbox session and it will automatically use autostart.

Startup programs are managed in ~/.config/openbox/autostart.sh. Full instructions and best practices for how to do this are available here.

Theming and Appearance

Aside from the Openbox Themes, the following section is intended for users who have configured Openbox to run as a standalone desktop, without the assistance of GNOME or KDE.

Openbox Themes

Openbox themes control the appearance of window borders, including the titlebar and titlebar buttons.

Additional themes are available from the standard repositories:

# pacman -S openbox-themes

This package is by no means definitive. Many Openbox themes are scattered throughout the web, at sites like box-look.org.

Downloaded themes should be extracted to ~/.themes and can be installed or selected with the ObConf tool.

Creating new themes is fairly easy and again well-documented.

Desktop Wallpaper

Openbox itself does not include a way to change the wallpaper. This can be done easily with programs like Feh or Nitrogen.

ImageMagick, hsetroot and xsetbg can also be used.

GTK Themes

GTK2 themes can be managed easily with gtk-chtheme:

# pacman -S gtk-chtheme

Simply run gtk-chtheme and set the desired theme.

For legacy GTK1 themes, install the gtk-theme-switch package and run switch.

GTK Fonts

If you want to change the type and size of your fonts, add the following to ~/.gtkrc.mine:

style "user-font"
{
font_name = "[font-name] [size]"
}
widget_class "*" style "user-font"
gtk-font-name = "[font-name] [size]"

where [font-name] [size] is the desired font and point size. For example:

style "user-font"
{
font_name = "DejaVu Sans 8"
}
widget_class "*" style "user-font"
gtk-font-name = "DejaVu Sans 8"

Both font_name and gtk-font-name fields are required for backwards compatibility.

GTK Icons

Extract the desired icon theme to /usr/share/icons (system-wide access) or ~/.icons (local user access).

Add the following to ~/.gtkrc.mine:

gtk-icon-theme-name = "[name-of-icon-theme]"

where [name-of-icon-theme] is the name of the icon theme directory. For example:

gtk-icon-theme-name = "Tango"

Mouse cursor themes

To change this, download a theme (http://www.kde-look.org/) and put the folder in /usr/share/icons or ~/.icons.

Add this to ~/.Xdefaults:

Xcursor*theme:   [name-of-cursor-theme]

where [name-of-cursor-theme] is the name of the cursor theme directory. For example:

Xcursor*theme:	Vanilla-DMZ-AA

Desktop Icons

Openbox does not provide a means of placing icons on the desktop. ROX, iDesk, or even Nautilus (and the gnome-settings-daemon) can provide this function.

ROX has the additional advantage of being a lightweight file manager.

Tips & Tricks

Recommended Programs

Run dialog

gmrun provides an excellent Run dialog box, similar to that found in Gnome and KDE when Alt+F2 is pressed:

pacman -S gmrun

Add the following entry to the <keyboard> section ~/.config/openbox/rc.xml to enable Alt+F2 functionality:

<keybind key="A-F2">
<action name="execute"><execute>gmrun</execute></action>
</keybind>

File managers

There are many possibilities, but the most popular lightweight file managers are:

• Thunar
• ROX
• PCMan (pcmanfm)

For even lighter options, consider Gentoo or emelFM, both of which use the familiar 'Midnight Commander' two pane layout (these two require gtk 1.2.x).

Of course, you can also use GNOME's Nautilus. Although slower than the above, it has the additional advantage of VFS support (e.g. remote SSH, FTP and Samba connections).

Panels

There are quite a lot of panels you can install to provide a taskbar and pager to Openbox. The most common are:

• PyPanel
• Tint
• Visibility
• LXPanel
• fbpanel
• PerlPanel
• fspanel
• gnome-panel
• bbpager

Make your choice and add it to your startup file.

Per-application settings

Openbox has per-application settings since openbox 3.3 These settings can be set in ~/.config/openbox/rc.xml by creating new XML element inside <openbox_config> called <applications>, which will contain the settings. Inside <applications> you will need <application name=""> which will determine which application this setting is going to affect. The ways to determine the application are name, class and role, eg.

<application class="Firefox-bin">

The class and name can be found by running

xprop | grep WM_CLASS

When you click the application you want to configure, it will return something like

WM_CLASS(STRING) = "Gecko", "Thunderbird-bin"

The first one is what you put inside name="" and the latter one is for class="", you can use either one, but I prefer the one which doesn't get mixed with anything. After this you need to set the settings you want, available settings are

decor - whether window has borders, titlebar and so on, values yes or no, on or off 
shade - whether the window is shaded to the titlebar or not (doesn't work with decorations off), values yes, no, on, off and so on
position - position of the window when started needs subsection
 <x>pos</x>     - position on pixels reading from top left corner
 <y>pos</y>     - center as value and such work too, you can also leave x or y out if you only want to adjust one value.
focus - whether the window gets focused when starting it (not sure about this), values yes no and so on
desktop - desktop (workspace) the application starts, value desktop number reading from 0 (if its opened to another desktop, it doesn't get focused)
monitor - xinerama head the application starts (useful when you have 2 monitors and want the application to open in another, eg nvidia twinview uses xinerama), values 0 1 screennumber and such
layer - layer the application starts on, values Bottom, Normal and Top
iconic - whether the application is to be launched iconic, values yes, no, on, off and so on
skip_pager - application skips pager, values yes, no, on, off and so on
skip_taskbar - same as above, just taskbar, values yes, no, on, off and so on
fullscreen - whether app should be started fullscreen, values yes, no, on, off and so on
maximized - type of maximization, values Horizontal, Vertical, yes, no, on, off and so on.

Example config showing firefox opening 30 pixels from top centered with horizontal maximization

<applications>
  <application class="Firefox-bin">
    <position>
      <x>center</x>
      <y>30</y>
    </position>
    <maximized>Horizontal</maximized>
  </application>
</applications>

Additional Resources

• Openbox Website - The official website
• Planet Openbox - Openbox news portal
• Box-Look.org - A good resource for themes and related artwork