1. Creating Icon themes for GNOME

GNOME 2.2 and beyond features great integrated theme capabilities both for the file and device type icons such as those used by Nautilus, and application icons such as those used in the GNOME menu and many other GNOME apps as well. This tutorial will try to explain how the GNOME icon theming works (as based on the icon theme specification and icon naming specification from freedesktop.org) and how you can make icon themes for your favorite desktop.

1.1. Understanding the GNOME Icon theme engine

GNOME2 keeps icons for system-wide and user themes in separate directories. For system-wide themes the icons are stored in either /usr/share/icons or /usr/local/share/icons and icons for user themes are stored in /.icons. These all contain a sub-directory for each theme installed on your computer. Inside each themes' directory is a description file named index.theme which contains the theme name, icon types, default sizes and so forth. The icons themselves and .icon files are also contained in the theme directory, categorized into sub-folders by size and type [, such as emblems & filesystems.]

Maybe need another paragraph here, or better flow from the first paragraph to this one..

GNOME2 icons should be created using one of the following formats:

• PNG
• SVG
• XPM

PNG is recommended for bitmap icons and SVG is recommended for vector icons. The XPM format is provided for legacy support, including themes supported by older GNOME1/Nautilus1 systems. There is no need to provide multiple sized versions of icons in the SVG format because they can be scaled to any size neccesary with no loss of quality. However, scaling and displaying SVG icons is more CPU intensive so older or slower machines might have problems running GNOME2 using themes that provide only SVG icons. For this reason, it is good practice to provide PNG versions of your icons as well as SVG.

Need another paragraph here, perhaps describing general things to do to prepare to make a new theme.. I suggest starting with another theme when creating a new theme and then replace the icons one by one. Creating a directory with the same name as your planned theme and creating the index.theme inside it is all that is needed to make the theme available in the Gnome theme manager.

1.1.1. Step 1. Creating an index.theme configuration file

To begin making your theme, create a folder of the same name as you wish to call your theme, or by copying another theme as suggested above, and then you will be ready to start setting up the theme.

The most important aspect of the icon theme is index.theme, an ini style configuration file which describes the theme in various sections. The main and most important section is broken down as follows:

This whole bit needs to be put into a user friendly, easily readable layout... ideas anyone? I accept/prefer actual code as a valid suggestion.

[IconTheme]
This section describes the layout of the theme in a very simple fairly intuitive way

Name = ThemeName
this field represents the name of the theme as should be displayed in the icons section of the Gnome Theme Manager, it is very important that the themes folder name matches this field

Comment = This is the theme comment
this field represents the comment of the theme as is sometimes displayed in Gnome Theme Manager

Directories = iconsize1/iconcategory1, iconsize1/iconcategory2, iconsize2/iconcategory1
this field represents the directories which contain the actual icons

Inherits = RootTheme
this field represents the root theme from which this theme inherits. If the theme does not supply a particular icon, GNOME will look in this root theme for icons before falling back on the system defaults.

Each directory as listed in the IconTheme section will also need its own section to describe icon size and type :

[Directory]
this section describes the characteristics of the icons located in this directory

Size = IconSize
this field represents the size of the icons located in this directory if they are bitmap icons (PNG or XPM), or the default scale if they are scalable icons (aka SVG)

MinSize = IconSize
this field represents the mimimum size that scalable icons (SVG) located in this directory can be scaled to.

MaxSize = IconSize
this field represents the maximum size that scalable icons (SVG) located in this directory can be scaled to.

Threshold = SizeThreshold==
this field represents the maximum size threshold that bitmap icons (PNG/XPM) located in this directory be used for if the icon type is Threshold.

Context = IconCategory
this field represents the category or context in which these icons are used. This value can be FileSystems (for Folder or HardDrives), Emblems, Applications, Devices, or MimeTypes

Type = IconType
this field represents the type of icons located in this directory, it can be Scalable for Scalable Icons (SVG), Threshold or Fixed(I have seen Scaled used as well, is this valid?!) for Bitmap Icons(PNG or XPM)

See the HighContrastTheme index.theme file as an example.

1.1.2. Step 2. General Directory and Icon Layout

Once you have a basic index.theme, the next step is to make the actual icon directories, and place the right icons in the right directories. First off, it should made apparent that the Directory entries you put in Index.theme are the actual names of the directories, so if you have a 48x48/filesystems section in the index.theme, you should have a corresponding folder 48x48/filesystems, and so forth. So, for the above example your should have a directory layout something like this:

HighContrastLargePrint/
        48x48/
                actions/
                apps/
                devices/
                mimetypes/
        scalable/
                actions/
                apps/
                devices/
                mimetypes/
        index.theme

As you can see the actual directory layout is the same layout as is described in the index.theme, making both updating the directory to match the index, or the index to match the layout very very easy.

Once you have created the directories you need, you need to organize the icons first by size and then by context, again exactly as is laid out in the index. So any 48x48 icons will go somewhere into the 48x48/ subdirectory tree by context.

1.1.3. Step 3. Icon naming & organization

In general icons are simply and intuitively named. You do not need to replace all the icons for your theme. In this case the absent icons will be taken form RootTheme specified in Inherits = RootTheme option in the index.theme file. The specific breakdown of the icons by context is as follows :

1.1.3.1. Filesystem

The FileSystem context is for icons intended to be used by a FileManager, such as Nautilus, to represent the core parts of a directory tree, essentially such icons as would be used to represent Folders, Network Servers, Network workstations, Fifo's, Character Devices, Executables and so forth.

For this context, every theme should probably have an icon representing

1.1.3.2. Devices

The Device context is for icons intended to be used to represent commonly used devices, such as CDROM, DVD, Floppy etc, from within a Desktop Manager, and/or a FileManager to diplay mounted hardware devices. These icons will usually have a context prefix of 'dev-'(i.e. cdrom = gnome-dev-cdrom).

For this context, every theme should probably have an icon representing

1.1.3.3. MimeTypes

Icons for MimeTypes such as msword, html or pdf will go into the mimetypes folder, the folder in the index matching the Size = 48, and Context = MimeTypes. In the case of this example the mimetypes folder is "mimetypes".

More specifically here are a handful of the 120 standard icons such as are set by the default Gnome icon theme :

1.1.3.4. Applications

Application icons, usually for GNOME specific applications such as gnome-calc, will go into the applications folder, the folder in the index matching the Size = 48, and Context = Applications. In the case of this example the applications folder is "apps".

Here are those standard icons such as are set by the default Gnome icon theme :

1.1.3.5. Emblems

Emblems are the little icons that can be added to the standard (big) icon :

1.1.3.6. Stock Icons

As of GTK2.4, stock icons (the icons used in toolbar buttons, menu items, and other widgets) can be defined in the icon theme.