summaryrefslogtreecommitdiff
path: root/pango
diff options
context:
space:
mode:
authorMatthias Clasen <mclasen@redhat.com>2022-01-24 14:42:37 -0500
committerMatthias Clasen <mclasen@redhat.com>2022-01-25 15:31:25 -0500
commitff04aaa22877c0c867df157a93d78679c1408ae3 (patch)
tree32341effe6e97b437d8f6ebf577e0c90e6357c17 /pango
parent55097b869512e3805e785c8c8a8bed74654acb42 (diff)
downloadpango-ff04aaa22877c0c867df157a93d78679c1408ae3.tar.gz
lines: Add docs
Diffstat (limited to 'pango')
-rw-r--r--pango/pango-lines.c33
1 files changed, 33 insertions, 0 deletions
diff --git a/pango/pango-lines.c b/pango/pango-lines.c
index bf28f9e9..896a9dd8 100644
--- a/pango/pango-lines.c
+++ b/pango/pango-lines.c
@@ -5,6 +5,39 @@
#include "pango-item-private.h"
#include "pango-layout-iter-private.h"
+/**
+ * PangoLines:
+ *
+ * A `PangoLines` object represents the result of formatting an
+ * entire paragraph (or more) of text.
+ *
+ * A `PangoLines` object contains a list of `PangoLayoutLine` objects,
+ * together with information about where to position each line
+ * in layout coordinates.
+ *
+ * `PangoLines` has APIs to query collective information about
+ * its lines (such as ellipsization or unknown glyphs), to translate
+ * between logical character positions within the text and the physical
+ * position of the resulting glyphs, and to determine cursor positions
+ * for editing the text.
+ *
+ * One way to obtain a `PangoLines` object is to use a [class@Pango.Layout].
+ * But it is also possible to populate a `PangoLines` manually with lines
+ * produced by a [class@Pango.LineBreaker] object.
+ *
+ * Note that the lines that make up a `PangoLines` object don't have to
+ * share the same underlying text. Therefore, using byte indexes to refer
+ * to positions within the `PangoLines` is, in general, ambiguous. All the
+ * `PangoLines` APIs that take a byte index as argument or return one have
+ * a `PangoLine*` companion argument to handle this situation. When all
+ * the lines in the `PangoLines` share the same text (such as when they
+ * originate from the same `PangoLayout`), it is safe to always pass `NULL`
+ * for the `PangoLines*`.
+ *
+ * The most convenient way to access the visual extents and components
+ * of a `PangoLines` is via a [struct@Pango.LayoutIter] iterator.
+ */
+
/* {{{ PangoLines implementation */
typedef struct _Line Line;