Bug 377948 – Make pango_glyph_item_iter public

2008-08-06  Behdad Esfahbod  <behdad@gnome.org>

        Bug 377948 – Make pango_glyph_item_iter public

        * pango/pango-glyph-item.c (pango_glyph_item_iter_copy),
        (pango_glyph_item_iter_free), (pango_glyph_item_iter_get_type),
        (pango_glyph_item_iter_next_cluster),
        (pango_glyph_item_iter_prev_cluster),
        (pango_glyph_item_iter_init_start),
        (pango_glyph_item_iter_init_end), (pango_glyph_item_apply_attrs),
        (pango_glyph_item_letter_space):
        * pango/pango-glyph-item.h:
        New public API, for iterating a PangoGlyphItem:

                PangoGlyphItemIter
                PANGO_TYPE_GLYPH_ITEM_ITER
                pango_glyph_item_iter_copy()
                pango_glyph_item_iter_free()
                pango_glyph_item_iter_init_start()
                pango_glyph_item_iter_init_end()
                pango_glyph_item_iter_next_cluster()
                pango_glyph_item_iter_prev_cluster()

        * pango/pango.def:
        * docs/tmpl/glyphs.sgml:
        * docs/pango-sections.txt:
        * pango/Makefile.am:
        * pango/ellipsize.c (line_iter_next_cluster),
        (line_iter_prev_cluster), (find_initial_span):
        * pango/pango-layout.c (justify_words):
        Update.

        * pango/pango-glyph-item-private.h:
        Remove.

svn path=/trunk/; revision=2679

2 files changed, 131 insertions, 4 deletions

diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
index 6c804a9c..772e70c5 100644
--- a/docs/pango-sections.txt
+++ b/docs/pango-sections.txt
@@ -100,6 +100,7 @@ PangoGlyphUnit
 PangoGlyphVisAttr
 PangoGlyphString
 PangoGlyphItem
+PangoGlyphItemIter
 PANGO_TYPE_GLYPH_STRING
 pango_glyph_string_new
 pango_glyph_string_copy
@@ -112,15 +113,23 @@ pango_glyph_string_index_to_x
 pango_glyph_string_x_to_index
 pango_glyph_string_get_logical_widths
 PANGO_TYPE_GLYPH_ITEM
+pango_glyph_item_copy
+pango_glyph_item_free
 pango_glyph_item_split
 pango_glyph_item_apply_attrs
 pango_glyph_item_letter_space
-pango_glyph_item_copy
-pango_glyph_item_free
+PANGO_TYPE_GLYPH_ITEM_ITER
+pango_glyph_item_iter_copy
+pango_glyph_item_iter_free
+pango_glyph_item_iter_init_start
+pango_glyph_item_iter_init_end
+pango_glyph_item_iter_next_cluster
+pango_glyph_item_iter_prev_cluster
 
 <SUBSECTION Private>
 pango_glyph_string_get_type
 pango_glyph_item_get_type
+pango_glyph_item_iter_get_type
 pango_matrix_get_type
 </SECTION>
 
diff --git a/docs/tmpl/glyphs.sgml b/docs/tmpl/glyphs.sgml
index fb9bd7bf..cb82ba96 100644
--- a/docs/tmpl/glyphs.sgml
+++ b/docs/tmpl/glyphs.sgml
@@ -412,6 +412,59 @@ each of which contains a list of #PangoGlyphItem.
 @glyphs: the glyphs obtained by shaping the text
          corresponding to @item.
 
