<chapter id="css">
  <title>CSS in GTK</title>
  <para>
    This chapter describes how GTK uses CSS for styling and layout. It
    is not meant to be an explanation of CSS from first principles, but
    focuses on listing supported CSS features and differences between
    Web CSS and GTK.
  </para>
  <para>
    There is plenty of introductory documentation available that can be
    used to learn about CSS in general. In the tables below we include
    links to the official specs that can be used to look up the
    definition of individual selectors and properties.
  </para>
  <sect1>
    <title>CSS nodes</title>
    <para>
      GTK applies the style information found in style sheets by
      matching the selectors against a tree of nodes. Each node in the
      tree has a name, a state and possibly style classes. The children
      of each node are linearly ordered.
    </para>
    <para>
      Every widget has one or more of these CSS nodes, and determines
      their name, state, style classes and how they are laid out as
      children and siblings in the overall node tree. The documentation
      for each widget explains what CSS nodes it has.
    </para>
    <sect2>
      <title>The CSS nodes of a GtkScale</title>
      <programlisting>
scale[.fine-tune]
├── marks.top
│   ├── mark
┊   ┊
│   ╰── mark
├── trough
│   ├── slider
│   ├── [highlight]
│   ╰── [fill]
╰── marks.bottom
    ├── mark
    ┊
    ╰── mark
</programlisting>
    </sect2>
  </sect1>
  <sect1>
    <title>Selectors</title>
    <para>
      Selectors work very similar to the way they do on the web.
    </para>
    <para>
      All widgets have one or more CSS nodes with element names and
      style classes. When style classes are used in selectors, they have
      to be prefixed with a period. Widget names can be used in
      selectors like IDs. When used in a selector, widget names must be
      prefixed with a # character.
    </para>
    <sect2>
      <title>GTK CSS Selectors</title>
      <informaltable>
        <tgroup cols="3">
          <colspec colwidth="33*" align="left" />
          <colspec colwidth="40*" align="left" />
          <colspec colwidth="25*" align="left" />
          <thead>
            <row>
              <entry>
                Pattern
              </entry>
              <entry>
                Reference
              </entry>
              <entry>
                Notes
              </entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>
                *
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#universal-selector">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
              </entry>
            </row>
            <row>
              <entry>
                E
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#type-selectors">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
              </entry>
            </row>
            <row>
              <entry>
                E.class
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#class-html">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
              </entry>
            </row>
            <row>
              <entry>
                E#id
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#id-selectors">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
              </entry>
            </row>
            <row>
              <entry>
                E:nth-child(n)
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#structural-pseudos">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
              </entry>
            </row>
            <row>
              <entry>
                E:nth-last-child(n)
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#structural-pseudos">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
              </entry>
            </row>
            <row>
              <entry>
                E:first-child
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#structural-pseudos">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
              </entry>
            </row>
            <row>
              <entry>
                E:last-child
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#structural-pseudos">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
              </entry>
            </row>
            <row>
              <entry>
                E:only-child
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#structural-pseudos">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
              </entry>
            </row>
            <row>
              <entry>
                E:link, E:visited
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#link">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
                Corresponds to GTK_STATE_FLAG_LINK and
                GTK_STATE_FLAGS_VISITED
              </entry>
            </row>
            <row>
              <entry>
                E:active, E:hover, E:focus
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#useraction-pseudos">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
                Correspond to GTK_STATE_FLAG_ACTIVE,
                GTK_STATE_FLAG_PRELIGHT, GTK_STATE_FLAGS_FOCUSED
              </entry>
            </row>
            <row>
              <entry>
                E:focus-within
              </entry>
              <entry>
                <ulink url="https://drafts.csswg.org/selectors/#focus-within-pseudo">CSS
                Selector Level 4</ulink>
              </entry>
              <entry>
                Set on all ancestors of the focus widget, unlike CSS
              </entry>
            </row>
            <row>
              <entry>
                E:focus-visible
              </entry>
              <entry>
                <ulink url="https://drafts.csswg.org/selectors/#focus-within-pseudo">CSS
                Selector Level 4</ulink>
              </entry>
              <entry>
                Set on focus widget and all ancestors, unlike CSS
              </entry>
            </row>
            <row>
              <entry>
                E:disabled
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#UIstates">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
                Corresponds to GTK_STATE_FLAG_INSENSITIVE
              </entry>
            </row>
            <row>
              <entry>
                E:disabled
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#UIstates">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
                Corresponds to GTK_STATE_FLAG_CHECKED
              </entry>
            </row>
            <row>
              <entry>
                E:indeterminate
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#indeterminate">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
                Corresponds to GTK_STATE_FLAG_INCONSISTENT
              </entry>
            </row>
            <row>
              <entry>
                E:backdrop, E:selected
              </entry>
              <entry>
              </entry>
              <entry>
                Corresponds to GTK_STATE_FLAG_BACKDROP,
                GTK_STATE_FLAG_SELECTED
              </entry>
            </row>
            <row>
              <entry>
                E:not(selector)
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#negation">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
              </entry>
            </row>
            <row>
              <entry>
                E:dir(ltr), E:dir(rtl)
              </entry>
              <entry>
                <ulink url="https://drafts.csswg.org/selectors/#the-dir-pseudo">CSS
                Selector Level 4</ulink>
              </entry>
              <entry>
              </entry>
            </row>
            <row>
              <entry>
                E:drop(active)
              </entry>
              <entry>
                <ulink url="https://drafts.csswg.org/selectors/#drag-pseudos">CSS
                Selector Level 4</ulink>
              </entry>
              <entry>
              </entry>
            </row>
            <row>
              <entry>
                E F
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#descendent-combinators">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
              </entry>
            </row>
            <row>
              <entry>
                E &gt; F
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#child-combinators">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
              </entry>
            </row>
            <row>
              <entry>
                E ~ F
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#general-sibling-combinators">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
              </entry>
            </row>
            <row>
              <entry>
                E + F
              </entry>
              <entry>
                <ulink url="https://www.w3.org/TR/css3-selectors/#adjacent-sibling-combinators">CSS
                Selector Level 3</ulink>
              </entry>
              <entry>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </sect2>
  </sect1>
</chapter>
