Fix cairo_show_text to advance the current point. Add documentation for cairo_show_text.

Add test to verify that the current-point-advancing behavior of cairo_show_text is working.
Remove bug about cairo_show_text not advancing the current point.

BUGS

@@ -19,7 +19,3 @@ Recent improvements to make the intersection code more robust (using
 128-bit arithmetic where needed), have exposed some of the weakness in
 the current tessellation implementation. So, for now, filling some
 polygons will cause "leaking" until we implement Hobby's algorithm.
-
---
-
-cairo_show_text is not updating the current point by the string's advance values.

ChangeLog

@@ -1,3 +1,18 @@
+2005-08-24  Carl Worth  <cworth@cworth.org>
+
+	* src/cairo.c: (cairo_show_text): Fix cairo_show_text to advance
+	the current point. Add documentation for cairo_show_text.
+	
+	* test/.cvsignore:
+	* test/Makefile.am:
+	* test/show-text-current-point-ref.png:
+	* test/show-text-current-point.c: (draw), (main): Add test to
+	verify that the current-point-advancing behavior of
+	cairo_show_text is working.
+
+	* BUGS: Remove bug about cairo_show_text not advancing the current
+	point.
+
 2005-08-24  Carl Worth  <cworth@cworth.org>
 
 	* src/cairo.c:

src/cairo.c

@@ -359,7 +359,7 @@ cairo_pop_group (cairo_t *cr)
  * 
  * Sets the compositing operator to be used for all drawing
  * operations. See #cairo_operator_t for details on the semantics of
- * each available drawing operator.
+ * each available compositing operator.
  *
  * XXX: I'd also like to direct the reader's attention to some
  * (not-yet-written) section on cairo's imaging model. How would I do
@@ -2074,10 +2074,38 @@ cairo_glyph_extents (cairo_t                *cr,
 	_cairo_set_error (cr, cr->status);
 }
 
