Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkrc.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Resource Files
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Routines for handling resource files
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 GTK+ provides resource file mechanism for configuring
  10 various aspects of the operation of a GTK+ program
  11 at runtime.
  12 </para>
  13
  14 <refsect2><title>Default files</title>
  15 <para>
  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
  20 <filename>&lt;SYSCONFDIR&gt;/gtk-2.0/gtkrc</filename>
  21 and <filename>.gtkrc-3.0</filename> in the users home directory.
  22 (<filename>&lt;SYSCONFDIR&gt;</filename> defaults to
  23 <filename>/usr/local/etc</filename>. It can be changed with the
  24 <option>--prefix</option> or <option>--sysconfdir</option> options when
  25 configuring GTK+.)
  26 </para>
  27 <para>
  28 The set of these <firstterm>default</firstterm> files
  29 can be retrieved with gtk_rc_get_default_files()
  30 and modified with gtk_rc_add_default_file() and
  31 gtk_rc_set_default_files().
  32 Additionally, the <envar>GTK2_RC_FILES</envar> environment variable
  33 can be set to a #G_SEARCHPATH_SEPARATOR_S-separated list of files
  34 in order to overwrite the set of default files at runtime.
  35 </para>
  36 <para><anchor id="locale-specific-rc"/>
  37 For each RC file, in addition to the file itself, GTK+ will look for
  38 a locale-specific file that will be parsed after the main file.
  39 For instance, if <envar>LANG</envar> is set to <literal>ja_JP.ujis</literal>,
  40 when loading the default file <filename>~/.gtkrc</filename> then GTK+ looks
  41 for <filename>~/.gtkrc.ja_JP</filename> and <filename>~/.gtkrc.ja</filename>,
  42 and parses the first of those that exists.
  43 </para>
  44 </refsect2>
  45
  46 <refsect2><title>Pathnames and patterns</title>
  47 <anchor id="gtkrc-pathnames-and-patterns"/>
  48 <para>
  49 A resource file defines a number of styles and key bindings and
  50 attaches them to particular widgets. The attachment is done
  51 by the <literal>widget</literal>, <literal>widget_class</literal>,
  52 and <literal>class</literal> declarations. As an example
  53 of such a statement:
  54
  55 <informalexample><programlisting>
  56 widget "mywindow.*.GtkEntry" style "my-entry-class"
  57 </programlisting></informalexample>
  58
  59 attaches the style <literal>"my-entry-class"</literal> to all
  60 widgets  whose <firstterm>widget path</firstterm> matches the
  61 <firstterm>pattern</firstterm> <literal>"mywindow.*.GtkEntry"</literal>.
  62 That is, all #GtkEntry widgets which are part of a #GtkWindow named
  63 <literal>"mywindow"</literal>.
  64 </para>
  65
  66 <para>
  67 The patterns here are given in the standard shell glob syntax.
  68 The <literal>"?"</literal> wildcard matches any character, while
  69 <literal>"*"</literal> matches zero or more of any character.
  70 The three types of matching are against the widget path, the
  71 <firstterm>class path</firstterm> and the class hierarchy. Both the
  72 widget path and the class path consist of a <literal>"."</literal>
  73 separated list of all the parents of the widget and the widget itself
  74 from outermost to innermost. The difference is that in the widget path,
  75 the name assigned by gtk_widget_set_name() is used if present, otherwise
  76 the class name of the widget, while for the class path, the class name is
  77 always used.
  78 </para>
  79 <para>
  80 Since GTK+ 2.10,<literal>widget_class</literal> paths can also contain
  81 <literal>&lt;classname&gt;</literal> substrings, which are matching
  82 the class with the given name and any derived classes. For instance,
  83 <informalexample><programlisting>
  84 widget_class "*&lt;GtkMenuItem&gt;.GtkLabel" style "my-style"
  85 </programlisting></informalexample>
  86 will match #GtkLabel widgets which are contained in any kind of menu item.
  87 </para>
  88 <para>
  89 So, if you have a #GtkEntry named <literal>"myentry"</literal>, inside of a
  90 horizontal box in a window named <literal>"mywindow"</literal>, then the
  91 widget path is: <literal>"mywindow.GtkHBox.myentry"</literal>
  92 while the class path is: <literal>"GtkWindow.GtkHBox.GtkEntry"</literal>.
  93 </para>
  94 <para>
  95 Matching against class is a little different. The pattern match is done
  96 against all class names in the widgets class hierarchy (not the layout
  97 hierarchy) in sequence, so the pattern:
  98 <informalexample><programlisting>
  99 class "GtkButton" style "my-style"
 100 </programlisting></informalexample>
 101 will match not just #GtkButton widgets, but also #GtkToggleButton and
 102 #GtkCheckButton widgets, since those classes derive from #GtkButton.
 103 </para>
 104 <para>
 105 Additionally, a priority can be specified for each pattern, and styles
 106 override other styles first by priority, then by pattern type and then
 107 by order of specification (later overrides earlier). The priorities
 108 that can be specified are (highest to lowest):
 109 <simplelist>
 110 <member><literal>highest</literal></member>
 111 <member><literal>rc</literal></member>
 112 <member><literal>theme</literal></member>
 113 <member><literal>application</literal></member>
 114 <member><literal>gtk</literal></member>
 115 <member><literal>lowest</literal></member>
 116 </simplelist>
 117 <literal>rc</literal> is the default for styles
 118 read from an RC file, <literal>theme</literal>
 119 is the default for styles read from theme RC files,
 120 <literal>application</literal>
 121 should be used for styles an application sets
 122 up, and <literal>gtk</literal> is used for styles
 123 that GTK+ creates internally.
 124 </para>
 125
 126 </refsect2>
 127
 128 <refsect2><title>Theme gtkrc files</title>
 129 <anchor id="theme-gtkrc-files"/>
 130 <para>
 131 Theme RC files are loaded first from under the <filename>~/.themes/</filename>,
 132 then from the directory from gtk_rc_get_theme_dir(). The files looked at will
 133 be <filename>gtk-3.0/gtkrc</filename>.
 134 </para>
 135 <para>
 136 When the application prefers dark themes
 137 (see the #GtkSettings:gtk-application-prefer-dark-theme property for details),
 138 <filename>gtk-3.0/gtkrc-dark</filename> will be loaded first, and if not present
 139 <filename>gtk-3.0/gtkrc</filename> will be loaded.
 140 </para>
 141 </refsect2>
 142
 143 <refsect2>
 144 <anchor id="optimizing-rc-style-matches"/>
 145 <title>Optimizing RC Style Matches</title>
 146 <para>
 147 Everytime a widget is created and added to the layout hierarchy of a #GtkWindow
 148 ("anchored" to be exact), a list of matching RC styles out of all RC styles read
 149 in so far is composed.
 150 For this, every RC style is matched against the widgets class path,
 151 the widgets name path and widgets inheritance hierarchy.
 152 As a consequence, significant slowdown can be caused by utilization of many
 153 RC styles and by using RC style patterns that are slow or complicated to match
 154 against a given widget.
 155 The following ordered list provides a number of advices (prioritized by
 156 effectiveness) to reduce the performance overhead associated with RC style
 157 matches:
 158
 159 <orderedlist>
 160
 161   <listitem><para>
 162   Move RC styles for specific applications into RC files dedicated to those
 163   applications and parse application specific RC files only from
 164   applications that are affected by them.
 165   This reduces the overall amount of RC styles that have to be considered
 166   for a match across a group of applications.
 167   </para></listitem>
 168
 169   <listitem><para>
 170   Merge multiple styles which use the same matching rule, for instance:
 171 <informalexample><programlisting>
 172      style "Foo" { foo_content }
 173      class "X" style "Foo"
 174      style "Bar" { bar_content }
 175      class "X" style "Bar"
 176 </programlisting></informalexample>
 177    is faster to match as:
 178 <informalexample><programlisting>
 179      style "FooBar" { foo_content bar_content }
 180      class "X" style "FooBar"
 181 </programlisting></informalexample>
 182   </para></listitem>
 183
 184   <listitem><para>
 185   Use of wildcards should be avoided, this can reduce the individual RC style
 186   match to a single integer comparison in most cases.
 187   </para></listitem>
 188
 189   <listitem><para>
 190   To avoid complex recursive matching, specification of full class names
 191   (for <literal>class</literal> matches) or full path names (for
 192   <literal>widget</literal> and <literal>widget_class</literal> matches)
 193   is to be preferred over shortened names
 194   containing <literal>"*"</literal> or <literal>"?"</literal>.
 195   </para></listitem>
 196
 197   <listitem><para>
 198   If at all necessary, wildcards should only be used at the tail or head
 199   of a pattern. This reduces the match complexity to a string comparison
 200   per RC style.
 201   </para></listitem>
 202
 203   <listitem><para>
 204   When using wildcards, use of <literal>"?"</literal> should be preferred
 205   over <literal>"*"</literal>. This can reduce the matching complexity from
 206   O(n^2) to O(n). For example <literal>"Gtk*Box"</literal> can be turned into
 207   <literal>"Gtk?Box"</literal> and will still match #GtkHBox and #GtkVBox.
 208   </para></listitem>
 209
 210   <listitem><para>
 211   The use of <literal>"*"</literal> wildcards should be restricted as much
 212   as possible, because matching <literal>"A*B*C*RestString"</literal> can
 213   result in matching complexities of O(n^2) worst case.
 214   </para></listitem>
 215 </orderedlist>
 216
 217 </para>
 218 </refsect2>
 219
 220 <refsect2><title>Toplevel declarations</title>
 221 <para>
 222 An RC file is a text file which is composed of a sequence
 223 of declarations. <literal>'#'</literal> characters delimit comments and
 224 the portion of a line after a <literal>'#'</literal> is ignored when parsing
 225 an RC file.
 226 </para>
 227
 228 <para>
 229 The possible toplevel declarations are:
 230
 231 <variablelist>
 232   <varlistentry>
 233     <term><literal>binding <replaceable>name</replaceable>
 234      { ... }</literal></term>
 235     <listitem>
 236       <para>Declares a binding set.</para>
 237     </listitem>
 238   </varlistentry>
 239
 240   <varlistentry>
 241     <term><literal>class <replaceable>pattern</replaceable>
 242           [ style | binding ][ : <replaceable>priority</replaceable> ]
 243           <replaceable>name</replaceable></literal></term>
 244     <listitem>
 245      <para>Specifies a style or binding set for a particular
 246      branch of the inheritance hierarchy.</para>
 247     </listitem>
 248   </varlistentry>
 249
 250   <varlistentry>
 251     <term><literal>include <replaceable>filename</replaceable></literal></term>
 252     <listitem>
 253       <para>Parses another file at this point. If
 254         <replaceable>filename</replaceable> is not an absolute filename,
 255         it is searched in the directories of the currently open RC files.
 256       </para>
 257       <para>GTK+ also tries to load a
 258         <link linkend="locale-specific-rc">locale-specific variant</link> of
 259         the included file.
 260        </para>
 261     </listitem>
 262   </varlistentry>
 263
 264   <varlistentry>
 265     <term><literal>module_path <replaceable>path</replaceable></literal></term>
 266     <listitem>
 267       <para>Sets a path (a list of directories separated
 268       by colons) that will be searched for theme engines referenced in
 269       RC files.</para>
 270     </listitem>
 271   </varlistentry>
 272
 273   <varlistentry>
 274     <term><literal>pixmap_path <replaceable>path</replaceable></literal></term>
 275     <listitem>
 276       <para>Sets a path (a list of directories separated
 277       by colons) that will be searched for pixmaps referenced in
 278       RC files.</para>
 279     </listitem>
 280   </varlistentry>
 281
 282   <varlistentry>
 283     <term><literal>im_module_file <replaceable>pathname</replaceable></literal></term>
 284     <listitem>
 285       <para>Sets the pathname for the IM modules file. Setting this from RC files
 286       is deprecated; you should use the environment variable <envar>GTK_IM_MODULE_FILE</envar>
 287       instead.</para>
 288     </listitem>
 289   </varlistentry>
 290
 291   <varlistentry>
 292     <term><literal>style <replaceable>name</replaceable> [ =
 293     <replaceable>parent</replaceable> ] { ... }</literal></term>
 294     <listitem>
 295       <para>Declares a style.</para>
 296     </listitem>
 297   </varlistentry>
 298
 299   <varlistentry>
 300     <term><literal>widget <replaceable>pattern</replaceable>
 301           [ style | binding ][ : <replaceable>priority</replaceable> ]
 302           <replaceable>name</replaceable></literal></term>
 303     <listitem>
 304      <para>Specifies a style or binding set for a particular
 305      group of widgets by matching on the widget pathname.</para>
 306     </listitem>
 307   </varlistentry>
 308
 309   <varlistentry>
 310     <term><literal>widget_class <replaceable>pattern</replaceable>
 311           [ style | binding ][ : <replaceable>priority</replaceable> ]
 312           <replaceable>name</replaceable></literal></term>
 313     <listitem>
 314      <para>Specifies a style or binding set for a particular
 315      group of widgets by matching on the class pathname.</para>
 316     </listitem>
 317   </varlistentry>
 318
 319   <varlistentry>
 320     <term><replaceable>setting</replaceable> = <replaceable>value</replaceable></term>
 321     <listitem>
 322       <para>Specifies a value for a <link linkend="GtkSettings">setting</link>.
 323         Note that settings in RC files are overwritten by system-wide settings
 324         (which are managed by an XSettings manager on X11).</para>
 325     </listitem>
 326   </varlistentry>
 327 </variablelist>
 328 </para>
 329 </refsect2>
 330
 331 <refsect2><title>Styles</title>
 332 <para>
 333 A RC style is specified by a <literal>style</literal>
 334 declaration in a RC file, and then bound to widgets
 335 with a <literal>widget</literal>, <literal>widget_class</literal>,
 336 or <literal>class</literal> declaration. All styles
 337 applying to a particular widget are composited together
 338 with <literal>widget</literal> declarations overriding
 339 <literal>widget_class</literal> declarations which, in
 340 turn, override <literal>class</literal> declarations.
 341 Within each type of declaration, later declarations override
 342 earlier ones.
 343 </para>
 344
 345 <para>
 346 Within a <literal>style</literal> declaration, the possible
 347 elements are:
 348
 349 <variablelist>
 350   <varlistentry>
 351     <term><literal>bg[<replaceable>state</replaceable>] =
 352       <replaceable>color</replaceable></literal></term>
 353      <listitem>
 354        <para>
 355          Sets the color used for the background of most widgets.
 356        </para>
 357      </listitem>
 358   </varlistentry>
 359   <varlistentry>
 360     <term><literal>fg[<replaceable>state</replaceable>] =
 361       <replaceable>color</replaceable></literal></term>
 362      <listitem>
 363        <para>
 364          Sets the color used for the foreground of most widgets.
 365        </para>
 366      </listitem>
 367   </varlistentry>
 368   <varlistentry>
 369     <term><literal>base[<replaceable>state</replaceable>] =
 370       <replaceable>color</replaceable></literal></term>
 371      <listitem>
 372        <para>
 373          Sets the color used for the background of widgets displaying
 374          editable text. This color is used for the background
 375          of, among others, #GtkText, #GtkEntry, #GtkList, and #GtkCList.
 376        </para>
 377      </listitem>
 378   </varlistentry>
 379   <varlistentry>
 380     <term><literal>text[<replaceable>state</replaceable>] =
 381       <replaceable>color</replaceable></literal></term>
 382      <listitem>
 383        <para>
 384          Sets the color used for foreground of widgets using
 385          <literal>base</literal> for the background color.
 386        </para>
 387      </listitem>
 388   </varlistentry>
 389   <varlistentry>
 390     <term><literal>xthickness =
 391       <replaceable>number</replaceable></literal></term>
 392      <listitem>
 393        <para>
 394          Sets the xthickness, which is used for various horizontal padding
 395          values in GTK+.
 396        </para>
 397      </listitem>
 398   </varlistentry>
 399   <varlistentry>
 400     <term><literal>ythickness =
 401       <replaceable>number</replaceable></literal></term>
 402      <listitem>
 403        <para>
 404          Sets the ythickness, which is used for various vertical padding
 405          values in GTK+.
 406        </para>
 407      </listitem>
 408   </varlistentry>
 409
 410   <varlistentry>
 411     <term><literal>bg_pixmap[<replaceable>state</replaceable>] =
 412       <replaceable>pixmap</replaceable></literal></term>
 413      <listitem>
 414        <para>
 415          Sets a background pixmap to be used in place of
 416          the <literal>bg</literal> color (or for #GtkText,
 417          in place of the <literal>base</literal> color. The special
 418          value <literal>"&lt;parent&gt;"</literal> may be used to indicate that the widget should
 419          use the same background pixmap as its parent. The special value
 420          <literal>"&lt;none&gt;"</literal> may be used to indicate no background pixmap.
 421        </para>
 422      </listitem>
 423   </varlistentry>
 424   <varlistentry>
 425     <term><literal>font = <replaceable>font</replaceable></literal></term>
 426      <listitem>
 427        <para>
 428          Starting with GTK+ 2.0, the "font" and "fontset"
 429          declarations are ignored; use "font_name" declarations instead.
 430        </para>
 431      </listitem>
 432   </varlistentry>
 433   <varlistentry>
 434     <term><literal>fontset = <replaceable>font</replaceable></literal></term>
 435      <listitem>
 436        <para>
 437          Starting with GTK+ 2.0, the "font" and "fontset"
 438          declarations are ignored; use "font_name" declarations instead.
 439        </para>
 440      </listitem>
 441   </varlistentry>
 442   <varlistentry>
 443     <term><literal>font_name = <replaceable>font</replaceable></literal></term>
 444      <listitem>
 445        <para>
 446          Sets the font for a widget. <replaceable>font</replaceable> must be
 447          a Pango font name, e.g. <literal>"Sans Italic 10"</literal>.
 448          For details about Pango font names, see
 449          pango_font_description_from_string().
 450        </para>
 451      </listitem>
 452   </varlistentry>
 453   <varlistentry>
 454     <term><literal>stock[<replaceable>"stock-id"</replaceable>] = { <replaceable>icon source specifications</replaceable> }</literal></term>
 455      <listitem>
 456        <para>
 457         Defines the icon for a stock item.
 458        </para>
 459      </listitem>
 460   </varlistentry>
 461   <varlistentry>
 462     <term><literal>color[<replaceable>"color-name"</replaceable>] = <replaceable>color specification</replaceable></literal></term>
 463      <listitem>
 464        <para>
 465         Since 2.10, this element can be used to defines symbolic colors. See below for
 466         the syntax of color specifications.
 467        </para>
 468      </listitem>
 469   </varlistentry>
 470   <varlistentry>
 471     <term><literal>engine <replaceable>"engine"</replaceable> { <replaceable>engine-specific
 472 settings</replaceable> }</literal></term>
 473      <listitem>
 474        <para>
 475         Defines the engine to be used when drawing with this style.
 476        </para>
 477      </listitem>
 478   </varlistentry>
 479   <varlistentry>
 480     <term><literal><replaceable>class</replaceable>::<replaceable>property</replaceable> = <replaceable>value</replaceable></literal></term>
 481      <listitem>
 482        <para>
 483         Sets a <link linkend="style-properties">style property</link> for a widget class.
 484        </para>
 485      </listitem>
 486   </varlistentry>
 487 </variablelist>
 488 </para>
 489 <para>
 490 The colors and background pixmaps are specified as a function of the
 491 state of the widget. The states are:
 492
 493 <variablelist>
 494   <varlistentry>
 495     <term><literal>NORMAL</literal></term>
 496     <listitem>
 497       <para>
 498         A color used for a widget in its normal state.
 499       </para>
 500     </listitem>
 501   </varlistentry>
 502   <varlistentry>
 503     <term><literal>ACTIVE</literal></term>
 504     <listitem>
 505       <para>
 506         A variant of the <literal>NORMAL</literal> color used when the
 507         widget is in the %GTK_STATE_ACTIVE state, and also for
 508         the trough of a ScrollBar, tabs of a NoteBook
 509         other than the current tab and similar areas.
 510         Frequently, this should be a darker variant
 511         of the <literal>NORMAL</literal> color.
 512       </para>
 513     </listitem>
 514   </varlistentry>
 515   <varlistentry>
 516     <term><literal>PRELIGHT</literal></term>
 517     <listitem>
 518       <para>
 519         A color used for widgets in the %GTK_STATE_PRELIGHT state. This
 520         state is the used for Buttons and MenuItems
 521         that have the mouse cursor over them, and for
 522         their children.
 523       </para>
 524     </listitem>
 525   </varlistentry>
 526   <varlistentry>
 527     <term><literal>SELECTED</literal></term>
 528     <listitem>
 529       <para>
 530         A color used to highlight data selected by the user.
 531         for instance, the selected items in a list widget, and the
 532         selection in an editable widget.
 533       </para>
 534     </listitem>
 535   </varlistentry>
 536   <varlistentry>
 537     <term><literal>INSENSITIVE</literal></term>
 538     <listitem>
 539       <para>
 540         A color used for the background of widgets that have
 541         been set insensitive with gtk_widget_set_sensitive().
 542       </para>
 543     </listitem>
 544   </varlistentry>
 545 </variablelist>
 546 </para>
 547
 548 <para><anchor id="color-format"/>
 549 Colors can be specified as a string containing a color name (GTK+ knows
 550 all names from the X color database <filename>/usr/lib/X11/rgb.txt</filename>),
 551 in one of the hexadecimal forms <literal>&num;rrrrggggbbbb</literal>,
 552 <literal>&num;rrrgggbbb</literal>, <literal>&num;rrggbb</literal>,
 553 or <literal>&num;rgb</literal>, where <literal>r</literal>,
 554 <literal>g</literal> and <literal>b</literal> are
 555 hex digits, or they can be specified as a triplet
 556 <literal>{ <replaceable>r</replaceable>, <replaceable>g</replaceable>,
 557 <replaceable>b</replaceable>}</literal>, where <literal>r</literal>,
 558 <literal>g</literal> and <literal>b</literal> are either integers in
 559 the range 0-65535 or floats in the range 0.0-1.0.
 560 </para>
 561 <para>
 562 Since 2.10, colors can also be specified by refering to a symbolic color, as
 563 follows: <literal>@<!-- -->color-name</literal>, or by using expressions to combine
 564 colors. The following expressions are currently supported:
 565   <variablelist>
 566     <varlistentry>
 567       <term>mix (<replaceable>factor</replaceable>, <replaceable>color1</replaceable>, <replaceable>color2</replaceable>)</term>
 568       <listitem><para>
 569         Computes a new color by mixing <replaceable>color1</replaceable> and
 570         <replaceable>color2</replaceable>. The <replaceable>factor</replaceable>
 571         determines how close the new color is to <replaceable>color1</replaceable>.
 572         A factor of 1.0 gives pure <replaceable>color1</replaceable>, a factor of
 573         0.0 gives pure <replaceable>color2</replaceable>.
 574       </para></listitem>
 575     </varlistentry>
 576
 577     <varlistentry>
 578       <term>shade (<replaceable>factor</replaceable>, <replaceable>color</replaceable>)</term>
 579       <listitem><para>
 580         Computes a lighter or darker variant of <replaceable>color</replaceable>.
 581         A <replaceable>factor</replaceable> of 1.0 leaves the color unchanged, smaller
 582         factors yield darker colors, larger factors yield lighter colors.
 583       </para></listitem>
 584     </varlistentry>
 585
 586     <varlistentry>
 587       <term>lighter (<replaceable>color</replaceable>)</term>
 588       <listitem><para>
 589         This is an abbreviation for
 590         <literal>shade (1.3, <replaceable>color</replaceable>)</literal>.
 591       </para></listitem>
 592     </varlistentry>
 593
 594     <varlistentry>
 595       <term>darker (<replaceable>color</replaceable>)</term>
 596       <listitem><para>
 597         This is an abbreviation for
 598         <literal>shade (0.7, <replaceable>color</replaceable>)</literal>.
 599       </para></listitem>
 600     </varlistentry>
 601   </variablelist>
 602 </para>
 603 <para>
 604 Here are some examples of color expressions:
 605 <informalexample><programlisting>
 606  mix (0.5, "red", "blue")
 607  shade (1.5, mix (0.3, "&num;0abbc0", { 0.3, 0.5, 0.9 }))
 608  lighter (@<!-- -->foreground)
 609 </programlisting></informalexample>
 610 </para>
 611
 612 <para>
 613 In a <literal>stock</literal> definition, icon sources are specified as a
 614 4-tuple of image filename or icon name, text direction, widget state, and size, in that
 615 order.  Each icon source specifies an image filename or icon name to use with a given
 616 direction, state, and size. Filenames are specified as a string such
 617 as <literal>"itemltr.png"</literal>, while icon names (looked up
 618 in the current icon theme), are specified with a leading
 619 <literal>@</literal>, such as <literal>@"item-ltr"</literal>.
 620 The <literal>*</literal> character can be used as a
 621 wildcard, and if direction/state/size are omitted they default to
 622 <literal>*</literal>. So for example, the following specifies different icons to
 623 use for left-to-right and right-to-left languages:
 624 <informalexample><programlisting>
 625 stock["my-stock-item"] =
 626 {
 627   { "itemltr.png", LTR, *, * },
 628   { "itemrtl.png", RTL, *, * }
 629 }
 630 </programlisting></informalexample>
 631 This could be abbreviated as follows:
 632 <informalexample><programlisting>
 633 stock["my-stock-item"] =
 634 {
 635   { "itemltr.png", LTR },
 636   { "itemrtl.png", RTL }
 637 }
 638 </programlisting></informalexample>
 639 </para>
 640
 641 <para>
 642 You can specify custom icons for specific sizes, as follows:
 643 <informalexample><programlisting>
 644 stock["my-stock-item"] =
 645 {
 646   { "itemmenusize.png", *, *, "gtk-menu" },
 647   { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" }
 648   { "itemgeneric.png" } /* implicit *, *, * as a fallback */
 649 }
 650 </programlisting></informalexample>
 651 The sizes that come with GTK+ itself are <literal>"gtk-menu"</literal>,
 652 <literal>"gtk-small-toolbar"</literal>, <literal>"gtk-large-toolbar"</literal>,
 653 <literal>"gtk-button"</literal>, <literal>"gtk-dialog"</literal>. Applications
 654 can define other sizes.
 655 </para>
 656
 657 <para>
 658 It's also possible to use custom icons for a given state, for example:
 659 <informalexample><programlisting>
 660 stock["my-stock-item"] =
 661 {
 662   { "itemprelight.png", *, PRELIGHT },
 663   { "iteminsensitive.png", *, INSENSITIVE },
 664   { "itemgeneric.png" } /* implicit *, *, * as a fallback */
 665 }
 666 </programlisting></informalexample>
 667 </para>
 668
 669 <para>
 670 When selecting an icon source to use, GTK+ will consider text direction most
 671 important, state second, and size third. It will select the best match based on
 672 those criteria. If an attribute matches exactly (e.g. you specified
 673 <literal>PRELIGHT</literal> or specified the size), GTK+ won't modify the image;
 674 if the attribute matches with a wildcard, GTK+ will scale or modify the image to
 675 match the state and size the user requested.
 676 </para>
 677
 678 </refsect2>
 679
 680 <refsect2><title>Key bindings</title>
 681 <para>
 682 Key bindings allow the user to specify actions to be
 683 taken on particular key presses. The form of a binding
 684 set declaration is:
 685 </para>
 686
 687 <informalexample><programlisting>
 688 binding <replaceable>name</replaceable> {
 689   bind <replaceable>key</replaceable> {
 690     <replaceable>signalname</replaceable> (<replaceable>param</replaceable>, ...)
 691     ...
 692   }
 693   ...
 694 }
 695 </programlisting></informalexample>
 696
 697 <para>
 698 <replaceable>key</replaceable> is a string consisting of a
 699 series of modifiers followed by the name of a key. The
 700 modifiers can be:
 701 <simplelist>
 702 <member><literal>&lt;alt&gt;</literal></member>
 703 <member><literal>&lt;ctl&gt;</literal></member>
 704 <member><literal>&lt;control&gt;</literal></member>
 705 <member><literal>&lt;meta&gt;</literal></member>
 706 <member><literal>&lt;hyper&gt;</literal></member>
 707 <member><literal>&lt;super&gt;</literal></member>
 708 <member><literal>&lt;mod1&gt;</literal></member>
 709 <member><literal>&lt;mod2&gt;</literal></member>
 710 <member><literal>&lt;mod3&gt;</literal></member>
 711 <member><literal>&lt;mod4&gt;</literal></member>
 712 <member><literal>&lt;mod5&gt;</literal></member>
 713 <member><literal>&lt;release&gt;</literal></member>
 714 <member><literal>&lt;shft&gt;</literal></member>
 715 <member><literal>&lt;shift&gt;</literal></member>
 716 </simplelist>
 717 <literal>&lt;shft&gt;</literal> is an alias for
 718 <literal>&lt;shift&gt;</literal>,
 719 <literal>&lt;ctl&gt;</literal> is an alias for
 720 <literal>&lt;control&gt;</literal>,
 721  and
 722 <literal>&lt;alt&gt;</literal> is an alias for
 723 <literal>&lt;mod1&gt;</literal>.
 724 </para>
 725
 726 <para>
 727 The action that is bound to the key is a sequence
 728 of signal names (strings) followed by parameters for
 729 each signal. The signals must be action signals.
 730 (See g_signal_new()). Each parameter can be
 731 a float, integer, string, or unquoted string
 732 representing an enumeration value. The types of
 733 the parameters specified must match the types of the
 734 parameters of the signal.
 735 </para>
 736
 737 <para>
 738 Binding sets are connected to widgets in the same manner as styles,
 739 with one difference: Binding sets override other binding sets first
 740 by pattern type, then by priority and then by order of specification.
 741 The priorities that can be specified and their default values are the
 742 same as for styles.
 743 </para>
 744 </refsect2>
 745
 746 <!-- ##### SECTION See_Also ##### -->
 747 <para>
 748
 749 </para>
 750
 751 <!-- ##### SECTION Stability_Level ##### -->
 752
 753
 754 <!-- ##### SECTION Image ##### -->
 755
 756
 757 <!-- ##### STRUCT GtkRcStyle ##### -->
 758 <para>
 759 The #GtkRcStyle structure is used to represent a set
 760 of information about the appearance of a widget.
 761 This can later be composited together with other
 762 #GtkRcStyle structures to form a #GtkStyle.
 763 </para>
 764
 765 @name:
 766 @bg_pixmap_name:
 767 @font_desc:
 768 @color_flags:
 769 @fg:
 770 @bg:
 771 @text:
 772 @base:
 773 @xthickness:
 774 @ythickness:
 775
 776 <!-- ##### ENUM GtkRcFlags ##### -->
 777 <para>
 778 The #GtkRcFlags enumeration is used as a bitmask
 779 to specify which fields of a #GtkRcStyle have been
 780 set for each state.
 781 </para>
 782
 783 @GTK_RC_FG: If present, the foreground color has been set for this state.
 784 @GTK_RC_BG: If present, the background color has been set for this state.
 785 @GTK_RC_TEXT: If present, the text color has been set for this state.
 786 @GTK_RC_BASE: If present, the base color has been set for this state.
 787
 788 <!-- ##### ENUM GtkRcTokenType ##### -->
 789 <para>
 790 The #GtkRcTokenType enumeration represents the tokens
 791 in the RC file. It is exposed so that theme engines
 792 can reuse these tokens when parsing the theme-engine
 793 specific portions of a RC file.
 794 </para>
 795
 796 @GTK_RC_TOKEN_INVALID:
 797 @GTK_RC_TOKEN_INCLUDE:
 798 @GTK_RC_TOKEN_NORMAL:
 799 @GTK_RC_TOKEN_ACTIVE:
 800 @GTK_RC_TOKEN_PRELIGHT:
 801 @GTK_RC_TOKEN_SELECTED:
 802 @GTK_RC_TOKEN_INSENSITIVE:
 803 @GTK_RC_TOKEN_FG:
 804 @GTK_RC_TOKEN_BG:
 805 @GTK_RC_TOKEN_TEXT:
 806 @GTK_RC_TOKEN_BASE:
 807 @GTK_RC_TOKEN_XTHICKNESS:
 808 @GTK_RC_TOKEN_YTHICKNESS:
 809 @GTK_RC_TOKEN_FONT:
 810 @GTK_RC_TOKEN_FONTSET:
 811 @GTK_RC_TOKEN_FONT_NAME:
 812 @GTK_RC_TOKEN_BG_PIXMAP:
 813 @GTK_RC_TOKEN_PIXMAP_PATH:
 814 @GTK_RC_TOKEN_STYLE:
 815 @GTK_RC_TOKEN_BINDING:
 816 @GTK_RC_TOKEN_BIND:
 817 @GTK_RC_TOKEN_WIDGET:
 818 @GTK_RC_TOKEN_WIDGET_CLASS:
 819 @GTK_RC_TOKEN_CLASS:
 820 @GTK_RC_TOKEN_LOWEST:
 821 @GTK_RC_TOKEN_GTK:
 822 @GTK_RC_TOKEN_APPLICATION:
 823 @GTK_RC_TOKEN_THEME:
 824 @GTK_RC_TOKEN_RC:
 825 @GTK_RC_TOKEN_HIGHEST:
 826 @GTK_RC_TOKEN_ENGINE:
 827 @GTK_RC_TOKEN_MODULE_PATH:
 828 @GTK_RC_TOKEN_IM_MODULE_PATH:
 829 @GTK_RC_TOKEN_IM_MODULE_FILE:
 830 @GTK_RC_TOKEN_STOCK:
 831 @GTK_RC_TOKEN_LTR:
 832 @GTK_RC_TOKEN_RTL:
 833 @GTK_RC_TOKEN_COLOR:
 834 @GTK_RC_TOKEN_UNBIND:
 835 @GTK_RC_TOKEN_LAST:
 836
 837 <!-- ##### FUNCTION gtk_rc_scanner_new ##### -->
 838 <para>
 839
 840 </para>
 841
 842 @void:
 843 @Returns:
 844
 845
 846 <!-- ##### FUNCTION gtk_rc_get_style ##### -->
 847 <para>
 848 </para>
 849
 850 @widget:
 851 @Returns:
 852
 853
 854 <!-- ##### FUNCTION gtk_rc_get_style_by_paths ##### -->
 855 <para>
 856
 857 </para>
 858
 859 @settings:
 860 @widget_path:
 861 @class_path:
 862 @type:
 863 @Returns:
 864
 865
 866 <!-- ##### FUNCTION gtk_rc_parse ##### -->
 867 <para>
 868 Parses a given resource file.
 869 </para>
 870
 871 @filename: the filename of a file to parse. If @filename is not absolute, it
 872   is searched in the current directory.
 873
 874
 875 <!-- ##### FUNCTION gtk_rc_parse_string ##### -->
 876 <para>
 877 Parses resource information directly from a string.
 878 </para>
 879
 880 @rc_string: a string to parse.
 881
 882
 883 <!-- ##### FUNCTION gtk_rc_reparse_all ##### -->
 884 <para>
 885 </para>
 886
 887 @void:
 888 @Returns:
 889
 890
 891 <!-- ##### FUNCTION gtk_rc_reparse_all_for_settings ##### -->
 892 <para>
 893
 894 </para>
 895
 896 @settings:
 897 @force_load:
 898 @Returns:
 899
 900
 901 <!-- ##### FUNCTION gtk_rc_reset_styles ##### -->
 902 <para>
 903
 904 </para>
 905
 906 @settings:
 907
 908
 909 <!-- ##### FUNCTION gtk_rc_add_default_file ##### -->
 910 <para>
 911 </para>
 912
 913 @filename:
 914
 915
 916 <!-- ##### FUNCTION gtk_rc_get_default_files ##### -->
 917 <para>
 918 </para>
 919
 920 @void:
 921 @Returns:
 922
 923
 924 <!-- ##### FUNCTION gtk_rc_set_default_files ##### -->
 925 <para>
 926 </para>
 927
 928 @filenames:
 929
 930
 931 <!-- ##### FUNCTION gtk_rc_parse_color ##### -->
 932 <para>
 933
 934 </para>
 935
 936 @scanner:
 937 @color:
 938 @Returns:
 939
 940
 941 <!-- ##### FUNCTION gtk_rc_parse_color_full ##### -->
 942 <para>
 943
 944 </para>
 945
 946 @scanner:
 947 @style:
 948 @color:
 949 @Returns:
 950
 951
 952 <!-- ##### FUNCTION gtk_rc_parse_state ##### -->
 953 <para>
 954 Parses a #GtkStateType variable from the format expected
 955 in a RC file.
 956 </para>
 957
 958 @scanner: a #GtkScanner (must be initialized for parsing an RC file)
 959 @state: A pointer to a #GtkStateType variable in which to
 960 store the result.
 961 @Returns: %G_TOKEN_NONE if parsing succeeded, otherwise the token
 962 that was expected but not found.
 963
 964
 965 <!-- ##### FUNCTION gtk_rc_parse_priority ##### -->
 966 <para>
 967 Parses a #GtkPathPriorityType variable from the format expected
 968 in a RC file.
 969 </para>
 970
 971 @scanner: a #GtkScanner (must be initialized for parsing an RC file)
 972 @priority: A pointer to #GtkPathPriorityType variable in which
 973 to store the result.
 974 @Returns: %G_TOKEN_NONE if parsing succeeded, otherwise the token
 975 that was expected but not found.
 976
 977
 978 <!-- ##### FUNCTION gtk_rc_find_module_in_path ##### -->
 979 <para>
 980 </para>
 981
 982 @module_file: The name of the module to search for.
 983 @Returns:
 984
 985
 986 <!-- ##### FUNCTION gtk_rc_find_pixmap_in_path ##### -->
 987 <para>
 988 </para>
 989
 990 @settings:
 991 @scanner: a #GtkScanner. Used for printing out warning messages
 992 if the file is not found.
 993 @pixmap_file: The name of the file to search for.
 994 @Returns: The filename, if found (must be freed with g_free()),
 995 otherwise %NULL.
 996
 997
 998 <!-- ##### FUNCTION gtk_rc_get_module_dir ##### -->
 999 <para>
1000 </para>
1001
1002 @void:
1003 @Returns:
1004
1005
1006 <!-- ##### FUNCTION gtk_rc_get_im_module_path ##### -->
1007 <para>
1008
1009 </para>
1010
1011 @void:
1012 @Returns:
1013
1014
1015 <!-- ##### FUNCTION gtk_rc_get_im_module_file ##### -->
1016 <para>
1017
1018 </para>
1019
1020 @void:
1021 @Returns:
1022
1023
1024 <!-- ##### FUNCTION gtk_rc_get_theme_dir ##### -->
1025 <para>
1026 Returns the standard directory in which themes should
1027 be installed. (GTK+ does not actually use this directory
1028 itself.)
1029 </para>
1030
1031 @void:
1032 @Returns: The directory (must be freed with g_free()).
1033
1034
1035 <!-- ##### FUNCTION gtk_rc_style_new ##### -->
1036 <para>
1037 Creates a new #GtkRcStyle with no fields set and
1038 a reference count of 1.
1039 </para>
1040
1041 @void:
1042 @Returns: the newly-created #GtkRcStyle
1043
1044
1045 <!-- ##### FUNCTION gtk_rc_style_copy ##### -->
1046 <para>
1047
1048 </para>
1049
1050 @orig:
1051 @Returns:
1052
1053