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 CSS-like input
+ * in order to style widgets.
*
- *
- * Widget selectors
+ *
+ * Default files
*
- * Selectors work in a really similar way than in common CSS, widget object
- * names act as HTML tags:
+ * 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 HOME/.gtk-3.0.css
+ * is loaded if it exists. Then, GTK+ tries to load
+ * HOME/.themes/theme-name/gtk-3.0/gtk.css,
+ * falling back to
+ * GTK_DATA_PREFIX/share/themes/theme-name/gtk-3.0/gtk.css,
+ * where theme-name is the name of the current theme
+ * (see the #GtkSettings:gtk-theme-name setting) and GTK_DATA_PREFIX
+ * is the prefix configured when GTK+ was compiled, unless overridden by the
+ * GTK_DATA_PREFIX environment variable.
+ *
+ *
+ *
+ * Style sheets
+ *
+ * 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.
+ *
+ *
+ * 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.
+ *
+ * A rule set with two selectors
+ *
+ * GtkButton, GtkEntry {
+ * color: #ff00ea;
+ * font: Comic Sans 12
+ * }
+ *
+ *
+ *
+ *
+ * Selectors
+ *
+ * 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.
+ *
+ *
+ * To express more complicated situations, selectors can be combined in
+ * various ways:
+ *
+ * To require that a widget satisfies several conditions,
+ * combine several selectors into one by concatenating them. E.g.
+ * GtkButton#button1 matches a GtkButton widget
+ * with the name button1.
+ * To only match a widget when it occurs inside some other
+ * widget, write the two selectors after each other, separated by whitespace.
+ * E.g. GtkToolBar GtkButton matches GtkButton widgets
+ * that occur inside a GtkToolBar.
+ * 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. GtkNotebook > GtkLabel matches
+ * GtkLabel widgets that are direct children of a GtkNotebook.
+ *
*
*
- * Widgets in selectors
- *
+ * Widget classes and names in selectors
+ *
* /* Theme labels that are descendants of a window */
* GtkWindow GtkLabel {
* background-color: #898989
@@ -70,14 +134,7 @@
* GtkBin * {
* font-name: Sans 20
* }
- *
- *
- *
- * Widget names may be matched in CSS as well:
- *
- *
- * Widget names in selectors
- *
+ *
* /* Theme a label named title-label */
* GtkLabel#title-label {
* font-name: Sans 15
@@ -90,12 +147,17 @@
*
*
*
- * 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.
+ *
+ *
+ * Refer to the documentation of individual widgets to learn which
+ * style classes they define.
*
*
- * Widget names in selectors
- *
+ * Style classes in selectors
+ *
* /* Theme all widgets defining the class entry */
* .entry {
* color: #39f1f9;
@@ -108,21 +170,33 @@
*
*
*
- * 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.
+ *
+ *
+ * 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.
+ *
+ *
+ * Refer to the documentation of individual widgets to learn which
+ * regions and pseudo-classes they define.
*
*
- * Region names in containers
- *
+ * Regions in selectors
+ *
* /* 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 @@
*
*
*
- * 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.
*
*
* Styling specific widget states
- *
+ *
* /* 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 @@
*
*
*
- * 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.
*
*
- * 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.
*
*
*
- * @ rules
+ * @ Rules
*
- * 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.
*
*
* Using the @import rule
- *
+ *
* @import url ("path/to/common.css");
*
*
*
- * 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.
*
*
* Defining colors
- *
+ *
* @define-color bg_color #f9a039;
*
* * {
@@ -220,14 +295,14 @@
*
* Symbolic colors
*
- * 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.
*
*
* Using symbolic colors
- *
+ *
* @define-color entry-color shade (@bg_color, 0.7);
*
* GtkEntry {
@@ -241,6 +316,63 @@
* }
*
*
+ *
+ * The various ways to express colors in GTK+ CSS are:
+ *
+ *
+ *
+ *
+ *
+ * Syntax
+ * Explanation
+ * Examples
+ *
+ *
+ *
+ *
+ * rgb(@r, @g, @b)
+ * An opaque color; @r, @g, @b can be either integers between 0 and 255 or percentages
+ * rgb(128, 10, 54)
+ * rgb(20%, 30%, 0%)
+ *
+ *
+ * rgba(@r, @g, @b, @a)
+ * A translucent color; @r, @g, @b are as in the previous row, @a is a floating point number between 0 and 1
+ * rgba(255, 255, 0, 0.5)
+ *
+ *
+ * #@xxyyzz
+ * 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
+ * #ff12ab
+ * #f0c
+ *
+ *
+ * @name
+ * Reference to a color that has been defined with @define-color
+ * @bg_color
+ *
+ *
+ * mix(@color1, @color2, @f)
+ * A linear combination of @color1 and @color2. @f is a floating point number between 0 and 1.
+ * mix(#ff1e0a, @bg_color, 0.8)
+ *
+ *
+ * shade(@color, @f)
+ * A lighter or darker variant of @color. @f is a floating point number.
+ * shade(@fg_color, 0.5)
+ *
+ *
+ * lighter(@color)
+ * A lighter variant of @color
+ *
+ *
+ * darker(@color)
+ * A darker variant of @color
+ *
+ *
+ *
+ *
*
*
* Supported properties
@@ -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 #GtkStyleProviders, 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().
*/