+<!-- ##### STRUCT PangoGlyphItemIter ##### -->
+<para>
+A #PangoGlyphItemIter is an iterator over the clusters in a
+#PangoGlyphItem.  The <firstterm>forward direction</firstterm> of the
+iterator is the logical direction of text.  That is, with increasing
+@start_index and @start_char values.  If @glyph_item is right-to-left
+(that is, if <literal>@glyph_item->item->analysis.level</literal> is odd),
+then @start_glyph decreases as the iterator moves forward.  Moreover,
+in right-to-left cases, @start_glyph is greater than @end_glyph.
+
+An iterator should be initialized using either of
+pango_glyph_item_iter_init_start() and
+pango_glyph_item_iter_init_end(), for forward and backward iteration
+respectively, and walked over using any desired mixture of
+pango_glyph_item_iter_next_cluster() and
+pango_glyph_item_iter_prev_cluster().  A common idiom for doing a
+forward iteration over the clusters is:
+<programlisting>
+PangoGlyphItemIter cluster_iter;
+gboolean have_cluster;
+
+for (have_cluster = pango_glyph_item_iter_init_start (&amp;cluster_iter,
+                                                      glyph_item, text);
+     have_cluster;
+     have_cluster = pango_glyph_item_iter_next_cluster (&amp;cluster_iter))
+{
+  ...
+}
+</programlisting>
+
+Note that @text is the start of the text for layout, which is then
+indexed by <literal>@glyph_item->item->offset</literal> to get to the
+text of @glyph_item.  The @start_index and @end_index values can directly
+index into @text.  The @start_glyph, @end_glyph, @start_char, and @end_char
+values however are zero-based for the @glyph_item.  For each cluster, the
+item pointed at by the start variables is included in the cluster while
+the one pointed at by end variables is not.
+
+None of the members of a #PangoGlyphItemIter should be modified manually.
+
+</para>
+
+@glyph_item: the #PangoGlyphItem this iterator iterates over
+@text: the UTF-8 text that @glyph_item refers to
+@start_glyph: starting glyph of the cluster
+@start_index: starting text index of the cluster
+@start_char: starting number of characters of the cluster
+@end_glyph: ending glyph of the cluster
+@end_index: ending text index of the cluster
+@end_char: ending number of characters of the cluster
+
+@Since: 1.22
+
 <!-- ##### MACRO PANGO_TYPE_GLYPH_STRING ##### -->
 <para>
 The #GObject type for #PangoGlyphString.
@@ -534,6 +587,23 @@ The #GObject type for #PangoGlyphItem.
 @Since: 1.20
 
 
+<!-- ##### FUNCTION pango_glyph_item_copy ##### -->
+<para>
+
+</para>
+
+@orig:
+@Returns:
+
+
+<!-- ##### FUNCTION pango_glyph_item_free ##### -->
+<para>
+
+</para>
+
+@glyph_item:
+
+
 <!-- ##### FUNCTION pango_glyph_item_split ##### -->
 <para>
 
@@ -567,7 +637,15 @@ The #GObject type for #PangoGlyphItem.
 @letter_spacing: 
 
 
-<!-- ##### FUNCTION pango_glyph_item_copy ##### -->
+<!-- ##### MACRO PANGO_TYPE_GLYPH_ITEM_ITER ##### -->
+<para>
+The #GObject type for #PangoGlyphItemIter.
+</para>
+
+@Since: 1.22
+
+
+<!-- ##### FUNCTION pango_glyph_item_iter_copy ##### -->
 <para>
 
 </para>
@@ -576,11 +654,51 @@ The #GObject type for #PangoGlyphItem.
 @Returns: 
 
 
-<!-- ##### FUNCTION pango_glyph_item_free ##### -->
+<!-- ##### FUNCTION pango_glyph_item_iter_free ##### -->
+<para>
+
+</para>
+
+@iter:
+
+
+<!-- ##### FUNCTION pango_glyph_item_iter_init_start ##### -->
+<para>
+
+</para>
+
+@iter:
+@glyph_item:
+@text:
+@Returns:
+
+
+<!-- ##### FUNCTION pango_glyph_item_iter_init_end ##### -->
 <para>
 
 </para>
 
+@iter:
 @glyph_item: 
+@text:
+@Returns:
+
+
+<!-- ##### FUNCTION pango_glyph_item_iter_next_cluster ##### -->
+<para>
+
+</para>
+
+@iter:
+@Returns:
+
+
+<!-- ##### FUNCTION pango_glyph_item_iter_prev_cluster ##### -->
+<para>
+
+</para>
+
+@iter:
+@Returns: