Default files

An application can cause GTK+ to parse a specific RC file by calling gtk_rc_parse(). In addition to this, certain files will be read at the end of gtk_init(). Unless modified, the files looked for will be <SYSCONFDIR>/gtk-2.0/gtkrc and .gtkrc-2.0 in the users home directory. (<SYSCONFDIR> defaults to /usr/local/etc. It can be changed with the --prefix or --sysconfdir options when configuring GTK+.)

The set of these default files can be retrieved with gtk_rc_get_default_files() and modified with gtk_rc_add_default_file() and gtk_rc_set_default_files(). Additionally, the GTK2_RC_FILES environment variable can be set to a G_SEARCHPATH_SEPARATOR_S-separated list of files in order to overwrite the set of default files at runtime.

For each RC file, in addition to the file itself, GTK+ will look for a locale-specific file that will be parsed after the main file. For instance, if LANG is set to ja_JP.ujis, when loading the default file ~/.gtkrc then GTK+ looks for ~/.gtkrc.ja_JP and ~/.gtkrc.ja, and parses the first of those that exists.

Pathnames and patterns

A resource file defines a number of styles and key bindings and attaches them to particular widgets. The attachment is done by the widget, widget_class, and class declarations. As an example of such a statement:

widget "mywindow.*.GtkEntry" style "my-entry-class"

attaches the style "my-entry-class" to all widgets whose widget class matches the pattern "mywindow.*.GtkEntry".

The patterns here are given in the standard shell glob syntax. The "?" wildcard matches any character, while "*" matches zero or more of any character. The three types of matching are against the widget path, the class path and the class hierarchy. Both the widget and the class paths consists of a "." separated list of all the parents of the widget and the widget itself from outermost to innermost. The difference is that in the widget path, the name assigned by gtk_widget_set_name() is used if present, otherwise the class name of the widget, while for the widget path, the class name is always used.

So, if you have a GtkEntry named "myentry", inside of a of a window named "mywindow", then the widget path is: "mwindow.GtkHBox.myentry" while the class path is: "GtkWindow.GtkHBox.GtkEntry".

Matching against class is a little different. The pattern match is done against all class names in the widgets class hierarchy (not the layout hierarchy) in sequence, so the pattern:

class "GtkButton" style "my-style"

will match not just GtkButton widgets, but also GtkToggleButton and GtkCheckButton widgets, since those classes derive from GtkButton.

Toplevel declarations

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:

Styles

A RC style is specified by a style declaration in a RC file, and then bound to widgets with a widget, widget_class, or class declaration. All styles applying to a particular widget are composited together with widget declarations overriding widget_class declarations which, in turn, override class declarations. Within each type of declaration, later declarations override earlier ones.

Within a style declaration, the possible elements are:

The colors and background pixmaps are specified as a function of the state of the widget. The states are:

Colors can be specified as a string containing a color name (GTK+ knows all names from the X color database /usr/lib/X11/rgb.txt), in one of the hexadecimal forms #rrrrggggbbbb, #rrrgggbbb, #rrggbb, or #rgb, where r, g and b are hex digits, or they can be specified 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.

In a stock definition, icon sources are specified as a 4-tuple of image filename, text direction, widget state, and size, in that order. Each icon source specifies an image filename to use with a given direction, state, and size. The * character can be used as a wildcard, and if direction/state/size are omitted they default to *. So for example, the following specifies different icons to use for left-to-right and right-to-left languages:

stock["my-stock-item"] = 
{
  { "itemltr.png", LTR, *, * },
  { "itemrtl.png", RTL, *, * }
}

This could be abbreviated as follows:

stock["my-stock-item"] = 
{
  { "itemltr.png", LTR },
  { "itemrtl.png", RTL }
}

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 */
}

The sizes that come with GTK+ itself are "gtk-menu", "gtk-small-toolbar", "gtk-large-toolbar", "gtk-button", "gtk-dialog". Applications can define other sizes.

It's also possible to use custom icons for a given state, for example:

stock["my-stock-item"] = 
{
  { "itemprelight.png", *, PRELIGHT },
  { "iteminsensitive.png", *, INSENSITIVE }, 
  { "itemgeneric.png" } /* implicit *, *, * as a fallback */
}

When selecting an icon source to use, GTK+ will consider text direction most important, state second, and size third. It will select the best match based on those criteria. If an attribute matches exactly (e.g. you specified PRELIGHT or specified the size), GTK+ won't modify the image; if the attribute matches with a wildcard, GTK+ will scale or modify the image to match the state and size the user requested.

Key bindings

Key bindings allow the user to specify actions to be taken on particular key presses. The form of a binding set declaration is:

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

key is a string consisting of a series of modifiers followed by the name of a key. The modifiers can be:

<shft> is an alias for <shift> and <alt> is an alias for <mod1>.

The action that is bound to the key is a sequence of signal names (strings) followed by parameters for each signal. The signals must be action signals. (See g_signal_new()). Each parameter can be a float, integer, string, or unquoted string representing an enumeration value. The types of the parameters specified must match the types of the parameters of the signal.

