summaryrefslogtreecommitdiff
path: root/pango/pango-glyph-item.h
diff options
context:
space:
mode:
Diffstat (limited to 'pango/pango-glyph-item.h')
-rw-r--r--pango/pango-glyph-item.h64
1 files changed, 64 insertions, 0 deletions
diff --git a/pango/pango-glyph-item.h b/pango/pango-glyph-item.h
index 71c4ab31..61b5ec47 100644
--- a/pango/pango-glyph-item.h
+++ b/pango/pango-glyph-item.h
@@ -29,6 +29,15 @@
G_BEGIN_DECLS
+/**
+ * PangoGlyphItem:
+ *
+ * A #PangoGlyphItem is a pair of a #PangoItem and the glyphs
+ * resulting from shaping the text corresponding to an item.
+ * As an example of the usage of #PangoGlyphItem, the results
+ * of shaping text with #PangoLayout is a list of #PangoLayoutLine,
+ * each of which contains a list of #PangoGlyphItem.
+ */
typedef struct _PangoGlyphItem PangoGlyphItem;
struct _PangoGlyphItem
@@ -37,6 +46,11 @@ struct _PangoGlyphItem
PangoGlyphString *glyphs;
};
+/**
+ * PANGO_TYPE_GLYPH_ITEM:
+ *
+ * The #GObject type for #PangoGlyphItem.
+ */
#define PANGO_TYPE_GLYPH_ITEM (pango_glyph_item_get_type ())
GType pango_glyph_item_get_type (void) G_GNUC_CONST;
@@ -58,6 +72,49 @@ void pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item,
int *logical_widths);
+/**
+ * PangoGlyphItemIter:
+ *
+ * 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.
+ *
+ * Since: 1.22
+ */
typedef struct _PangoGlyphItemIter PangoGlyphItemIter;
struct _PangoGlyphItemIter
@@ -74,6 +131,13 @@ struct _PangoGlyphItemIter
int end_char;
};
+/**
+ * PANGO_TYPE_GLYPH_ITEM_ITER:
+ *
+ * The #GObject type for #PangoGlyphItemIter.
+ *
+ * Since: 1.22
+ */
#define PANGO_TYPE_GLYPH_ITEM_ITER (pango_glyph_item_iter_get_type ())
GType pango_glyph_item_iter_get_type (void) G_GNUC_CONST;