GNOME.org
 

pango r2679 - in trunk: . docs docs/tmpl pango

Author: behdad
Date: Wed Aug  6 08:39:43 2008
New Revision: 2679
URL: http://svn.gnome.org/viewvc/pango?rev=2679&view=rev

Log:
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.

Removed:
   trunk/pango/pango-glyph-item-private.h
Modified:
   trunk/ChangeLog
   trunk/docs/pango-sections.txt
   trunk/docs/tmpl/glyphs.sgml
   trunk/pango/Makefile.am
   trunk/pango/ellipsize.c
   trunk/pango/pango-glyph-item.c
   trunk/pango/pango-glyph-item.h
   trunk/pango/pango-layout.c
   trunk/pango/pango.def

Modified: trunk/docs/pango-sections.txt
==============================================================================
--- trunk/docs/pango-sections.txt	(original)
+++ trunk/docs/pango-sections.txt	Wed Aug  6 08:39:43 2008
@@ -100,6 +100,7 @@
 PangoGlyphVisAttr
 PangoGlyphString
 PangoGlyphItem
+PangoGlyphItemIter
 PANGO_TYPE_GLYPH_STRING
 pango_glyph_string_new
 pango_glyph_string_copy
@@ -112,15 +113,23 @@
 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>
 

Modified: trunk/docs/tmpl/glyphs.sgml
==============================================================================
--- trunk/docs/tmpl/glyphs.sgml	(original)
+++ trunk/docs/tmpl/glyphs.sgml	Wed Aug  6 08:39:43 2008
@@ -412,6 +412,59 @@
 @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 @@
 @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 @@
 @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 @@
 @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:
 
 

Modified: trunk/pango/Makefile.am
==============================================================================
--- trunk/pango/Makefile.am	(original)
+++ trunk/pango/Makefile.am	Wed Aug  6 08:39:43 2008
@@ -76,7 +76,6 @@
 	pango-fontmap.c				\
 	pango-fontset.c				\
 	pango-glyph-item.c			\
-	pango-glyph-item-private.h		\
 	pango-gravity.c				\
 	pango-impl-utils.h			\
 	pango-item.c				\

Modified: trunk/pango/ellipsize.c
==============================================================================
--- trunk/pango/ellipsize.c	(original)
+++ trunk/pango/ellipsize.c	Wed Aug  6 08:39:43 2008
@@ -22,7 +22,7 @@
 #include "config.h"
 #include <string.h>
 
-#include "pango-glyph-item-private.h"
+#include "pango-glyph-item.h"
 #include "pango-layout-private.h"
 #include "pango-engine-private.h"
 
