GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# Resource Files

## Name

Resource Files -- Routines for handling resource files

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkRcStyle;
    enum        GtkRcFlags;
    GdkPixmap*  (*GtkImageLoader)               (GdkWindow *window,
                                                 GdkColormap *colormap,
                                                 GdkBitmap **mask,
                                                 GdkColor *transparent_color,
                                                 const gchar *filename);
    enum        GtkRcTokenType;
    GtkStyle*   gtk_rc_get_style                (GtkWidget *widget);
    void        gtk_rc_add_widget_name_style    (GtkRcStyle *rc_style,
                                                 const gchar *pattern);
    void        gtk_rc_add_widget_class_style   (GtkRcStyle *rc_style,
                                                 const gchar *pattern);
    void        gtk_rc_add_class_style          (GtkRcStyle *rc_style,
                                                 const gchar *pattern);
    void        gtk_rc_parse                    (const gchar *filename);
    void        gtk_rc_parse_string             (const gchar *rc_string);
    gboolean    gtk_rc_reparse_all              (void);
    void        gtk_rc_add_default_file         (const gchar *filename);
    gchar**     gtk_rc_get_default_files        (void);
    void        gtk_rc_set_default_files        (gchar **filenames);
    guint       gtk_rc_parse_color              (GScanner *scanner,
                                                 GdkColor *color);
    guint       gtk_rc_parse_state              (GScanner *scanner,
                                                 GtkStateType *state);
    guint       gtk_rc_parse_priority           (GScanner *scanner,
                                                 GtkPathPriorityType *priority);
    gchar*      gtk_rc_find_module_in_path      (const gchar *module_file);
    gchar*      gtk_rc_find_pixmap_in_path      (GScanner *scanner,
                                                 const gchar *pixmap_file);
    gchar*      gtk_rc_get_module_dir           (void);
    gchar*      gtk_rc_get_theme_dir            (void);
    void        gtk_rc_set_image_loader         (GtkImageLoader loader);
    GdkPixmap*  gtk_rc_load_image               (GdkColormap *colormap,
                                                 GdkColor *transparent_color,
                                                 const gchar *filename);
    GtkRcStyle* gtk_rc_style_new                (void);
    void        gtk_rc_style_ref                (GtkRcStyle *rc_style);
    void        gtk_rc_style_unref              (GtkRcStyle *rc_style);

    void        gtk_rc_init                     (void);

## Description

GTK+ provides resource file mechanism for configuring various aspects of the operation of a GTK+ program at runtime.

### 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 `.gtkrc` in the users home directory, and `$localstatedir/gtk/gtkrc` (`$localstatedir` defaults to `/usr/local/etc`).

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().