+/**
+ * cairo_show_text:
+ * @cr: a cairo context
+ * @utf8: a string of text encoded in utf-8
+ * 
+ * A drawing operator that generates the shape from a string of utf-8
+ * characters, rendered according to the current font_face, font_size
+ * (font_matrix), and font_options.
+ *
+ * This function first computes a set of glyphs for the string of
+ * text. The first glyph is placed so that its origin is at the
+ * current point. The origin of each subsequent glyph is offset from
+ * that of the previous glyph by th advance values of the previous
+ * glyph.
+ *
+ * After this call the current point is moved to the origin of where
+ * the next glyph would be placed in this same progression. That is,
+ * the current point will be at the origin of the final glyph offset
+ * by its advance values. This allows for easy display of a single
+ * logical string with multiple calls to cairo_show_text.
+ *
+ * NOTE: The cairo_show_text() function call is part of what the cairo
+ * designers call the "toy" text API. It is convenient for short demos
+ * and simple programs, but it is not expected to be adequate for the
+ * most serious of text-using applications. See cairo_show_glyphs()
+ * for the "real" text display API in cairo.
+ **/
 void
 cairo_show_text (cairo_t *cr, const char *utf8)
 {
-    cairo_glyph_t *glyphs = NULL;
+    cairo_text_extents_t extents;
+    cairo_glyph_t *glyphs = NULL, *last_glyph;
     int num_glyphs;
     double x, y;
 
@@ -2092,16 +2120,28 @@ cairo_show_text (cairo_t *cr, const char *utf8)
     cr->status = _cairo_gstate_text_to_glyphs (cr->gstate, utf8,
 					       x, y,
 					       &glyphs, &num_glyphs);
+    if (cr->status)
+	goto BAIL;
 
-    if (cr->status) {
-	if (glyphs)
-	    free (glyphs);
-	_cairo_set_error (cr, cr->status);
+    if (num_glyphs == 0)
 	return;
-    }
 
     cr->status = _cairo_gstate_show_glyphs (cr->gstate, glyphs, num_glyphs);
+    if (cr->status)
+	goto BAIL;
 
+    last_glyph = &glyphs[num_glyphs - 1];
+    cr->status = _cairo_gstate_glyph_extents (cr->gstate,
+					      last_glyph, 1,
+					      &extents);
+    if (cr->status)
+	goto BAIL;
+
+    x = last_glyph->x + extents.x_advance;
+    y = last_glyph->y + extents.y_advance;
+    cairo_move_to (cr, x, y);
+
+ BAIL:
     if (glyphs)
 	free (glyphs);
 

test/.cvsignore

@@ -48,6 +48,7 @@ select-font-no-show-text
 self-copy
 self-intersecting
 set-source
+show-text-current-point
 source-clip
 source-surface-scale-paint
 surface-finish-twice

test/Makefile.am

@@ -36,6 +36,7 @@ select-font-no-show-text	\
 self-copy			\
 self-intersecting		\
 set-source			\
+show-text-current-point		\
 source-clip			\
 source-surface-scale-paint	\
 surface-finish-twice		\
@@ -109,6 +110,7 @@ self-copy-ref.png			\
 self-intersecting-ref.png		\
 scale-source-surface-paint-ref.png	\
 set-source-ref.png			\
+show-text-current-point-ref.png		\
 source-clip-ref.png			\
 source-surface-scale-paint-ref.png	\
 surface-pattern-ref.png			\
@@ -220,6 +222,7 @@ select_font_no_show_text_LDADD = $(LDADDS)
 self_copy_LDADD = $(LDADDS)
 self_intersecting_LDADD = $(LDADDS)
 set_source_LDADD = $(LDADDS)
+show_text_current_point_LDADD = $(LDADDS)
 source_clip_LDADD = $(LDADDS)
 source_surface_scale_paint_LDADD = $(LDADDS)
 surface_finish_twice_LDADD = $(LDADDS)

test/show-text-current-point.c

@@ -0,0 +1,68 @@
+/*
+ * Copyright © 2005 Red Hat, Inc.
+ *
+ * Permission to use, copy, modify, distribute, and sell this software
+ * and its documentation for any purpose is hereby granted without
+ * fee, provided that the above copyright notice appear in all copies
+ * and that both that copyright notice and this permission notice
+ * appear in supporting documentation, and that the name of
+ * Red Hat, Inc. not be used in advertising or publicity pertaining to
+ * distribution of the software without specific, written prior
+ * permission. Red Hat, Inc. makes no representations about the
+ * suitability of this software for any purpose.  It is provided "as
+ * is" without express or implied warranty.
+ *
+ * RED HAT, INC. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
+ * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS, IN NO EVENT SHALL RED HAT, INC. BE LIABLE FOR ANY SPECIAL,
+ * INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
+ * RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+ * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ * Author: Carl D. Worth <cworth@cworth.org>
+ */
+
+#include "cairo-test.h"
+
+#define TEXT_SIZE 12
+
+cairo_test_t test = {
+    "show-text-current-point",
+    "Test that cairo_show_text adjusts the current point properly",
+    263, TEXT_SIZE + 4
+};
+
+static cairo_test_status_t
+draw (cairo_t *cr, int width, int height)
+{
+    cairo_font_options_t *font_options;
+
+    cairo_select_font_face (cr, "Bitstream Vera Sans",
+			    CAIRO_FONT_SLANT_NORMAL,
+			    CAIRO_FONT_WEIGHT_NORMAL);
+    cairo_set_font_size (cr, TEXT_SIZE);
+
+    font_options = cairo_font_options_create ();
+
+    cairo_font_options_set_hint_style (font_options, CAIRO_HINT_STYLE_NONE);
+    cairo_font_options_set_antialias (font_options, CAIRO_ANTIALIAS_GRAY);
+
+    cairo_set_font_options (cr, font_options);
+    cairo_font_options_destroy (font_options);
+
+    cairo_set_source_rgb (cr, 0, 0, 0); /* black */
+
+    cairo_move_to (cr, 0, TEXT_SIZE);
+    cairo_show_text (cr, "Hello from the ");
+    cairo_show_text (cr, test.name);
+    cairo_show_text (cr, " test.");
+
+    return CAIRO_TEST_SUCCESS;
+}
+
+int
+main (void)
+{
+    return cairo_test (&test, draw);
+}