* which is always rendered on top of the shadow layer.
* </para>
* </refsect2>
- * <refsect2 id="gtkcssprovider-slices">
+ * <refsect2>
+ * <title>Box shadow</title>
+ * <para>
+ * Themes can apply shadows on framed elements using the CSS3 box-shadow syntax,
+ * as defined in
+ * <ulink url="http://www.w3.org/TR/css3-background/#the-box-shadow">the CSS3 specification</ulink>.
+ * </para>
+ * <para>
+ * A box shadow is specified using the 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,
+ * 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 inset parameter defines whether the drop shadow should be rendered inside or outside
+ * the box canvas. Only inset box-shadows are currently supported by the GTK+ theming engine,
+ * non-inset elements are currently ignored.
+ * </para>
+ * <para>
+ * 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
+ * front-back, i.e. the first shadow specified is on top of the others, so they may
+ * overlap other boxes or other shadows.
+ * </para>
+ * </refsect2>
+ * <refsect2 id="gtkcssprovider-border-image">
* <title>Border images</title>
* <para>
- * Images can be used in 'slices' for the purpose of creating scalable
- * borders.
+ * Images and gradients can also be used in slices for the purpose of creating
+ * scalable borders.
+ * For more information, see the CSS3 documentation for the border-image property,
+ * which can be found <ulink url="http://www.w3.org/TR/css3-background/#border-images">here</ulink>.
* </para>
* <inlinegraphic fileref="slices.png" format="PNG"/>
* <para>
- * The syntax for specifying border images of this kind is:
- * <literallayout>url(@path) @top @right @bottom @left [repeat|stretch]? [repeat|stretch]?</literallayout>
- * The sizes of the 'cut off' portions are specified
- * with the @top, @right, @bottom and @left parameters.
- * The 'middle' sections can be repeated or stretched to create
- * the desired effect, by adding the 'repeat' or 'stretch' options after
- * the dimensions. If two options are specified, the first one affects
+ * The parameters of the slicing process are controlled by
+ * four separate properties. Note that you can use the
+ * <literallayout>border-image</literallayout> shorthand property
+ * to set values for the three properties at the same time.
+ * </para>
+ * <para>
+ * <literallayout>border-image-source: url(@path)
+ * (or border-image-source: -gtk-gradient(...))</literallayout>:
+ * Specifies the source of the border image, and it can either
+ * be an URL or a gradient (see above).
+ * </para>
+ * <para>
+ * <literallayout>border-image-slice: @top @right @bottom @left</literallayout>
+ * 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
+ * of the border.
+ * </para>
+ * <para>
+ * <literallayout>border-image-width: @top @right @bottom @left</literallayout>
+ * The sizes specified by the @top, @right, @bottom and @left parameters
+ * are inward distances from the border box edge, used to specify the
+ * rendered size of each slice determined by border-image-slice.
+ * If this property is not specified, the values of border-width will
+ * be used as a fallback.
+ * </para>
+ * <para>
+ * <literallayout>border-image-repeat: [stretch|repeat|round|space] ?
+ * [stretch|repeat|round|space]</literallayout>
+ * Specifies how the image slices should be rendered in the area
+ * 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
+ * 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
+ * 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.
* </para>
* <entry>border-color</entry>
* </row>
* <row>
- * <entry>font-family</entry>
- * <entry>@family [, @family]*</entry>
- * <entry>#gchararray</entry>
- * <entry>font-family: Sans, Arial;</entry>
- * </row>
- * <row>
- * <entry>font-style</entry>
- * <entry>[normal|oblique|italic]</entry>
- * <entry>#PANGO_TYPE_STYLE</entry>
- * <entry>font-style: italic;</entry>
- * </row>
- * <row>
- * <entry>font-variant</entry>
- * <entry>[normal|small-caps]</entry>
- * <entry>#PANGO_TYPE_VARIANT</entry>
- * <entry>font-variant: normal;</entry>
- * </row>
- * <row>
- * <entry>font-weight</entry>
- * <entry>[normal|bold|bolder|lighter|100|200|300|400|500|600|700|800|900]</entry>
- * <entry>#PANGO_TYPE_WEIGHT</entry>
- * <entry>font-weight: bold;</entry>
- * </row>
- * <row>
- * <entry>font-size</entry>
- * <entry>Font size in point</entry>
- * <entry>#gint</entry>
- * <entry>font-size: 13;</entry>
- * </row>
- * <row>
* <entry>font</entry>
* <entry>@family [@style] [@size]</entry>
* <entry>#PangoFontDescription</entry>
projects / ~andy / gtk / blobdiff