[gtk+/gtk-style-context: 421/540] Documentation improvements
- From: Carlos Garnacho <carlosg src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk+/gtk-style-context: 421/540] Documentation improvements
- Date: Fri, 3 Dec 2010 03:11:31 +0000 (UTC)
commit aa656a200d280ab5be28ce13bec09215d679601b
Author: Matthias Clasen <mclasen redhat com>
Date: Sat Nov 20 00:22:29 2010 -0500
Documentation improvements
This patch adds more detail to the explanation of CSS, and also
adds documentation about which files are read.
We also make :focus an alternative to :focused (since :focus is
a standard CSS pseudo-class).
gtk/gtkcssprovider.c | 235 +++++++++++++++++++++++++++++++++++++-----------
gtk/gtkstylecontext.c | 10 +-
gtk/gtkstyleprovider.c | 4 +-
3 files changed, 191 insertions(+), 58 deletions(-)
---
diff --git a/gtk/gtkcssprovider.c b/gtk/gtkcssprovider.c
index a1020d7..31b2872 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 e880c82..adb9cd0 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 5033410..76257ba 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().
*/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
