Both the icon theme description file and the icon data files are ini-style text files, as described in the desktop file specification. They don't have any encoding field. Instead, they must always be stored in UTF-8 encoding.
The index.theme file must start with a section called Icon Theme, with contents according to table 1 below. All lists are comma-separated.
Table 1. Standard Keys
| Key | Description | Value Type | Required |
|---|---|---|---|
| Name | short name of the icon theme, used in e.g. lists when selecting themes. | localestring | YES |
| Comment | longer string describing the theme | localestring | YES |
| Inherits |
The name of the theme that this theme inherits from. If an icon name is not found in the current theme, it is searched for in the inherited theme (and recursively in all the inherited themes). If no theme is specified implementations are required to add the "hicolor" theme to the inheritance tree. An implementation may optionally add other default themes in between the last specified theme and the hicolor theme. | strings | NO |
| Directories | list of subdirectories for this theme. For every subdirectory there must be a section in the index.theme file describing that directory. | strings | YES |
| ScaledDirectories | Additional list of subdirectories for this theme, in addition to the ones in Directories. These directories should only be read by implementations supporting scaled directories and was added to keep compatibility with old implementations that don't support these. | strings | NO |
| Hidden | Whether to hide the theme in a theme selection user interface. This is used for things such as fallback-themes that are not supposed to be visible to the user. | boolean | NO |
| Example | The name of an icon that should be used as an example of how this theme looks. | string | NO |
Each directory specified in the Directory key has a corresponding section with the same name as the directory. The contents of this section is listed in table 2 below.
Table 2. Per-Directory Keys
| Key | Description | Value Type | Required | Type |
|---|---|---|---|---|
| Size | Nominal (unscaled) size of the icons in this directory. | integer | YES | |
| Scale | Target scale of of the icons in this directory. Defaults to the value 1 if not present. Any directory with a scale other than 1 should be listed in the ScaledDirectories list rather than Directories for backwards compatibility. | integer | NO | |
| Context | The context the icon is normally used in. This is in detail discussed in the section called “Context”. | string | NO | |
| Type | The type of icon sizes for the icons in this directory. Valid types are Fixed, Scalable and Threshold. The type decides what other keys in the section are used. If not specified, the default is Threshold. | string | NO | |
| MaxSize | Specifies the maximum (unscaled) size that the icons in this directory can be scaled to. Defaults to the value of Size if not present. | integer | NO | Scalable |
| MinSize | Specifies the minimum (unscaled) size that the icons in this directory can be scaled to. Defaults to the value of Size if not present. | integer | NO | Scalable |
| Threshold | The icons in this directory can be used if the size differ at most this much from the desired (unscaled) size. Defaults to 2 if not present. | integer | NO | Threshold |
In addition to these groups you may add extra groups to the index.theme file in order to extend it. These extensions must begin with "X-", and can be used to add desktop specific information to the theme file. Example group names would be "X-KDE Icon Theme" or "X-Gnome Icon Theme".
The optional filename.icon file contains a group called "Icon Data", with the content listed in table 3.
Table 3. Icon Data Keys
| Key | Description | Value Type | Required |
|---|---|---|---|
| DisplayName | A translated UTF8 string that can be used instead of the icon name when the icon is listed in e.g. a user interface. | localestring | NO |
| EmbeddedTextRectangle | If this exists, it specifies the four corners of a rectangle where the program displaying the icon can embed text. This is normally used by e.g. file managers that want to display a preview of text file contents in the icon. The corners are specified by a list of four values: x0,y0,x1,y1. The values are pixel coordinates from the top left corner of the icon, except for SVG files, where they are specified in a 1000x1000 coordinate space that is scaled to the final rendered size of the icon. | integers | NO |
| AttachPoints | A list of points, separated by "|" that may be used as anchor points for emblems/overlays. The points are pixel coordinates from the top left corner of the icon, except for SVG files, where they are specified in a 1000x1000 coordinate space that is scaled to the final rendered size of the icon. | points | NO |
Extensions to the filename.icon file are allowed, but the keys must be begin with "X-" to avoid collisions with future standardized extensions to this format.
The Context allows
the designer to group icons on a conceptual level.
It doesn't act as a namespace in the file system, such
that icons can have identical names, but allows
implementations to categorize and sort by it, for example.
These are the available contexts:
Actions. Icons representing actions which the user initiates, such as Save As.
Devices. Icons representing real world devices, such as printers and mice. It's not for file system nodes such as character or block devices.
FileSystems. Icons for objects which are represented as part of the file system. This is for example, the local network, “Home”, and “Desktop” folders.
MimeTypes. Icons representing MIME types.