Gtk2 Theme Creation Guide

Contents

introduction:

Gtk programmers will tell you that writing a gtk theme is easy. If you have a full understanding of how gtk is put together, then that may be so, but if you dont have an intimate knowledge of the gtk api and you want to change the visual appearance of your gtk apps then this document may hopefully save you some swearing while you go through the process of trial and error trying to figure out what works and what doesn't. Its not difficult stuff, but can appear to be somewhat random and non-intuitive due to its close correlation with the underlying widget structure.

Warning: this document is incomplete. The gnome.org tutorial (and useful links) may be useful.

theme browsing

LXAppearance is a great new tool for browsing gtk and icon themes. Also good are gtk-chtheme, and the older and slightly buggy gtk-theme-switch.

general widget properties:

• fg - Sets the foreground color of a widget.
• bg - Sets the background color of a widget.
• text - Sets the foreground color for widgets that have editable text.
• base - Sets the background color for widgets that have editable text.
• bg_pixmap - Sets the background of a widget to a tiled pixmap.
• font_name - Sets the font to be used with the given widget.
• xthickness - Sets the left and right border width. This is not what you might think; it sets the borders of children(?)
• ythickness - similar to above but for the top and bottom.

There are several states a widget can be in, and you can set different colors, pixmaps and fonts for each state. These states are:

• NORMAL - The normal state of a widget. Ie the mouse is not over it, and it is not being pressed, etc.
  
• PRELIGHT - When the mouse is over top of the widget, colors defined using this state will be in effect.
  
• ACTIVE - When the widget is pressed or clicked it will be active, and the attributes assigned by this tag will be in effect.
  
• INSENSITIVE - This is the state when a widget is 'greyed out'. It is not active, and cannot be clicked on.
  
• SELECTED - When an object is selected, it takes these attributes.
  

gtkrc files:

colours:
colours can be specified in several different ways:
-by name: Gtk knows all names from the X color database /usr/lib/X11/rgb.txt
eg "red"
-one of the hexadecimal forms "#rrrrggggbbbb", "#rrrgggbbb", "#rrggbb", or "#rgb", where r, g and b are hex digits. They must be in quotes.
-as a triplet { r, g, b}, where r, g and b are either integers in the range 0-65635 or floats in the range 0.0-1.0.
eg {1.00, 0.00, 0.00} for red.

Gtk 2.10 introduced the "gtk-color-scheme" property. This contains a list of colours. gtk-color-scheme = "fg_color : white tooltip_bg_color: black" The meaning of the colour names is explained in http://live.gnome.org/GnomeArt/Tutorials/GtkThemes/SymbolicColors. Apparently this setting doesnt work under all circumstances.

The GtkInfoBar uses symbolic colors for theming its background color depending on the message type. The color names are info_fg_color, info_bg_color, warning_fg_color", warning_bg_color, etc. (Since Gtk 2.18)

binding styles to widget classes:
The syntax is of the form: class "GtkButton" style "my-button"
This would bind the my-button style to all instances of GtkButton.
Alternatively you can use the form: widget_class "*Text*" style "bright_yellow"
where a "*" can be used as a wildcard in the class string, in this example to bind the bright_yellow style to any widget with "Text" in its the name.
To select a widget class only if it is a child of a particular widget class, eg the header of a treeview. use this type of notation: widget_class "*TreeView*Button*" style "mystyle" Standard shell globbing is used, so * represents zero or more chars, and ? represents any single character.

RC styles bound with widget take precedence over RC styles bound with widget_class, which, in turn, take precedence over RC styles bound with class. If multiple declarations are made for the same widget class, the later one takes priority. This can be overridden by specifying a priority highest, rc, theme, application, gtk, lowest
eg: widget_class "*Button*" style : highest "mystyle".
This aspect is easily overlooked, and can be a big source of problems if you are not careful.

application specific styles:
If the application developer has explicitly exposed an element, it can be styled by specifying that element name in a gtkrc file.
eg if an app has an element called 'funky bar', you can style it using: widget "funky bar" style "mystyle"

The environment variable GTK2_RC_FILES can be used to change the theme for a particular application. It specifies a list of RC files to parse instead of the default ones.

