Bdtyktl

I am trying to create one theme for GTK+ and while doing so, I found index.theme. Now, where do I find specification for this file similar to Icon Theme and Desktop entry?

There is nowhere to be found.

The 'index.theme' specification for GTK+ theme doesn't seem to be documented anymore since GNOME 2 had deprecated. Both GTK+ and GNOME Developer websites are essentially having zero documentation about 'index.theme' for GTK+ theme.

Known documentation

The earliest known documentation, GNOME 2.4 Desktop System Administration Guide, was last updated in 2003. That is possibly the original 'index.theme' specification for GTK+ theme.

[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

Following that, some changes have been introduced in GNOME mailing list dated July 2004 and October 2004 (only latter is quoted below). Unfortunately, there is no updated documentation by GTK+ or GNOME developers to illustrate those changes.

gnome-theme-manager currently handles GTK, Metacity and Icon themes,
but could be extended to handle splash screens and backgrounds
(possible integration with current background chooser?).

A relatively new documentation, Gnome Theme Package format by Xfce, was last updated in 2010. This included more variables in the index.theme file that are not found in the original specification and reflects some of the changes mentioned in GNOME mailing list.

[Desktop Entry]

Name=example theme

Type=X-GNOME-Metatheme

Comment=

Encoding=UTF-8



[X-GNOME-Metatheme]

GtkTheme=Gilouche

MetacityTheme=Gilouche

IconTheme=gnome



BackgroundImage=.local/share/wallpapers/Naptime.jpg

MonospaceFont=

ApplicationFont=

DesktopFont=

SoundTheme=

GtkColorScheme=

Supporting fact has been found in Artwork/Documentation/GTK-Themes on Ubuntu Wiki, which mentioned one of the additional variables. This material however, was last updated in 2009.

In your index.theme file put a line like "BackgroundImage=/absolute/path/to/image.png" under the X-GNOME-Metatheme header. For packaged themes wallpapers should be assumed to be placed in /usr/share/wallpapers.

To use or not

If you are less confident to use the provided example in outdated documentation, I'd suggest to copy index.theme file from existing THEME and modify accordingly. GTK+ themes will include the file at /usr/share/themes/THEME/index.theme in some Ubuntu and official flavours.

Another way to use index.theme file is, by not having to write one.

There is at least one example that demonstrates custom GTK+ theme could just reference to existing file by using symbolic link. This way, it is possible to create slightly modified version of existing theme in less time and without having to worry about the specification of index.theme file.

TL;DR The most recent documentation that you can find today, albeit without explanation, is Gnome Theme Package format by Xfce. Or just forget that and follow what other themes do.

You can find a document here. I don't know how up to date it is though. It discusses the structure of the file, the possible keys that are allowed and their descriptions.

If you do have the time try joining #gtk+ and #gnome-design on IRC. They may be able to answer your queries better. See here for learning how.