Ubuntu: Where to find 'index.theme' specification for GTK+ theme


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.

Notable documentation

The earliest known documentation, GNOME 2.4 Desktop System Administration Guide, was last updated in 2003 and that contained the possibly 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 by 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 GTK+ theme and modify accordingly. Ubuntu and official flavours that uses GTK+ themes include the file at /usr/share/themes/[theme]/index.theme.

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.

Note:If u also have question or solution just comment us below or mail us on toontricks1994@gmail.com
Next Post »