Top | ![]() |
![]() |
![]() |
![]() |
GTK+ provides resource file mechanism for configuring various aspects of the operation of a GTK+ program at runtime.
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+.) 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.
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:
1 |
widget "mywindow.*.GtkEntry" style "my-entry-class" |
attaches the style "my-entry-class"
to all
widgets whose widget path matches the
pattern "mywindow.*.GtkEntry"
.
That is, all GtkEntry widgets which are part of a GtkWindow named
"mywindow"
.
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 path and the class path consist 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.
Since GTK+ 2.10, widget_class
paths can also contain
<classname>
substrings, which are matching
the class with the given name and any derived classes. For instance,
1 |
widget_class "*<GtkMenuItem>.GtkLabel" style "my-style" |
will match GtkLabel widgets which are contained in any kind of menu item.
So, if you have a GtkEntry named "myentry"
, inside of a
horizontal box in a window named "mywindow"
, then the
widget path is: "mywindow.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:
1 |
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):
highest |
rc |
theme |
application |
gtk |
lowest |
rc
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.
Everytime a widget is created and added to the layout hierarchy of a GtkWindow ("anchored" to be exact), a list of matching RC styles out of all RC styles read in so far is composed. For this, every RC style is matched against the widgets class path, the widgets name path and widgets inheritance hierarchy. As a consequence, significant slowdown can be caused by utilization of many RC styles and by using RC style patterns that are slow or complicated to match against a given widget. The following ordered list provides a number of advices (prioritized by effectiveness) to reduce the performance overhead associated with RC style matches:
Move RC styles for specific applications into RC files dedicated to those applications and parse application specific RC files only from applications that are affected by them. This reduces the overall amount of RC styles that have to be considered for a match across a group of applications.
Merge multiple styles which use the same matching rule, for instance:
1 2 3 4 |
style "Foo" { foo_content } class "X" style "Foo" style "Bar" { bar_content } class "X" style "Bar" |
is faster to match as:
1 2 |
style "FooBar" { foo_content bar_content } class "X" style "FooBar" |
Use of wildcards should be avoided, this can reduce the individual RC style match to a single integer comparison in most cases.
To avoid complex recursive matching, specification of full class names
(for class
matches) or full path names (for
widget
and widget_class
matches)
is to be preferred over shortened names
containing "*"
or "?"
.
If at all necessary, wildcards should only be used at the tail or head of a pattern. This reduces the match complexity to a string comparison per RC style.
When using wildcards, use of "?"
should be preferred
over "*"
. This can reduce the matching complexity from
O(n^2) to O(n). For example "Gtk*Box"
can be turned into
"Gtk?Box"
and will still match GtkHBox and GtkVBox.
The use of "*"
wildcards should be restricted as much
as possible, because matching "A*B*C*RestString"
can
result in matching complexities of O(n^2) worst case.
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:
|
Declares a binding set. |
|
Specifies a style or binding set for a particular branch of the inheritance hierarchy. |
|
Parses another file at this point. If
GTK+ also tries to load a locale-specific variant of the included file. |
|
Sets a path (a list of directories separated by colons) that will be searched for theme engines referenced in RC files. |
|
Sets a path (a list of directories separated by colons) that will be searched for pixmaps referenced in RC files. |
|
Sets the pathname for the IM modules file. Setting this from RC files
is deprecated; you should use the environment variable |
|
Declares a style. |
|
Specifies a style or binding set for a particular group of widgets by matching on the widget pathname. |
|
Specifies a style or binding set for a particular group of widgets by matching on the class pathname. |
|
Specifies a value for a setting. Note that settings in RC files are overwritten by system-wide settings (which are managed by an XSettings manager on X11). |
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:
|
Sets the color used for the background of most widgets. |
|
Sets the color used for the foreground of most widgets. |
|
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. |
|
Sets the color used for foreground of widgets using
|
|
Sets the xthickness, which is used for various horizontal padding values in GTK+. |
|
Sets the ythickness, which is used for various vertical padding values in GTK+. |
|
Sets a background pixmap to be used in place of
the |
|
Starting with GTK+ 2.0, the "font" and "fontset" declarations are ignored; use "font_name" declarations instead. |
|
Starting with GTK+ 2.0, the "font" and "fontset" declarations are ignored; use "font_name" declarations instead. |
|
Sets the font for a widget. |
|
Defines the icon for a stock item. |
|
Since 2.10, this element can be used to defines symbolic colors. See below for the syntax of color specifications. |
|
Defines the engine to be used when drawing with this style. |
|
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:
|
A color used for a widget in its normal state. |
|
A variant of the |
|
A color used for widgets in the |
|
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. |
|
A color used for the background of widgets that have
been set insensitive with |
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
{
, where r
, g
,
b
}r
,
g
and b
are either integers in
the range 0-65535 or floats in the range 0.0-1.0.
Since 2.10, colors can also be specified by refering to a symbolic color, as
follows: @color-name
, or by using expressions to combine
colors. The following expressions are currently supported:
mix ( |
Computes a new color by mixing |
shade ( |
Computes a lighter or darker variant of |
lighter ( |
This is an abbreviation for
|
darker ( |
This is an abbreviation for
|
Here are some examples of color expressions:
1 2 3 |
mix (0.5, "red", "blue") shade (1.5, mix (0.3, "#0abbc0", { 0.3, 0.5, 0.9 })) lighter (@foreground) |
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:
1 2 3 4 5 |
stock["my-stock-item"] = { { "itemltr.png", LTR, *, * }, { "itemrtl.png", RTL, *, * } } |
This could be abbreviated as follows:
1 2 3 4 5 |
stock["my-stock-item"] = { { "itemltr.png", LTR }, { "itemrtl.png", RTL } } |
You can specify custom icons for specific sizes, as follows:
1 2 3 4 5 6 |
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:
1 2 3 4 5 6 |
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 allow the user to specify actions to be taken on particular key presses. The form of a binding set declaration is:
1 2 3 4 5 6 7 |
binding <em class="replaceable"><code>name</code></em> { bind <em class="replaceable"><code>key</code></em> { <em class="replaceable"><code>signalname</code></em> (<em class="replaceable"><code>param</code></em>, ...) ... } ... } |
key
is a string consisting of a
series of modifiers followed by the name of a key. The
modifiers can be:
<alt> |
<ctl> |
<control> |
<meta> |
<hyper> |
<super> |
<mod1> |
<mod2> |
<mod3> |
<mod4> |
<mod5> |
<release> |
<shft> |
<shift> |
<shft>
is an alias for
<shift>
,
<ctl>
is an alias for
<control>
,
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.