General overview of gtk2panel principles

Once gtk2panel has been installed properly you will get a default panel that will very likely not meet your needs. Furthermore, gtk2panel does not ship a single icon but, instead, it relies on external icon themes. This means that it is expected the default example will have missing icons, although default.xml tries to follow as close as possible the icon naming specification to limit this problem.

The default gtk2panel icons have been selected from a sligthly changed version of the nuvola theme by Davide Vignoni. The theme used is available for download from the gtk2panel project page on sourceforge and is based on the work done by the kde folks (although documented as "for KDE 3.x", the theme has been standardized and can be used outside too). To use this theme, download the tarball and unpack it under $HOME/.icons, that is for example:

mkdir -p $HOME/.icons
cd $HOME/.icons
wget http://sourceforge.net/projects/gtk2panel/files/nuvola-icons/nuvola-icons-svn997448.tar.bz2
tar xf nuvola-icons-svn997448.tar.bz2

To enable the theme from within the Gtk+ world, just modify your $HOME/.gtkrc-2.0 (create it if not present) by adding this couple of line at the beginning:

gtk-icon-theme-name = "nuvola"
gtk-theme-name = "nuvola"

Alternatively, you can still get good results by using a comprehensive theme such as the tango icon library but in any case you will always get the best by customizing the GtkBuilder file.

gtk2panel looks for this file using the following algorithm:

  1. Get the configuration file from the command line (either using -c or --config). Put the result in a variable... let's call it xml_file. If the file is not specified or, more in general, if xml_file is empty, the string "default.xml" will be used.
  2. Check for the existence of a file named xml_file. If you passed in a relative path, this will depend from where you start gtk2panel: if you don't want this behaviour just use absolute paths. If the file is found, it will be used.
  3. If the file is not found by the previous step, gtk2panel will try to prepend $CONFIGDIR/gtk2panel/, usual resolved to $HOME/.config/gtk2panel/. If xml_file is found under this path it will be used.
  4. If the file is not found by the previous step, gtk2panel will change the prepended path to $pkgdatadir/examples/ where $pkgdatadir is the directory where the gtk2panel data will reside (specified with ./configure --datadir ...). This is usually resolved to /usr/local/gtk2panel/examples/ if you didn't specified a different prefix. If the file is not found, the program will abort with a file not found error.

In other words, if you configured gtk2panel leaving the default prefix (/usr/local) and you are calling it without arguments, the following files will be looked up in a standard system (order matters):

default.xml
$HOME/.config/gtk2panel/default.xml
/usr/local/gtk2panel/examples/default.xml

As you can easily guess, after a fresh gtk2panel installation the latter file (/usr/local/gtk2panel/examples/default.xml) is the only one present, so will be the one used. To use a custom one, just drop a default.xml in $HOME/.config/gtk2panel/ or manually specify the -c option when calling gtk2panel.

Additionaly, once the xml_file is found, gtk2panel tries to merge the file gtkrc if it exists in the same directory of xml_file. This file is optional and could provide additional Gtk+ customization: check the resource file syntax for further information.

Creating and customizing the panel

The fastest way to start is by copying the default xml file to your home directory, taking into account what reported in the previous section. You can also copy the binded Gtk resource file, that basically changes the color of GpwCpu:

mkdir -p $HOME/.config/gtk2panel
cp /usr/local/gtk2panel/examples/{default.xml,gtkrc} $HOME/.config/gtk2panel/

Now you can use the glade editor (version 3.6.0 or later) and modify the panel to suit your needs:

glade-3 $HOME/.config/gtk2panel/default.xml

Glade has still some quirk in managing the panel so what you see will not be exactly what you get. Anyway in Tristan we trust, so we are confident this situation will become better.

Alternatively, if you are brave enough, you can accomplish the same task by using your preferred text editor: just be sure to follow the GtkBuilder syntax.

Using gtk2panel: final destination

Now you own the perfect panel you can use in the way you prefer. The following .xinitrc is how I'm using it: gtk2panel is used to close the session, that is when it ends it brings down all the X client (and yes, I don't care about the other programs):

#! /bin/sh
# .xinitrc: start the X client session

xsetroot -cursor_name watch
if [ -r $HOME/.config/Xcursor.xrdb ]; then
  xrdb $HOME/.config/Xcursor.xrdb
fi

if test -z "$DBUS_SESSION_BUS_ADDRESS"; then
  eval `dbus-launch --sh-syntax --exit-with-session`
  export DBUS_SESSION_BUS_ADDRESS
fi

xset m 25/10 15
xhost +localhost

xnots -c $HOME/.config/xnotsrc -d $HOME/.config/notes -q &
rox -p=default &
openbox &
gtk2panel

If you are aware of a more creative way to use it, just let us know.