HOWTO Openbox

[edit] Getting started guide

This wiki section is outdated. See the Openbox getting started guide for how to run Openbox 3.4.

[edit] 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.

[edit] 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:

# Startup stuff for X

# Make openbox the KDE window manager
export KDEWM=openbox

# Make KDE system tray apps work
kdetrayproxy &

# Start the KDE environment
startkde

[edit] Standalone Openbox

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

#Startup stuff for X
exec openbox-session

[edit] 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:

#!/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):

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

[edit] 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...

[edit] 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.

[edit] 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.

[edit] 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.

gtk-icon-theme-name = "Etiquette"
gtk-theme-name = "Clearlooks"
gtk-font-name = "Bitstream Vera Sans 8"

style "user-font"
{
        font_name = "Bitstream Vera Sans 8"
}

widget_class "*" style "user-font"

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.

[edit] Generate Menu Entries

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.

[edit] Manual Configuration

For more information, goto Openbox Configuration Page

Open a text editor, such as nano, vim, emacs, nedit, etc. and head to these directories:

1. $HOME/.config/openbox/ - for specific users
2. /etc/xdg/openbox/ - for the whole system, though if Openbox finds one in ~ first, that's the default

The main two files you will find there are rc.xml and menu.xml

• rc.xml handles - general options (size, snapping, etc) - keyboard shortcuts - mouse options
• menu.xml handles - all your menu placement for the right click pop-up menu

An example menu.xml file:

 <?xml version="1.0" encoding="UTF-8"?>

 <openbox_menu xmlns="http://openbox.org/"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://openbox.org/
                 file:///usr/share/openbox/menu.xsd">

 <menu id="appall-menu" label="Apps">
 <menu id="apps-menu" label="Applications">
   <item label="Firefox">
     <action name="Execute"><execute>firefox</execute></action>
   </item>
     <item label="Links">
     <action name="Execute"><execute>links -g</execute></action>
   </item>
   <item label="AMSN">
     <action name="Execute"><execute>amsn</execute></action>
   </item>
   <item label="Blender CVS">
     <action name="Execute"><execute>/home/blender/blender/blender -w</execute></action>
   </item>
   <item label="XChat-2">
     <action name="Execute"><execute>xchat-2</execute></action>
   </item>
   <item label="Torsmo">
     <action name="Execute"><execute>torsmo</execute></action>
   </item>
   <item label="Scrot">
     <action name="Execute"><execute> scrot $f /home/smerity/ping.png </execute></action>
   </item>
 </menu>
 <menu id="games-menu" label="Games">
   <item label="Frozen Bubble">
     <action name="Execute"><execute>/usr/games/bin/frozen-bubble</execute></action>
   </item>
   <item label="FreeDroid">
     <action name="Execute"><execute>/usr/games/bin/freedroid</execute></action>
   </item>
   <item label="Amor">
     <action name="Execute"><execute>/usr/kde/3.3/bin/amor</execute></action>
   </item>
   <item label="XBill">
     <action name="Execute"><execute>/usr/games/bin/xbill</execute></action>
   </item>
   <item label="SuperTux">
     <action name="Execute"><execute>/usr/games/bin/supertux</execute></action>
   </item>
   <item label="WMFortune">
     <action name="Execute"><execute>wmfortune -s 19999</execute></action>
   </item>
 </menu>
 <menu id="term-menu" label="Terminals">
  <item label="Smerterm">
     <action name="Execute"><execute>aterm -bg LightBlue -tr -tint LightBlue -sh 70 -fade 70 -bgtype scale -name
 Smerity -ls -fg grey +st</execute></action>
   </item>
   <item label="Aterm">
     <action name="Execute"><execute>aterm</execute></action>
   </item>
   <item label="Xterm">
     <action name="Execute"><execute>xterm</execute></action>
   </item>
   <item label="Rox FM">
     <action name="Execute"><execute>rox /root/</execute></action>
   </item>
 </menu>
 </menu>

 <menu id="kde-menu" label="KDE">
   <item label="Kicker">
     <action name="Execute"><execute>kicker</execute></action>
   </item>
   <item label="KDesktop">
     <action name="Execute"><execute>kdesktop</execute></action>
   </item>
   <item label="KDE System Guard">
     <action name="Execute"><execute>ksysguard</execute></action>
   </item>
 </menu>

 <menu id="open-menu" label="OpenBox Apps">
   <item label="ObConf">
     <action name="Execute"><execute>obconf</execute></action>
   </item>
   <item label="Reconfigure">
     <action name="Reconfigure" />
   </item>
   <separator />
   <item label="Feh">
     <action name="Execute"><execute>feh --bg-scale /home/mountain_man2.jpg</execute></action>
   </item>
   <item label="Menu.xml">
     <action name="Execute"><execute>nedit /etc/xdg/openbox/menu.xml</execute></action>
   </item>
   <item label="Rc.xml">
     <action name="Execute"><execute>nedit /etc/xdg/openbox/rc.xml</execute></action>
   </item>
   <separator />
   <item label="Gkrellm">
     <action name="Execute"><execute>gkrellm2</execute></action>
   </item>
   <menu id="kdm-menu" />
 </menu>

 <menu id="root-menu" label="Openbox 3">
   <item label="Smerterm">
     <action name="Execute"><execute>aterm -bg LightBlue -tr -tint LightBlue -sh 70 -fade 70 -bgtype scale -name Smerity -ls -fg grey +st</execute></action></item>
   <item label="Konqueror">
     <action name="Execute"><execute>/usr/kde/3.3/bin/konqueror / </execute></action>
 </item>
   <menu id="appall-menu" />
   <menu id="open-menu" />
   <separator />
   <menu id="client-list-menu" />
   <separator />
   <item label="Nedit">
     <action name="Execute"><execute>nedit</execute></action>
   </item>
   <item label="Notes">
     <action name="Execute"><execute>nedit /home/Notes</execute></action>
   </item>
   <separator />
   <item label="Reboot">
     <action name="Execute"><execute>reboot</execute></action>
   </item>
   <item label="Exit">
     <action name="Exit" />
   </item>
 </menu>

 </openbox_menu>

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:

 <?xml version="1.0" encoding="UTF-8"?>

 <openbox_menu xmlns="http://openbox.org/"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://openbox.org/"
         file:///usr/share/openbox/menu.xsd">

