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