From: Matthias Clasen Date: Sat, 20 Nov 2010 05:22:29 +0000 (-0500) Subject: Documentation improvements X-Git-Url: http://pileus.org/git/?a=commitdiff_plain;h=e2f91f7201da8f6690353e84fc445d08c4fc1be5;p=~andy%2Fgtk 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). --- diff --git a/gtk/gtkcssprovider.c b/gtk/gtkcssprovider.c index a1020d774..31b28727f 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. * + * + * Default files + * + * 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 + * } + * + * + * * - * Widget selectors + * Selectors * - * 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. + * + * + * 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 e880c8294..adb9cd005 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 503341018..76257ba5e 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(). */