Binding sets are connected to widgets in the same manner as styles, with one addition. A priority can be specified for each pattern, and within each type of pattern, binding sets override other binding sets first by priority, and only then by order of specification. (Later overrides earlier). The priorities that can be specified are (highest to lowest):

rc is the default for bindings read from an RC file, theme is the default for bindings read from theme RC files, application should be used for bindings an application sets up, and gtk is used for bindings that GTK+ creates internally.

struct GtkRcStyle

struct GtkRcStyle {
  
  gchar *name;
  gchar *bg_pixmap_name[5];
  PangoFontDescription *font_desc;

  GtkRcFlags color_flags[5];
  GdkColor   fg[5];
  GdkColor   bg[5];
  GdkColor   text[5];
  GdkColor   base[5];

  gint xthickness;
  gint ythickness;

};

The GtkRcStyle structure is used to represent a set of information about the appearance of a widget. This can later be composited together with other GtkRcStyle structures to form a GtkStyle.

enum GtkRcFlags

typedef enum
{
  GTK_RC_FG		= 1 << 0,
  GTK_RC_BG		= 1 << 1,
  GTK_RC_TEXT		= 1 << 2,
  GTK_RC_BASE		= 1 << 3
} GtkRcFlags;

The GtkRcFlags enumeration is used as a bitmask to specify which fields of a GtkRcStyle have been set for each state.

enum GtkRcTokenType

typedef enum {
  GTK_RC_TOKEN_INVALID = G_TOKEN_LAST,
  GTK_RC_TOKEN_INCLUDE,
  GTK_RC_TOKEN_NORMAL,
  GTK_RC_TOKEN_ACTIVE,
  GTK_RC_TOKEN_PRELIGHT,
  GTK_RC_TOKEN_SELECTED,
  GTK_RC_TOKEN_INSENSITIVE,
  GTK_RC_TOKEN_FG,
  GTK_RC_TOKEN_BG,
  GTK_RC_TOKEN_TEXT,
  GTK_RC_TOKEN_BASE,
  GTK_RC_TOKEN_XTHICKNESS,
  GTK_RC_TOKEN_YTHICKNESS,
  GTK_RC_TOKEN_FONT,
  GTK_RC_TOKEN_FONTSET,
  GTK_RC_TOKEN_FONT_NAME,
  GTK_RC_TOKEN_BG_PIXMAP,
  GTK_RC_TOKEN_PIXMAP_PATH,
  GTK_RC_TOKEN_STYLE,
  GTK_RC_TOKEN_BINDING,
  GTK_RC_TOKEN_BIND,
  GTK_RC_TOKEN_WIDGET,
  GTK_RC_TOKEN_WIDGET_CLASS,
  GTK_RC_TOKEN_CLASS,
  GTK_RC_TOKEN_LOWEST,
  GTK_RC_TOKEN_GTK,
  GTK_RC_TOKEN_APPLICATION,
  GTK_RC_TOKEN_THEME,
  GTK_RC_TOKEN_RC,
  GTK_RC_TOKEN_HIGHEST,
  GTK_RC_TOKEN_ENGINE,
  GTK_RC_TOKEN_MODULE_PATH,
  GTK_RC_TOKEN_IM_MODULE_PATH,
  GTK_RC_TOKEN_IM_MODULE_FILE,
  GTK_RC_TOKEN_STOCK,
  GTK_RC_TOKEN_LTR,
  GTK_RC_TOKEN_RTL,
  GTK_RC_TOKEN_LAST
} GtkRcTokenType;

The GtkRcTokenType enumeration represents the tokens in the RC file. It is exposed so that theme engines can reuse these tokens when parsing the theme-engine specific portions of a RC file.

gtk_rc_scanner_new ()

GScanner*   gtk_rc_scanner_new              (void);

gtk_rc_get_style ()

GtkStyle*   gtk_rc_get_style                (GtkWidget *widget);

Finds all matching RC styles for a given widget, composites them together, and then creates a GtkStyle representing the composite appearance. (GTK+ actually keeps a cache of previously created styles, so a new style may not be created.)

gtk_rc_get_style_by_paths ()

GtkStyle*   gtk_rc_get_style_by_paths       (GtkSettings *settings,
                                             const char *widget_path,
                                             const char *class_path,
                                             GType type);

Creates up a GtkStyle from styles defined in a RC file by providing the raw components used in matching. This function may be useful when creating pseudo-widgets that should be themed like widgets but don't actually have corresponding GTK+ widgets. An example of this would be items inside a GNOME canvas widget.

The action of gtk_rc_get_style() is similar to:

 gtk_widget_path (widget, NULL, &path, NULL);
 gtk_widget_class_path (widget, NULL, &class_path, NULL);
 gtk_rc_get_style_by_paths (gtk_widget_get_settings (widget), path, class_path,
                            G_OBJECT_TYPE (widget));

gtk_rc_add_widget_name_style ()