@@ -187,16 +187,16 @@
 line_iter_next_cluster (EllipsizeState *state,
 			LineIter       *iter)
 {
-  if (!_pango_glyph_item_iter_next_cluster (&iter->run_iter))
+  if (!pango_glyph_item_iter_next_cluster (&iter->run_iter))
     {
       if (iter->run_index == state->n_runs - 1)
 	return FALSE;
       else
 	{
 	  iter->run_index++;
-	  _pango_glyph_item_iter_init_start (&iter->run_iter,
-					     state->run_info[iter->run_index].run,
-					     state->layout->text);
+	  pango_glyph_item_iter_init_start (&iter->run_iter,
+					    state->run_info[iter->run_index].run,
+					    state->layout->text);
 	}
     }
 
@@ -209,16 +209,16 @@
 line_iter_prev_cluster (EllipsizeState *state,
 			LineIter       *iter)
 {
-  if (!_pango_glyph_item_iter_prev_cluster (&iter->run_iter))
+  if (!pango_glyph_item_iter_prev_cluster (&iter->run_iter))
     {
       if (iter->run_index == 0)
 	return FALSE;
       else
 	{
 	  iter->run_index--;
-	  _pango_glyph_item_iter_init_end (&iter->run_iter,
-					   state->run_info[iter->run_index].run,
-					   state->layout->text);
+	  pango_glyph_item_iter_init_end (&iter->run_iter,
+					  state->run_info[iter->run_index].run,
+					  state->layout->text);
 	}
     }
 
@@ -513,9 +513,9 @@
   glyph_item = state->run_info[i].run;
 
   cluster_width = 0;		/* Quiet GCC, the line must have at least one cluster */
-  for (have_cluster = _pango_glyph_item_iter_init_start (run_iter, glyph_item, state->layout->text);
+  for (have_cluster = pango_glyph_item_iter_init_start (run_iter, glyph_item, state->layout->text);
        have_cluster;
-       have_cluster = _pango_glyph_item_iter_next_cluster (run_iter))
+       have_cluster = pango_glyph_item_iter_next_cluster (run_iter))
     {
       cluster_width = get_cluster_width (&state->gap_start_iter);
 

Modified: trunk/pango/pango-glyph-item.c
==============================================================================
--- trunk/pango/pango-glyph-item.c	(original)
+++ trunk/pango/pango-glyph-item.c	Wed Aug  6 08:39:43 2008
@@ -23,7 +23,6 @@
 #include <string.h>
 
 #include "pango-glyph-item.h"
-#include "pango-glyph-item-private.h"
 #include "pango-impl-utils.h"
 
 #define LTR(glyph_item) (((glyph_item)->item->analysis.level % 2) == 0)
@@ -134,7 +133,7 @@
  * pango_glyph_item_copy:
  * @orig: a #PangoGlyphItem, may be %NULL
  *
- * Make a deep copy an existing #PangoGlyphItem structure.
+ * Make a deep copy of an existing #PangoGlyphItem structure.
  *
  * Return value: the newly allocated #PangoGlyphItem, which should
  *               be freed with pango_glyph_item_free(), or %NULL
@@ -162,7 +161,7 @@
  * pango_glyph_item_free:
  * @glyph_item: a #PangoGlyphItem, may be %NULL
  *
- * Frees a #PangoGlyphItem and memory to which it points.
+ * Frees a #PangoGlyphItem and resources to which it points.
  *
  * Since: 1.6
  **/
@@ -192,17 +191,77 @@
   return our_type;
 }
 
+
 /**
- * _pango_glyph_item_iter_next_cluster:
+ * pango_glyph_item_iter_copy:
+ * @orig: a #PangoGlyphItemIter, may be %NULL
+ *
+ * Make a shallow copy of an existing #PangoGlyphItemIter structure.
+ *
+ * Return value: the newly allocated #PangoGlyphItemIter, which should
+ *               be freed with pango_glyph_item_iter_free(), or %NULL
+ *               if @orig was %NULL.
+ *
+ * Since: 1.22
+ **/
+PangoGlyphItemIter *
+pango_glyph_item_iter_copy  (PangoGlyphItemIter *orig)
+{
+  PangoGlyphItemIter *result;
+
+  if (orig == NULL)
+    return NULL;
+
+  result = g_slice_new (PangoGlyphItemIter);
+
+  *result = *orig;
+
+  return result;
+}
+
+/**
+ * pango_glyph_item_iter_free:
+ * @iter: a #PangoGlyphItemIter, may be %NULL
+ *
+ * Frees a #PangoGlyphItemIter created by pango_glyph_item_iter_copy().
+ *
+ * Since: 1.22
+ **/
+void
+pango_glyph_item_iter_free  (PangoGlyphItemIter *iter)
+{
+  if (iter == NULL)
+    return;
+
+  g_slice_free (PangoGlyphItemIter, iter);
+}
+
+GType
+pango_glyph_item_iter_get_type (void)
+{
+  static GType our_type = 0;
+
+  if (G_UNLIKELY (our_type == 0))
+    our_type = g_boxed_type_register_static (I_("PangoGlyphItemIter"),
+					     (GBoxedCopyFunc) pango_glyph_item_iter_copy,
+					     (GBoxedFreeFunc) pango_glyph_item_iter_free);
+  return our_type;
+}
+
+/**
+ * pango_glyph_item_iter_next_cluster:
  * @iter: a #PangoGlyphItemIter
  *
  * Advances the iterator to the next cluster in the glyph item.
+ * See #PangoGlyphItemIter for details of cluster orders.
  *
  * Return value: %TRUE if the iterator was advanced, %FALSE if we were already on the
  *  last cluster.
+ *
+ * Since: 1.22
  **/
 gboolean
-_pango_glyph_item_iter_next_cluster (PangoGlyphItemIter *iter)
+pango_glyph_item_iter_next_cluster (PangoGlyphItemIter *iter)
 {
   int glyph_index = iter->end_glyph;
   PangoGlyphString *glyphs = iter->glyph_item->glyphs;
@@ -276,16 +335,19 @@
 }
 
 /**
- * _pango_glyph_item_iter_prev_cluster:
+ * pango_glyph_item_iter_prev_cluster:
  * @iter: a #PangoGlyphItemIter
  *
  * Moves the iterator to the preceding cluster in the glyph item.
+ * See #PangoGlyphItemIter for details of cluster orders.
  *
  * Return value: %TRUE if the iterator was moved, %FALSE if we were already on the
  *  first cluster.
+ *
+ * Since: 1.22
  **/
 gboolean
-_pango_glyph_item_iter_prev_cluster (PangoGlyphItemIter *iter)
+pango_glyph_item_iter_prev_cluster (PangoGlyphItemIter *iter)
 {
   int glyph_index = iter->start_glyph;
   PangoGlyphString *glyphs = iter->glyph_item->glyphs;
@@ -362,21 +424,23 @@
 }
 
 /**
- * _pango_glyph_item_iter_init_start:
- * @iter: pointer to a #PangoGlyphItemIter structure
- * @glyph_item: the glyph item that @iter points into
+ * pango_glyph_item_iter_init_start:
+ * @iter: a #PangoGlyphItemIter
+ * @glyph_item: the glyph item to iterate over
  * @text: text corresponding to the glyph item
  *
  * Initializes a #PangoGlyphItemIter structure to point to the
  * first cluster in a glyph item.
+ * See #PangoGlyphItemIter for details of cluster orders.
+ *
+ * Return value: %FALSE if there are no clusters in the glyph item
  *
- * Return value: %FALSE if there are no clusters in the glyph item;
- *  in this case, the state of @iter is undefined.
+ * Since: 1.22
  **/
 gboolean
-_pango_glyph_item_iter_init_start (PangoGlyphItemIter  *iter,
-				   PangoGlyphItem      *glyph_item,
-				   const char          *text)
+pango_glyph_item_iter_init_start (PangoGlyphItemIter  *iter,
+				  PangoGlyphItem      *glyph_item,
+				  const char          *text)
 {
   iter->glyph_item = glyph_item;
   iter->text = text;
@@ -389,26 +453,32 @@
   iter->end_index = glyph_item->item->offset;
   iter->end_char = 0;
 
+  iter->start_glyph = iter->end_glyph;
+  iter->start_index = iter->end_index;
+  iter->start_char = iter->end_char;
+
   /* Advance onto the first cluster of the glyph item */
-  return _pango_glyph_item_iter_next_cluster (iter);
+  return pango_glyph_item_iter_next_cluster (iter);
 }
 
 /**
- * _pango_glyph_item_iter_init_end:
- * @iter: pointer to a #PangoGlyphItemIter structure
- * @glyph_item: the glyph item that @iter points into
+ * pango_glyph_item_iter_init_end:
+ * @iter: a #PangoGlyphItemIter
+ * @glyph_item: the glyph item to iterate over
  * @text: text corresponding to the glyph item
  *
  * Initializes a #PangoGlyphItemIter structure to point to the
  * last cluster in a glyph item.
+ * See #PangoGlyphItemIter for details of cluster orders.
+ *
+ * Return value: %FALSE if there are no clusters in the glyph item
  *
- * Return value: %FALSE if there are no clusters in the glyph item;
- *  in this case, the state of @iter is undefined.
+ * Since: 1.22
  **/
 gboolean
-_pango_glyph_item_iter_init_end (PangoGlyphItemIter  *iter,
-				 PangoGlyphItem      *glyph_item,
-				 const char          *text)
+pango_glyph_item_iter_init_end (PangoGlyphItemIter  *iter,
+				PangoGlyphItem      *glyph_item,
+				const char          *text)
 {
   iter->glyph_item = glyph_item;
   iter->text = text;
@@ -421,8 +491,12 @@
   iter->start_index = glyph_item->item->offset + glyph_item->item->length;
   iter->start_char = glyph_item->item->num_chars;
 
+  iter->end_glyph = iter->start_glyph;
+  iter->end_index = iter->start_index;
+  iter->end_char = iter->start_char;
+
   /* Advance onto the first cluster of the glyph item */
-  return _pango_glyph_item_iter_prev_cluster (iter);
+  return pango_glyph_item_iter_prev_cluster (iter);
 }
 
 typedef struct
@@ -556,9 +630,9 @@
       range_end >= glyph_item->item->offset + glyph_item->item->length)
     goto out;
 
-  for (have_cluster = _pango_glyph_item_iter_init_start (&state.iter, glyph_item, text);
+  for (have_cluster = pango_glyph_item_iter_init_start (&state.iter, glyph_item, text);
        have_cluster;
-       have_cluster = _pango_glyph_item_iter_next_cluster (&state.iter))
+       have_cluster = pango_glyph_item_iter_next_cluster (&state.iter))
     {
       gboolean have_next;
 
@@ -675,9 +749,9 @@
 
   space_right = letter_spacing - space_left;
 
-  for (have_cluster = _pango_glyph_item_iter_init_start (&iter, glyph_item, text);
+  for (have_cluster = pango_glyph_item_iter_init_start (&iter, glyph_item, text);
        have_cluster;
-       have_cluster = _pango_glyph_item_iter_next_cluster (&iter))
+       have_cluster = pango_glyph_item_iter_next_cluster (&iter))
     {
       if (!log_attrs[iter.start_char].is_cursor_position)
         continue;

Modified: trunk/pango/pango-glyph-item.h
==============================================================================
--- trunk/pango/pango-glyph-item.h	(original)
+++ trunk/pango/pango-glyph-item.h	Wed Aug  6 08:39:43 2008
@@ -54,6 +54,38 @@
 					       PangoLogAttr   *log_attrs,
 					       int             letter_spacing);
 
+
+typedef struct _PangoGlyphItemIter PangoGlyphItemIter;
+
+struct _PangoGlyphItemIter
+{
+  PangoGlyphItem *glyph_item;
+  const gchar *text;
+
+  int start_glyph;
+  int start_index;
+  int start_char;
+
+  int end_glyph;
+  int end_index;
+  int end_char;
+};
+
+#define PANGO_TYPE_GLYPH_ITEM_ITER (pango_glyph_item_iter_get_type ())
+
+GType               pango_glyph_item_iter_get_type (void) G_GNUC_CONST;
+PangoGlyphItemIter *pango_glyph_item_iter_copy (PangoGlyphItemIter *orig);
+void                pango_glyph_item_iter_free (PangoGlyphItemIter *iter);
+
+gboolean pango_glyph_item_iter_init_start   (PangoGlyphItemIter *iter,
+					     PangoGlyphItem     *glyph_item,
+					     const char         *text);
+gboolean pango_glyph_item_iter_init_end     (PangoGlyphItemIter *iter,
+					     PangoGlyphItem     *glyph_item,
+					     const char         *text);
+gboolean pango_glyph_item_iter_next_cluster (PangoGlyphItemIter *iter);
+gboolean pango_glyph_item_iter_prev_cluster (PangoGlyphItemIter *iter);
+
 G_END_DECLS
 
 #endif /* __PANGO_GLYPH_ITEM_H__ */

Modified: trunk/pango/pango-layout.c
==============================================================================
--- trunk/pango/pango-layout.c	(original)
+++ trunk/pango/pango-layout.c	Wed Aug  6 08:39:43 2008
@@ -25,7 +25,7 @@
 #include "pango-item.h"
 #include "pango-engine.h"
 #include "pango-impl-utils.h"
-#include "pango-glyph-item-private.h"
+#include "pango-glyph-item.h"
 #include <string.h>
 
 #include "pango-layout-private.h"
@@ -5064,9 +5064,9 @@
 	  PangoGlyphItemIter cluster_iter;
 	  gboolean have_cluster;
 
-	  for (have_cluster = _pango_glyph_item_iter_init_start (&cluster_iter, run, text);
+	  for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter, run, text);
 	       have_cluster;
-	       have_cluster = _pango_glyph_item_iter_next_cluster (&cluster_iter))
+	       have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter))
 	    {
 	      int i;
 	      int dir;

Modified: trunk/pango/pango.def
==============================================================================
--- trunk/pango/pango.def	(original)
+++ trunk/pango/pango.def	Wed Aug  6 08:39:43 2008
@@ -183,6 +183,13 @@
 	pango_glyph_item_copy
 	pango_glyph_item_free
 	pango_glyph_item_get_type
+	pango_glyph_item_iter_copy
+	pango_glyph_item_iter_free
+	pango_glyph_item_iter_get_type
+	pango_glyph_item_iter_init_end
+	pango_glyph_item_iter_init_start
+	pango_glyph_item_iter_next_cluster
+	pango_glyph_item_iter_prev_cluster
 	pango_glyph_item_letter_space
 	pango_glyph_item_split
 	pango_glyph_string_copy
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]