logo Theme management

Page updated July 21, 2011
When Puppy is running, you see desktop icons, a color scheme in the tray and windows, and a background image. Altogether, this should present a harmonious theme. It does however consist of four or five distinct parts:
  • Desktop background
  • Desktop icons
  • GTK2
  • Window manager
  • Tray (may be part of window manager)
You can create a theme for any one of these, or the whole lot. You could create a PET package to install your own theme.

From the user's point of view, each of these components can be configured individually, so you can compose combinations to suit your taste. GUI applications to select the theme for each component are to be found in the 'Desktop' menu. Take a look, it's pretty self-explanatory.

Desktop background

This is easy. There is a directory, /usr/share/backgrounds. You put an image file in there and it is automatically recognised. There is a Wallpaper setter in the 'Desktop' menu, that lists whatever is in /usr/share/backgrounds and you choose what you want.

Note that 'default.jpg' is the background you get the very first time that Puppy is booted. If you were building your own custom Puppy, you can change this file to whatever image you want.

Desktop icons

Icons that you see on the deskop, such as those labelled 'file', 'write', 'lock', 'zip', 'trash' and so on, are all to be found at /usr/local/lib/X11/pixmaps.
Why that location? The reason is historical, from the early Puppy days when we were using the Fvwm95 window manager. We have moved on, but kept that path for most of Puppy's icons (and /usr/local/lib/X11/mini-icons for smaller 16x16 icons).

Open ROX-Filer (click the 'file' icon on the desktop) and take a look at /usr/local/lib/X11/pixmaps. Right-click on the "eye" icon on the top of ROX-Filer to turn-on thumbnail view. Notice the correlation with what's in there and what is on the desktop.

A user can change the desktop-icon theme by running my little GUI application Desktop icon switcher, that you will find in the 'Desktop' menu.

But, where are these alternative icons obtained from? using ROX-Filer, take a look in /usr/local/lib/X11/themes. That's it. If you create a directory in there, with your own set of desktop icons, they will be automatically recognised by my Desktop icon switcher application.

When you choose a theme, and some examples in Puppy are 'FlatOrange', 'Original' and 'StarDust', what actually happens? The chosen theme gets copied into /usr/local/lib/x11/pixmaps. The current theme is whatever is in the 'pixmaps' directory.

If you want to create your own set of desktop icons, you need to create them with the same names as you see in the existing themes. For example, this is the 'Original' theme (one that we used in some earlier versions of Puppy):
original icons

Notice that they have '24' or '48' in the name. These are to designate that the icons are 24x24 pixels or 48x48 pixels. The '24' images are only used in the window manager (or tray) menu, not on the desktop -- take a look at the top-level of the 'Menu' (button in the tray, bottom-left of screen).

The 'Original' theme is all PNG images, however you can create a theme with SVG images. The Desktop icon switcher GUI application will convert them to PNG images. The 'FlatOrange' is an example -- note that it has a mix of SVG and PNG images. The SVG files do not have a '24' or '48' in their name as they are scalable.

July 2011: Enhanced drive icons

For puppies built from Woof of July 23 2011, there is a significant ehancement to the above. You can see in the above picture, the files 'drive48.png', 'drive_mntd48.png' and 'drive_mntd_boot48.png' -- well, icon themes in future will only require 'drive48.png' as the second two are autogenerated from the first by Puppy. This makes it easier for anyone putting together an icon theme for Puppy. If you want to read more about this, see my blog:


Furthermore, as explained in the above blog link, the desktop drive icons may now have a "close box", making it very simple and quick to unmount a partition, if for example you want to extract a USB pen drive. Here is a snapshot, the outlined icons are mounted, and those that are permitted to be unmounted have a "close box":

drive icons with close box

It should also be mentioned that the two types of outlining shown are themselves image files and can be included in an icon theme (see blog link for details).


GTK2 provides the menus, widgets and dialog boxes for an application. Basically, that's everything inside a window -- but not the window border and title-bar as that is handled by the window manager.

For users, the GUI application to choose a GTK2 theme is Chtheme, that you will find in the 'Desktop' menu. This application was created by Aristotle Pagaltzis.

GTK2 themes are a bit more fiddly to create. There are heaps of them out there and you can either find one ready-made or modify one -- it is a very steep learning curve to create one from scratch.

The GTK2 themes are located at /usr/share/themes. Take a look there -- you will find that the simplest themes have just one file, 'gtkrc'. Then there's my creation,  'Gradient-grey', which in addition to the 'gtkrc' file has four images. From there, it goes up and up, some themes having a hundred or more image files.

So how does a theme get chosen as the current theme? When a GTK2 application starts, by default it looks first for the file /etc/gtk-2.0/gtkrc, and then for the file /root/.gtkrc-2.0. If it finds both, they are both read, but anything in the latter will override the former. It is the latter that Chtheme modifies. Taking a look inside /root/.gtkrc-2.0:
include "/usr/share/themes/Gradient-grey/gtk-2.0/gtkrc"
In other words, the 'Gradient-grey' theme is chosen.

Window manager/tray

Puppy can be built with different window managers and tray/panel applications, so  theme management will be different for each. The 'official' Puppy uses the JWM window manager, which also has a tray/panel, so that's what I will describe here.

For users, there is a GUI application named (very imaginatively!) JWM configuration, that is found in the 'Desktop' menu. This was created especially for Puppy, and the original author is 'thought journey' (forum name). Since then there have been various contributors, including Dougal, plinej (forum names) and myself. I gave it an overhaul prior to Puppy 4.00.

At startup, JWM reads a configuration file, /root/.jwmrc, and you can use this as a starting point to understand what's going on. However, there's a lot involved here, so moving on the actual theme management...

What thought journey did was create a directory /root/.jwm/themes, and that's where they are. When I was developing Puppy4, I created a new script for JWM-configuration, /usr/local/jwmconfig2/theme_switcher, called from the main GUI window in the JWM Config tool. The script scans the contents of /root/.jwm/themes and displays found themes.

Each theme in /root/.jwm/themes consists of 4 files. For example, I created a ‘Gradient-grey’ theme to match the GTK theme,and the files are ‘Gradient-grey-colors’, ‘Gradient-grey-jwmrc’, ‘Gradient-grey-tray.png’ and ‘Gradient-grey-window.png’. They are self-explanatory when you look at them. The two images are thumbnails of the theme and are displayed in the theme_selector GUI window. Here is a snapshot inside /root/.jwm/themes:

You can use one of the existing themes as a starting point to creating your own. Note that the JWM website has some documentation that will be helpful.

When the GUI application is used to choose a theme, what happens is the two text files are copied to /root/.jwm and renamed to 'jwm_colors' and 'jwmrc-theme'. That is, if you chose the 'Gradient-grey' theme, then 'Gradient-grey-colors' and 'Gradient-grey-jwmrc' would get copied to 'jwm_colors' and 'jwmrc-theme'. You then need to restart JWM for the change to take affect.

Have fun!

(c) Copyright 2008,2011 Barry Kauler, all reproduction rights reserved. puppylinux.com