gtk.RcStyle
Prev | The gtk Class Reference | Next

## gtk.RcStyle

gtk.RcStyle — an object holding resource styles

## Synopsis

    class gtk.RcStyle(gobject.GObject):
        def copy()

    Functions

        def gtk.rc_add_default_file(filename)
        def gtk.rc_set_default_files(filenames)
        def gtk.rc_get_default_files()
        def gtk.rc_get_style_by_paths(settings, widget_path, class_path, type)
        def gtk.rc_reparse_all_for_settings(settings, force_load)
        def gtk.rc_reset_styles(settings)
        def gtk.rc_parse(filename)
        def gtk.rc_parse_string(rc_string)
        def gtk.rc_reparse_all()
        def gtk.rc_find_module_in_path(module_file)
        def gtk.rc_get_theme_dir()
        def gtk.rc_get_module_dir()
        def gtk.rc_get_im_module_path()
        def gtk.rc_get_im_module_file()

## Ancestry

    +-- gobject.GObject
      +-- gtk.RcStyle

## gtk.RcStyle Signal Prototypes

gobject.GObject Signal Prototypes

## Description

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

## Default files

An application can cause `GTK+` to parse a specific RC file by calling the `gtk.rc_parse`() function. In addition to this, certain files will be read at the end of `GTK+` initialization. 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`.) The set of these default files can be retrieved with the `gtk.rc_get_default_files`() function and modified with the `gtk.rc_add_default_file`() and `gtk.rc_set_default_files`() functions. Additionally, the `GTK_RC_FILES` environment variable can be set to a 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 the `set_name`() method 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 `gtk.Entry` 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 `gtk.Button` widgets, but also `gtk.ToggleButton` and `gtk.CheckButton` widgets, since those classes derive from `gtk.Button`.

## 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 ]] `name` | Specifies a style or binding set for a particular branch of the inheritance hierarchy.
include `filename` | Parses 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 `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` ] { ... } | Declares a style.
widget `pattern` [ style | binding [ : priority ]] `name` | Specifies a style or binding set for a particular group of widgets by matching on the widget pathname.
widget_class `pattern` [ style | binding [ : priority ]] `name` | Specifies 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, `gtk.TextView` and `gtk.Entry`.
text[`state`] = `color` | Sets the color used for foreground of widgets using `base` for the background color.
bg_pixmap[`state`] = `pixmap` | Sets a background pixmap to be used in place of the `bg` color (or for `gtk.TextView`, 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` | Sets the font for a widget. font must be a XLFD font description, e.g. "-*-helvetica-medium-r-normal--10-*-*-*-*-*-*-*".
fontset = `font` | Sets the fontset for a widget. Overrides any font declarations. font must be a comma-separated list of XLFD font descriptions, e.g. "-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240, -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120, -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240, -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150".
font_name = `font` | Sets the font for a widget. Overrides any `font` or `fontset` declarations. `font` must be a Pango font name, e.g. "Sans Italic 10".
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 `gtk.Scrollbar`, tabs of a `gtk.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 `gtk.Button` and `gtk.MenuItem` widgets 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 the `set_sensitive`() method.

Colors can be specified as a string containing a color name (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:

- <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. 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
- theme
- application
- gtk
- 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.

## Methods

### gtk.RcStyle.copy

        def copy()

Returns : | a new `gtk.RcStyle` that is a copy of the rcstyle

The copy() method returns a new `gtk.RcStyle` that is a copy of the RC style. This method will correctly copy an RC style that is a member of a class derived from `gtk.RcStyle`.

## Functions

### gtk.rc_add_default_file

        def gtk.rc_add_default_file(filename)

`filename` : | the name of a file containing resource data

The `gtk.rc_add_default_file`() function adds the file specified by `filename` to the list of files to be parsed for resource data.

### gtk.rc_set_default_files

        def gtk.rc_set_default_files(filenames)

`filenames` : | a list of filenames

The `gtk.rc_set_default_files`() function sets the list of files (specified by `filenames`) that will be parsed for resource information.

### gtk.rc_get_default_files

        def gtk.rc_get_default_files()

Returns : | the current list of resource files

The `gtk.rc_get_default_files`() function returns a list of filenames (as set by the `gtk.rc_set_default_files`() function) that will be parsed for resource data.

### gtk.rc_get_style_by_paths

        def gtk.rc_get_style_by_paths(settings, widget_path, class_path, type)

`settings` : | a `gtk.Settings` object
`widget_path` : | the widget path to use when looking up the style
`class_path` : | the class path to use when looking up the style
`type` : | a type that will be used along with parent types of this type when matching against class styles, or `gobject.TYPE_NONE`
Returns : | a `gtk.Style` created by matching with the supplied paths, or `None` if nothing matching was specified and the default style should be used.

The `gtk.rc_get_style_by_paths`() function returns a `gtk.Style` created 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 `PyGTK` widgets. An example of this would be items inside a `GNOME` canvas widget.

### gtk.rc_reparse_all_for_settings

        def gtk.rc_reparse_all_for_settings(settings, force_load)

`settings` : | a `gtk.Settings` object
`force_load` : | if `True` reparse the RC files even if they haven't changed
Returns : | `True` if the files were reparsed

The `gtk.rc_reparse_all_for_settings`() function reparses the files associated with the `gtk.Settings` object specified by `settings` if any of the files have changed and `force_load` is `False` and . If `force_load` is `True` the files are always reparsed.

### gtk.rc_reset_styles

        def gtk.rc_reset_styles(settings)

`settings` : | a `gtk.Settings` object
Returns : | a `gtk.Style`

### Note

This function is available in PyGTK 2.4 and above.

The `gtk.rc_reset_styles`() function returns a `gtk.Style`. This function computes the styles for all widgets that use the `gtk.Settings` object specified by `settings`. (There is one `gtk.Settings` object per `gtk.gdk.Screen`, see the `gtk.settings_get_for_screen`() function). It is useful when some global parameter has changed that affects the appearance of all widgets, because when a widget gets a new style, it will both redraw and recompute any cached information about its appearance. As an example, it is used when the default font size set by the operating system changes. Note that this function doesn't affect widgets that have a style set explicitly on them with the `gtk.Widget.set_style`() method.

### gtk.rc_parse

        def gtk.rc_parse(filename)

`filename` : | the name of a file to parse for resource data

The `gtk.rc_parse`() function parses the file specified by `filename` for resource data.

### gtk.rc_parse_string

        def gtk.rc_parse_string(rc_string)

`rc_string` : | a string to parse for resource data

The `gtk.rc_parse_string`() function parses the string specified by `rc_string` for resource data.

### gtk.rc_reparse_all

        def gtk.rc_reparse_all()

Returns : | `True` if the files were reparsed.

The `gtk.rc_reparse_all`() function discards all style data and reparses all the RC files for resource data if any of them have changed.

### gtk.rc_find_module_in_path

        def gtk.rc_find_module_in_path(module_file)

`module_file` : | the name of a theme engine
Returns : | the filename of the theme engine or `None`

The `gtk.rc_find_module_in_path`() function searches for a theme engine named by `module_file`. This function is not useful for applications and should not be used.

### gtk.rc_get_theme_dir

        def gtk.rc_get_theme_dir()

Returns : | the name of the themes directory

The `gtk.rc_get_theme_dir`() function returns the name of the directory where themes should be installed.

### gtk.rc_get_module_dir

        def gtk.rc_get_module_dir()

Returns : | the theme engines directory name

The `gtk.rc_get_module_dir`() function returns the name of the directory where `PyGTK` searches for theme engines.

### gtk.rc_get_im_module_path

        def gtk.rc_get_im_module_path()

Returns : | the IM modules path

The `gtk.rc_get_im_module_path`() function returns the path where `PyGTK` searches for IM modules.

### gtk.rc_get_im_module_file

        def gtk.rc_get_im_module_file()

Returns : | the name of the IM modules file

The `gtk.rc_get_im_module_file`() function returns the name of the `PyGTK` IM modules file.

Prev | Up | Next
gtk.Range | Home | gtk.RecentChooserDialog