+--- 60 lines: <menu id="appall-menu" label="Apps">---------------------------------

+--- 11 lines: <menu id="kde-menu" label="KDE">-------------------------------------

+--- 23 lines: <menu id="open-menu" label="OpenBox Apps">---------------------------

+--- 25 lines: <menu id="root-menu" label="Openbox 3">------------------------------

</openbox_menu>

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:

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.

[edit] 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:

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

[edit] Panels, Desktops and Backgrounds

[edit] 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.
• KoolDock - A MacOSX like dock. Very nice !
• lxpanel - An fbpanel clone with some very nice features.

[edit] Desktops

• kdesktop - KDE's Desktop Manager, a little bloated.
• 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.
• PCManFM - An extremly fast and lightweight file manager with desktop icons support.

[edit] Background

feh - A lightweight image viewer, supporting many file formats. This can also set the background. It can be run from the command line:

feh --bg-scale ~/your/background.jpg

Feh stores its background command in ~/.fehbg, making it simple to set your desktop when X starts up:~/.xinitrc:

eval `cat $HOME/.fehbg` &
exec openbox-session

You can only set an image as a background with feh, not a color or gradient.

xsetbg - Comes with X, but doesn't support many formats and can be painful to set up. It does not do well with (xcompmgr), if ever you want to use it.

Another option is ImageMagick. It's also easy:

display -dispose Background -window root ~/your/background.jpg

It is also possible to Make your background rotate with feh.