
@c %start of fragment

@node Resource Files
@chapter Resource Files
Routines for handling resource files

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

@section Default files
An application can cause GTK+ to parse a specific RC file by calling
@code{gtk-rc-parse}. In addition to this, certain files will be read at the end
of @code{gtk-init}. Unless modified, the files looked for will be
@file{<SYSCONFDIR>/gtk-2.0/gtkrc} and @file{.gtkrc-2.0} in the users home
directory. (@file{<SYSCONFDIR>} defaults to @file{/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 @dfn{default} files can be retrieved with
@code{gtk-rc-get-default-files} and modified with @code{gtk-rc-add-default-file}
and @code{gtk-rc-set-default-files}. Additionally, the @env{GTK2_RC_FILES}
environment variable can be set to a @code{<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
@env{LANG} is set to @samp{ja_JP.ujis}, when loading the default file
@file{~/.gtkrc} then GTK+ looks for @file{~/.gtkrc.ja_JP} and
@file{~/.gtkrc.ja}, and parses the first of those that exists.

@section 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 @samp{widget},
@samp{widget_class}, and @samp{class} declarations. As an example of such a
statement: attaches the style @samp{"my-entry-class"} to all widgets whose
@dfn{widget path} matches the @dfn{pattern}@samp{"mywindow.*.GtkEntry"}. That
is, all @code{<gtk-entry>} widgets which are part of a @code{<gtk-window>} named
@samp{"mywindow"}.

@example 

widget "mywindow.*.GtkEntry" style "my-entry-class"
@end example

The patterns here are given in the standard shell glob syntax. The @samp{"?"}
wildcard matches any character, while @samp{"*"} matches zero or more of any
character. The three types of matching are against the widget path, the
@dfn{class path} and the class hierarchy. Both the widget path and the class
path consist of a @samp{"."} 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 @code{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,@samp{widget_class} paths can also contain @samp{<classname>}
substrings, which are matching the class with the given name and any derived
classes. For instance, will match @code{<gtk-label>} widgets which are contained
in any kind of menu item.

@example 

widget_class "*<GtkMenuItem>.GtkLabel" style "my-style"
@end example

So, if you have a @code{<gtk-entry>} named @samp{"myentry"}, inside of a
horizontal box in a window named @samp{"mywindow"}, then the widget path is:
@samp{"mywindow.GtkHBox.myentry"} while the class path is:
@samp{"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: will match not just @code{<gtk-button>} widgets, but
also @code{<gtk-toggle-button>} and @code{<gtk-check-button>} widgets, since
those classes derive from @code{<gtk-button>}.

@example 

class "GtkButton" style "my-style"
@end example

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): @samp{rc} is the default for styles read from an RC
file, @samp{theme} is the default for styles read from theme RC files,
@samp{application} should be used for styles an application sets up, and
@samp{gtk} is used for styles that GTK+ creates internally.

@section Optimizing RC Style Matches
Everytime a widget is created and added to the layout hierarchy of a
@code{<gtk-window>} ("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:

@enumerate 
@item
@item
@item
@item
@item
@item
@item
@end enumerate

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: is faster
to match as:

@example 

     style "Foo" @{ foo_content @}
     class "X" style "Foo"
     style "Bar" @{ bar_content @}
     class "X" style "Bar"
@end example

@example 

     style "FooBar" @{ foo_content bar_content @}
     class "X" style "FooBar"
@end example

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
@samp{class} matches) or full path names (for @samp{widget} and
@samp{widget_class} matches) is to be preferred over shortened names containing
@samp{"*"} or @samp{"?"}.

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 @samp{"?"} should be preferred over @samp{"*"}.
This can reduce the matching complexity from O(n^2) to O(n). For example
@samp{"Gtk*Box"} can be turned into @samp{"Gtk?Box"} and will still match
@code{<gtk-hbox>} and @code{<gtk-vbox>}.

The use of @samp{"*"} wildcards should be restricted as much as possible,
because matching @samp{"A*B*C*RestString"} can result in matching complexities
of O(n^2) worst case.

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

The possible toplevel declarations are:

@table @var
@item class  
          [ style | binding ][ :  ]
          

@c %start of fragment


@c %end of fragment
@item include 

@c %start of fragment


@c %end of fragment
@item module_path 

@c %start of fragment


@c %end of fragment
@item pixmap_path 

@c %start of fragment


@c %end of fragment
@item im_module_file 

@c %start of fragment


@c %end of fragment
@item style  [ =
     ] @{ ... @}

@c %start of fragment


@c %end of fragment
@item widget  
          [ style | binding ][ :  ]
          

@c %start of fragment


@c %end of fragment
@item widget_class  
          [ style | binding ][ :  ]
          

@c %start of fragment


@c %end of fragment
@item 

@c %start of fragment


@c %end of fragment
@end table

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

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 @env{GTK_IM_MODULE_FILE}
instead.

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

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

Within a @samp{style} declaration, the possible elements are:

@table @var
@item fg[] =
      

@c %start of fragment


@c %end of fragment
@item base[] =
      

@c %start of fragment


@c %end of fragment
@item text[] =
      

@c %start of fragment


@c %end of fragment
@item xthickness =
      

@c %start of fragment


@c %end of fragment
@item ythickness =
      

@c %start of fragment


@c %end of fragment
@item bg_pixmap[] =
      

@c %start of fragment


@c %end of fragment
@item font = 

@c %start of fragment


@c %end of fragment
@item fontset = 

@c %start of fragment


@c %end of fragment
@item font_name = 

@c %start of fragment


@c %end of fragment
@item stock[] = @{  @}

@c %start of fragment


@c %end of fragment
@item color[] = 

@c %start of fragment


@c %end of fragment
@item engine  @{  @}

@c %start of fragment


@c %end of fragment
@item :: = 

@c %start of fragment


@c %end of fragment
@end table

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, @code{<gtk-text>},
@code{<gtk-entry>}, @code{<gtk-list>}, and @code{<gtk-clist>}.

Sets the color used for foreground of widgets using @samp{base} for the
background color.

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 @samp{bg} color (or for
@code{<gtk-text>}, in place of the @samp{base} color. The special value
@samp{"<parent>"} may be used to indicate that the widget should use the same
background pixmap as its parent. The special value @samp{"<none>"} may be used
to indicate no background pixmap.

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. must be a Pango font name, e.g. @samp{"Sans Italic
10"}. For details about Pango font names, see
@code{pango-font-description-from-string}.

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:

@table @var
@item ACTIVE

@c %start of fragment


@c %end of fragment
@item PRELIGHT

@c %start of fragment


@c %end of fragment
@item SELECTED

@c %start of fragment


@c %end of fragment
@item INSENSITIVE

@c %start of fragment


@c %end of fragment
@end table

A color used for a widget in its normal state.

A variant of the @samp{NORMAL} color used when the widget is in the
@samp{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 @samp{NORMAL} color.

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

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
@code{gtk-widget-set-sensitive}.

Colors can be specified as a string containing a color name (GTK+ knows all
names from the X color database @file{/usr/lib/X11/rgb.txt}), in one of the
hexadecimal forms @samp{&#x0023;rrrrggggbbbb}, @samp{&#x0023;rrrgggbbb},
@samp{&#x0023;rrggbb}, or @samp{&#x0023;rgb}, where @samp{r}, @samp{g} and
@samp{b} are hex digits, or they can be specified as a triplet @samp{@{ , , @}},
where @samp{r}, @samp{g} and @samp{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: @samp{@@color-name}, or by using expressions to combine colors. The
following expressions are currently supported:

@table @var
@item shade (

@c %start of fragment


@c %end of fragment
@item lighter (

@c %start of fragment


@c %end of fragment
@item darker (

@c %start of fragment


@c %end of fragment
@end table

Computes a new color by mixing and . The determines how close the new color is
to . A factor of 1.0 gives pure , a factor of 0.0 gives pure .

Computes a lighter or darker variant of . A of 1.0 leaves the color unchanged,
smaller factors yield darker colors, larger factors yield lighter colors.

This is an abbreviation for @samp{shade (1.3, )}.

This is an abbreviation for @samp{shade (0.7, )}.

Here are some examples of color expressions:

@example 
  
 mix (0.5, "red", "blue")
 shade (1.5, mix (0.3, "&#x0023;0abbc0", @{ 0.3, 0.5, 0.9 @}))
 lighter (@@foreground)
@end example

In a @samp{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
@samp{"itemltr.png"}, while icon names (looked up in the current icon theme),
are specified with a leading @samp{@@}, such as @samp{@@"item-ltr"}. The
@samp{*} character can be used as a wildcard, and if direction/state/size are
omitted they default to @samp{*}. So for example, the following specifies
different icons to use for left-to-right and right-to-left languages: This could
be abbreviated as follows:

@example 

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

@example 

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

You can specify custom icons for specific sizes, as follows: The sizes that come
with GTK+ itself are @samp{"gtk-menu"}, @samp{"gtk-small-toolbar"},
@samp{"gtk-large-toolbar"}, @samp{"gtk-button"}, @samp{"gtk-dialog"}.
Applications can define other sizes.

@example 

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

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

@example 

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

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
@samp{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.

@section 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:

@example 

binding  @{
  bind  @{ 
     (, ...)
    ...
  @}
  ...
@}
@end example

is a string consisting of a series of modifiers followed by the name of a key.
The modifiers can be: @samp{<shft>} is an alias for @samp{<shift>}, @samp{<ctl>}
is an alias for @samp{<control>}, and @samp{<alt>} is an alias for
@samp{<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
@code{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.

@section Usage
@include defuns-gtkrc.xml.texi

@c %end of fragment
