summaryrefslogtreecommitdiff
path: root/pango/shape.c
diff options
context:
space:
mode:
authorMatthias Clasen <mclasen@redhat.com>2020-11-07 12:01:23 -0500
committerMatthias Clasen <mclasen@redhat.com>2020-11-07 12:02:05 -0500
commit2f45a0933160f33cc968e32d93c4baf3df067a66 (patch)
treebd55121ac48f1bb4fb37c9634fba2e3c1ad7530b /pango/shape.c
parent17d8202d6be7870a30b8f62e59390f1dd328e49e (diff)
downloadpango-2f45a0933160f33cc968e32d93c4baf3df067a66.tar.gz
Amend the shaping api docsshape-docs
Discuss problems with extra_attr indices in the docs for pango_shape() and friends. See: #511
Diffstat (limited to 'pango/shape.c')
-rw-r--r--pango/shape.c23
1 files changed, 19 insertions, 4 deletions
diff --git a/pango/shape.c b/pango/shape.c
index efdb3177..04624b00 100644
--- a/pango/shape.c
+++ b/pango/shape.c
@@ -45,14 +45,18 @@
* @analysis: #PangoAnalysis structure from pango_itemize()
* @glyphs: glyph string in which to store results
*
- * Given a segment of text and the corresponding
- * #PangoAnalysis structure returned from pango_itemize(),
- * convert the characters into glyphs. You may also pass
- * in only a substring of the item from pango_itemize().
+ * Given a segment of text and the corresponding #PangoAnalysis structure
+ * returned from pango_itemize(), convert the characters into glyphs. You
+ * may also pass in only a substring of the item from pango_itemize().
*
* It is recommended that you use pango_shape_full() instead, since
* that API allows for shaping interaction happening across text item
* boundaries.
+ *
+ * Note that the extra attributes in the @analyis that is returned from
+ * pango_itemize() have indices that are relative to the entire paragraph,
+ * so you need to subtract the item offset from their indices before
+ * calling pango_shape().
*/
void
pango_shape (const gchar *text,
@@ -83,6 +87,11 @@ pango_shape (const gchar *text,
* text of which @item_text is part of, provide the broader text as
* @paragraph_text. If @paragraph_text is %NULL, item text is used instead.
*
+ * Note that the extra attributes in the @analyis that is returned from
+ * pango_itemize() have indices that are relative to the entire paragraph,
+ * so you do not pass the full paragraph text as @paragraph_text, you need
+ * to subtract the item offset from their indices before calling pango_shape_full().
+ *
* Since: 1.32
*/
void
@@ -170,6 +179,12 @@ fallback_shape (const char *text,
* This is similar to pango_shape_full(), except it also takes
* flags that can influence the shaping process.
*
+ * Note that the extra attributes in the @analyis that is returned from
+ * pango_itemize() have indices that are relative to the entire paragraph,
+ * so you do not pass the full paragraph text as @paragraph_text, you need
+ * to subtract the item offset from their indices before calling
+ * pango_shape_with_flags().
+ *
* Since: 1.44
*/
void