Default Files

An application can cause CTK+ to parse a specific RC file by calling ctk_rc_parse(). In addition to this, certain files will be read at the end of ctk_init(). Unless modified, the files looked for will be SYSCONFDIR/ctk-2.0/ctkrc and .ctkrc-3.0 in the users home directory. (SYSCONFDIR defaults to /usr/local/etc. It can be changed with the --prefix or --sysconfdir options when configuring CTK+.)

The set of these “default” files can be retrieved with ctk_rc_get_default_files() and modified with ctk_rc_add_default_file() and ctk_rc_set_default_files(). Additionally, the CTK2_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.

Locale Specific Files

For each RC file, in addition to the file itself, CTK+ 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 ~/.ctkrc then CTK+ looks for ~/.ctkrc.ja_JP and ~/.ctkrc.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:

1

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

attaches the style "my-entry-class" to all widgets whose “widget path” matches the “pattern” "mywindow.*.CtkEntry". That is, all CtkEntry widgets which are part of a CtkWindow 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 ctk_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 CTK+ 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 "*<CtkMenuItem>.CtkLabel" style "my-style"

will match CtkLabel widgets which are contained in any kind of menu item.

So, if you have a CtkEntry named "myentry", inside of a horizontal box in a window named "mywindow", then the widget path is: "mywindow.CtkHBox.myentry" while the class path is: "CtkWindow.CtkHBox.CtkEntry".

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 "CtkButton" style "my-style"

will match not just CtkButton widgets, but also CtkToggleButton and CtkCheckButton widgets, since those classes derive from CtkButton.

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

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 ctk is used for styles that CTK+ creates internally.

Theme ctkrc Files

Theme RC files are loaded first from under the ~/.themes/, then from the directory from ctk_rc_get_theme_dir(). The files looked at will be ctk-3.0/ctkrc.

When the application prefers dark themes (see the “ctk-application-prefer-dark-theme” property for details), ctk-3.0/ctkrc-dark will be loaded first, and if not present ctk-3.0/ctkrc will be loaded.

Optimizing RC Style Matches

