What is Openbox?

Openbox is a fast, lightweight and highly configurable X11 window manager with extensive standards support. It is released under the GNU GPL. It can act as a full-featured standalone window manager or be used as a drop-in window manager for desktop environments like Gnome or KDE.

Openbox 2 and earlier versions were based on the Blackbox 0.65.0 code base, written in C++, with no dependencies other than X11. Openbox 3 has been completely rewritten in C and is not based upon any existing code base. It depends on libxft2 and X11.

Getting started guide

Openbox with Gnome

The default window manager for the GNOME environment is metacity. To switch from metacity to Openbox, run the following command as the user you want to run openbox:

openbox --replace

Choose Save your Session next time you log out so that Openbox will be started for you when you log in again.

Since GNOME 2.4, gnome-panel no longer manages its own key bindings and requires that the window manager provide its own key bindings for showing the Main Menu and Run dialog. Openbox does this through gnome-panel-control, which can be used in keybindings to access the gnome-panel. Use the --main-menu option to display gnome-panel's menu, and the --run-dialog to display the Run dialog.

Openbox with KDE

The default window manager for the KDE environment is kwin. To switch from kwin to Openbox, set the following environment variable in your startup scripts:

export KDEWM=openbox

Openbox will now be used in kwin's place.

The current release of KDE is still using a non-standard, deprecated protocol for its system tray. This protocol requires interaction from the window manager. Openbox includes the kdetrayproxy application, which acts as a go-between between Openbox and KDE. Once you run kdetrayproxy, KDE system tray apps will work with window managers that don't support KDE's protocol.

To run kdetrayproxy before running KDE, make a startup script or modify xinitrc as shown:

Standalone Openbox

If you want Openbox as a standalone window manager, run openbox or modify $HOME/.xinitrc or /etc/X11/xinit/xinitrc as such:

File: ~/.xinitrc or /etc/X11/xinit/xinitrc

#Startup stuff for X
exec openbox-session

If you run X via a display manager (xdm, gdm, kdm, ...)

You may consult the documentation for your specific display manager regarding adding entries to it. Alternately, you can edit a $HOME/.xsession file. The file is a shell script and can be made identical to the .xinitrc example above. With this method, you would choose "default" as the login target in your display manager.

gdm - if you have gdm installed, when you emerge openbox, portage will install /usr/share/xsessions/openbox.desktop

kdm -- kdm also uses the /usr/share/xsessions/openbox.desktop to give you a nice graphical selection in the sessions menu. But if you want other programs to run at startup (like the background scripts listed below) you need to put all the commands in the ~/.xsession file. Be sure to end with exec openbox and make it executable, for example:

File: ~/.xsession

#!/bin/sh
gkrellm2 &
xscreensaver -nosplash
exec openbox

This starts the gkrellm monitoring program, the xscreensaver dameon and finally Openbox. Now you can select the "Custom" session at the kdm/gdm login prompt to execute the ~/.xsession file.

There is another method to start other programs at startup not using the ~/.xsession (for example because you want to have two different Openbox session that start different applications):

Write a script that looks like the ~/.xsession above, save it (e.g. to /usr/local/bin/startopenbox) and make it executable.

Now edit /usr/share/xsessions/openbox.desktop (or create a new *.desktop):

File: /usr/share/xsessions/openbox.desktop

[Desktop Entry]
Encoding=UTF-8
Name=Openbox
Comment=Openbox and other apps
Exec=startopenbox # <- this should be the name/path of/to your new script
Icon=
Type=Application

Instead of selecting the "Custom" session you can now use the "Openbox" session (or whatever you named it).

Basic Introduction

When Openbox first starts, it'll look like nothing is there. Right click, and there's your menu. At this point, you may be a little shocked by how bare it looks. Don't worry, that will soon be fixed! (Assuming you want to "fix" it, of course...)

Also, Openbox doesn't come with a panel (a bar down the bottom), but instead uses a system of right clicking on the desktop. A panel may be added after configuration. If you rightclick on the desktop now, you should see some sample entries, such as Quake 3, Mozilla etc etc...

