1. Symbolic Colors

GTK+ 2.10 introduced a new feature called symbolic colors. This new feature allows for recolorable themes without the need to change the gtkrc.

If not specified otherwise, the information below concerns GTK+ 2.10.

Contents

Symbolic Colors
Defining and using symbolic colors
Color Expressions
Default colors in GNOME
1. Defining multiple color schemes for a theme
Bugs

2. Defining and using symbolic colors

There are three different places symbolic colors can be defined. Theser are in the order of importance (from most to least important):

Inside the style in the gtkrc
Application set symbolic colors
The gtk-color-scheme xsetting (set to the gconf key "/desktop/gnome/interface/gtk_color_scheme" in GNOME). This is what the user uses to override the default color scheme.
The "gtk-color-scheme" option in the gtkrc file. This is used to define the default color scheme.

2.1. Inside a style

It is possible to define a symbolic color inside the style:

  color["name"] = "#ff0000"

There are some caveats though. The change will not be picked up by other styles, so any colors using it may need to be redefined. (This is because the colors are calculated right away while parsing.)

2.2. The xsetting/gconf key

The format is exactly the same as in the gtkrc. See below.

2.3. The default color scheme

Setting a default color scheme works as following (global option in the gtkrc):

gtk_color_scheme = "color1:#001\ncolor2:Blue\ncolor3:#ff0000"

The seperator is \n (new line). Newer GTK versions (XXX which exactly?) also accept ';'.

gtk_color_scheme = "color1: #001;color2: Blue;color3: #ff0000"

Note that spaces are only accepted between the ':' and the color definition. (Hmm, is this really correct, and if yes, is it version specific?)

2.4. Example

# Set the default color scheme:
gtk_color_scheme = "fg_color:#000\nbg_color:#ede9e3\nbase_color:#fff\ntext_color:#000\nselected_bg_color:#5598d7\nselected_fg_color:#fff"
style "default"
{
  fg[NORMAL]        = @fg_color
  fg[PRELIGHT]      = @fg_color
  fg[SELECTED]      = @selected_fg_color
  fg[ACTIVE]        = @fg_color
  # There are color expressions to change the colors
  fg[INSENSITIVE]   = darker (@bg_color)
  [...]
}
style "progress"
{
  # You can override symbolic colors per style (XXX did I get this right?)
  color["fg_color"] = "#00ff00"
  # Not that this will *NOT* change the foreground colors as they
  # were set in the default style. For that to work, everything using
  # fg_color needs to be copied.
  # This is a design limitation. (Hm, should report a bug really ...)
  fg[NORMAL]        = @fg_color
  fg[PRELIGHT]      = @fg_color
  fg[ACTIVE]        = @fg_color
}
class "GtkWidget"    style "default"
class "GtkProgress"  style "default"

3. Color Expressions

It is possible to modify colors using color expressions. This means it is possible to create a whole theme with only a small set of colors.

The possible color expressions are:

function	description
`mix(value, color1, color2)`	Mix the two colors according to value
`shade(value, color)`	Shades the color by the given value (multiplying saturation and brightness)
`lighter(color)`	Same as `shade(1.3, color)`
`darker(color)`	Same as `shade(0.7, color)`

It is possible to nest these, so for example the following will work:

  # Make bg_color a little lighter, and then add some red.
  bg[NORMAL] = mix(0.1, "#ff0000", shade(1.1, @bg_color))

4. Default colors in GNOME

Currently there is a set of eight symbolic colors, that can be set by the gnome-appearance-properties. So if you want your theme to work well with a standard GNOME installation, you may want to stick to these colors. These map almost directly to the GTK+ colors.

They are:

color	Usage
`fg_color`	The base for the foreground colors.
`bg_color`	Color to generate the background colors from.
`base_color`	The `base` color.
`text_color`	The `text` color in input widgets.
`selected_bg_color`	Color for the background of selected text.
`selected_fg_color`	Color of selected text.
`tooltip_bg_color`	Background color of tooltips.
`tooltip_fg_color`	Text color for text in tooltips.

Any other colors will not be changable by the user from the gnome-appearance-properties. They can of course still be set directly using for example the gconf-editor.

4.1. Defining multiple color schemes for a theme

There are plans to add support for themes with multiple color schemes. This may be handled with an extension to the index.theme file.

See http://bugzilla.gnome.org/show_bug.cgi?id=499575 for more information about the current development in this area.

5. Bugs

All fixed?