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):

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":

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

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.