For each default file, in addition to the file itself, GTK+ will look for a locale-specific file that will be parsed in addition to 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.ujis`, `~/.gtkrc.ja_JP`, and `~/.gtkrc.ja`, and parses the first one it finds.

### 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 heirarchy. 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 heirarchy (not the layout heirarchy) 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:

`binding `name` { ... }`

  Declare a binding set

`class `pattern` [ style | binding [ : `priority` ]] `name``

  Specify a style or binding set for a particular branch of the inheritance heirarchy.

`include `filename``

  Parse another file at this point

`module_path `path>``

  Sets a path (a list of directories separated by colons) that will be searched for theme engines referenced in RC files.

`pixmap_path `path>``

  Sets a path (a list of directories separated by colons) that will be searched for pixmaps referenced in RC files.

`style `name` [ = `parent` ] { ... }`

  Declare a style

`widget `pattern` [ style | binding [ : `priority` ]] `name``

  Specify a style or binding set for a particular group of widgets by matching on the widget pathname.

`widget_class `pattern` [ style | binding [ : `priority` ]] `name``

  Specify a style or binding set for a particular group of widgets by matching on the class pathname.

### 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 `widget` declarations. Within each type of declaration, later declarations override earlier ones.

Within a `style` declaration, the possible elements are:

`bg[`state`] = `color``

  Set color used for the background of most widgets.

`fg[`state`] = `color``

  Set color used for the foreground of most widgets.

`base[`state`] = `color``

  Set color used for the background of widgets displaying editable text. This color is used for the background of, among others, GtkText, GtkEntry, GtkList, and GtkClist.

`text[`state`] = `color``

  Set color used for foreground of widgets using `base` for the background color.

`bg_text[`state`] = `color``

  Set a background pixmap to be used in place of the `bg` color (or for GtkText, in place of the `base` color.

`font = `font``

  Set the font for a widget.

`fontset = `font``

  Set the fontset for a widget. Overrides any `font` declarations.

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

`NORMAL`

  A color used for a widget in its normal state

`ACTIVE`

  A variant of the `NORMAL` color used when the widget is in the `GTK_STATE_ACTIVE` state, and also for the trough of a ScrollBar, tabs of a NoteBook other than the current tab and similar areas. Frequently, this should be a darker variant of the `NORMAL` color.

`PRELIGHT`

  A color used for widgets in the `GTK_STATE_PRELIGHT` state. This state is the used for Buttons and MenuItems that have the mouse cursor over them, and for their children.

`SELECTED`

  A color used to highlight data selected by the user. for instance, the selected ListItems in a List widget, and the selection in an Editable widget.

`INSENSITIVE`

  A color used for the background of widgets that have been set insenstivie with gtk_widget_set_senstive()

Colors can be specified as a string `"#rrrrggggbbbb"`, `"#rrrgggbbb"`, `"#rrggbb"`, or `"#rgb"`, where `r` `g`, and `b` are hex digits, or they can be specified as a triplet of floats `{ `r`, `g`, `b`}`.

### 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:

`<alt>`
`<control>`
`<mod1>`
`<mod2>`
`<mod3>`
`<mod4>`
`<mod5>`
`<release>`
`<shft>`
`<shift>`

`<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 gtk_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):

`HIGHEST`
`RC`
`APPLICATION`
`GTK`
`LOWEST`

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

## Details

### struct GtkRcStyle

    struct GtkRcStyle
    {
      gchar *name;
      gchar *font_name;
      gchar *fontset_name;
      gchar *bg_pixmap_name[5];

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

      GtkThemeEngine *engine;
      gpointer        engine_data;

      /* Private */
      guint ref_count;
    };

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.

`GTK_RC_FG`

  If present, the foreground color has been set for this state.

`GTK_RC_BG`

  If present, the background color has been set for this state.

`GTK_RC_TEXT`

  If present, the text color has been set for this state.

`GTK_RC_BASE`

  If present, the base color has been set for this state.

### GtkImageLoader ()

    GdkPixmap*  (*GtkImageLoader)               (GdkWindow *window,
                                                 GdkColormap *colormap,
                                                 GdkBitmap **mask,
                                                 GdkColor *transparent_color,
                                                 const gchar *filename);

A GtkImageLoader is used to load a filename found in a RC file.

`window` : | the window for creating image
`colormap` : | the colormap for this image
`mask` : | a pointer to the location to store the mask
`transparent_color` : | the transparent color for the image
`filename` : | filename to load
Returns : | a GtkPixmap representing `filename`

### 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_BASE,
      GTK_RC_TOKEN_TEXT,
      GTK_RC_TOKEN_FONT,
      GTK_RC_TOKEN_FONTSET,
      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_RC,
      GTK_RC_TOKEN_HIGHEST,
      GTK_RC_TOKEN_ENGINE,
      GTK_RC_TOKEN_MODULE_PATH,
      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_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.)

`widget` : | a GtkWidget
Returns : | the resulting style. The caller should reference the result, since GTK+ will retain the initial reference count itself for the cache of created styles.

### gtk_rc_add_widget_name_style ()

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

Add a RcStyle 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.

`rc_style` : | the GtkRcStyle to use for widgets matching `pattern`
`pattern` : | the pattern

### gtk_rc_add_widget_class_style ()

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

Add a RcStyle 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.

`rc_style` : | the GtkRcStyle to use for widgets matching `pattern`
`pattern` : | the pattern

### gtk_rc_add_class_style ()

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

