diff options
| -rw-r--r-- | gtk/gtkcssprovider.c | 235 | ||||
| -rw-r--r-- | gtk/gtkstylecontext.c | 10 | ||||
| -rw-r--r-- | gtk/gtkstyleprovider.c | 4 |
3 files changed, 191 insertions, 58 deletions
diff --git a/gtk/gtkcssprovider.c b/gtk/gtkcssprovider.c index a1020d774a..31b28727fa 100644 --- a/gtk/gtkcssprovider.c +++ b/gtk/gtkcssprovider.c @@ -37,17 +37,81 @@ * @See_also: #GtkStyleContext, #GtkStyleProvider * * #GtkCssProvider is an object implementing #GtkStyleProvider, it is able - * to parse CSS-like input in order to style widgets. + * to parse <ulink url="http://www.w3.org/TR/CSS2">CSS</ulink>-like input + * in order to style widgets. * + * <refsect2 id="gtkcssprovider-files"> + * <title>Default files</title> + * <para> + * An application can cause GTK+ to parse a specific CSS style sheet by + * calling gtk_css_provider_load_from_file() and adding the provider with + * gtk_style_context_add_provider() or gtk_style_context_add_provider_for_screen(). + * In addition, certain files will be read when GTK+ is initialized. First, + * the file <filename><replaceable>HOME</replaceable>/.gtk-3.0.css</filename> + * is loaded if it exists. Then, GTK+ tries to load + * <filename><replaceable>HOME</replaceable>/.themes/<replaceable>theme-name</replaceable>/gtk-3.0/gtk.css</filename>, + * falling back to + * <filename><replaceable>GTK_DATA_PREFIX</replaceable>/share/themes/<replaceable>theme-name</replaceable>/gtk-3.0/gtk.css</filename>, + * where <replaceable>theme-name</replaceable> is the name of the current theme + * (see the #GtkSettings:gtk-theme-name setting) and <replaceable>GTK_DATA_PREFIX</replaceable> + * is the prefix configured when GTK+ was compiled, unless overridden by the + * <envar>GTK_DATA_PREFIX</envar> environment variable. + * </para> + * </refsect2> + * <refsect2 id="gtkcssprovider-stylesheets"> + * <title>Style sheets</title> + * <para> + * The basic structure of the style sheets understood by this provider is + * a series of statements, which are either rule sets or '@-rules', separated + * by whitespace. + * </para> + * <para> + * A rule set consists of a selector and a declaration block, which is + * a series of declarations enclosed in curly braces ({ and }). The + * declarations are separated by semicolons (;). Multiple selectors can + * share the same declaration block, by putting all the separators in + * front of the block, separated by commas. + * </para> + * <example><title>A rule set with two selectors</title> + * <programlisting language="text"> + * GtkButton, GtkEntry { + * color: #ff00ea; + * font: Comic Sans 12 + * } + * </programlisting> + * </example> + * </refsect2> * <refsect2 id="gtkcssprovider-selectors"> - * <title>Widget selectors</title> + * <title>Selectors</title> * <para> - * Selectors work in a really similar way than in common CSS, widget object - * names act as HTML tags: + * Selectors work very similar to the way they do in CSS, with widget class + * names taking the role of element names, and widget names taking the role + * of IDs. When used in a selector, widget names must be prefixed with a + * '#' character. The '*' character represents the so-called universal + * selector, which matches any widget. + * </para> + * <para> + * To express more complicated situations, selectors can be combined in + * various ways: + * <itemizedlist> + * <listitem><para>To require that a widget satisfies several conditions, + * combine several selectors into one by concatenating them. E.g. + * <literal>GtkButton#button1</literal> matches a GtkButton widget + * with the name button1.</para></listitem> + * <listitem><para>To only match a widget when it occurs inside some other + * widget, write the two selectors after each other, separated by whitespace. + * E.g. <literal>GtkToolBar GtkButton</literal> matches GtkButton widgets + * that occur inside a GtkToolBar.</para></listitem> + * <listitem><para>In the previous example, the GtkButton is matched even + * if it occurs deeply nested inside the toolbar. To restrict the match + * to direct children of the parent widget, insert a '>' character between + * the two selectors. E.g. <literal>GtkNotebook > GtkLabel</literal> matches + * GtkLabel widgets that are direct children of a GtkNotebook.</para></listitem> + * </itemizedlist> * </para> * <example> - * <title>Widgets in selectors</title> - * <programlisting> + * <title>Widget classes and names in selectors</title> + * <programlisting language="text"> * /* Theme labels that are descendants of a window */ * GtkWindow GtkLabel { * background-color: #898989 @@ -70,14 +134,7 @@ * GtkBin * { * font-name: Sans 20 * } - * </programlisting> - * </example> - * <para> - * Widget names may be matched in CSS as well: - * </para> - * <example> - * <title>Widget names in selectors</title> - * <programlisting> + * * /* Theme a label named title-label */ * GtkLabel#title-label { * font-name: Sans 15 @@ -90,12 +147,17 @@ * </programlisting> * </example> * <para> - * Widgets may also define different classes, so these can be matched - * in CSS: + * Widgets may also define style classes, which can be used for matching. + * When used in a selector, style classes must be prefixed with a '.' + * character. + * </para> + * <para> + * Refer to the documentation of individual widgets to learn which + * style classes they define. * </para> * <example> - * <title>Widget names in selectors</title> - * <programlisting> + * <title>Style classes in selectors</title> + * <programlisting language="text"> * /* Theme all widgets defining the class entry */ * .entry { * color: #39f1f9; @@ -108,21 +170,33 @@ * </programlisting> * </example> * <para> - * Container widgets may define regions, these region names may be - * referenced in CSS, it's also possible to apply :nth-child - * pseudo-class information if the widget implementation provides - * such data. + * In complicated widgets like e.g. a GtkNotebook, it may be desirable + * to style different parts of the widget differently. To make this + * possible, container widgets may define regions, whose names + * may be used for matching in selectors. + * </para> + * <para> + * Some containers allow to further differentiate between regions by + * applying so-called pseudo-classes to the region. For example, the + * tab region in GtkNotebook allows to single out the first or last + * tab by using the :first-child or :last-child pseudo-class. + * When used in selectors, pseudo-classes must be prefixed with a + * ':' character. + * </para> + * <para> + * Refer to the documentation of individual widgets to learn which + * regions and pseudo-classes they define. * </para> * <example> - * <title>Region names in containers</title> - * <programlisting> + * <title>Regions in selectors</title> + * <programlisting language="text"> * /* Theme any label within a notebook */ * GtkNotebook GtkLabel { * color: #f90192; * } * * /* Theme labels within notebook tabs */ - * GtkNotebook tab:nth-child GtkLabel { + * GtkNotebook tab GtkLabel { * color: #703910; * } * @@ -135,20 +209,22 @@ * </programlisting> * </example> * <para> - * Widget states may be matched as pseudoclasses. - * Given the needed widget states differ from the - * offered pseudoclasses in CSS, some are unsupported, - * and some custom ones have been added. + * Another use of pseudo-classes is to match widgets depending on their + * state. This is conceptually similar to the :hover, :active or :focus + * pseudo-classes in CSS. The available pseudo-classes for widget states + * are :active, :prelight (or :hover), :insensitive, :selected, :focused + * and :inconsistent. * </para> * <example> * <title>Styling specific widget states</title> - * <programlisting> + * <programlisting language="text"> * /* Theme active (pressed) buttons */ * GtkButton:active { * background-color: #0274d9; * } * - * /* Theme buttons with the mouse pointer on it */ + * /* Theme buttons with the mouse pointer on it, + * both are equivalent */ * GtkButton:hover, * GtkButton:prelight { * background-color: #3085a9; @@ -177,38 +253,37 @@ * </programlisting> * </example> * <para> - * Widget state pseudoclasses may only apply to the - * last element in a selector. + * Widget state pseudoclasses may only apply to the last element + * in a selector. * </para> * <para> - * All the mentioned elements may be combined to create - * complex selectors that match specific widget paths. - * As in CSS, rules apply by specificity, so the selectors - * describing the best a widget path will take precedence + * To determine the effective style for a widget, all the matching rule + * sets are merged. As in CSS, rules apply by specificity, so the rules + * whose selectors more closely match a widget path will take precedence * over the others. * </para> * </refsect2> * <refsect2 id="gtkcssprovider-rules"> - * <title>@ rules</title> + * <title>@ Rules</title> * <para> - * GTK+'s CSS supports the @import rule, in order - * to load another CSS file in addition to the currently - * parsed one. + * GTK+'s CSS supports the @import rule, in order to load another + * CSS style sheet in addition to the currently parsed one. * </para> * <example> * <title>Using the @import rule</title> - * <programlisting> + * <programlisting language="text"> * @import url ("path/to/common.css"); * </programlisting> * </example> * <para> - * GTK+ also supports an additional @define-color - * rule, in order to define a color name which may be used - * instead of color numeric representations. + * GTK+ also supports an additional @define-color rule, in order + * to define a color name which may be used instead of color numeric + * representations. Also see the #GtkSettings:gtk-color-scheme setting + * for a way to override the values of these named colors. * </para> * <example> * <title>Defining colors</title> - * <programlisting> + * <programlisting language="text"> * @define-color bg_color #f9a039; * * * { @@ -220,14 +295,14 @@ * <refsect2 id="gtkcssprovider-symbolic-colors"> * <title>Symbolic colors</title> * <para> - * Besides being able to define color names, the CSS - * parser is also able to read different color modifiers, - * which can also be nested, providing a rich language - * to define colors starting from other colors. + * Besides being able to define color names, the CSS parser is also able + * to read different color expressions, which can also be nested, providing + * a rich language to define colors which are derived from a set of base + * colors. * </para> * <example> * <title>Using symbolic colors</title> - * <programlisting> + * <programlisting language="text"> * @define-color entry-color shade (@bg_color, 0.7); * * GtkEntry { @@ -241,6 +316,63 @@ * } * </programlisting> * </example> + * <para> + * The various ways to express colors in GTK+ CSS are: + * </para> + * <informaltable> + * <tgroup cols="3"> + * <thead> + * <row> + * <entry>Syntax</entry> + * <entry>Explanation</entry> + * <entry>Examples</entry> + * </row> + * </thead> + * <tbody> + * <row> + * <entry>rgb(@r, @g, @b)</entry> + * <entry>An opaque color; @r, @g, @b can be either integers between 0 and 255 or percentages</entry> + * <entry>rgb(128, 10, 54) + * rgb(20%, 30%, 0%)</entry> + * </row> + * <row> + * <entry>rgba(@r, @g, @b, @a)</entry> + * <entry>A translucent color; @r, @g, @b are as in the previous row, @a is a floating point number between 0 and 1</entry> + * <entry>rgba(255, 255, 0, 0.5)</entry> + * </row> + * <row> + * <entry>#@xxyyzz</entry> + * <entry>An opaque color; @xx, @yy, @zz are hexadecimal numbers specifying @r, @g, @b + * variants with between 1 and 4 hexadecimal digits per component are allowed</entry> + * <entry>#ff12ab + * #f0c</entry> + * </row> + * <row> + * <entry>@name</entry> + * <entry>Reference to a color that has been defined with @define-color</entry> + * <entry>@bg_color</entry> + * </row> + * <row> + * <entry>mix(@color1, @color2, @f)</entry> + * <entry>A linear combination of @color1 and @color2. @f is a floating point number between 0 and 1.</entry> + * <entry>mix(#ff1e0a, @bg_color, 0.8)</entry> + * </row> + * <row> + * <entry>shade(@color, @f)</entry> + * <entry>A lighter or darker variant of @color. @f is a floating point number.</entry> + * <entry>shade(@fg_color, 0.5)</entry> + * </row> + * <row> + * <entry>lighter(@color)</entry> + * <entry>A lighter variant of @color</entry> + * </row> + * <row> + * <entry>darker(@color)</entry> + * <entry>A darker variant of @color</entry> + * </row> + * </tbody> + * </tgroup> + * </informaltable> * </refsect2> * <refsect2 id="gtkcssprovider-properties"> * <title>Supported properties</title> @@ -693,6 +825,7 @@ create_scanner (void) g_scanner_scope_add_symbol (scanner, SCOPE_PSEUDO_CLASS, "insensitive", GUINT_TO_POINTER (GTK_STATE_INSENSITIVE)); g_scanner_scope_add_symbol (scanner, SCOPE_PSEUDO_CLASS, "inconsistent", GUINT_TO_POINTER (GTK_STATE_INCONSISTENT)); g_scanner_scope_add_symbol (scanner, SCOPE_PSEUDO_CLASS, "focused", GUINT_TO_POINTER (GTK_STATE_FOCUSED)); + g_scanner_scope_add_symbol (scanner, SCOPE_PSEUDO_CLASS, "focus", GUINT_TO_POINTER (GTK_STATE_FOCUSED)); g_scanner_scope_add_symbol (scanner, SCOPE_PSEUDO_CLASS, "nth-child", GUINT_TO_POINTER (SYMBOL_NTH_CHILD)); g_scanner_scope_add_symbol (scanner, SCOPE_PSEUDO_CLASS, "first-child", GUINT_TO_POINTER (SYMBOL_FIRST_CHILD)); diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c index e880c8294f..adb9cd005f 100644 --- a/gtk/gtkstylecontext.c +++ b/gtk/gtkstylecontext.c @@ -43,11 +43,11 @@ * a widget defined by #GtkWidgetPath. * * In order to construct the final style information, #GtkStyleContext - * queries information to all attached #GtkStyleProvider<!-- -->s, either - * to the context specifically through gtk_style_context_add_provider(), or - * to the screen through gtk_style_context_add_provider_for_screen(). The - * resulting style is a combination of all provider's information in priority - * order. + * queries information from all attached #GtkStyleProviders. Style providers + * can be either attached explicitly to the context through + * gtk_style_context_add_provider(), or to the screen through + * gtk_style_context_add_provider_for_screen(). The resulting style is a + * combination of all provider's information in priority order. * * For GTK+ widgets, any #GtkStyleContext returned by * gtk_widget_get_style_context() will already have a #GtkWidgetPath, a diff --git a/gtk/gtkstyleprovider.c b/gtk/gtkstyleprovider.c index 5033410188..76257ba5e0 100644 --- a/gtk/gtkstyleprovider.c +++ b/gtk/gtkstyleprovider.c @@ -25,11 +25,11 @@ /** * SECTION:gtkstyleprovider - * @Short_description: Interface to provide style information to #GtkStyleContext + * @Short_description: Interface to provide style information to GtkStyleContext * @Title: GtkStyleProvider * @See_also: #GtkStyleContext, #GtkCssProvider * - * #GtkStyleProvider is an interface used to provide style information to a #GtkStyleContext, + * GtkStyleProvider is an interface used to provide style information to a #GtkStyleContext, * see gtk_style_context_add_provider() and gtk_style_context_add_provider_for_screen(). */ |