Configuring Openbox

Openbox is easily configurable, as all the files it has are in simple to grasp XML. You can either edit the files manually, or get a tool called Obconf to do (the majority) of it for you.

Obconf

Obconf is a configurator for Openbox, and lets you control Appearance, Behavior, Desktops and Docking.
Simple emerge obconf and you have it.

It doesn't have the ability to modify menus, or for that matter anything other than the largest options. You'll have to go the XML route to configure the other options.

You need to emerge version 1.6 if you plan to install it.

GTK Applications

If you don't have a full-blown GNOME installation on your system and you want greater control of your GTK applications, you can use the .gtkrc-2.0 file. You can set things such as the theme name, icon theme, and specify some font settings among other things.

The icon and theme name are specified based on the given name of that particular theme. There are two font settings purely for backwards compatibility with certain applications, but some applications still partially ignore these settings. For instance, Mozilla Firefox 1.0.7 will still use larger fonts in rendered pages, but the application font itself will use the font that you specified.

Note: If you use Obconf with this custom file, Obconf will overwrite this rather than appending to it.

Generate Menu Entries

The Openbox menu contains (out of the box) only the most widely distributed applications. You can use the menuMaker (emerge menumaker) tool to generate the menu configuration file, like so:

mmaker OpenBox3

This utility scans for applications it knows about, and it knows a lot!

There is also another utility which you can use, it's called Denu and it's in portage.

As you can see, this file can get big very fast. If you are a Vim user you can tell Vim to fold the different sections so that you can get a better idea of the overall picture. With xml folding enabled the menu file given above looks like:

To look at the contents of the fold simply put your cursor on the desired line and type "zo" (fold open). To close it again type "zc" (fold close).

To enable folding for xml files create a file named ~/.vim/after/syntax/xml.vim (creating directories as needed) with the following contents:

File: xml.vim

syn sync fromstart
set foldmethod=syntax
"This variable sets the fold level that you start in
set foldlevel=1
"This variable tells vim depth of nesting to use
set foldnestmax=3
"This sets the color of the folds to distinguish them from
"the rest of the text
highlight Folded ctermbg=DarkGrey ctermfg=DarkCyan

Then add "let g:xml_syntax_folding = 1" to your ~/.vimrc file. Now open up the menu.xml to test it out.

Pipe Menus

One of the more useful features of Openbox is the ability to pipe scripts into a menu. An entry in your menu.xml might look like this:

File: menu.xml

<menu id="pipemenu" label="Piped Script" execute="~/obmenuscript" />

There are many sites dedicated to Openbox scripts; here is a collection of most of them. If you feel like writing your own, it is very simple. Simply write a script or program in whatever language you want and make sure it outputs a properly formatted menu (follows the general rules for menu.xml) to standard output. Make sure that errors are also properly formatted entries in the menu.

Panels, Desktops and Backgrounds

Panels

pypanel - A Python based panel, supporting icons, transparency and lots of other candy while remaining at 25 Kb (source).

FSPanel - F***ing Small Panel, a tiny panel, coming in at 9Kb of code.

FBPanel - Coming in at 77Kb source, FBPanel is based on FSPanel, with many more features.

kicker - KDE's kicker, works well except with some buttons not working (Logout, Lock Desktop, etc)

perlpanel - A perl based panel, has icons, and supports many applets. Also, its pretty easy to write applets for it.

Desktops

idesk - Small, efficient, and when combined with idesktool is as simple to use as any other...

nautilus - GNOME's Desktop Manager. Works great with Openbox.

ROX-Filer - Fast, user friendly desktop making extensive use of drag-and-drop. The interface revolves around the file manager, following the traditional Unix view that `everything is a file' rather than trying to hide the filesystem. The aim is clear presentation and proper design in all facets of the system. The ROX style favours using several small programs together instead of creating all-in-one mega-applications.