# Installing Themes

This chapter describes themes, the theme settings that are available in the GNOME Desktop, how to install options for theme settings, and how to create a custom option.

## Introduction to Themes

A theme is a group of coordinated settings that specifies the visual appearance of a part of the GNOME Desktop. Users can choose themes to change the appearance of the GNOME Desktop.

A theme contains settings that affect different parts of the GNOME Desktop, as follows:

Controls

- The controls setting for a theme determines the visual appearance of windows, panels, and applets. The controls setting also determines the visual appearance of the GNOME-compliant interface items that appear on windows, panels, and applets, such as menus, icons, and buttons. Some of the controls setting options that are available are designed for special accessibility needs. Users can choose an option for the controls setting from the Controls tabbed section in the Theme preference tool.

Window frame

- The window frame setting for a theme determines the appearance of the frames around windows only. Users can choose an option for the window frame setting from the Window Border tabbed section in the Theme preference tool.

Icon

- The icon setting for a theme determines the appearance of the icons on panels and the desktop background. Users can choose an option for the icon setting from the Icons tabbed section in the Theme preference tool.

## Theme Index File

Each theme has an index file which defines the characteristics of the theme. The name of the index file is `/usr/share/themes/`theme-name`/index.theme`.

The following is a sample theme index file:

    [Desktop Entry]
    Type=X-GNOME-Metatheme
    Name=High Contrast Large
    Name[es]=Alto contraste grande
    Comment=Large black-on-white text and icons
    Comment[es]=Textos e iconos grandes en negro sobre blanco
    Encoding=UTF-8

    [X-GNOME-Metatheme]
    GtkTheme=HighContrastLargePrint
    IconTheme=HighContrast
    MetacityTheme=Atlanta
    ApplicationFont=sans 18

The following table describes the keys in theme index files:

## Keys in Theme Index Files

Index File Key | Description
`Type` | Specifies that this theme determines the appearance of several theme options, such as controls, window frames, and icons.
`Name` | The name of the theme. This is the name of the theme that is displayed in the Theme preference tool.
`Comment` | A brief description of the theme. This is the text that is displayed under the name of the theme in the Theme preference tool.
`GtkTheme` | Corresponds to the controls setting in the Theme preference tool. Specifies which controls setting option to apply to windows, panels, and applets.
`IconTheme` | Corresponds to the icons setting in the Theme preference tool. Specifies which icons setting option to apply to panels and the desktop background.
`MetacityTheme` | Corresponds to the window frame setting in the Theme preference tool. Specifies which window frame setting option to apply to windows.
`ApplicationFont` | Corresponds to the application font setting in the Font preference tool.

## To Install a New Controls Option

You can add a new option for the controls setting in the Theme preference tool. Controls options reside in the `/usr/share/themes` directory. The typical structure of a controls option in the file system is as follows:

Option file

- `/usr/share/themes/`option-name`/gtk-2.0/gtkrc`

Image files

- `/usr/share/themes/`option-name`/pixmaps/*.*`

Typically, a new option for the controls setting is supplied as a `.tar.gz` file. To install the new controls option, unzip the `.tar.gz` file, then untar the `.tar` file into the `/usr/share/themes` directory.

Users can install their own options for the controls setting. If a user installs an option for the controls setting, the option is stored in the `$HOME/.themes` directory.

## To Install a New Window Frame Option

You can add a new option for the window frame setting in the Theme preference tool. Window frame options reside in the `/usr/share/themes/`option-name`/metacity-1` directory. The typical structure of a window frame option in the file system is as follows:

Option file

- `/usr/share/themes/`option-name`/metacity-1/metacity-theme-1.xml`

Image files

- `/usr/share/themes/`option-name`/metacity-1/*.*`

Typically, a new option for the window frame setting is supplied as a `.tar.gz` file. To install the new window frame option, unzip the `.tar.gz` file, then untar the `.tar` file into the `/usr/share/themes` directory.

Users can install their own options for the window frame setting. If a user installs an option for the window frame setting, the option is stored in the `$HOME/.themes` directory.

## To Install a New Icons Option

You can add a new option for the icons setting in the Theme preference tool. Icons options reside in the `/usr/share/icons/`option-name`` directory. The typical structure of an icons option in the file system is as follows:

Option file

- `/usr/share/icons/`option-name``

Image files

- `/usr/share/icons/`option-name`/icons/*.*`

Typically, a new option for the icons setting is supplied as a `.tar.gz` file. To install the new icons option, unzip the `.tar.gz` file, then untar the `.tar` file into the `/usr/share/icons` directory.

Users can install their own options for the icons setting. If a user installs an option for the icons setting, the option is stored in the `$HOME/.icons/`option-name`` directory.

## Installing Icons for Themes

The GNOME Desktop provides several themes that are designed for users with special visual needs. For example, some of the themes are designed for users with low vision. Several versions of icons might be required so that the icon can be displayed properly in each theme.

You might need to install a new icon for an application. When you install a new icon, you must create several versions of the icon, so that the icon displays correctly in the themes. You must create several versions of the following types of icon:

- Icons that are used within applications in the GNOME Desktop.

- Icons that are used internally by GTK+ applications, or GTK+ stock icons.

When you install a new icon, you must create several versions of the icon, so that the icon displays correctly in the themes. You can create the icons in several formats, for example Portable Network Graphic (PNG) format. The suggested size of icons for the desktop environment is 48 pixels by 48 pixels. At this size, most themes can rescale the icons.

When you install a new icon, create the following 48 × 48 pixel versions of the icon:

- Regular icon

- Low contrast icon

- High contrast icon

- Inverse high contrast icon

If possible, create 16 × 16 pixel versions of the each of the icons above also, for themes that do not require large print.

Install the icons to the image files location that is specified for the theme in themes-3 or themes-5. For example, to add icons to the HighContrastLargePrint theme, add the icons to the `/usr/share/themes/HighContrastLargePrint/pixmaps` directory. Add references to the icons to the relevant theme files. For example, to add icons to the HighContrastLargePrint theme, add references to the icons to the `/usr/share/themes/HighContrastLargePrint/gtk-2.0/gtkrc` file. Modify the `gtkrc` file for the theme to associate the icon with a GTK stock icon identifier.

For more information on how to create icons for application launchers and for panels, see http://www.freedesktop.org/Standards/icon-theme-spec.

## To Create a Custom Controls Option

If the options for the controls setting are not suitable for the needs of your users, you can create a custom controls option. To create a custom controls option, perform the following steps:

1. Create a directory structure for the option in the `/usr/share/themes` directory. Use the same directory structure that other options use. For example, to create an option that is called SmallPrint, create the following directories:

   - `/usr/share/themes/SmallPrint`

   - `/usr/share/themes/SmallPrint/gtk-2.0`

2. Locate the `gtkrc` file that is closest to meeting the needs of your users. Copy the file to the `gtk-2.0` directory of your new option.

3. Open the `gtkrc` file in a text editor, and modify the attributes of the interface elements as required.

4. If the new option includes images, install the images for the new option in the `pixmaps` directory of your new option. If the new option uses images from another option, you do not need to create copies of the images for the new option. Instead, ensure that the reference to the images in the `pixmap_path` entry in the `gtkrc` file is correct.

Users can now choose the new option for the controls setting.

For more information on `gtkrc` files, see http://developer.gnome.org/doc/API/2.0/gtk/index.html.