Resource Files
Routines for handling resource files
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
<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
or options when
configuring GTK+.) Note that although the filenames contain the version
number 2.0, all 2.x versions of GTK+ look for these files.
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 class 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.
Additionally, a priority can be specified for each pattern, and styles
override other styles first by priority, then by pattern type and then
by order of specification (later overrides earlier). The priorities
that can be specified are (highest to lowest):
highestrcthemeapplicationgtklowestrc is the default for styles
read from an RC file, theme
is the default for styles read from theme RC files,
application
should be used for styles an application sets
up, and gtk is used for styles
that GTK+ creates internally.
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
{ ... }Declares a binding set.class pattern
[ style | binding ][ : priority ]
nameSpecifies a style or binding set for a particular
branch of the inheritance hierarchy.include filenameParses another file at this point. If
filename is not an absolute filename,
it is searched in the directories of the currently open RC files.
GTK+ also tries to load a
locale-specific variant of
the included file.
module_path pathSets a path (a list of directories separated
by colons) that will be searched for theme engines referenced in
RC files.pixmap_path pathSets a path (a list of directories separated
by colons) that will be searched for pixmaps referenced in
RC files.style name [ =
parent ] { ... }Declares a style.widget pattern
[ style | binding ][ : priority ]
nameSpecifies a style or binding set for a particular
group of widgets by matching on the widget pathname.widget_class pattern
[ style | binding ][ : priority ]
nameSpecifies 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 class declarations.
Within each type of declaration, later declarations override
earlier ones.
Within a style declaration, the possible
elements are:
bg[state] =
color
Sets the color used for the background of most widgets.
fg[state] =
color
Sets the color used for the foreground of most widgets.
base[state] =
color
Sets the 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
Sets the color used for foreground of widgets using
base for the background color.
xthickness =
number
Sets the xthickness, which is used for various horizontal padding
values in GTK+.
ythickness =
number
Sets the ythickness, which is used for various vertical padding
values in GTK+.
bg_pixmap[state] =
pixmap
Sets a background pixmap to be used in place of
the bg color (or for #GtkText,
in place of the base color. The special
value "<parent>" may be used to indicate that the widget should
use the same background pixmap as its parent. The special value
"<none>" may be used to indicate no background pixmap.
font = font
Starting with GTK+ 2.0, the "font" and "fontset"
declarations are ignored; use "font_name" declarations instead.
fontset = font
Starting with GTK+ 2.0, the "font" and "fontset"
declarations are ignored; use "font_name" declarations instead.
font_name = font
Sets the font for a widget. font must be
a Pango font name, e.g. "Sans Italic 10".
For details about Pango font names, see
pango_font_description_from_string().
stock["stock-id"] = { icon source specifications }
Defines the icon for a stock item.
engine "engine" { engine-specific
settings }
Defines the engine to be used when drawing with this style.
class::property = value
Sets a style property for a widget class.
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 items in a list widget, and the
selection in an editable widget.
INSENSITIVE
A color used for the background of widgets that have
been set insensitive with gtk_widget_set_sensitive().
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-65535 or floats in the range 0.0-1.0.
In a stock definition, icon sources are specified as a
4-tuple of image filename or icon name, text direction, widget state, and size, in that
order. Each icon source specifies an image filename or icon name to use with a given
direction, state, and size. Filenames are specified as a string such
as "itemltr.png", while icon names (looked up
in the current icon theme), are specified with a leading
@, such as @"item-ltr".
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:
<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 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 difference: Binding sets override other binding sets first
by pattern type, then by priority and then by order of specification.
The priorities that can be specified and their default values are the
same as for styles.
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.
@name:
@bg_pixmap_name:
@font_desc:
@color_flags:
@fg:
@bg:
@text:
@base:
@xthickness:
@ythickness:
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.
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_TOKEN_INVALID:
@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:
@Returns:
@widget:
@Returns:
@settings:
@widget_path:
@class_path:
@type:
@Returns:
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.
@rc_style: the #GtkRcStyle to use for widgets matching @pattern
@pattern: the 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.
@rc_style: the #GtkRcStyle to use for widgets matching @pattern
@pattern: the 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.
@rc_style: the #GtkRcStyle to use for widgets deriving from @pattern
@pattern: the pattern
Parses a given resource file.
@filename: the filename of a file to parse. If @filename is not absolute, it
is searched in the current directory.
Parses resource information directly from a string.
@rc_string: a string to parse.
@Returns:
@settings:
@force_load:
@Returns:
@settings:
@filename:
@Returns:
@filenames:
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 succeeded, otherwise the token
that was expected but not found.
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 succeeded, otherwise the token
that was expected but not found.
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 succeeded, otherwise the token
that was expected but not found.
@module_file: The name of the module to search for.
@Returns:
@settings:
@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.
@context:
@Returns:
@Returns:
@Returns:
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()).
Creates a new #GtkRcStyle with no fields set and
a reference count of 1.
@Returns: the newly-created #GtkRcStyle
@orig:
@Returns:
Increments the reference count of a #GtkRcStyle.
@rc_style: a #GtkRcStyle
Decrements the reference count of a #GtkRcStyle and
frees if the result is 0.
@rc_style: a #GtkRcStyle