1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 Routines for handling resource files
7 <!-- ##### SECTION Long_Description ##### -->
9 GTK+ provides resource file mechanism for configuring
10 various aspects of the operation of a GTK+ program
14 <refsect2><title>Default files</title>
16 An application can cause GTK+ to parse a specific RC
17 file by calling gtk_rc_parse(). In addition to this,
18 certain files will be read at the end of gtk_init().
19 Unless modified, the files looked for will be <filename>.gtkrc</filename>
20 in the users home directory, and
21 <filename>$localstatedir/gtk/gtkrc</filename>
22 (<literal>$localstatedir</literal> defaults to
23 <filename>/usr/local/etc</filename>).
26 The set of these <firstterm>default</firstterm> files
27 can be retrieved with gtk_rc_get_default_files()
28 and modified with gtk_rc_add_default_file() and
29 gtk_rc_set_default_files().
32 For each default file, in addition to the file itself,
33 GTK+ will look for a locale-specific file that will
34 be parsed in addition to the main file. For instance,
35 if <literal>LANG</literal> is set to <literal>ja_JP.ujis</literal>,
36 when loading the default file <filename>~/.gtkrc</filename>
37 then GTK+ looks for <filename>~/.gtkrc.ja_JP.ujis</filename>,
38 <filename>~/.gtkrc.ja_JP</filename>, and
39 <filename>~/.gtkrc.ja</filename>, and parses the
44 <refsect2><title>Pathnames and patterns</title>
46 A resource file defines a number of styles and key bindings and
47 attaches them to particular widgets. The attachment is done
48 by the <literal>widget</literal>, <literal>widget_class</literal>,
49 and <literal>class</literal> declarations. As an example
52 widget "mywindow.*.GtkEntry" style "my-entry-class"
54 attaches the style <literal>"my-entry-class"</literal>
55 to all widgets whose <firstterm>widget class</firstterm>
56 matches the <firstterm>pattern</firstterm>
57 <literal>"mywindow.*.GtkEntry"</literal>.
60 The patterns here are given in the standard shell glob
61 syntax. The <literal>"?"</literal> wildcard matches
62 any character, while <literal>"*"</literal> matches
63 zero or more of any character. The three types of
64 matching are against the widget path, the
65 <firstterm>class path</firstterm> and the class
66 heirarchy. Both the widget and the class paths consists of a
67 <literal>"."</literal> separated list of all the
68 parents of the widget and the widget itself from
69 outermost to innermost. The difference is that in
70 the widget path, the name assigned by
71 <function>gtk_widget_set_name()</function> is used
72 if present, otherwise the class name of the widget, while
73 for the widget path, the class name is always used.
76 So, if you have a <classname>GtkEntry</classname> named
77 <literal>"myentry"</literal>, inside of a of a window
78 named <literal>"mywindow"</literal>, then the
81 "mwindow.GtkHBox.myentry"
83 while the class path is:
85 "GtkWindow.GtkHBox.GtkEntry"
89 Matching against class is a little different. The pattern
90 match is done against all class names in the widgets
91 class heirarchy (not the layout heirarchy) in sequence, so the
94 class "GtkButton" style "my-style"
96 will match not just <classname>GtkButton</classname> widgets,
97 but also <classname>GtkToggleButton</classname> and
98 <classname>GtkCheckButton</classname> widgets, since
99 those classes derive from <classname>GtkButton</classname>.
103 <refsect2><title>Toplevel declarations</title>
105 An RC file is a text file which is composed of a sequence
106 of declarations. '#' characters delimit comments and
107 the portion of a line after a '#' is ignored when parsing
112 The possible toplevel declarations are:
116 <term><literal>binding <replaceable>name</replaceable>
117 { ... }</literal></term>
119 <para>Declare a binding set</para>
123 <term><literal>class <replaceable>pattern</replaceable>
124 [ style | binding [ : <replaceable>priority</replaceable> ]]
125 <replaceable>name</replaceable></literal></term>
127 <para>Specify a style or binding set for a particular
128 branch of the inheritance heirarchy.</para>
132 <term><literal>include <replaceable>filename</replaceable></literal></term>
134 <para>Parse another file at this point</para>
138 <term><literal>module_path <replaceable>path></replaceable></literal></term>
140 <para>Sets a path (a list of directories separated
141 by colons) that will be searched for theme engines referenced in
146 <term><literal>pixmap_path <replaceable>path></replaceable></literal></term>
148 <para>Sets a path (a list of directories separated
149 by colons) that will be searched for pixmaps referenced in
154 <term><literal>style <replaceable>name</replaceable> [ =
155 <replaceable>parent</replaceable> ] { ... }</literal></term>
157 <para>Declare a style</para>
161 <term><literal>widget <replaceable>pattern</replaceable>
162 [ style | binding [ : <replaceable>priority</replaceable> ]]
163 <replaceable>name</replaceable></literal></term>
165 <para>Specify a style or binding set for a particular
166 group of widgets by matching on the widget pathname.</para>
170 <term><literal>widget_class <replaceable>pattern</replaceable>
171 [ style | binding [ : <replaceable>priority</replaceable> ]]
172 <replaceable>name</replaceable></literal></term>
174 <para>Specify a style or binding set for a particular
175 group of widgets by matching on the class pathname.</para>
182 <refsect2><title>Styles</title>
184 A RC style is specified by a <literal>style</literal>
185 declaration in a RC file, and then bound to widgets
186 with a <literal>widget</literal>, <literal>widget_class</literal>,
187 or <literal>class</literal> declaration. All styles
188 applying to a particular widget are composited together
189 with <literal>widget</literal> declarations overriding
190 <literal>widget_class</literal> declarations which, in
191 turn, override <literal>widget</literal> declarations.
192 Within each type of declaration, later declarations override
197 Within a <literal>style</literal> declaration, the possible
202 <term><literal>bg[<replaceable>state</replaceable>] =
203 <replaceable>color</replaceable></literal></term>
206 Set color used for the background of most widgets.
211 <term><literal>fg[<replaceable>state</replaceable>] =
212 <replaceable>color</replaceable></literal></term>
215 Set color used for the foreground of most widgets.
220 <term><literal>base[<replaceable>state</replaceable>] =
221 <replaceable>color</replaceable></literal></term>
224 Set color used for the background of widgets displaying
225 editable text. This color is used for the background
226 of, among others, #GtkText, #GtkEntry, #GtkList, and #GtkClist.
231 <term><literal>text[<replaceable>state</replaceable>] =
232 <replaceable>color</replaceable></literal></term>
235 Set color used for foreground of widgets using
236 <literal>base</literal> for the background color.
241 <term><literal>bg_text[<replaceable>state</replaceable>] =
242 <replaceable>color</replaceable></literal></term>
245 Set a background pixmap to be used in place of
246 the <literal>bg</literal> color (or for #GtkText,
247 in place of the <literal>base</literal> color.
252 <term><literal>font = <replaceable>font</replaceable></literal></term>
255 Set the font for a widget.
260 <term><literal>fontset = <replaceable>font</replaceable></literal></term>
263 Set the fontset for a widget. Overrides any
264 <literal>font</literal> declarations.
269 <term><literal>stock[<replaceable>"stock-id"</replaceable>] = { <replaceable>icon source specifications</replaceable> }</literal></term>
272 Defines the icon for a stock item.
279 The colors and background pixmaps are specified as a function of the
280 state of the widget. The states are:
284 <term><literal>NORMAL</literal></term>
287 A color used for a widget in its normal state
292 <term><literal>ACTIVE</literal></term>
295 A variant of the <literal>NORMAL</literal> color used when the
296 widget is in the %GTK_STATE_ACTIVE state, and also for
297 the trough of a ScrollBar, tabs of a NoteBook
298 other than the current tab and similar areas.
299 Frequently, this should be a darker variant
300 of the <literal>NORMAL</literal> color.
305 <term><literal>PRELIGHT</literal></term>
308 A color used for widgets in the %GTK_STATE_PRELIGHT state. This
309 state is the used for Buttons and MenuItems
310 that have the mouse cursor over them, and for
316 <term><literal>SELECTED</literal></term>
319 A color used to highlight data selected by the user.
320 for instance, the selected ListItems in a List widget, and the
321 selection in an Editable widget.
326 <term><literal>INSENSITIVE</literal></term>
329 A color used for the background of widgets that have
330 been set insensitive with gtk_widget_set_sensitive()
338 Colors can be specified as a string <literal>"&hash;rrrrggggbbbb"</literal>,
339 <literal>"&hash;rrrgggbbb"</literal>, <literal>"&hash;rrggbb"</literal>,
340 or <literal>"&hash;rgb"</literal>, where <literal>r</literal>
341 <literal>g</literal>, and <literal>b</literal> are
342 hex digits, or they can be specified as a triplet of floats
343 <literal>{ <replaceable>r</replaceable>, <replaceable>g</replaceable>,
344 <replaceable>b</replaceable>}</literal>.
348 In a <literal>stock</literal> definition, icon sources are specified as a
349 4-tuple of image filename, text direction, widget state, and size, in that
350 order. Each icon source specifies an image filename to use with a given
351 direction, state, and size. The <literal>*</literal> character can be used as a
352 wildcard, and if direction/state/size are omitted they default to
353 <literal>*</literal>. So for example, the following specifies different icons to
354 use for left-to-right and right-to-left languages:
356 stock["my-stock-item"] =
358 { "itemltr.png", LTR, *, * },
359 { "itemrtl.png", RTL, *, * }
362 This could be abbreviated as follows:
364 stock["my-stock-item"] =
366 { "itemltr.png", LTR },
367 { "itemrtl.png", RTL }
373 You can specify custom icons for specific sizes, as follows:
375 stock["my-stock-item"] =
377 { "itemmenusize.png", *, *, "gtk-menu" },
378 { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" }
379 { "itemgeneric.png" } /* implicit *, *, * as a fallback */
382 The sizes that come with GTK+ itself are <literal>"gtk-menu"</literal>,
383 <literal>"gtk-small-toolbar"</literal>, <literal>"gtk-large-toolbar"</literal>,
384 <literal>"gtk-button"</literal>, <literal>"gtk-dialog"</literal>. Applications
385 can define other sizes.
389 It's also possible to use custom icons for a given state, for example:
390 You can specify custom icons for specific sizes, as follows:
392 stock["my-stock-item"] =
394 { "itemprelight.png", *, PRELIGHT },
395 { "iteminsensitive.png", *, INSENSITIVE },
396 { "itemgeneric.png" } /* implicit *, *, * as a fallback */
402 When selecting an icon source to use, GTK+ will consider text direction most
403 important, state second, and size third. It will select the best match based on
404 those criteria. If an attribute matches exactly (e.g. you specified
405 <literal>PRELIGHT</literal> or specified the size), GTK+ won't modify the image;
406 if the attribute matches with a wildcard, GTK+ will scale or modify the image to
407 match the state and size the user requested.
412 <refsect2><title>Key bindings</title>
414 Key bindings allow the user to specify actions to be
415 taken on particular key presses. The form of a binding
420 binding <replaceable>name</replaceable> {
421 bind <replaceable>key</replaceable> {
422 <replaceable>signalname</replaceable> (<replaceable>param</replaceable>, ...)
430 <replaceable>key</replaceable> is a string consisting of a
431 series of modifiers followed by the name of a key. The
434 <member><literal><alt></literal></member>
435 <member><literal><control></literal></member>
436 <member><literal><mod1></literal></member>
437 <member><literal><mod2></literal></member>
438 <member><literal><mod3></literal></member>
439 <member><literal><mod4></literal></member>
440 <member><literal><mod5></literal></member>
441 <member><literal><release></literal></member>
442 <member><literal><shft></literal></member>
443 <member><literal><shift></literal></member>
445 <literal><shft></literal> is an alias for
446 <literal><shift></literal> and
447 <literal><alt></literal> is an alias for
448 <literal><mod1></literal>.
452 The action that is bound to the key is a sequence
453 of signal names (strings) followed by parameters for
454 each signal. The signals must be action signals.
455 (See gtk_signal_new()). Each parameter can be
456 a float, integer, string, or unquoted string
457 representing an enumeration value. The types of
458 the parameters specified must match the types of the
459 parameters of the signal.
463 Binding sets are connected to widgets in the
464 same manner as styles, with one addition.
465 A priority can be specified for each pattern,
466 and within each type of pattern, binding sets
467 override other binding sets first by priority,
468 and only then by order of specification. (Later
469 overrides earlier). The priorities that can
470 be specified are (highest to lowest):
472 <member><literal>HIGHEST</literal></member>
473 <member><literal>RC</literal></member>
474 <member><literal>APPLICATION</literal></member>
475 <member><literal>GTK</literal></member>
476 <member><literal>LOWEST</literal></member>
478 <literal>RC</literal> is the default for bindings
479 read from an RC file, <literal>APPLICATION</literal>
480 should be used for bindings an application sets
481 up, and <literal>GTK</literal> is used for bindings
482 that GTK+ creates internally.
486 <!-- ##### SECTION See_Also ##### -->
491 <!-- ##### STRUCT GtkRcStyle ##### -->
493 The #GtkRcStyle structure is used to represent a set
494 of information about the appearance of a widget.
495 This can later be composited together with other
496 #GtkRcStyle structures to form a #GtkStyle.
511 <!-- ##### STRUCT GtkRcStyleClass ##### -->
517 <!-- ##### ENUM GtkRcFlags ##### -->
519 The #GtkRcFlags enumeration is used as a bitmask
520 to specify which fields of a #GtkRcStyle have been
524 <varlistentry><term> %GTK_RC_FG </term>
527 If present, the foreground color has been set for this state.
531 <varlistentry><term> %GTK_RC_BG </term>
534 If present, the background color has been set for this state.
538 <varlistentry><term> %GTK_RC_TEXT </term>
541 If present, the text color has been set for this state.
545 <varlistentry><term> %GTK_RC_BASE </term>
548 If present, the base color has been set for this state.
559 <!-- ##### USER_FUNCTION GtkImageLoader ##### -->
561 A GtkImageLoader is used to load a filename found in
565 @window: the window for creating image
566 @colormap: the colormap for this image
567 @mask: a pointer to the location to store the mask
568 @transparent_color: the transparent color for the image
569 @filename: filename to load
570 @Returns: a #GtkPixmap representing @filename
573 <!-- ##### ENUM GtkRcTokenType ##### -->
575 The #GtkRcTokenType enumeration represents the tokens
576 in the RC file. It is exposed so that theme engines
577 can reuse these tokens when parsing the theme-engine
578 specific portions of a RC file.
581 @GTK_RC_TOKEN_INVALID:
582 @GTK_RC_TOKEN_INCLUDE:
583 @GTK_RC_TOKEN_NORMAL:
584 @GTK_RC_TOKEN_ACTIVE:
585 @GTK_RC_TOKEN_PRELIGHT:
586 @GTK_RC_TOKEN_SELECTED:
587 @GTK_RC_TOKEN_INSENSITIVE:
592 @GTK_RC_TOKEN_XTHICKNESS:
593 @GTK_RC_TOKEN_YTHICKNESS:
595 @GTK_RC_TOKEN_FONTSET:
596 @GTK_RC_TOKEN_FONT_NAME:
597 @GTK_RC_TOKEN_BG_PIXMAP:
598 @GTK_RC_TOKEN_PIXMAP_PATH:
600 @GTK_RC_TOKEN_BINDING:
602 @GTK_RC_TOKEN_WIDGET:
603 @GTK_RC_TOKEN_WIDGET_CLASS:
605 @GTK_RC_TOKEN_LOWEST:
607 @GTK_RC_TOKEN_APPLICATION:
609 @GTK_RC_TOKEN_HIGHEST:
610 @GTK_RC_TOKEN_ENGINE:
611 @GTK_RC_TOKEN_MODULE_PATH:
612 @GTK_RC_TOKEN_IM_MODULE_PATH:
613 @GTK_RC_TOKEN_IM_MODULE_FILE:
619 <!-- ##### FUNCTION gtk_rc_get_style ##### -->
621 Finds all matching RC styles for a given widget,
622 composites them together, and then creates a
623 #GtkStyle representing the composite appearance.
624 (GTK+ actually keeps a cache of previously
625 created styles, so a new style may not be
629 @widget: a #GtkWidget
630 @Returns: the resulting style. The caller should
631 reference the result, since GTK+ will retain the
632 initial reference count itself for the cache
636 <!-- ##### FUNCTION gtk_rc_add_widget_name_style ##### -->
638 Add a RcStyle that will be looked up by a match against
639 the widget's pathname. This is equivalent to a:
641 widget PATTERN style STYLE
643 statement in a RC file.
646 @rc_style: the #GtkRcStyle to use for widgets matching @pattern
647 @pattern: the pattern
650 <!-- ##### FUNCTION gtk_rc_add_widget_class_style ##### -->
652 Add a RcStyle that will be looked up by a match against
653 the widget's class pathname. This is equivalent to a:
656 widget_class PATTERN style STYLE
658 statement in a RC file.
661 @rc_style: the #GtkRcStyle to use for widgets matching @pattern
662 @pattern: the pattern
665 <!-- ##### FUNCTION gtk_rc_add_class_style ##### -->
667 Add a RcStyle that will be looked up by a matching against
668 the class heirarchy of the widget. This is equivalent to a:
670 class PATTERN style STYLE
672 statement in a RC file.
675 @rc_style: the #GtkRcStyle to use for widgets deriving from @pattern
676 @pattern: the pattern
679 <!-- ##### FUNCTION gtk_rc_parse ##### -->
681 Parse a given resource file.
684 @filename: the filename of a file to parse.
687 <!-- ##### FUNCTION gtk_rc_parse_string ##### -->
689 Parse resource information directly from a string.
692 @rc_string: a string to parse.
695 <!-- ##### FUNCTION gtk_rc_reparse_all ##### -->
697 If the modification time on any previously read file
698 has changed, discard all style information
699 and then reread all previously read RC files.
702 @Returns: %TRUE if the files were reread.
705 <!-- ##### FUNCTION gtk_rc_add_default_file ##### -->
707 Adds a file to the list of files to be parsed at the
711 @filename: the pathname to the file.
714 <!-- ##### FUNCTION gtk_rc_get_default_files ##### -->
716 Retrieves the current list of RC files that will be parsed
717 at the end of gtk_init()
720 @Returns: A NULL terminated array of filenames. This memory
721 is owned by GTK+ and must not be freed by the application.
722 If you want to store this information, you should make a
726 <!-- ##### FUNCTION gtk_rc_set_default_files ##### -->
728 Sets the list of files that GTK+ will read at the
732 @filenames: A %NULL terminated list of filenames.
735 <!-- ##### FUNCTION gtk_rc_parse_color ##### -->
737 Parses a color in the format expected in a RC file.
740 @scanner: a #GtkScanner
741 @color: a pointer to a #GtkColor structure in which to store the result
742 @Returns: %G_TOKEN_NONE if parsing suceeded, otherwise the token
743 that was expected but not found.
746 <!-- ##### FUNCTION gtk_rc_parse_state ##### -->
748 Parses a #GtkStateType variable from the format expected
752 @scanner: a #GtkScanner (must be initialized for parsing an RC file)
753 @state: A pointer to a #GtkStateType variable in which to
755 @Returns: %G_TOKEN_NONE if parsing suceeded, otherwise the token
756 that was expected but not found.
759 <!-- ##### FUNCTION gtk_rc_parse_priority ##### -->
761 Parses a #GtkPathPriorityType variable from the format expected
765 @scanner: a #GtkScanner (must be initialized for parsing an RC file)
766 @priority: A pointer to #GtkPathPriorityType variable in which
768 @Returns: %G_TOKEN_NONE if parsing suceeded, otherwise the token
769 that was expected but not found.
772 <!-- ##### FUNCTION gtk_rc_find_module_in_path ##### -->
774 Looks up a file in the current module path.
777 @module_file: The name of the module to search for.
778 @Returns: The filename, if found. (Must be freed with g_free()),
782 <!-- ##### FUNCTION gtk_rc_find_pixmap_in_path ##### -->
784 Looks up a file in the current pixmap path. If the file is
785 not found, it outputs a warning message using g_warning()
789 @scanner: a #GtkScanner. Used for printing out warning messages
790 if the file is not found.
791 @pixmap_file: The name of the file to search for.
792 @Returns: The filename, if found. (Must be freed with g_free()),
796 <!-- ##### FUNCTION gtk_rc_get_module_dir ##### -->
798 Returns the directory in which GTK+ will look for
802 @Returns: The directory. (Must be freed with g_free())
805 <!-- ##### FUNCTION gtk_rc_get_im_module_path ##### -->
813 <!-- ##### FUNCTION gtk_rc_get_im_module_file ##### -->
821 <!-- ##### FUNCTION gtk_rc_get_theme_dir ##### -->
823 Returns the standard directory in which themes should
824 be installed. (GTK+ does not actually use this directory
828 @Returns: The directory. (Must be freed with g_free())
831 <!-- ##### FUNCTION gtk_rc_set_image_loader ##### -->
833 Sets the function that GTK+ will use to load images
836 @loader: the #GtkImageLoader to use
839 <!-- ##### FUNCTION gtk_rc_load_image ##### -->
841 Internal function. Loads an image using the current
845 @colormap: the colormap to use for the image
846 @transparent_color: the transparent color for the image
847 @filename: the filename of the image file
848 @Returns: a #GtkPixmap representing @filename
851 <!-- ##### FUNCTION gtk_rc_style_new ##### -->
853 Create a new #GtkRcStyle with no fields set and
854 a reference count of 1.
857 @Returns: the newly create #GtkRcStyle
860 <!-- ##### FUNCTION gtk_rc_style_copy ##### -->
869 <!-- ##### FUNCTION gtk_rc_style_ref ##### -->
871 Increment the reference count of a #GtkRcStyle.
874 @rc_style: a #GtkRcStyle
877 <!-- ##### FUNCTION gtk_rc_style_unref ##### -->
879 Decrement the reference count of a #GtkRcStyle and
880 free if the result is 0.
883 @rc_style: a #GtkRcStyle