Add new public API cairo_surface_has_show_text_glyphs()

We added cairo_has_show_text_glyphs() before.  Since this is really a
surface property, should have the surface method too.  Like we added
cairo_surface_show_page()...

doc/public/cairo-sections.txt

@@ -189,6 +189,7 @@ cairo_surface_set_user_data
 cairo_surface_get_user_data
 cairo_surface_copy_page
 cairo_surface_show_page
+cairo_surface_has_show_text_glyphs
 </SECTION>
 
 <SECTION>

doc/public/tmpl/cairo-surface.sgml

@@ -250,3 +250,12 @@ cairo_<emphasis>backend</emphasis>_surface_create().
 @surface: 
 
 
+<!-- ##### FUNCTION cairo_surface_has_show_text_glyphs ##### -->
+<para>
+
+</para>
+
+@surface:
+@Returns:
+
+

src/cairo-analysis-surface.c

@@ -621,7 +621,7 @@ _cairo_analysis_surface_has_show_text_glyphs (void *abstract_surface)
 {
     cairo_analysis_surface_t *surface = abstract_surface;
 
-    return _cairo_surface_has_show_text_glyphs (surface->target);
+    return cairo_surface_has_show_text_glyphs (surface->target);
 }
 
 static cairo_int_status_t

src/cairo-gstate.c

@@ -1525,7 +1525,7 @@ _cairo_gstate_glyph_extents (cairo_gstate_t *gstate,
 cairo_bool_t
 _cairo_gstate_has_show_text_glyphs (cairo_gstate_t *gstate)
 {
-    return _cairo_surface_has_show_text_glyphs (gstate->target);
+    return cairo_surface_has_show_text_glyphs (gstate->target);
 }
 
 cairo_status_t

src/cairo-paginated-surface.c

@@ -609,7 +609,7 @@ _cairo_paginated_surface_has_show_text_glyphs (void *abstract_surface)
 {
     cairo_paginated_surface_t *surface = abstract_surface;
 
-    return _cairo_surface_has_show_text_glyphs (surface->target);
+    return cairo_surface_has_show_text_glyphs (surface->target);
 }
 
 static cairo_int_status_t

src/cairo-surface.c

@@ -1738,6 +1738,9 @@ _cairo_surface_composite_trapezoids (cairo_operator_t		op,
  * be retained for the next page.  Use cairo_surface_show_page() if you
  * want to get an empty page after the emission.
  *
+ * There is a convenience function for this that takes a #cairo_t,
+ * namely cairo_copy_page().
+ *
  * Since: 1.6
  */
 void
@@ -1772,6 +1775,9 @@ slim_hidden_def (cairo_surface_copy_page);
  * Emits and clears the current page for backends that support multiple
  * pages.  Use cairo_surface_copy_page() if you don't want to clear the page.
  *
+ * There is a convenience function for this that takes a #cairo_t,
+ * namely cairo_show_page().
+ *
  * Since: 1.6
  **/
 void
@@ -2141,14 +2147,50 @@ _cairo_surface_get_extents (cairo_surface_t         *surface,
     return status;
 }
 
+/**
+ * cairo_surface_has_show_text_glyphs:
+ * @surface: a #cairo_surface_t
+ *
+ * Returns whether the surface supports
+ * sophisticated cairo_show_text_glyphs() operations.  That is,
+ * whether it actually uses the provided text and cluster data
+ * to a cairo_show_text_glyphs() call.
+ *
+ * Note: Even if this function returns %FALSE, a
+ * cairo_show_text_glyphs() operation targeted at @surface will
+ * still succeed.  It just will
+ * act like a cairo_show_glyphs() operation.  Users can use this
+ * function to avoid computing UTF-8 text and cluster mapping if the
+ * target surface does not use it.
+ *
+ * There is a convenience function for this that takes a #cairo_t,
+ * namely cairo_has_show_text_glyphs().
+ *
+ * Return value: %TRUE if @surface supports
+ *               cairo_show_text_glyphs(), %FALSE otherwise
+ *
+ * Since: 1.8
+ **/
 cairo_bool_t
-_cairo_surface_has_show_text_glyphs (cairo_surface_t	    *surface)
+cairo_surface_has_show_text_glyphs (cairo_surface_t	    *surface)
 {
+    cairo_status_t status_ignored;
+
+    if (surface->status)
+	return FALSE;
+
+    if (surface->finished) {
+	status_ignored = _cairo_surface_set_error (surface,
+						   CAIRO_STATUS_SURFACE_FINISHED);
+	return FALSE;
+    }
+
     if (surface->backend->has_show_text_glyphs)
 	return surface->backend->has_show_text_glyphs (surface);
     else
 	return surface->backend->show_text_glyphs != NULL;
 }
+slim_hidden_def (cairo_surface_has_show_text_glyphs);
 
 /* Note: the backends may modify the contents of the glyph array as long as
  * they do not return %CAIRO_INT_STATUS_UNSUPPORTED. This makes it possible to

src/cairo.c

@@ -3227,6 +3227,9 @@ cairo_show_glyphs (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs)
  * function to avoid computing UTF-8 text and cluster mapping if the
  * target surface does not use it.
  *
+ * This is a convenience function that simply calls
+ * cairo_surface_has_show_text_glyphs() on @cr's target.
+ *
  * Return value: %TRUE if the target surface of @cr supports
  *               cairo_show_text_glyphs(), %FALSE otherwise
  *

src/cairo.h

@@ -1981,6 +1981,9 @@ cairo_surface_copy_page (cairo_surface_t *surface);
 cairo_public void
 cairo_surface_show_page (cairo_surface_t *surface);
 
+cairo_public cairo_bool_t
+cairo_surface_has_show_text_glyphs (cairo_surface_t *surface);
+
 /* Image-surface functions */
 
 /**

src/cairoint.h

@@ -1752,9 +1752,6 @@ _cairo_surface_fill (cairo_surface_t	*surface,
 		     double		 tolerance,
 		     cairo_antialias_t	 antialias);
 
-cairo_private cairo_bool_t
-_cairo_surface_has_show_text_glyphs (cairo_surface_t	    *surface);
-
 cairo_private cairo_status_t
 _cairo_surface_show_text_glyphs (cairo_surface_t	    *surface,
 				 cairo_operator_t	     op,
@@ -2454,6 +2451,7 @@ slim_hidden_proto (cairo_surface_get_content);
 slim_hidden_proto (cairo_surface_get_device_offset);
 slim_hidden_proto (cairo_surface_get_font_options);
 slim_hidden_proto (cairo_surface_get_type);
+slim_hidden_proto (cairo_surface_has_show_text_glyphs);
 slim_hidden_proto (cairo_surface_mark_dirty_rectangle);
 slim_hidden_proto_no_warn (cairo_surface_reference);
 slim_hidden_proto (cairo_surface_set_device_offset);

src/test-meta-surface.c

@@ -260,7 +260,7 @@ _test_meta_surface_has_show_text_glyphs (void *abstract_surface)
 {
     test_meta_surface_t *surface = abstract_surface;
 
-    return _cairo_surface_has_show_text_glyphs (surface->meta);
+    return cairo_surface_has_show_text_glyphs (surface->meta);
 }
 
 static cairo_int_status_t

src/test-paginated-surface.c

@@ -237,7 +237,7 @@ _test_paginated_surface_has_show_text_glyphs (void *abstract_surface)
 {
     test_paginated_surface_t *surface = abstract_surface;
 
-    return _cairo_surface_has_show_text_glyphs (surface->target);
+    return cairo_surface_has_show_text_glyphs (surface->target);
 }
 
 static cairo_int_status_t