diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index ac14a49130..d482ae0581 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -95,6 +95,7 @@ gtkradiobutton.sgml gtkradiomenuitem.sgml gtkradiotoolbutton.sgml gtkrange.sgml +gtkrc.sgml gtkrecentaction.sgml gtkrecentchooser.sgml gtkrecentchooserdialog.sgml diff --git a/docs/reference/gtk/tmpl/gtkrc.sgml b/docs/reference/gtk/tmpl/gtkrc.sgml deleted file mode 100644 index 7901b3b73b..0000000000 --- a/docs/reference/gtk/tmpl/gtkrc.sgml +++ /dev/null @@ -1,1057 +0,0 @@ - -Resource Files - - -Deprecated routines for handling resource files - - - -GTK+ provides resource file mechanism for configuring -various aspects of the operation of a GTK+ program -at runtime. - - -In GTK+ 3.0, resource files have been deprecated and replaced -by CSS-like style sheets, which are understood by #GtkCssProvider. - - -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_init(). -Unless modified, the files looked for will be -<SYSCONFDIR>/gtk-2.0/gtkrc -and .gtkrc-3.0 in the users home directory. -(<SYSCONFDIR> defaults to -/usr/local/etc. It can be changed with the - or options when -configuring GTK+.) - - -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 path matches the -pattern "mywindow.*.GtkEntry". -That is, all #GtkEntry widgets which are part of a #GtkWindow 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 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, widget_class paths can also contain -<classname> substrings, which are matching -the class with the given name and any derived classes. For instance, - -widget_class "*<GtkMenuItem>.GtkLabel" style "my-style" - -will match #GtkLabel widgets which are contained in any kind of menu item. - - -So, if you have a #GtkEntry named "myentry", inside of a -horizontal box in a window named "mywindow", then the -widget path is: "mywindow.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 #GtkButton widgets, but also #GtkToggleButton and -#GtkCheckButton widgets, since those classes derive from #GtkButton. - - -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. - - - - -Theme gtkrc files - - -Theme RC files are loaded first from under the ~/.themes/, -then from the directory from gtk_rc_get_theme_dir(). The files looked at will -be gtk-3.0/gtkrc. - - -When the application prefers dark themes -(see the #GtkSettings:gtk-application-prefer-dark-theme property for details), -gtk-3.0/gtkrc-dark will be loaded first, and if not present -gtk-3.0/gtkrc will be loaded. - - - - - -Optimizing RC Style Matches - -Everytime a widget is created and added to the layout hierarchy of a #GtkWindow -("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: - - - - - 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: - - style "Foo" { foo_content } - class "X" style "Foo" - style "Bar" { bar_content } - class "X" style "Bar" - - is faster to match as: - - style "FooBar" { foo_content bar_content } - class "X" style "FooBar" - - - - - 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 class matches) or full path names (for - widget and widget_class matches) - is to be preferred over shortened names - containing "*" or "?". - - - - 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 "?" should be preferred - over "*". This can reduce the matching complexity from - O(n^2) to O(n). For example "Gtk*Box" can be turned into - "Gtk?Box" and will still match #GtkHBox and #GtkVBox. - - - - The use of "*" wildcards should be restricted as much - as possible, because matching "A*B*C*RestString" can - result in matching complexities of O(n^2) worst case. - - - - - - -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 on X11). - - - - - - -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, #GtkText, #GtkEntry, #GtkList, and #GtkCList. - - - - - 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 "<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 - - - Starting with GTK+ 2.0, the "font" and "fontset" - declarations are ignored; use "font_name" declarations instead. - - - - - 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_description_from_string(). - - - - - stock["stock-id"] = { icon source specifications } - - - Defines the icon for a stock item. - - - - - color["color-name"] = color specification - - - Since 2.10, this element can be used to defines symbolic colors. See below for - the syntax of color specifications. - - - - - 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. - - -Since 2.10, colors can also be specified by refering to a symbolic color, as -follows: @color-name, or by using expressions to combine -colors. The following expressions are currently supported: - - - mix (factor, color1, color2) - - Computes a new color by mixing color1 and - color2. The factor - determines how close the new color is to color1. - A factor of 1.0 gives pure color1, a factor of - 0.0 gives pure color2. - - - - - shade (factor, color) - - Computes a lighter or darker variant of color. - A factor of 1.0 leaves the color unchanged, smaller - factors yield darker colors, larger factors yield lighter colors. - - - - - lighter (color) - - This is an abbreviation for - shade (1.3, color). - - - - - darker (color) - - This is an abbreviation for - shade (0.7, color). - - - - - -Here are some examples of color expressions: - - mix (0.5, "red", "blue") - shade (1.5, mix (0.3, "#0abbc0", { 0.3, 0.5, 0.9 })) - lighter (@foreground) - - - - -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. - - - -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> -<ctl> -<control> -<meta> -<hyper> -<super> -<mod1> -<mod2> -<mod3> -<mod4> -<mod5> -<release> -<shft> -<shift> - -<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. - - - - - - - - - - - - - - - - -The #GtkRcStyle structure is used to represent a set -of information about the appearance of a widget. -This can later be composited together with other -#GtkRcStyle structures to form a #GtkStyle. - - -@name: -@bg_pixmap_name: -@font_desc: -@color_flags: -@fg: -@bg: -@text: -@base: -@xthickness: -@ythickness: - - - -The #GtkRcFlags enumeration is used as a bitmask -to specify which fields of a #GtkRcStyle have been -set for each state. - - -@GTK_RC_FG: If present, the foreground color has been set for this state. -@GTK_RC_BG: If present, the background color has been set for this state. -@GTK_RC_TEXT: If present, the text color has been set for this state. -@GTK_RC_BASE: If present, the base color has been set for this state. - - - -The #GtkRcTokenType enumeration represents the tokens -in the RC file. It is exposed so that theme engines -can reuse these tokens when parsing the theme-engine -specific portions of a RC file. - - -@GTK_RC_TOKEN_INVALID: -@GTK_RC_TOKEN_INCLUDE: -@GTK_RC_TOKEN_NORMAL: -@GTK_RC_TOKEN_ACTIVE: -@GTK_RC_TOKEN_PRELIGHT: -@GTK_RC_TOKEN_SELECTED: -@GTK_RC_TOKEN_INSENSITIVE: -@GTK_RC_TOKEN_FG: -@GTK_RC_TOKEN_BG: -@GTK_RC_TOKEN_TEXT: -@GTK_RC_TOKEN_BASE: -@GTK_RC_TOKEN_XTHICKNESS: -@GTK_RC_TOKEN_YTHICKNESS: -@GTK_RC_TOKEN_FONT: -@GTK_RC_TOKEN_FONTSET: -@GTK_RC_TOKEN_FONT_NAME: -@GTK_RC_TOKEN_BG_PIXMAP: -@GTK_RC_TOKEN_PIXMAP_PATH: -@GTK_RC_TOKEN_STYLE: -@GTK_RC_TOKEN_BINDING: -@GTK_RC_TOKEN_BIND: -@GTK_RC_TOKEN_WIDGET: -@GTK_RC_TOKEN_WIDGET_CLASS: -@GTK_RC_TOKEN_CLASS: -@GTK_RC_TOKEN_LOWEST: -@GTK_RC_TOKEN_GTK: -@GTK_RC_TOKEN_APPLICATION: -@GTK_RC_TOKEN_THEME: -@GTK_RC_TOKEN_RC: -@GTK_RC_TOKEN_HIGHEST: -@GTK_RC_TOKEN_ENGINE: -@GTK_RC_TOKEN_MODULE_PATH: -@GTK_RC_TOKEN_IM_MODULE_PATH: -@GTK_RC_TOKEN_IM_MODULE_FILE: -@GTK_RC_TOKEN_STOCK: -@GTK_RC_TOKEN_LTR: -@GTK_RC_TOKEN_RTL: -@GTK_RC_TOKEN_COLOR: -@GTK_RC_TOKEN_UNBIND: -@GTK_RC_TOKEN_LAST: - - - - - - -@void: -@Returns: - - - - - - -@widget: -@Returns: - - - - - - - -@settings: -@widget_path: -@class_path: -@type: -@Returns: - - - - -Parses a given resource file. - - -@filename: the filename of a file to parse. If @filename is not absolute, it - is searched in the current directory. - - - - -Parses resource information directly from a string. - - -@rc_string: a string to parse. - - - - - - -@void: -@Returns: - - - - - - - -@settings: -@force_load: -@Returns: - - - - - - - -@settings: - - - - - - -@filename: - - - - - - -@void: -@Returns: - - - - - - -@filenames: - - - - - - - -@scanner: -@color: -@Returns: - - - - - - - -@scanner: -@style: -@color: -@Returns: - - - - -Parses a #GtkStateType variable from the format expected -in a RC file. - - -@scanner: a #GtkScanner (must be initialized for parsing an RC file) -@state: A pointer to a #GtkStateType variable in which to -store the result. -@Returns: %G_TOKEN_NONE if parsing succeeded, otherwise the token -that was expected but not found. - - - - -Parses a #GtkPathPriorityType variable from the format expected -in a RC file. - - -@scanner: a #GtkScanner (must be initialized for parsing an RC file) -@priority: A pointer to #GtkPathPriorityType variable in which -to store the result. -@Returns: %G_TOKEN_NONE if parsing succeeded, otherwise the token -that was expected but not found. - - - - - - -@module_file: The name of the module to search for. -@Returns: - - - - - - -@settings: -@scanner: a #GtkScanner. Used for printing out warning messages -if the file is not found. -@pixmap_file: The name of the file to search for. -@Returns: The filename, if found (must be freed with g_free()), -otherwise %NULL. - - - - - - -@void: -@Returns: - - - - - - - -@void: -@Returns: - - - - - - - -@void: -@Returns: - - - - -Returns the standard directory in which themes should -be installed. (GTK+ does not actually use this directory -itself.) - - -@void: -@Returns: The directory (must be freed with g_free()). - - - - -Creates a new #GtkRcStyle with no fields set and -a reference count of 1. - - -@void: -@Returns: the newly-created #GtkRcStyle - - - - - - - -@orig: -@Returns: - - diff --git a/gtk/gtkrc.c b/gtk/gtkrc.c index fa5789b1c2..3a471d8512 100644 --- a/gtk/gtkrc.c +++ b/gtk/gtkrc.c @@ -59,6 +59,668 @@ #include #endif + +/** + * SECTION:gtkrc + * @Short_description: Deprecated routines for handling resource files + * @Title: Resource Files + * + * GTK+ provides resource file mechanism for configuring + * various aspects of the operation of a GTK+ program + * at runtime. + * + * + * In GTK+ 3.0, resource files have been deprecated and replaced + * by CSS-like style sheets, which are understood by #GtkCssProvider. + * + * + * + * 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_init(). + * Unless modified, the files looked for will be + * <SYSCONFDIR>/gtk-2.0/gtkrc + * and .gtkrc-3.0 in the users home directory. + * (<SYSCONFDIR> defaults to + * /usr/local/etc. It can be changed with the + * or options when + * configuring GTK+.) + * + * 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 path matches the + * pattern "mywindow.*.GtkEntry". + * That is, all #GtkEntry widgets which are part of a #GtkWindow 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 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, widget_class paths can also contain + * <classname> substrings, which are matching + * the class with the given name and any derived classes. For instance, + * + * widget_class "*<GtkMenuItem>.GtkLabel" style "my-style" + * + * will match #GtkLabel widgets which are contained in any kind of menu item. + * + * So, if you have a #GtkEntry named "myentry", inside of a + * horizontal box in a window named "mywindow", then the + * widget path is: "mywindow.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 #GtkButton widgets, but also #GtkToggleButton and + * #GtkCheckButton widgets, since those classes derive from #GtkButton. + * + * 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. + * + * + * + * Theme gtkrc files + * + * + * Theme RC files are loaded first from under the ~/.themes/, + * then from the directory from gtk_rc_get_theme_dir(). The files looked at will + * be gtk-3.0/gtkrc. + * + * When the application prefers dark themes + * (see the #GtkSettings:gtk-application-prefer-dark-theme property for details), + * gtk-3.0/gtkrc-dark will be loaded first, and if not present + * gtk-3.0/gtkrc will be loaded. + * + * + * + * Optimizing RC Style Matches + * + * + * Everytime a widget is created and added to the layout hierarchy of a #GtkWindow + * ("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: + * + * + * + * 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: + * + * style "Foo" { foo_content } + * class "X" style "Foo" + * style "Bar" { bar_content } + * class "X" style "Bar" + * + * is faster to match as: + * + * style "FooBar" { foo_content bar_content } + * class "X" style "FooBar" + * + * + * + * 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 class matches) or full path names (for + * widget and widget_class matches) + * is to be preferred over shortened names + * containing "*" or "?". + * + * + * 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 "?" should be preferred + * over "*". This can reduce the matching complexity from + * O(n^2) to O(n). For example "Gtk*Box" can be turned into + * "Gtk?Box" and will still match #GtkHBox and #GtkVBox. + * + * + * The use of "*" wildcards should be restricted as much + * as possible, because matching "A*B*C*RestString" can + * result in matching complexities of O(n^2) worst case. + * + * + * + * + * + * 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 on X11). + * + * + * + * + * + * + * 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, #GtkText, #GtkEntry, #GtkList, and #GtkCList. + * + * + * + * 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 "<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 + * + * Starting with GTK+ 2.0, the "font" and "fontset" + * declarations are ignored; use "font_name" declarations instead. + * + * + * + * 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_description_from_string(). + * + * + * + * stock["stock-id"] = { icon source specifications } + * + * Defines the icon for a stock item. + * + * + * + * color["color-name"] = color specification + * + * Since 2.10, this element can be used to defines symbolic colors. See below for + * the syntax of color specifications. + * + * + * + * 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. + * + * Since 2.10, colors can also be specified by refering to a symbolic color, as + * follows: @color-name, or by using expressions to combine + * colors. The following expressions are currently supported: + * + * + * mix (factor, color1, color2) + * + * Computes a new color by mixing color1 and + * color2. The factor + * determines how close the new color is to color1. + * A factor of 1.0 gives pure color1, a factor of + * 0.0 gives pure color2. + * + * + * + * shade (factor, color) + * + * Computes a lighter or darker variant of color. + * A factor of 1.0 leaves the color unchanged, smaller + * factors yield darker colors, larger factors yield lighter colors. + * + * + * + * lighter (color) + * + * This is an abbreviation for + * shade (1.3, color). + * + * + * + * darker (color) + * + * This is an abbreviation for + * shade (0.7, color). + * + * + * + * + * Here are some examples of color expressions: + * + * + * mix (0.5, "red", "blue") + * shade (1.5, mix (0.3, "#0abbc0", { 0.3, 0.5, 0.9 })) + * lighter (@foreground) + * + * + * 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. + * + * 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> + * <ctl> + * <control> + * <meta> + * <hyper> + * <super> + * <mod1> + * <mod2> + * <mod3> + * <mod4> + * <mod5> + * <release> + * <shft> + * <shift> + * + * <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. + * + * + */ + + enum { PATH_ELT_PSPEC, @@ -258,6 +920,8 @@ gtk_rc_make_default_dir (const gchar *type) * 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. + * + * Deprecated: 3.0: Use #GtkCssProvider instead. */ gchar * gtk_rc_get_im_module_path (void) @@ -277,6 +941,8 @@ gtk_rc_get_im_module_path (void) * Obtains the path to the IM modules file. See the documentation * of the GTK_IM_MODULE_FILE * environment variable for more details. + * + * Deprecated: 3.0: Use #GtkCssProvider instead. */ gchar * gtk_rc_get_im_module_file (void) @@ -298,6 +964,17 @@ gtk_rc_get_im_module_file (void) return result; } +/** + * gtk_rc_get_theme_dir: + * + * Returns the standard directory in which themes should + * be installed. (GTK+ does not actually use this directory + * itself.) + * + * Returns: The directory (must be freed with g_free()). + * + * Deprecated: 3.0: Use #GtkCssProvider instead. + */ gchar * gtk_rc_get_theme_dir (void) { @@ -316,13 +993,15 @@ gtk_rc_get_theme_dir (void) /** * gtk_rc_get_module_dir: - * + * * Returns a directory in which GTK+ looks for theme engines. * For full information about the search for theme engines, * see the docs for GTK_PATH in * . - * + * * return value: (type filename): the directory. (Must be freed with g_free()) + * + * Deprecated: 3.0: Use #GtkCssProvider instead. **/ gchar * gtk_rc_get_module_dir (void) @@ -379,12 +1058,29 @@ gtk_rc_get_default_files (void) return gtk_rc_default_files; } +/** + * gtk_rc_parse_string: + * @rc_string: a string to parse. + * + * Parses resource information directly from a string. + * + * Deprecated: 3.0: Use #GtkCssProvider instead. + */ void gtk_rc_parse_string (const gchar *rc_string) { g_return_if_fail (rc_string != NULL); } +/** + * gtk_rc_parse: + * @filename: the filename of a file to parse. If @filename is not absolute, it + * is searched in the current directory. + * + * Parses a given resource file. + * + * Deprecated: 3.0: Use #GtkCssProvider instead. + */ void gtk_rc_parse (const gchar *filename) { @@ -429,7 +1125,7 @@ static void gtk_rc_style_class_init (GtkRcStyleClass *klass) { GObjectClass *object_class = G_OBJECT_CLASS (klass); - + object_class->finalize = gtk_rc_style_finalize; klass->parse = NULL; @@ -454,10 +1150,10 @@ gtk_rc_style_finalize (GObject *object) g_free (rc_style->name); if (rc_style->font_desc) pango_font_description_free (rc_style->font_desc); - + for (i = 0; i < 5; i++) g_free (rc_style->bg_pixmap_name[i]); - + /* Now remove all references to this rc_style from * realized_style_ht */ @@ -515,13 +1211,23 @@ gtk_rc_style_finalize (GObject *object) G_OBJECT_CLASS (gtk_rc_style_parent_class)->finalize (object); } +/** + * gtk_rc_style_new: + * + * Creates a new #GtkRcStyle with no fields set and + * a reference count of 1. + * + * Returns: the newly-created #GtkRcStyle + * + * Deprecated: 3.0: Use #GtkCssProvider instead. + */ GtkRcStyle * gtk_rc_style_new (void) { GtkRcStyle *style; - + style = g_object_new (GTK_TYPE_RC_STYLE, NULL); - + return style; } @@ -534,6 +1240,8 @@ gtk_rc_style_new (void) * derived from #GtkRcStyle. * * Return value: (transfer full): the resulting #GtkRcStyle + * + * Deprecated: 3.0: Use #GtkCssProvider instead. **/ GtkRcStyle * gtk_rc_style_copy (GtkRcStyle *orig) @@ -689,7 +1397,7 @@ gtk_rc_style_real_create_style (GtkRcStyle *rc_style) /** * gtk_rc_reset_styles: * @settings: a #GtkSettings - * + * * This function recomputes the styles for all widgets that use a * particular #GtkSettings object. (There is one #GtkSettings object * per #GdkScreen, see gtk_settings_get_for_screen()); It is useful @@ -702,6 +1410,8 @@ gtk_rc_style_real_create_style (GtkRcStyle *rc_style) * with gtk_widget_set_style(). * * Since: 2.4 + * + * Deprecated: 3.0: Use #GtkCssProvider instead. **/ void gtk_rc_reset_styles (GtkSettings *settings) @@ -713,12 +1423,14 @@ gtk_rc_reset_styles (GtkSettings *settings) * gtk_rc_reparse_all_for_settings: * @settings: a #GtkSettings * @force_load: load whether or not anything changed - * + * * If the modification time on any previously read file * for the given #GtkSettings has changed, discard all style information * and then reread all previously read RC files. - * + * * Return value: %TRUE if the files were reread. + * + * Deprecated: 3.0: Use #GtkCssProvider instead. **/ gboolean gtk_rc_reparse_all_for_settings (GtkSettings *settings, @@ -729,12 +1441,14 @@ gtk_rc_reparse_all_for_settings (GtkSettings *settings, /** * gtk_rc_reparse_all: - * + * * If the modification time on any previously read file for the * default #GtkSettings has changed, discard all style information * and then reread all previously read RC files. - * + * * Return value: %TRUE if the files were reread. + * + * Deprecated: 3.0: Use #GtkCssProvider instead. **/ gboolean gtk_rc_reparse_all (void) @@ -933,12 +1647,14 @@ lookup_color (GtkRcStyle *style, * @scanner: Scanner used to get line number information for the * warning message, or %NULL * @pixmap_file: name of the pixmap file to locate. - * + * * Looks up a file in pixmap path for the specified #GtkSettings. * If the file is not found, it outputs a warning message using * g_warning() and returns %NULL. * - * Return value: (type filename): the filename. + * Return value: (type filename): the filename. + * + * Deprecated: 3.0: Use #GtkCssProvider instead. **/ gchar* gtk_rc_find_pixmap_in_path (GtkSettings *settings, @@ -953,12 +1669,14 @@ gtk_rc_find_pixmap_in_path (GtkSettings *settings, /** * gtk_rc_find_module_in_path: * @module_file: name of a theme engine - * + * * Searches for a theme engine in the GTK+ search path. This function * is not useful for applications and should not be used. - * + * * Return value: (type filename): The filename, if found (must be * freed with g_free()), otherwise %NULL. + * + * Deprecated: 3.0: Use #GtkCssProvider instead. **/ gchar* gtk_rc_find_module_in_path (const gchar *module_file) @@ -968,10 +1686,17 @@ gtk_rc_find_module_in_path (const gchar *module_file) /** * gtk_rc_parse_state: - * @scanner: - * @state: (out): + * @scanner: a #GtkScanner (must be initialized for parsing an RC file) + * @state: (out): A pointer to a #GtkStateType variable in which to + * store the result. * - * Deprecated:3.0: Use #GtkCssProvider instead + * Parses a #GtkStateType variable from the format expected + * in a RC file. + * + * Returns: %G_TOKEN_NONE if parsing succeeded, otherwise the token + * that was expected but not found. + * + * Deprecated: 3.0: Use #GtkCssProvider instead */ guint gtk_rc_parse_state (GScanner *scanner, @@ -1026,8 +1751,15 @@ gtk_rc_parse_state (GScanner *scanner, /** * gtk_rc_parse_priority: - * @scanner: - * @priority: (out): + * @scanner: a #GtkScanner (must be initialized for parsing an RC file) + * @priority: A pointer to #GtkPathPriorityType variable in which + * to store the result. + * + * Parses a #GtkPathPriorityType variable from the format expected + * in a RC file. + * + * Returns: %G_TOKEN_NONE if parsing succeeded, otherwise the token + * that was expected but not found. * * Deprecated:3.0: Use #GtkCssProvider instead */ @@ -1088,9 +1820,9 @@ gtk_rc_parse_priority (GScanner *scanner, * the result * * Parses a color in the format expected - * in a RC file. + * in a RC file. * - * Note that theme engines should use gtk_rc_parse_color_full() in + * Note that theme engines should use gtk_rc_parse_color_full() in * order to support symbolic colors. * * Returns: %G_TOKEN_NONE if parsing succeeded, otherwise the token diff --git a/gtk/gtkrc.h b/gtk/gtkrc.h index dc3abe7635..ee7640736d 100644 --- a/gtk/gtkrc.h +++ b/gtk/gtkrc.h @@ -57,6 +57,24 @@ typedef enum GTK_RC_BASE = 1 << 3 } GtkRcFlags; +/** + * GtkRcStyle: + * @name: + * @bg_pixmap_name: + * @font_desc: + * @color_flags: + * @fg: + * @bg: + * @text: + * @base: + * @xthickness: + * @ythickness: + * + * The #GtkRcStyle structure is used to represent a set + * of information about the appearance of a widget. + * This can later be composited together with other + * #GtkRcStyle structures to form a #GtkStyle. + */ struct _GtkRcStyle { GObject parent_instance; @@ -164,6 +182,57 @@ gchar* gtk_rc_get_im_module_path (void); gchar* gtk_rc_get_im_module_file (void); /* private functions/definitions */ + +/** + * GtkRcTokenType: + * @GTK_RC_TOKEN_INVALID: + * @GTK_RC_TOKEN_INCLUDE: + * @GTK_RC_TOKEN_NORMAL: + * @GTK_RC_TOKEN_ACTIVE: + * @GTK_RC_TOKEN_PRELIGHT: + * @GTK_RC_TOKEN_SELECTED: + * @GTK_RC_TOKEN_INSENSITIVE: + * @GTK_RC_TOKEN_FG: + * @GTK_RC_TOKEN_BG: + * @GTK_RC_TOKEN_TEXT: + * @GTK_RC_TOKEN_BASE: + * @GTK_RC_TOKEN_XTHICKNESS: + * @GTK_RC_TOKEN_YTHICKNESS: + * @GTK_RC_TOKEN_FONT: + * @GTK_RC_TOKEN_FONTSET: + * @GTK_RC_TOKEN_FONT_NAME: + * @GTK_RC_TOKEN_BG_PIXMAP: + * @GTK_RC_TOKEN_PIXMAP_PATH: + * @GTK_RC_TOKEN_STYLE: + * @GTK_RC_TOKEN_BINDING: + * @GTK_RC_TOKEN_BIND: + * @GTK_RC_TOKEN_WIDGET: + * @GTK_RC_TOKEN_WIDGET_CLASS: + * @GTK_RC_TOKEN_CLASS: + * @GTK_RC_TOKEN_LOWEST: + * @GTK_RC_TOKEN_GTK: + * @GTK_RC_TOKEN_APPLICATION: + * @GTK_RC_TOKEN_THEME: + * @GTK_RC_TOKEN_RC: + * @GTK_RC_TOKEN_HIGHEST: + * @GTK_RC_TOKEN_ENGINE: + * @GTK_RC_TOKEN_MODULE_PATH: + * @GTK_RC_TOKEN_IM_MODULE_PATH: + * @GTK_RC_TOKEN_IM_MODULE_FILE: + * @GTK_RC_TOKEN_STOCK: + * @GTK_RC_TOKEN_LTR: + * @GTK_RC_TOKEN_RTL: + * @GTK_RC_TOKEN_COLOR: + * @GTK_RC_TOKEN_UNBIND: + * @GTK_RC_TOKEN_LAST: + * + * The #GtkRcTokenType enumeration represents the tokens + * in the RC file. It is exposed so that theme engines + * can reuse these tokens when parsing the theme-engine + * specific portions of a RC file. + * + * Deprecated: 3.0: Use #GtkCssProvider instead. + */ typedef enum { GTK_RC_TOKEN_INVALID = G_TOKEN_LAST, GTK_RC_TOKEN_INCLUDE,