Toc Gallery Index Tree Gtk.Rc

Hierarchy

See Also

Description

This package provides an interface to Gtk's configuration 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.Main.Init. Unless modified, the files looked for will be /gtk-2.0/gtkrc and .gtkrc-2.0 in the users home directory. ( 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.

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 Gtk_Button widgets, but also Gtk_Toggle_Button and Gtk_Check_Button widgets, since those classes derive from Gtk_Button.

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.

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. im_module_file pathname Sets the pathname for the IM modules file. Setting this from RC files is deprecated; you should use the environment variable GTK_IM_MODULE_FILE instead. 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. setting = value 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. See Gtk.Settings.

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_Text, Gtk_Entry, Gtk_List, and Gtk_CList. 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 "" may be used to indicate that the widget should use the same background pixmap as its parent. The special value "" may be used to indicate no background pixmap. font = font 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.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 (see also Gtk.Icon_Factory to learn more about this)

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: , , , , , , , , is an alias for and is an alias for .

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

Types

  • type Gtk_Rc_Style is access all Gtk_Rc_Style_Record'Class;
  • type Gtk_Rc_Style_Record is new Glib.Object.GObject_Record with private;

Subprograms

  • procedure Gtk_New (Rc_Style : out Gtk_Rc_Style);
  • procedure Initialize (Rc_Style : access Gtk_Rc_Style_Record'Class);
  • function Get_Type return Glib.GType;
    Return the internal value associated with Gtk_Rc_Style.
  • function Copy (Orig : access Gtk_Rc_Style_Record) return Gtk_Rc_Style;
    Make a copy of the specified Gtk_Rc.Style. This function will correctly copy an rc style that is a member of a class derived from Gtk_Rc_Style.
  • procedure Add_Default_File (Filename : String);
    Add a file to the list of files to be parsed at the end of Gtk.Main.Init
  • procedure Set_Default_Files (Filenames : Chars_Ptr_Array);
    function Get_Default_Files return Chars_Ptr_Array;
    Set the list of files that GtkAda will read at the end of Gtk.Main.Init
  • function Get_Style (Widget : access Gtk.Widget.Gtk_Widget_Record'Class) return Gtk_Style;
    Find all matching RC styles for a given widget, composites them together, and then create a Gtk_Style representing the composite appearance. (GtkAda actually keeps a cache of previously created styles, so a new style may not be created) Return the resulting style. No refcount is added to the returned style, so if you want to save this style around, you should add a reference yourself.
  • procedure Parse (Filename : String);
    procedure Parse_String (Rc_String : String);
    Parse either a file or a string containing a gtk+ configuration (see the description at the top of this package).
  • function Reparse_All return Boolean;
    If the modification time on any previously read file for the default Gtk_Settings has changed, discard all style information and then reread all previously read RC files. Return True if the files were reread.
  • function Find_Module_In_Path (Module_File : String) return String;
  • function Get_Theme_Dir return String;
    Returns the standard directory in which themes should be installed. (GTK+ does not actually use this directory itself.)
  • function Get_Module_Dir return String;
    Returns a directory in which GTK+ looks for theme engines. This is a dynamic library loaded by gtk+ that will be responsible for drawing parts of the application (ie implement all the functions in Gtk.Style)
  • function Get_Im_Module_Path return String;
    Obtains the path in which to look for IM modules. See the documentation of the GTK_PATH environment variable for more details about looking up modules. This function is useful solely for utilities supplied with GTK+ and should not be used by applications under normal circumstances.
  • function Get_Im_Module_File return String;
    Obtains the path to the IM modules file. See the documentation of the GTK_IM_MODULE_FILE environment variable for more details.
  • function Reparse_All_For_Settings (Settings : access Gtk.Settings.Gtk_Settings_Record'Class; Force_Load : Boolean) return Boolean;
    If the modification time on any previously read file for the given Gtk_Settings has changed, discard all style information and then reread all previously read RC files. If Force_Load is true, the files are reloaded even if unmodified. Return True if some files have been reparsed
  • procedure Reset_Styles (Settings : access Gtk.Settings.Gtk_Settings_Record'Class);
    This function recomputes the styles for all widgets that use a particular Gtk_Settings object. (There is one Gtk_Settings object per Gdk_Screen, see Gtk.Settings.Get_For_Screen); 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 explicitely on them with Gtk.Widget.Set_Style.
  • function Get_Style_By_Paths (Settings : access Gtk.Settings.Gtk_Settings_Record'Class; Widget_Path : String := ""; Class_Path : String := ""; Typ : Glib.GType := Glib.GType_None) return Gtk.Style.Gtk_Style;
    Creates up a Gtk_Style 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 GTK+ widgets. An example of this would be items inside a GNOME canvas widget. Returns null if nothing matching was found and the default style should be used. You must call Ref if you intend to keep a reference on the style.
  • Widget related functions

  • procedure Modify_Style (Widget : access Gtk.Widget.Gtk_Widget_Record'Class; Style : access Gtk_Rc_Style_Record'Class);
    Modifies style values on the widget. Modifications made using this technique take precedence over style values set via an RC file, however, they will be overriden if a style is explicitely set on the widget using gtk_widget_set_style(). The #GtkRcStyle structure is designed so each field can either be set or unset, so it is possible, using this function, to modify some style values and leave the others unchanged.

    Note that modifications made with this function are not cumulative with previous calls to gtk_widget_modify_style() or with such functions as gtk_widget_modify_fg(). If you wish to retain previous values, you must first call gtk_widget_get_modifier_style(), make your modifications to the returned style, then call gtk_widget_modify_style() with that style. On the other hand, if you first call gtk_widget_modify_style(), subsequent calls to such functions gtk_widget_modify_fg() will have a cumulative effect with the initial modifications.

  • function Get_Modifier_Style (Widget : access Gtk.Widget.Gtk_Widget_Record'Class) return Gtk_Rc_Style;
    Return the current modifier style for the widget. (As set by Modify_Style.) If no style has previously set, a new Gtk_Rc_Style will be created with all values unset, and set as the modifier style for the widget. If you make changes to this rc style, you must call Modify_Style, passing in the returned rc style, to make sure that your changes take effect.

    Return value: the modifier style for the widget. This rc style is owned by the widget. If you want to keep a pointer to value this around, you must add a refcount using Ref.

Alphabetical Index