AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

docs: improve the cssprovider documentation layout

Browse Source
This commit is contained in:
William Jon McCann 2014-02-07 17:35:22 -05:00
parent c823498b4c
commit f5e540d71a
1 changed files with 261 additions and 183 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

440
gtk/gtkcssprovider.c
View File

@ -342,142 +342,171 @@
* } * }
* ]| * ]|
* *
* The various ways to express colors in GTK+ CSS are: * # Specifying Colors
* <informaltable> * There are various ways to express colors in GTK+ CSS.
* <tgroup cols="3"> *
* <thead> * ## rgb(r, g, b)
* <row> *
* <entry>Syntax</entry> * An opaque color.
* <entry>Explanation</entry> *
* <entry>Examples</entry> * - `r`, `g`, `b` can be either integers between 0 and 255, or percentages.
* </row> *
* </thead> * |[
* <tbody> * color: rgb(128, 10, 54);
* <row> * background-color: rgb(20%, 30%, 0%);
* <entry>rgb(@r, @g, @b)</entry> * ]|
* <entry>An opaque color; @r, @g, @b can be either integers between *
* 0 and 255 or percentages</entry> * ## rgba(r, g, b, a)
* <entry><literallayout>rgb(128, 10, 54) *
* rgb(20%, 30%, 0%)</literallayout></entry> * A translucent color.
* </row> *
* <row> * - `r`, `g`, `b` can be either integers between 0 and 255, or percentages.
* <entry>rgba(@r, @g, @b, @a)</entry> * - `a` is a floating point number between 0 and 1.
* <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><literallayout>rgba(255, 255, 0, 0.5)</literallayout></entry> * color: rgb(128, 10, 54, 0.5);
* </row> * ]|
* <row> *
* <entry>&num;@xxyyzz</entry> * ## &num;xxyyzz
* <entry>An opaque color; @xx, @yy, @zz are hexadecimal numbers *
* specifying @r, @g, @b variants with between 1 and 4 * An opaque color.
* hexadecimal digits per component are allowed</entry> *
* <entry><literallayout>&num;ff12ab * - `xx`, `yy`, `zz` are hexadecimal numbers specifying `r`, `g`, `b`
* &num;f0c</literallayout></entry> * variants with between 1 and 4 hexadecimal digits per component.
* </row> *
* <row> * |[
* <entry>&commat;name</entry> * color: #f0c;
* <entry>Reference to a color that has been defined with * background-color: #ff00cc;
* &commat;define-color * border-color: #ffff0000cccc;
* </entry> * ]|
* <entry>&commat;bg_color</entry> *
* </row> * ## &commat;name
* <row> *
* <entry>mix(@color1, @color2, @f)</entry> * Reference to a color that has been defined with &commat;define-color
* <entry>A linear combination of @color1 and @color2. @f is a *
* floating point number between 0 and 1.</entry> * |[
* <entry><literallayout>mix(&num;ff1e0a, &commat;bg_color, 0.8)</literallayout></entry> * color: @bg_color;
* </row> * ]|
* <row> *
* <entry>shade(@color, @f)</entry> * ## mix(color1, color2, factor)
* <entry>A lighter or darker variant of @color. @f is a *
* floating point number. * A linear combination of `color1` and `color2`.
* </entry> *
* <entry>shade(&commat;fg_color, 0.5)</entry> * - `factor` is a floating point number between 0 and 1.
* </row> *
* <row> * |[
* <entry>lighter(@color)</entry> * color: mix(#ff1e0a, @bg_color, 0.8);
* <entry>A lighter variant of @color</entry> * ]|
* </row> *
* <row> * ## shade(color, factor)
* <entry>darker(@color)</entry> *
* <entry>A darker variant of @color</entry> * A lighter or darker variant of `color`.
* </row> *
* <row> * - `factor` is a floating point number.
* <entry>alpha(@color, @f)</entry> *
* <entry>Modifies passed color’s alpha by a factor @f. @f is a * |[
* floating point number. @f < 1.0 results in a more transparent * color: shade(@fg_color, 0.5);
* color while @f > 1.0 results in a more opaque color. * ]|
* </entry> *
* <entry>alhpa(blue, 0.5)</entry> * ## lighter(color)
* </row> *
* </tbody> * A lighter variant of `color`.
* </tgroup> *
* </informaltable> * |[
* color: lighter(@fg_color);
* ]|
*
* ## darker(color)
*
* A darker variant of `color`.
*
* |[
* color: darker(@bg_color);
* ]|
*
* ## alpha(color, factor)
*
* Modifies passed color’s alpha by a factor.
*
* - `factor` is a floating point number. `factor` < 1.0 results in a more
* transparent color while `factor` > 1.0 results in a more opaque color.
*
* |[
* color: alpha(@fg_color, 0.5);
* ]|
*
* *
* # Gradients * # Gradients
* *
* Linear or radial Gradients can be used as background images. * Linear or radial gradients can be used as background images.
*
* ## Linear Gradients
*
* A linear gradient along the line from (`start_x`, `start_y`) to
* (`end_x`, `end_y`) is specified using the following syntax:
*
* > `-gtk-gradient (linear, start_x start_y, end_x end_y, color-stop (position, color), ...)`
*
* - `start_x` and `end_x` can be either a floating point number between
* 0 and 1, or one of the special values: “left”, “right”, or “center”.
* - `start_y` and `end_y` can be either a floating point number between 0 and 1, or one
* of the special values: “top”, “bottom” or “center”.
* - `position` is a floating point number between 0 and 1.
* - `color` is a color expression (see above).
* *
* A linear gradient along the line from (@start_x, @start_y) to
* (@end_x, @end_y) is specified using the syntax
* <literallayout>-gtk-gradient (linear,
* @start_x @start_y, @end_x @end_y,
* color-stop (@position, @color),
* ...)</literallayout>
* where @start_x and @end_x can be either a floating point number between
* 0 and 1 or one of the special values “left”, “right” or “center”, @start_y
* and @end_y can be either a floating point number between 0 and 1 or one
* of the special values “top”, “bottom” or “center”, @position is a floating
* point number between 0 and 1 and @color is a color expression (see above).
* The color-stop can be repeated multiple times to add more than one color * The color-stop can be repeated multiple times to add more than one color
* stop. “from (@color)” and “to (@color)” can be used as abbreviations for * stop. “from (color)” and “to (color)” can be used as abbreviations for
* color stops with position 0 and 1, respectively. * color stops with position 0 and 1, respectively.
* *
* An example for a linear gradient: * ## Example: Linear Gradient
* ![](gradient1.png) * ![](gradient1.png)
* This gradient was specified with * |[
* <literallayout>-gtk-gradient (linear, * -gtk-gradient (linear,
* left top, right bottom, * left top, right bottom,
* from(&commat;yellow), to(&commat;blue))</literallayout> * from(@yellow), to(@blue));
* ]|
* *
* Another example for a linear gradient: * ## Example: Linear Gradient 2
* ![](gradient2.png) * ![](gradient2.png)
* This gradient was specified with * |[
* <literallayout>-gtk-gradient (linear, * -gtk-gradient (linear,
* 0 0, 0 1, * 0 0, 0 1,
* color-stop(0, &commat;yellow), * color-stop(0, @yellow),
* color-stop(0.2, &commat;blue), * color-stop(0.2, @blue),
* color-stop(1, &num;0f0))</literallayout> * color-stop(1, #0f0))
* ]|
* *
* A radial gradient along the two circles defined by (@start_x, @start_y, * ## Radial Gradients
* @start_radius) and (@end_x, @end_y, @end_radius) is specified using the
* syntax
* <literallayout>-gtk-gradient (radial,
* @start_x @start_y, @start_radius,
* @end_x @end_y, @end_radius,
* color-stop (@position, @color),
* ...)</literallayout>
* where @start_radius and @end_radius are floating point numbers and
* the other parameters are as before.
* *
* An example of a radial gradient: * A radial gradient along the two circles defined by (`start_x`,
* `start_y`, `start_radius`) and (`end_x`, `end_y`, `end_radius`) is
* specified using the following syntax:
*
* > `-gtk-gradient (radial, start_x start_y, start_radius, end_x end_y, end_radius, color-stop (position, color), ...)`
*
* where `start_radius` and `end_radius` are floating point numbers
* and the other parameters are as before.
*
* ## Example: Radial Gradient
* ![](gradient3.png) * ![](gradient3.png)
* This gradient was specified with * |[
* <literallayout>-gtk-gradient (radial, * -gtk-gradient (radial,
* center center, 0, * center center, 0,
* center center, 1, * center center, 1,
* from(&commat;yellow), to(&commat;green))</literallayout> * from(@yellow), to(@green))
* ]|
* *
* Another example of a radial gradient: * ## Example: Radial Gradient 2
* ![](gradient4.png) * ![](gradient4.png)
* This gradient was specified with * |[
* <literallayout>-gtk-gradient (radial, * -gtk-gradient (radial,
* 0.4 0.4, 0.1, * 0.4 0.4, 0.1,
* 0.6 0.6, 0.7, * 0.6 0.6, 0.7,
* color-stop (0, &num;f00), * color-stop (0, #f00),
* color-stop (0.1, &num;a0f), * color-stop (0.1, #a0f),
* color-stop (0.2, &commat;yellow), * color-stop (0.2, @yellow),
* color-stop (1, &commat;green))</literallayout> * color-stop (1, @green))
* ]|
* *
* # Text shadow * # Text shadow
* *
@ -485,19 +514,22 @@
* text-shadow syntax, as defined in the * text-shadow syntax, as defined in the
* [CSS3 Specification](http://www.w3.org/TR/css3-text/#text-shadow). * [CSS3 Specification](http://www.w3.org/TR/css3-text/#text-shadow).
* *
* A text shadow is specified using the syntax * A text shadow is specified using the following syntax:
* <literallayout>text-shadow: @horizontal_offset @vertical_offset [ @blur_radius ] @color</literallayout>
* The offset of the shadow is specified with the @horizontal_offset and @vertical_offset
* parameters. The optional blur radius is parsed, but it is currently not rendered by
* the GTK+ theming engine.
* *
* To set a shadow on an icon, use the icon-shadow property instead, * > `text-shadow: horizontal_offset vertical_offset [ blur_radius ] color`
*
* - The offset of the shadow is specified with the
* `horizontal_offset` and `vertical_offset` parameters.
* - The optional blur radius is parsed, but it is currently not
* rendered by the GTK+ theming engine.
*
* To set a shadow on an icon, use the `icon-shadow` property instead,
* with the same syntax. * with the same syntax.
* *
* To set multiple shadows on an element, you can specify a comma-separated list * To set multiple shadows on an element, you can specify a comma-separated list
* of shadow elements in the text-shadow or icon-shadow property. Shadows are * of shadow elements in the `text-shadow` or `icon-shadow` property. Shadows are
* always rendered front-back, i.e. the first shadow specified is on top of the * always rendered front to back (i.e. the first shadow specified is on top of the
* others. Shadows can thus overlay each other, but they can never overlay the * others). Shadows can thus overlay each other, but they can never overlay the
* text or icon itself, which is always rendered on top of the shadow layer. * text or icon itself, which is always rendered on top of the shadow layer.
* *
* # Box shadow * # Box shadow
@ -506,19 +538,22 @@
* as defined in the * as defined in the
* [CSS3 Specification](http://www.w3.org/TR/css3-background/#the-box-shadow). * [CSS3 Specification](http://www.w3.org/TR/css3-background/#the-box-shadow).
* *
* A box shadow is specified using the syntax * A box shadow is specified using the following syntax:
* <literallayout>box-shadow: [ @inset ] @horizontal_offset @vertical_offset [ @blur_radius ] [ @spread ] @color</literallayout> *
* A positive offset will draw a shadow that is offset to the right (down) of the box, * > `box-shadow: [ inset ] horizontal_offset vertical_offset [ blur_radius ] [ spread ] color`
* a negative offset to the left (top). The optional spread parameter defines an additional *
* distance to expand the shadow shape in all directions, by the specified radius. * - A positive offset will draw a shadow that is offset to the right (down) of the box,
* The optional blur radius parameter is parsed, but it is currently not rendered by * - A negative offset to the left (top).
* - The optional spread parameter defines an additional distance to
* expand the shadow shape in all directions, by the specified radius.
* - The optional blur radius parameter is parsed, but it is currently not rendered by
* the GTK+ theming engine. * the GTK+ theming engine.
* The inset parameter defines whether the drop shadow should be rendered inside or outside * - The inset parameter defines whether the drop shadow should be rendered inside or outside
* the box canvas. * the box canvas.
* *
* To set multiple box-shadows on an element, you can specify a comma-separated list * To set multiple box-shadows on an element, you can specify a comma-separated list
* of shadow elements in the box-shadow property. Shadows are always rendered * of shadow elements in the `box-shadow` property. Shadows are always rendered
* front-back, i.e. the first shadow specified is on top of the others, so they may * front to back (i.e. the first shadow specified is on top of the others) so they may
* overlap other boxes or other shadows. * overlap other boxes or other shadows.
* *
* # Border images * # Border images
@ -529,76 +564,119 @@
* *
* ![](slices.png) * ![](slices.png)
* *
* The parameters of the slicing process are controlled by * The parameters of the slicing process are controlled by four
* four separate properties. Note that you can use the * separate properties.
* <literallayout>border-image</literallayout> shorthand property
* to set values for the three properties at the same time.
* *
* <literallayout>border-image-source: url(@path) * - Image Source
* (or border-image-source: -gtk-gradient(...))</literallayout>: * - Image Slice
* Specifies the source of the border image, and it can either * - Image Width
* be an URL or a gradient (see above). * - Image Repeat
* *
* <literallayout>border-image-slice: @top @right @bottom @left</literallayout> * Note that you can use the `border-image` shorthand property to set
* The sizes specified by the @top, @right, @bottom and @left parameters * values for the properties at the same time.
* are the offsets, in pixels, from the relevant edge where the image *
* ## Image Source
*
* The border image source can be specified either as a
* URL or a gradient:
* |[
* border-image-source: url(path);
* ]|
* or
* |[
* border-image-source: -gtk-gradient(...);
* ]|
*
* ## Image Slice
*
* |[
* border-image-slice: top right bottom left;
* ]|
*
* The sizes specified by the `top`, `right`, `bottom`, and `left` parameters
* are the offsets (in pixels) from the relevant edge where the image
* should be “cut off” to build the slices used for the rendering * should be “cut off” to build the slices used for the rendering
* of the border. * of the border.
* *
* <literallayout>border-image-width: @top @right @bottom @left</literallayout> * ## Image Width
*
* |[
* border-image-width: top right bottom left;
* ]|
*
* The sizes specified by the @top, @right, @bottom and @left parameters * The sizes specified by the @top, @right, @bottom and @left parameters
* are inward distances from the border box edge, used to specify the * are inward distances from the border box edge, used to specify the
* rendered size of each slice determined by border-image-slice. * rendered size of each slice determined by border-image-slice.
* If this property is not specified, the values of border-width will * If this property is not specified, the values of border-width will
* be used as a fallback. * be used as a fallback.
* *
* <literallayout>border-image-repeat: [stretch|repeat|round|space] ? * ## Image Repeat
* [stretch|repeat|round|space]</literallayout> *
* Specifies how the image slices should be rendered in the area * Specifies how the image slices should be rendered in the area
* outlined by border-width. * outlined by border-width.
* The default (stretch) is to resize the slice to fill in the whole *
* allocated area. * |[
* If the value of this property is “repeat”, the image slice * border-image-repeat: [stretch|repeat|round|space];
* will be tiled to fill the area. * ]|
* If the value of this property is “round”, the image slice will * or
* be tiled to fill the area, and scaled to fit it exactly * |[
* a whole number of times. * border-image-repeat: [stretch|repeat|round|space] [stretch|repeat|round|space];
* If the value of this property is “space”, the image slice will * ]|
* be tiled to fill the area, and if it doesn’t fit it exactly a whole *
* - The default (stretch) is to resize the slice to fill in the
* whole allocated area.
*
* - If the value of this property is “repeat”, the image slice will
* be tiled to fill the area.
*
* - If the value of this property is “round”, the image slice will be
* tiled to fill the area, and scaled to fit it exactly a whole number
* of times.
*
* - If the value of this property is “space”, the image slice will be
* tiled to fill the area, and if it doesn’t fit it exactly a whole
* number of times, the extra space is distributed as padding around * number of times, the extra space is distributed as padding around
* the slices. * the slices.
* If two options are specified, the first one affects
* the horizontal behaviour and the second one the vertical behaviour.
* If only one option is specified, it affects both.
* *
* An example of a border image: * - If two options are specified, the first one affects the
* horizontal behaviour and the second one the vertical behaviour. If
* only one option is specified, it affects both.
*
*
* ## Example: Border Image
* ![](border1.png) * ![](border1.png)
* This border image was specified with * |[
* <literallayout>url("gradient1.png") 10 10 10 10</literallayout> * border-image: url("gradient1.png") 10 10 10 10;
* ]|
* *
* An example of a repeating border image: * ## Example: Repeating Border Image
* ![](border2.png) * ![](border2.png)
* This border image was specified with * |[
* <literallayout>url("gradient1.png") 10 10 10 10 repeat</literallayout> * border-image: url("gradient1.png") 10 10 10 10 repeat;
* ]|
* *
* An example of a stretched border image: * ## Example: Stetched Border Image
* ![](border3.png) * ![](border3.png)
* This border image was specified with * |[
* <literallayout>url("gradient1.png") 10 10 10 10 stretch</literallayout> * border-image: url("gradient1.png") 10 10 10 10 stretch;
* ]|
* *
* # Transitions * # Transitions
* *
* Styles can specify transitions that will be used to create a gradual * Styles can specify transitions that will be used to create a gradual
* change in the appearance when a widget state changes. The following * change in the appearance when a widget state changes. The following
* syntax is used to specify transitions: * syntax is used to specify transitions:
* <literallayout>@duration [s|ms] [linear|ease|ease-in|ease-out|ease-in-out] [loop]?</literallayout>
* The @duration is the amount of time that the animation will take for
* a complete cycle from start to end. If the loop option is given, the
* animation will be repated until the state changes again.
* The option after the duration determines the transition function from a
* small set of predefined functions.
* *
* # Linear transition * > `duration [s|ms] [linear|ease|ease-in|ease-out|ease-in-out] [loop]?`
*
* - The `duration` is the amount of time that the animation will take
* for a complete cycle from start to end.
* - If the loop option is given, the animation will be repated until
* the state changes again.
* - The option after the duration determines the transition function
* from a small set of predefined functions.
*
* ## Linear Transition
* *
* ![](linear.png) * ![](linear.png)
* *
@ -618,12 +696,12 @@
* *
* ![](ease-out.png) * ![](ease-out.png)
* *
* # Supported properties * # Supported Properties
* *
* Properties are the part that differ the most to common CSS, * Properties are the part that differ the most to common CSS, not all
* not all properties are supported (some are planned to be * properties are supported (some are planned to be supported
* supported eventually, some others are meaningless or don't * eventually, some others are meaningless or don't map intuitively in
* map intuitively in a widget based environment). * a widget based environment).
* *
* The currently supported properties are: * The currently supported properties are:
* <informaltable> * <informaltable>
@ -897,7 +975,7 @@
* GtkThemingEngines can register their own, engine-specific style properties * GtkThemingEngines can register their own, engine-specific style properties
* with the function gtk_theming_engine_register_property(). These properties * with the function gtk_theming_engine_register_property(). These properties
* can be set in CSS like other properties, using a name of the form * can be set in CSS like other properties, using a name of the form
* <literallayout>-namespace-name</literallayout>, where namespace is typically * `-namespace-name`, where namespace is typically
* the name of the theming engine, and name is the * the name of the theming engine, and name is the
* name of the property. Style properties that have been registered by widgets * name of the property. Style properties that have been registered by widgets
* using gtk_widget_class_install_style_property() can also be set in this * using gtk_widget_class_install_style_property() can also be set in this