Everytime a widget is created and added to the layout hierarchy of a CtkWindow ("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:

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:

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:

The colors and background pixmaps are specified as a function of the state of the widget. The states are:

1
2
3

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

1
2
3
4
5

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

1
2
3
4
5

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

1
2
3
4
5
6

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

1
2
3
4
5
6

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

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:

1
2
3
4
5
6
7

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:

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

ctk_rc_scanner_new ()

GScanner *
ctk_rc_scanner_new (void);

[skip]

ctk_rc_get_style ()

CtkStyle *
ctk_rc_get_style (CtkWidget *widget);

Finds all matching RC styles for a given widget, composites them together, and then creates a CtkStyle representing the composite appearance. (CTK+ actually keeps a cache of previously created styles, so a new style may not be created.)

ctk_rc_get_style_by_paths ()

CtkStyle *
ctk_rc_get_style_by_paths (CtkSettings *settings,
                           const char *widget_path,
                           const char *class_path,
                           GType type);

Creates up a CtkStyle 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 CTK+ widgets. An example of this would be items inside a GNOME canvas widget.

The action of ctk_rc_get_style() is similar to:

1
2
3
4
5

ctk_widget_path (widget, NULL, &path, NULL);
ctk_widget_class_path (widget, NULL, &class_path, NULL);
ctk_rc_get_style_by_paths (ctk_widget_get_settings (widget),
                           path, class_path,
                           G_OBJECT_TYPE (widget));

ctk_rc_parse ()

void
ctk_rc_parse (const gchar *filename);

Parses a given resource file.

ctk_rc_parse_string ()

void
ctk_rc_parse_string (const gchar *rc_string);

Parses resource information directly from a string.

ctk_rc_reparse_all ()

gboolean
ctk_rc_reparse_all (void);

If the modification time on any previously read file for the default CtkSettings has changed, discard all style information and then reread all previously read RC files.

ctk_rc_reparse_all_for_settings ()

gboolean
ctk_rc_reparse_all_for_settings (CtkSettings *settings,
                                 gboolean force_load);

If the modification time on any previously read file for the given CtkSettings has changed, discard all style information and then reread all previously read RC files.

ctk_rc_reset_styles ()

void
ctk_rc_reset_styles (CtkSettings *settings);

This function recomputes the styles for all widgets that use a particular CtkSettings object. (There is one CtkSettings object per CdkScreen, see ctk_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 explicitly on them with ctk_widget_set_style().

Since: 2.4

ctk_rc_add_default_file ()

void
ctk_rc_add_default_file (const gchar *filename);

Adds a file to the list of files to be parsed at the end of ctk_init().

ctk_rc_get_default_files ()

gchar **
ctk_rc_get_default_files (void);

Retrieves the current list of RC files that will be parsed at the end of ctk_init().

ctk_rc_set_default_files ()

void
ctk_rc_set_default_files (gchar **filenames);

Sets the list of files that CTK+ will read at the end of ctk_init().

ctk_rc_parse_color ()

guint
ctk_rc_parse_color (GScanner *scanner,
                    CdkColor *color);

Parses a color in the format expected in a RC file.

Note that theme engines should use ctk_rc_parse_color_full() in order to support symbolic colors.

ctk_rc_parse_color_full ()

guint
ctk_rc_parse_color_full (GScanner *scanner,
                         CtkRcStyle *style,
                         CdkColor *color);

Parses a color in the format expected in a RC file. If style is not NULL, it will be consulted to resolve references to symbolic colors.

Since: 2.12

ctk_rc_parse_state ()

guint
ctk_rc_parse_state (GScanner *scanner,
                    CtkStateType *state);

Parses a CtkStateType variable from the format expected in a RC file.

ctk_rc_parse_priority ()

guint
ctk_rc_parse_priority (GScanner *scanner,
                       CtkPathPriorityType *priority);

Parses a CtkPathPriorityType variable from the format expected in a RC file.

ctk_rc_find_module_in_path ()

gchar *
ctk_rc_find_module_in_path (const gchar *module_file);

Searches for a theme engine in the CTK+ search path. This function is not useful for applications and should not be used.

ctk_rc_find_pixmap_in_path ()

gchar *
ctk_rc_find_pixmap_in_path (CtkSettings *settings,
                            GScanner *scanner,
                            const gchar *pixmap_file);

Looks up a file in pixmap path for the specified CtkSettings. If the file is not found, it outputs a warning message using g_warning() and returns NULL.

ctk_rc_get_module_dir ()

gchar *
ctk_rc_get_module_dir (void);

Returns a directory in which CTK+ looks for theme engines. For full information about the search for theme engines, see the docs for CTK_PATH in Running CTK+ Applications.

ctk_rc_get_im_module_path ()

gchar *
ctk_rc_get_im_module_path (void);

Obtains the path in which to look for IM modules. See the documentation of the CTK_PATH environment variable for more details about looking up modules. This function is useful solely for utilities supplied with CTK+ and should not be used by applications under normal circumstances.

ctk_rc_get_im_module_file ()

gchar *
ctk_rc_get_im_module_file (void);

Obtains the path to the IM modules file. See the documentation of the CTK_IM_MODULE_FILE environment variable for more details.

ctk_rc_get_theme_dir ()

gchar *
ctk_rc_get_theme_dir (void);

Returns the standard directory in which themes should be installed. (CTK+ does not actually use this directory itself.)

ctk_rc_style_new ()

CtkRcStyle *
ctk_rc_style_new (void);

Creates a new CtkRcStyle with no fields set and a reference count of 1.

ctk_rc_style_copy ()

CtkRcStyle *
ctk_rc_style_copy (CtkRcStyle *orig);

Makes a copy of the specified CtkRcStyle. This function will correctly copy an RC style that is a member of a class derived from CtkRcStyle.

CtkRcStyle

typedef struct {
  gchar *name;
  gchar *bg_pixmap_name[5];
  PangoFontDescription *font_desc;

  CtkRcFlags color_flags[5];
  CdkColor   fg[5];
  CdkColor   bg[5];
  CdkColor   text[5];
  CdkColor   base[5];

  gint xthickness;
  gint ythickness;
} CtkRcStyle;

The CtkRcStyle is used to represent a set of information about the appearance of a widget. This can later be composited together with other CtkRcStyle<!-- -->s to form a CtkStyle.

struct CtkRcStyleClass

struct CtkRcStyleClass {
  GObjectClass parent_class;

  /* Create an empty RC style of the same type as this RC style.
   * The default implementation, which does
   * g_object_new (G_OBJECT_TYPE (style), NULL);
   * should work in most cases.
   */
  CtkRcStyle * (*create_rc_style) (CtkRcStyle *rc_style);

  /* Fill in engine specific parts of CtkRcStyle by parsing contents
   * of brackets. Returns G_TOKEN_NONE if successful, otherwise returns
   * the token it expected but didn't get.
   */
  guint     (*parse)  (CtkRcStyle   *rc_style,
                       CtkSettings  *settings,
                       GScanner     *scanner);

  /* Combine RC style data from src into dest. If overridden, this
   * function should chain to the parent.
   */
  void      (*merge)  (CtkRcStyle *dest,
                       CtkRcStyle *src);

  /* Create an empty style suitable to this RC style
   */
  CtkStyle * (*create_style) (CtkRcStyle *rc_style);
};

enum CtkRcFlags

enum CtkRcTokenType

enum CtkPathPriorityType

enum CtkPathType