widget specific styles:
the gtk api docs list some 'style properties' which are specific to a certain widget type. You can include them in an rc file with the syntax: eg: GtkWidget::focus-line-width = 2
These properties are also applicable to child widget-types, so for example, as most widgets are derived from GtkWidget, style properties of GtkWidget can also be used for these other widgets.
A list of widget style properties can be obtained via the object hierarchy in the api documentation. A more convenient listing of these can be found at ajgenius.us.

toplevel declarations:
(taken from the official gtk2 documentation)

An RC file is a text file which is composed of a sequence of declarations. '#' characters delimit comments and the portion of a line after a '#' is ignored when parsing an RC file.

The possible toplevel declarations are:

widget examples:

This information applies to the default gtk theme engine. Other engines may be slightly different and often have additional properties. The gnome.org wiki now has detailed theming information for each widget.

• buttons:
  • they dont have a background (is that true for all engines?). You must maniplulate the property of the widget that the button is sitting on.
  • bevelling (relief): -there are 3 states you can apply to a button: GTK_RELIEF_NORMAL, GTK_RELIEF_HALF, GTK_RELIEF_NONE.
    note: with some engines bevelling doesnt work with dark themes, as the colours are multiplied, this having little effect on a black background.
    
  • the 'default-button-indicator' takes the fg[NORMAL] of its parent not th
  • border size. I think this is taken from the xthickness and ythickness properties of the parent widget. This is a pain because it makes it more difficult to set properties that only apply to buttons.
• labels:
  • they dont have a background (on mailing list it was said that you use "base").
  • supposedly the foreground color is set using the "text" property.
• text boxes:
  • background: base[NORMAL]
  • text colour: text[NORMAL]
  • apply your style using: widget_class "*TextView*" style "my_style"
  • the edit cursor color can be changed with, eg: GtkWidget::cursor-color "red"
• scrollbars and scales:
  • use widget_class "*Scrollbar*"to select scrollbars.
  • arrow button and main draggable rectangle colour is controlled by bg[NORMAL]
  • background trough and border is controlled by bg[ACTIVE] (this appears not to be true for the Clear engine)
  • mouseover colour uses bg[PRELIGHT]
  • arrow colour uses fg[NORMAL]
• combobox: http://live.gnome.org/GnomeArt/Tutorials/GtkThemes/GtkComboBox
  • combobox is a button containing a label, separator, and arrow.
  • the comboboxentry type has is a text entry field and a drop-down list with a button for opening the drop-down list.
• icons:
  • You can specify custom icons for specific sizes, as follows:

      stock["my-stock-item"] = 
      {
        { "itemmenusize.png", *, *, "gtk-menu" },
        { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" }
        { "itemgeneric.png" } /* implicit *, *, * as a fallback */
      }

• menus:
  • menus are composite widgets, consisting of a menubar and menuitems.
  • top-level padding is set using, eg: GtkMenuBar::internal-padding = 2
  • The x/ythickness is not added if shadow-type is GTK_SHADOW_NONE.
  • http://live.gnome.org/GnomeArt/Tutorials/GtkThemes/GtkMenuBar
• lists:
  • -often these are actually TreeView widgets (see below).
• treeview:
  • Treeview background is controlled by the base colour, not the bg. If the tree is not focussed, it takes the colour base[ACTIVE].
  • Setting the bg controls the column heads colour.
  • The column heads appear to be buttons. They can be selected with widget_class "*TreeView.GtkButton*". The text colour in the heads is controlled with fg, and not text.
  • The default line spacing of TreeView lists is quite large. It is not possible to reduce it in the rc file. This is a known issue.
  • Treeview style properties: allow-rules, even-row-color, expander-size, horizontal-separator, indent-expanders, odd-row-color, vertical-separator.
• tabs:
  • -the text on non-selected tabs uses fg[ACTIVE], and the backgrounds of these tabs use bg[ACTIVE].
  • -the tabs text can be selected with widget_class "*GtkNotebook*GtkLabel".

binding name {
  bind key { 
    signalname (param, ...)
    ...
  }
  ...
}