Add a RcStyle that will be looked up by a matching against the class heirarchy of the widget. This is equivalent to a:

    class PATTERN style STYLE

statement in a RC file.

`rc_style` : | the GtkRcStyle to use for widgets deriving from `pattern`
`pattern` : | the pattern

### gtk_rc_parse ()

    void        gtk_rc_parse                    (const gchar *filename);

Parse a given resource file.

`filename` : | the filename of a file to parse.

### gtk_rc_parse_string ()

    void        gtk_rc_parse_string             (const gchar *rc_string);

Parse resource information directly from a string.

`rc_string` : | a string to parse.

### gtk_rc_reparse_all ()

    gboolean    gtk_rc_reparse_all              (void);

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

Returns : | `TRUE` if the files were reread.

### 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().

`filename` : | the pathname to the file.

### 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()

Returns : | A NULL terminated array of filenames. This memory is owned by GTK+ and must not be freed by the application. If you want to store this information, you should make a copy.

### 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()

`filenames` : | A `NULL` terminated list of filenames.

### gtk_rc_parse_color ()

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

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

`scanner` : | a GtkScanner
`color` : | a pointer to a GtkColor structure in which to store the result
Returns : | `G_TOKEN_NONE` if parsing suceeded, otherwise the token that was expected but not found.

### 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.

`scanner` : | a GtkScanner (must be initialized for parsing an RC file)
`state` : | A pointer to a GtkStateType variable in which to store the result.
Returns : | `G_TOKEN_NONE` if parsing suceeded, otherwise the token that was expected but not found.

### 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.

`scanner` : | a GtkScanner (must be initialized for parsing an RC file)
`priority` : | A pointer to GtkPathPriorityType variable in which to store the result.
Returns : | `G_TOKEN_NONE` if parsing suceeded, otherwise the token that was expected but not found.

### gtk_rc_find_module_in_path ()

    gchar*      gtk_rc_find_module_in_path      (const gchar *module_file);

Looks up a file in the current module path.

`module_file` : | The name of the module to search for.
Returns : | The filename, if found. (Must be freed with g_free()), otherwise `NULL`.

### gtk_rc_find_pixmap_in_path ()

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

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

`scanner` : | a GtkScanner. Used for printing out warning messages if the file is not found.
`pixmap_file` : | The name of the file to search for.
Returns : | The filename, if found. (Must be freed with g_free()), otherwise `NULL`.

### gtk_rc_get_module_dir ()

    gchar*      gtk_rc_get_module_dir           (void);

Returns the directory in which GTK+ will look for theme engines.

Returns : | The directory. (Must be freed with g_free())

### 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.)

Returns : | The directory. (Must be freed with g_free())

### gtk_rc_set_image_loader ()

    void        gtk_rc_set_image_loader         (GtkImageLoader loader);

Sets the function that GTK+ will use to load images

`loader` : | the GtkImageLoader to use

### gtk_rc_load_image ()

    GdkPixmap*  gtk_rc_load_image               (GdkColormap *colormap,
                                                 GdkColor *transparent_color,
                                                 const gchar *filename);

Internal function. Loads an image using the current image loader.

`colormap` : | the colormap to use for the image
`transparent_color` : | the transparent color for the image
`filename` : | the filename of the image file
Returns : | a GtkPixmap representing `filename`

### gtk_rc_style_new ()

    GtkRcStyle* gtk_rc_style_new                (void);

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

Returns : | the newly create GtkRcStyle

### gtk_rc_style_ref ()

    void        gtk_rc_style_ref                (GtkRcStyle *rc_style);

Increment the reference count of a GtkRcStyle.

`rc_style` : | a GtkRcStyle

### gtk_rc_style_unref ()

    void        gtk_rc_style_unref              (GtkRcStyle *rc_style);

Decrement the reference count of a GtkRcStyle and free if the result is 0.

`rc_style` : | a GtkRcStyle

### gtk_rc_init ()

    void        gtk_rc_init                     (void);

Internal function.

<<< Previous Page | Home | Up | Next Page >>>
Themes | Keyboard Accelerators