[gtk+/gtk-style-context: 439/533] Document border images better

[Carlos Garnacho <carlosg src gnome org>]

commit 417bf995ed1f80c3f9aa863a902091a9ea967b7d
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Nov 22 11:15:47 2010 -0500

    Document border images better

 docs/reference/gtk/Makefile.am        |    6 +++-
 docs/reference/gtk/images/border1.png |  Bin 0 -> 961 bytes
 docs/reference/gtk/images/border2.png |  Bin 0 -> 1684 bytes
 docs/reference/gtk/images/border3.png |  Bin 0 -> 2713 bytes
 docs/reference/gtk/images/slices.png  |  Bin 0 -> 1217 bytes
 gtk/gtkcssprovider.c                  |   64 +++++++++++++++++++++++----------
 6 files changed, 50 insertions(+), 20 deletions(-)
---
diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index 97fd4a8..0ce22bc 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -337,7 +337,11 @@ HTML_IMAGES = \
 	$(srcdir)/images/gradient1.png					\
 	$(srcdir)/images/gradient2.png					\
 	$(srcdir)/images/gradient3.png					\
-	$(srcdir)/images/gradient4.png
+	$(srcdir)/images/gradient4.png					\
+	$(srcdir)/images/border1.png					\
+	$(srcdir)/images/border2.png					\
+	$(srcdir)/images/border3.png					\
+	$(srcdir)/images/slices.png
 
 # Extra options to supply to gtkdoc-fixref
 FIXXREF_OPTIONS=--extra-dir=../gdk/html \
diff --git a/docs/reference/gtk/images/border1.png b/docs/reference/gtk/images/border1.png
new file mode 100644
index 0000000..92e2cc5
Binary files /dev/null and b/docs/reference/gtk/images/border1.png differ
diff --git a/docs/reference/gtk/images/border2.png b/docs/reference/gtk/images/border2.png
new file mode 100644
index 0000000..808c3a5
Binary files /dev/null and b/docs/reference/gtk/images/border2.png differ
diff --git a/docs/reference/gtk/images/border3.png b/docs/reference/gtk/images/border3.png
new file mode 100644
index 0000000..980f4bd
Binary files /dev/null and b/docs/reference/gtk/images/border3.png differ
diff --git a/docs/reference/gtk/images/slices.png b/docs/reference/gtk/images/slices.png
new file mode 100644
index 0000000..c0a064e
Binary files /dev/null and b/docs/reference/gtk/images/slices.png differ
diff --git a/gtk/gtkcssprovider.c b/gtk/gtkcssprovider.c
index 5739c9a..2629b59 100644
--- a/gtk/gtkcssprovider.c
+++ b/gtk/gtkcssprovider.c
@@ -446,8 +446,7 @@
  * <title>Another radial gradient</title>
  * <inlinegraphic fileref="gradient4.png" format="PNG"/>
  * <para>This gradient was specified with
- * <literallayout>
- * -gtk-gradient (radial,
+ * <literallayout>-gtk-gradient (radial,
  *                0.4 0.4, 0.1,
  *                0.6 0.6, 0.7,
  *                color-stop (0, &num;f00),
@@ -456,6 +455,43 @@
  *                color-stop (1, &commat;green))</literallayout></para>
  * </example>
  * </refsect2>
+ * <refsect2 id="gtkcssprovider-slices">
+ * <title>Image slices</title>
+ * <para>
+ * Images can be used in 'slices' for the purpose of creating scalable
+ * borders.
+ * </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 horizontal behaviour and the second one the vertical behaviour.
+ * If only one option is specified, it affects both.
+ * </para>
+ * <example>
+ * <title>A border image</title>
+ * <para>This border image was specified with
+ * <inlinegraphic fileref="border1.png" format="PNG"/>
+ * <literallayout>url("gradient1.png") 10 10 10 10</literallayout></para>
+ * </example>
+ * <example>
+ * <title>A repeating border image</title>
+ * <para>This border image was specified with
+ * <inlinegraphic fileref="border2.png" format="PNG"/>
+ * <literallayout>url("gradient1.png") 10 10 10 10 repeat</literallayout></para>
+ * </example>
+ * <example>
+ * <title>A stretched border image</title>
+ * <para>This border image was specified with
+ * <inlinegraphic fileref="border3.png" format="PNG"/>
+ * <literallayout>url("gradient1.png") 10 10 10 10 stretch</literallayout></para>
+ * </example>
+ * </refsect2>
  * <refsect2 id="gtkcssprovider-properties">
  * <title>Supported properties</title>
  * <para>
@@ -509,16 +545,16 @@
  *       </row>
  *       <row>
  *         <entry>font</entry>
- *         <entry>family [style] [size]</entry>
+ *         <entry>@family [ style] [ size]</entry>
  *         <entry>#PangoFontDescription</entry>
  *         <entry>font: Sans 15;</entry>
  *       </row>
  *       <row>
  *         <entry>margin</entry>
- *         <entry morerows="1"><literallayout>width
- * vertical-width horizontal-width
- * top-width horizontal-width bottom-width
- * top-width right-width bottom-width left-width</literallayout>
+ *         <entry morerows="1"><literallayout>@width
+ * @vertical-width @horizontal-width
+ * @top-width @horizontal-width @bottom-width
+ * @top-width @right-width @bottom-width @left-width</literallayout>
  *         </entry>
  *         <entry morerows="1">#GtkBorder</entry>
  *         <entry morerows="1"><literallayout>margin: 5;
@@ -532,17 +568,7 @@
  *       </row>
  *       <row>
  *         <entry>background-image</entry>
- *         <entry><literallayout>-gtk-gradient (linear,
- *                starting-x-position starting-y-position,
- *                ending-x-position ending-y-position,
- *                [ [from|to] (color) |
- *                  color-stop (percentage, color) ] )
- * -gtk-gradient (radial,
- *                starting-x-position starting-y-position, starting-radius,
- *                ending-x-position ending-y-position, ending-radius,
- *                [ [from|to] (color) |
- *                  color-stop (percentage, color) ]* )</literallayout>
- *         </entry>
+ *         <entry>gradient (see above)</entry>
  *         <entry>#cairo_pattern_t</entry>
  *         <entry><literallayout>-gtk-gradient (linear,
  *                left top, right top,
@@ -578,7 +604,7 @@
  *       </row>
  *       <row>
  *         <entry>border-image</entry>
- *         <entry><literallayout>url([path]) top right bottom left [repeat|stretch]? [repeat|stretch]?</literallayout></entry>
+ *         <entry><literallayout>border image (see above)</literallayout></entry>
  *         <entry></entry>
  *         <entry><literallayout>border-image: url("/path/to/image.png") 3 4 3 4 stretch;
  * border-image: url("/path/to/image.png") 3 4 4 3 repeat stretch;</literallayout>