Overview

This document defines a way for applications to set and get the default themes (icon theme, cursor theme and sound theme), as well as environment-specific themes and fallback themes.

The lists are stored in a theme.list file, located at the root of $XDG_DATA_DIRS/themes, as specified in the Base Directory specification.

The ‘theme.list’ file

This document specifies the format of a theme.list file. This is a human-readable file that follows the format for .ini files, commonly used for storing settings and programatically-readable information.

The values stored within those keys must follow the types defined in the Desktop Entry specification. The only value type this specification defines is a list of string (semicolon-separated string values).

The file lists two types of sections: “Environment” and “Default”. Environment sections should follow “[Environment <name>]”, where <name> is the name of the environment [See issue #1]. Default is a fallback.

Every section may store the following keys, all optional:

- IconTheme, containing a list of theme names for selected icon themes.

- CursorTheme, containing a list of theme names for selected cursor themes

- SoundTheme, containing a list of theme names for selected sound themes

Keys not present in this spec ification may be added, such keys must begin with X-, such as X-GTKTheme.

IconTheme and CursorTheme keys contain lists of theme names as specified in the Icon Theme specification. SoundTheme contains a list of theme names as specified in the Sound Theme specification.

List values must be semicolon-separated lists and must have a trailing semicolon.

In order to find the chosen icon theme for the current environment, the client application has to go through the following steps:

1. Look for theme.list in the next-highest priority XDG_DATA_DIR. If no readable theme.list file is found, or there is no more directory to check, go to step 2.

1.1. Look for a section called “Environment <name>”. If the environment is not known, go to 1.2.

1.1.1. Look for a key called “IconTheme” containing a non-empty list of values. If no such key is found, or a syntax error is encountered, go to 1.2.

1.1.2. Read, from left-to-right, the next key in the list.

1.1.3. Attempt to find a valid theme given the name. If not found, go to step 1.2.

1.1.4. Return the valid theme name.

1.2. Look for a section called “Default”. If no such section is found, go back to step 1.

2. Return “hicolor”

Finding the cursor theme would execute the same steps, replacing IconTheme by CursorTheme. For the sound theme, IconTheme would be replaced by SoundTheme.

## Examples

Example theme.list file

[Environment KDE]
IconTheme=oxygen;crystal;
CursorTheme=oxygen;
[Environment GNOME]
IconTheme=tango;
[Default]
IconTheme=oxygen;
CursorTheme=oxygen;
SoundTheme=freedesktop;

Example implementation in Python

# Pseudocode to get default Icon theme on GNOME
DE = "GNOME"

XDG_DIRS = os.environ.get("XDG_DATA_HOME", os.path.expandvars("$HOME/.local/share"))
XDG_DIRS += ":" + os.environ.get("XDG_DATA_DIRS", "/usr/local/share/:/usr/share/")
for path in XDG_DIRS:
f = IniFile(path + "themes/" + "theme.list")
if f:
for sectionName in (("Environment " + DE), "Default"):
section = f.section(sectionName)
if section:
if section.key("IconTheme"):
for theme in section.key("IconTheme").list():
if Theme(theme).isValid():
return theme
return "hicolor"

References

1. Portland Bug 43943 - Freedesktop needs to define a way to get/set the default icon theme

Issues

1. How does the app get the current environment? Alexander Sokorov proposes using $XDG_CURRENT_DESKTOP. Do gnome and kde use this yet? LXDE and Xfce do.
2. Proposed on xdg-list: Use Xsettings to expose the settings to the app. Should it be included?