gtkrc.sgml

This GTK+ version 2.12.3. GTK+ is a multi-platform toolkit for creating graphical user interfaces.

  <varlistentry>
    <term><literal>text[<replaceable>state</replaceable>] =
      <replaceable>color</replaceable></literal></term>
     <listitem>
       <para>
         Sets the color used for foreground of widgets using
         <literal>base</literal> for the background color.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>xthickness =
      <replaceable>number</replaceable></literal></term>
     <listitem>
       <para>
         Sets the xthickness, which is used for various horizontal padding
         values in GTK+.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>ythickness =
      <replaceable>number</replaceable></literal></term>
     <listitem>
       <para>
         Sets the ythickness, which is used for various vertical padding
         values in GTK+.
       </para>
     </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>bg_pixmap[<replaceable>state</replaceable>] =
      <replaceable>pixmap</replaceable></literal></term>
     <listitem>
       <para>
         Sets a background pixmap to be used in place of
         the <literal>bg</literal> color (or for #GtkText,
         in place of the <literal>base</literal> color. The special
         value <literal>"&lt;parent&gt;"</literal> may be used to indicate that the widget should
         use the same background pixmap as its parent. The special value
         <literal>"&lt;none&gt;"</literal> may be used to indicate no background pixmap.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>font = <replaceable>font</replaceable></literal></term>
     <listitem>
       <para>
         Starting with GTK+ 2.0, the "font" and "fontset"
         declarations are ignored; use "font_name" declarations instead.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>fontset = <replaceable>font</replaceable></literal></term>
     <listitem>
       <para>
         Starting with GTK+ 2.0, the "font" and "fontset"
         declarations are ignored; use "font_name" declarations instead.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>font_name = <replaceable>font</replaceable></literal></term>
     <listitem>
       <para>
         Sets the font for a widget. <replaceable>font</replaceable> must be 
         a Pango font name, e.g. <literal>"Sans Italic 10"</literal>. 
         For details about Pango font names, see 
         pango_font_description_from_string().
       </para>
     </listitem>   
  </varlistentry>
  <varlistentry>
    <term><literal>stock[<replaceable>"stock-id"</replaceable>] = { <replaceable>icon source specifications</replaceable> }</literal></term>
     <listitem>
       <para>
        Defines the icon for a stock item.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>color[<replaceable>"color-name"</replaceable>] = <replaceable>color specification</replaceable></literal></term>
     <listitem>
       <para>
        Since 2.10, this element can be used to defines symbolic colors. See below for
        the syntax of color specifications. 
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>engine <replaceable>"engine"</replaceable> { <replaceable>engine-specific
settings</replaceable> }</literal></term>
     <listitem>
       <para>
        Defines the engine to be used when drawing with this style.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal><replaceable>class</replaceable>::<replaceable>property</replaceable> = <replaceable>value</replaceable></literal></term>
     <listitem>
       <para>
        Sets a <link linkend="style-properties">style property</link> for a widget class.
       </para>
     </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
The colors and background pixmaps are specified as a function of the
state of the widget. The states are:

<variablelist>
  <varlistentry>
    <term><literal>NORMAL</literal></term>
    <listitem>
      <para>
        A color used for a widget in its normal state.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>ACTIVE</literal></term>
    <listitem>
      <para>
        A variant of the <literal>NORMAL</literal> color used when the
        widget is in the %GTK_STATE_ACTIVE state, and also for
        the trough of a ScrollBar, tabs of a NoteBook
        other than the current tab and similar areas.
        Frequently, this should be a darker variant
        of the <literal>NORMAL</literal> color.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>PRELIGHT</literal></term>
    <listitem>
      <para>
        A color used for widgets in the %GTK_STATE_PRELIGHT state. This
        state is the used for Buttons and MenuItems
        that have the mouse cursor over them, and for 
        their children.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>SELECTED</literal></term>
    <listitem>
      <para>
        A color used to highlight data selected by the user.
        for instance, the selected items in a list widget, and the
        selection in an editable widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>INSENSITIVE</literal></term>
    <listitem>
      <para>
        A color used for the background of widgets that have
        been set insensitive with gtk_widget_set_sensitive().
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</para>

<para><anchor id="color-format"/>
Colors can be specified as a string containing a color name (GTK+ knows
all names from the X color database <filename>/usr/lib/X11/rgb.txt</filename>),  
in one of the hexadecimal forms <literal>&num;rrrrggggbbbb</literal>,
<literal>&num;rrrgggbbb</literal>, <literal>&num;rrggbb</literal>,
or <literal>&num;rgb</literal>, where <literal>r</literal>,
<literal>g</literal> and <literal>b</literal> are
hex digits, or they can be specified as a triplet 
<literal>{ <replaceable>r</replaceable>, <replaceable>g</replaceable>,
<replaceable>b</replaceable>}</literal>, where <literal>r</literal>,
<literal>g</literal> and <literal>b</literal> are either integers in 
the range 0-65535 or floats in the range 0.0-1.0.
</para>
<para>
Since 2.10, colors can also be specified by refering to a symbolic color, as
follows: <literal>@<!-- -->color-name</literal>, or by using expressions to combine
colors. The following expressions are currently supported:
  <variablelist>
    <varlistentry>
      <term>mix (<replaceable>factor</replaceable>, <replaceable>color1</replaceable>, <replaceable>color2</replaceable>)</term>
      <listitem><para>
        Computes a new color by mixing <replaceable>color1</replaceable> and 
        <replaceable>color2</replaceable>. The <replaceable>factor</replaceable> 
        determines how close the new color is to <replaceable>color1</replaceable>. 
        A factor of 1.0 gives pure <replaceable>color1</replaceable>, a factor of 
        0.0 gives pure <replaceable>color2</replaceable>.  
      </para></listitem>        
    </varlistentry>

    <varlistentry>
      <term>shade (<replaceable>factor</replaceable>, <replaceable>color</replaceable>)</term>
      <listitem><para>
        Computes a lighter or darker variant of <replaceable>color</replaceable>. 
        A <replaceable>factor</replaceable> of 1.0 leaves the color unchanged, smaller 
        factors yield darker colors, larger factors yield lighter colors.
      </para></listitem>
    </varlistentry>

    <varlistentry>
      <term>lighter (<replaceable>color</replaceable>)</term>
      <listitem><para>
        This is an abbreviation for 
        <literal>shade (1.3, <replaceable>color</replaceable>)</literal>.
      </para></listitem>
    </varlistentry>

    <varlistentry>
      <term>darker (<replaceable>color</replaceable>)</term>
      <listitem><para>
        This is an abbreviation for 
        <literal>shade (0.7, <replaceable>color</replaceable>)</literal>.
      </para></listitem>
    </varlistentry>
  </variablelist>      
</para>
<para>
Here are some examples of color expressions:
<informalexample><programlisting>  
 mix (0.5, "red", "blue")
 shade (1.5, mix (0.3, "&num;0abbc0", { 0.3, 0.5, 0.9 }))
 lighter (@<!-- -->foreground)
</programlisting></informalexample>
</para>

<para>
In a <literal>stock</literal> definition, icon sources are specified as a
4-tuple of image filename or icon name, text direction, widget state, and size, in that
order.  Each icon source specifies an image filename or icon name to use with a given
direction, state, and size. Filenames are specified as a string such
as <literal>"itemltr.png"</literal>, while icon names (looked up
in the current icon theme), are specified with a leading
<literal>@</literal>, such as <literal>@"item-ltr"</literal>.
The <literal>*</literal> character can be used as a
wildcard, and if direction/state/size are omitted they default to
<literal>*</literal>. So for example, the following specifies different icons to
use for left-to-right and right-to-left languages:
<informalexample><programlisting>
stock["my-stock-item"] = 
{
  { "itemltr.png", LTR, *, * },
  { "itemrtl.png", RTL, *, * }
}
</programlisting></informalexample>
This could be abbreviated as follows:
<informalexample><programlisting>
stock["my-stock-item"] = 
{
  { "itemltr.png", LTR },
  { "itemrtl.png", RTL }
}
</programlisting></informalexample>
</para>

<para>
You can specify custom icons for specific sizes, as follows:
<informalexample><programlisting>
stock["my-stock-item"] = 
{
  { "itemmenusize.png", *, *, "gtk-menu" },
  { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" }
  { "itemgeneric.png" } /* implicit *, *, * as a fallback */
}
</programlisting></informalexample>
The sizes that come with GTK+ itself are <literal>"gtk-menu"</literal>,
<literal>"gtk-small-toolbar"</literal>, <literal>"gtk-large-toolbar"</literal>,
<literal>"gtk-button"</literal>, <literal>"gtk-dialog"</literal>. Applications
can define other sizes.
</para>

<para>
It's also possible to use custom icons for a given state, for example:
<informalexample><programlisting>
stock["my-stock-item"] = 
{
  { "itemprelight.png", *, PRELIGHT },
  { "iteminsensitive.png", *, INSENSITIVE }, 
  { "itemgeneric.png" } /* implicit *, *, * as a fallback */
}
</programlisting></informalexample>
</para>

<para>
When selecting an icon source to use, GTK+ will consider text direction most
important, state second, and size third. It will select the best match based on
those criteria. If an attribute matches exactly (e.g. you specified
<literal>PRELIGHT</literal> or specified the size), GTK+ won't modify the image;
if the attribute matches with a wildcard, GTK+ will scale or modify the image to
match the state and size the user requested.
</para>

</refsect2>

<refsect2><title>Key bindings</title>
<para>
Key bindings allow the user to specify actions to be 
taken on particular key presses. The form of a binding
set declaration is:
</para>

<informalexample><programlisting>
binding <replaceable>name</replaceable> {
  bind <replaceable>key</replaceable> { 
    <replaceable>signalname</replaceable> (<replaceable>param</replaceable>, ...)
    ...
  }
  ...
}
</programlisting></informalexample>

<para>
<replaceable>key</replaceable> is a string consisting of a 
series of modifiers followed by the name of a key. The
modifiers can be:
<simplelist>
<member><literal>&lt;alt&gt;</literal></member>
<member><literal>&lt;ctl&gt;</literal></member>
<member><literal>&lt;control&gt;</literal></member>
<member><literal>&lt;meta&gt;</literal></member>
<member><literal>&lt;hyper&gt;</literal></member>
<member><literal>&lt;super&gt;</literal></member>
<member><literal>&lt;mod1&gt;</literal></member>
<member><literal>&lt;mod2&gt;</literal></member>
<member><literal>&lt;mod3&gt;</literal></member>
<member><literal>&lt;mod4&gt;</literal></member>
<member><literal>&lt;mod5&gt;</literal></member>
<member><literal>&lt;release&gt;</literal></member>
<member><literal>&lt;shft&gt;</literal></member>
<member><literal>&lt;shift&gt;</literal></member>
</simplelist>
<literal>&lt;shft&gt;</literal> is an alias for 
<literal>&lt;shift&gt;</literal>,
<literal>&lt;ctl&gt;</literal> is an alias for 
<literal>&lt;control&gt;</literal>,
 and 
<literal>&lt;alt&gt;</literal> is an alias for
<literal>&lt;mod1&gt;</literal>.
</para>

<para>
The action that is bound to the key is a sequence
of signal names (strings) followed by parameters for 
each signal. The signals must be action signals.
(See g_signal_new()). Each parameter can be
a float, integer, string, or unquoted string
representing an enumeration value. The types of
the parameters specified must match the types of the 
parameters of the signal.
</para>

<para>
Binding sets are connected to widgets in the same manner as styles, 
with one difference: Binding sets override other binding sets first 
by pattern type, then by priority and then by order of specification.
The priorities that can be specified and their default values are the 
same as for styles.