void        gtk_rc_add_widget_name_style    (GtkRcStyle *rc_style,
                                             const gchar *pattern);

Adds a GtkRcStyle that will be looked up by a match against the widget's pathname. This is equivalent to a: widget PATTERN style STYLE statement in a RC file.

gtk_rc_add_widget_class_style ()

void        gtk_rc_add_widget_class_style   (GtkRcStyle *rc_style,
                                             const gchar *pattern);

Adds a GtkRcStyle that will be looked up by a match against the widget's class pathname. This is equivalent to a: widget_class PATTERN style STYLE statement in a RC file.

gtk_rc_add_class_style ()

void        gtk_rc_add_class_style          (GtkRcStyle *rc_style,
                                             const gchar *pattern);

Adds a GtkRcStyle that will be looked up by a matching against the class hierarchy of the widget. This is equivalent to a: class PATTERN style STYLE statement in a RC file.

gtk_rc_parse ()

void        gtk_rc_parse                    (const gchar *filename);

Parses a given resource file.

gtk_rc_parse_string ()

void        gtk_rc_parse_string             (const gchar *rc_string);

Parses resource information directly from a string.

gtk_rc_reparse_all ()

gboolean    gtk_rc_reparse_all              (void);

If the modification time on any previously read file for the default GtkSettings has changed, discard all style information and then reread all previously read RC files.

gtk_rc_reparse_all_for_settings ()

gboolean    gtk_rc_reparse_all_for_settings (GtkSettings *settings,
                                             gboolean force_load);

If the modification time on any previously read file for the given GtkSettings has changed, discard all style information and then reread all previously read RC files.

gtk_rc_add_default_file ()

void        gtk_rc_add_default_file         (const gchar *filename);

Adds a file to the list of files to be parsed at the end of gtk_init().

gtk_rc_get_default_files ()

gchar**     gtk_rc_get_default_files        (void);

Retrieves the current list of RC files that will be parsed at the end of gtk_init().

gtk_rc_set_default_files ()

void        gtk_rc_set_default_files        (gchar **filenames);

Sets the list of files that GTK+ will read at the end of gtk_init().

gtk_rc_parse_color ()

guint       gtk_rc_parse_color              (GScanner *scanner,
                                             GdkColor *color);

Parses a color in the format expected in a RC file.

gtk_rc_parse_state ()

guint       gtk_rc_parse_state              (GScanner *scanner,
                                             GtkStateType *state);

Parses a GtkStateType variable from the format expected in a RC file.

gtk_rc_parse_priority ()

guint       gtk_rc_parse_priority           (GScanner *scanner,
                                             GtkPathPriorityType *priority);

Parses a GtkPathPriorityType variable from the format expected in a RC file.

gtk_rc_find_module_in_path ()

gchar*      gtk_rc_find_module_in_path      (const gchar *module_file);

Searches for a theme engine in the GTK+ search path. This function is not useful for applications and should not be used.

gtk_rc_find_pixmap_in_path ()

gchar*      gtk_rc_find_pixmap_in_path      (GtkSettings *settings,
                                             GScanner *scanner,
                                             const gchar *pixmap_file);

Looks up a file in pixmap path for the specified GtkSettings. If the file is not found, it outputs a warning message using g_warning() and returns NULL.

gtk_rc_get_module_dir ()

gchar*      gtk_rc_get_module_dir           (void);

Returns a directory in which GTK+ looks for theme engines. For full information about the search for theme engines, see the docs for GTK_PATH in Running GTK+ Applications(3).

gtk_rc_get_im_module_path ()

gchar*      gtk_rc_get_im_module_path       (void);

Obtains the path in which to look for IM modules. See the documentation of the GTK_PATH environment variable for more details about looking up modules. This function is useful solely for utilities supplied with GTK+ and should not be used by applications under normal circumstances.

gtk_rc_get_im_module_file ()

gchar*      gtk_rc_get_im_module_file       (void);

Obtains the path to the IM modules file. See the documentation of the GTK_IM_MODULE_FILE environment variable for more details.

gtk_rc_get_theme_dir ()

gchar*      gtk_rc_get_theme_dir            (void);

Returns the standard directory in which themes should be installed. (GTK+ does not actually use this directory itself.)

gtk_rc_style_new ()

GtkRcStyle* gtk_rc_style_new                (void);

Creates a new GtkRcStyle with no fields set and a reference count of 1.

gtk_rc_style_copy ()

GtkRcStyle* gtk_rc_style_copy               (GtkRcStyle *orig);

Makes a copy of the specified GtkRcStyle. This function will correctly copy an RC style that is a member of a class derived from GtkRcStyle.

gtk_rc_style_ref ()

void        gtk_rc_style_ref                (GtkRcStyle *rc_style);

Increments the reference count of a GtkRcStyle.

gtk_rc_style_unref ()

void        gtk_rc_style_unref              (GtkRcStyle *rc_style);

Decrements the reference count of a GtkRcStyle and frees if the result is 0.