widget "mywindow.*.GtkEntry" style "my-entry-class"

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

module_path pat

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.

C.1.2. Pathnames and patterns

Keep the following in mind when attaching a style to a widget, widget_class, or a class.

• Patterns are given in the standard shell glob syntax. The "?" wildcard matches any character, while "*" matches zero or more of any character.

• Matching are against one of the following:

  • The widget path.(widget)

  • The class path.(widget_class)

  • The class hierarchy.(class)

• Both the widget and the class paths consists of a "." separated list of all the parents of the widget and also the widget itself. This start with outermost to innermost.

• The difference is that in the widget path, the name assigned by set_name method of the Gtk2::Widget class, 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 Gtk2::Entry named "myentry", inside of a of a Gtk2::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 Gtk2::Button widgets, but also Gtk2::ToggleButton and Gtk2::CheckButton widgets, since those classes derive from Gtk2::Button.

C.1.3. Creating a style

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, Gtk2::TextView, Gtk2::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 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.

	 
text[state] = color

Sets the color used for foreground of widgets using base for the background color.

	 
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.

Widget States:

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 the set_sensitive method of the Gtk2::Widget class.

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

C.1.4. Creating a binding

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

Here is a sample:

binding "test2"
{
  bind "<ctrl>1" {
    "debug-msg" ("jup!") 
  }
}

class "GtkButton" binding : highest "test2" # override "rc" priority