summaryrefslogtreecommitdiff
path: root/pango
diff options
context:
space:
mode:
authorMatthias Clasen <mclasen@redhat.com>2021-02-19 08:10:54 -0500
committerMatthias Clasen <mclasen@redhat.com>2021-03-11 13:17:36 -0500
commitbaea52e0a6cbff7397ec35269284ee1091cee844 (patch)
tree6cdde9ad65bfa598ddfdc1ff572b53ad56c6887d /pango
parent1b559404a56d3ccc075283e38222df064a13eac0 (diff)
downloadpango-baea52e0a6cbff7397ec35269284ee1091cee844.tar.gz
docs: Tweak layout docs
Add summaries, convert markup, etc.
Diffstat (limited to 'pango')
-rw-r--r--pango/pango-layout.c220
-rw-r--r--pango/pango-layout.h31
2 files changed, 141 insertions, 110 deletions
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index d287df50..2a836f64 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -20,25 +20,24 @@
*/
/**
- * SECTION:pangolayout
- * @short_description:High-level layout driver objects
- * @title:Layout Objects
+ * PangoLayout:
+ *
+ * A `PangoLayout` structure represents an entire paragraph of text.
*
* While complete access to the layout capabilities of Pango is provided
* using the detailed interfaces for itemization and shaping, using
* that functionality directly involves writing a fairly large amount
- * of code. The objects and functions in this section provide a
- * high-level driver for formatting entire paragraphs of text
- * at once. This includes paragraph-level functionality such as
- * line breaking, justification, alignment and ellipsization.
- *
- * The `PangoLayout` structure represents an entire paragraph
- * of text. It is initialized with a `PangoContext`, UTF-8 string
- * and set of attributes for that string. Once that is done, the
- * set of formatted lines can be extracted from the object,
- * the layout can be rendered, and conversion between logical
- * character positions within the layout's text, and the physical
- * position of the resulting glyphs can be made.
+ * of code. `PangoLayout` provides a high-level driver for formatting
+ * entire paragraphs of text at once. This includes paragraph-level
+ * functionality such as line breaking, justification, alignment and
+ * ellipsization.
+ *
+ * A `PangoLayout is initialized with a `PangoContext`, UTF-8 string
+ * and set of attributes for that string. Once that is done, the set of
+ * formatted lines can be extracted from the object, the layout can be
+ * rendered, and conversion between logical character positions within
+ * the layout's text, and the physical position of the resulting glyphs
+ * can be made.
*
* There are a number of parameters to adjust the formatting of a
* `PangoLayout`. The following image shows adjustable parameters
@@ -51,17 +50,12 @@
*/
/**
- * PangoLayout:
- *
- * The `PangoLayout` structure is opaque, and has no user-visible fields.
- */
-
-/**
* PangoLayoutIter:
*
- * A `PangoLayoutIter` structure can be used to iterate over the visual
- * extents of a [class@Pango.Layout]. To obtain a `PangoLayoutIter`, use
- * pango_layout_get_iter().
+ * A `PangoLayoutIter` can be used to iterate over the visual
+ * extents of a `PangoLayout`.
+ *
+ * To obtain a `PangoLayoutIter`, use [method@Pango.Layout.get_iter].
*
* The `PangoLayoutIter` structure is opaque, and has no user-visible fields.
*/
@@ -285,9 +279,10 @@ pango_layout_new (PangoContext *context)
* pango_layout_copy:
* @src: a `PangoLayout`
*
- * Does a deep copy-by-value of the @src layout. The attribute list,
- * tab array, and text from the original layout are all copied by
- * value.
+ * Creates a deep copy-by-value of the layout.
+ *
+ * The attribute list, tab array, and text from the original layout
+ * are all copied by value.
*
* Return value: (transfer full): the newly allocated `PangoLayout`,
* with a reference count of one, which should be freed
@@ -345,7 +340,9 @@ pango_layout_get_context (PangoLayout *layout)
* wrapping or ellipsization should be performed.
*
* Sets the width to which the lines of the `PangoLayout` should wrap or
- * ellipsized. The default value is -1: no width set.
+ * ellipsized.
+ *
+ * The default value is -1: no width set.
*/
void
pango_layout_set_width (PangoLayout *layout,
@@ -390,6 +387,7 @@ pango_layout_get_width (PangoLayout *layout)
* or desired number of lines if negative.
*
* Sets the height to which the `PangoLayout` should be ellipsized at.
+ *
* There are two different behaviors, based on whether @height is positive
* or negative.
*
@@ -442,6 +440,7 @@ pango_layout_set_height (PangoLayout *layout,
* @layout: a `PangoLayout`
*
* Gets the height of layout used for ellipsization.
+ *
* See [method@Pango.Layout.set_height] for details.
*
* Return value: the height, in Pango units if positive,
@@ -461,9 +460,11 @@ pango_layout_get_height (PangoLayout *layout)
* @layout: a `PangoLayout`
* @wrap: the wrap mode
*
- * Sets the wrap mode; the wrap mode only has effect if a width
- * is set on the layout with [method@Pango.Layout.set_width].
- * To turn off wrapping, set the width to -1.
+ * Sets the wrap mode.
+ *
+ * The wrap mode only has effect if a width is set on the layout
+ * with [method@Pango.Layout.set_width]. To turn off wrapping,
+ * set the width to -1.
*/
void
pango_layout_set_wrap (PangoLayout *layout,
@@ -556,8 +557,9 @@ pango_layout_set_indent (PangoLayout *layout,
* pango_layout_get_indent:
* @layout: a `PangoLayout`
*
- * Gets the paragraph indent width in Pango units. A negative value
- * indicates a hanging indentation.
+ * Gets the paragraph indent width in Pango units.
+ *
+ * A negative value indicates a hanging indentation.
*
* Return value: the indent in Pango units.
*/
@@ -574,8 +576,9 @@ pango_layout_get_indent (PangoLayout *layout)
* @spacing: the amount of spacing
*
* Sets the amount of spacing in Pango unit between
- * the lines of the layout. When placing lines with
- * spacing, Pango arranges things so that
+ * the lines of the layout.
+ *
+ * When placing lines with spacing, Pango arranges things so that
*
* line2.top = line1.bottom + spacing
*
@@ -619,8 +622,8 @@ pango_layout_get_spacing (PangoLayout *layout)
* @factor: the new line spacing factor
*
* Sets a factor for line spacing.
- * Typical values are: 0, 1, 1.5, 2.
- * The default values is 0.
+ *
+ * Typical values are: 0, 1, 1.5, 2. The default values is 0.
*
* If @factor is non-zero, lines are placed so that
*
@@ -651,8 +654,9 @@ pango_layout_set_line_spacing (PangoLayout *layout,
* pango_layout_get_line_spacing:
* @layout: a `PangoLayout`
*
- * Gets the value that has been set with
- * [method@Pango.Layout.set_line_spacing].
+ * Gets the line spacing factor of @layout.
+ *
+ * See [method@Pango.Layout.set_line_spacing].
*
* Since: 1.44
*/
@@ -726,8 +730,9 @@ pango_layout_get_attributes (PangoLayout *layout)
* @desc: (allow-none): the new `PangoFontDescription`, or %NULL
* to unset the current font description
*
- * Sets the default font description for the layout. If no font
- * description is set on the layout, the font description from
+ * Sets the default font description for the layout.
+ *
+ * If no font description is set on the layout, the font description from
* the layout's context is used.
*/
void
@@ -776,10 +781,11 @@ pango_layout_get_font_description (PangoLayout *layout)
* @justify: whether the lines in the layout should be justified.
*
* Sets whether each complete line should be stretched to fill the
- * entire width of the layout. This stretching is typically done by
- * adding whitespace, but for some scripts (such as Arabic), the
- * justification may be done in more complex ways, like extending
- * the characters.
+ * entire width of the layout.
+ *
+ * Stretching is typically done by adding whitespace, but for some scripts
+ * (such as Arabic), the justification may be done in more complex ways,
+ * like extending the characters.
*
* Note that this setting is not implemented and so is ignored in
* Pango older than 1.18.
@@ -821,14 +827,14 @@ pango_layout_get_justify (PangoLayout *layout)
* @auto_dir: if %TRUE, compute the bidirectional base direction
* from the layout's contents.
*
- * Sets whether to calculate the bidirectional base direction
- * for the layout according to the contents of the layout;
- * when this flag is on (the default), then paragraphs in
- @layout that begin with strong right-to-left characters
- * (Arabic and Hebrew principally), will have right-to-left
- * layout, paragraphs with letters from other scripts will
- * have left-to-right layout. Paragraphs with only neutral
- * characters get their direction from the surrounding paragraphs.
+ * Sets whether to calculate the base direction
+ * for the layout according to its contents.
+ *
+ * When this flag is on (the default), then paragraphs in @layout that
+ * begin with strong right-to-left characters (Arabic and Hebrew principally),
+ * will have right-to-left layout, paragraphs with letters from other scripts
+ * will have left-to-right layout. Paragraphs with only neutral characters
+ * get their direction from the surrounding paragraphs.
*
* When %FALSE, the choice between left-to-right and right-to-left
* layout is done according to the base direction of the layout's
@@ -859,8 +865,9 @@ pango_layout_set_auto_dir (PangoLayout *layout,
* pango_layout_get_auto_dir:
* @layout: a `PangoLayout`
*
- * Gets whether to calculate the bidirectional base direction
- * for the layout according to the contents of the layout.
+ * Gets whether to calculate the base direction for the layout
+ * according to its contents.
+ *
* See [method@Pango.Layout.set_auto_dir].
*
* Return value: %TRUE if the bidirectional base direction
@@ -919,8 +926,9 @@ pango_layout_get_alignment (PangoLayout *layout)
* @layout: a `PangoLayout`
* @tabs: (allow-none): a `PangoTabArray`, or %NULL
*
- * Sets the tabs to use for @layout, overriding the default tabs
- * (by default, tabs are every 8 spaces). If @tabs is %NULL, the
+ * Sets the tabs to use for @layout, overriding the default tabs.
+ *
+ * By default, tabs are every 8 spaces. If @tabs is %NULL, the
* default tabs are reinstated. @tabs is copied into the layout;
* you must free your copy of @tabs yourself.
*/
@@ -972,6 +980,8 @@ pango_layout_get_tabs (PangoLayout *layout)
* @layout: a `PangoLayout`
* @setting: new setting
*
+ * Sets the single paragraph mode of @layout.
+ *
* If @setting is %TRUE, do not treat newlines and similar characters
* as paragraph separators; instead, keep all text in a single paragraph,
* and display a glyph for paragraph separator characters. Used when
@@ -996,7 +1006,9 @@ pango_layout_set_single_paragraph_mode (PangoLayout *layout,
* pango_layout_get_single_paragraph_mode:
* @layout: a `PangoLayout`
*
- * Obtains the value set by [method@Pango.Layout.set_single_paragraph_mode].
+ * Obtains whether @layout is in single paragraph mode.
+ *
+ * See [method@Pango.Layout.set_single_paragraph_mode].
*
* Return value: %TRUE if the layout does not break paragraphs at
* paragraph separator characters, %FALSE otherwise.
@@ -1015,6 +1027,7 @@ pango_layout_get_single_paragraph_mode (PangoLayout *layout)
* @ellipsize: the new ellipsization mode for @layout
*
* Sets the type of ellipsization being performed for @layout.
+ *
* Depending on the ellipsization mode @ellipsize text is
* removed from the start, middle, or end of text so they
* fit within the width and height of layout set with
@@ -1048,6 +1061,7 @@ pango_layout_set_ellipsize (PangoLayout *layout,
* @layout: a `PangoLayout`
*
* Gets the type of ellipsization being performed for @layout.
+ *
* See [method@Pango.Layout.set_ellipsize].
*
* Use [method@Pango.Layout.is_ellipsized] to query whether any
@@ -1223,7 +1237,12 @@ pango_layout_get_character_count (PangoLayout *layout)
* @length: length of marked-up text in bytes, or -1 if @markup is
* null-terminated
*
- * Same as [method@Pango.Layout.set_markup_with_accel],
+ * Sets the layout text and attribute list from marked-up text.
+ *
+ * See [Pango Markup](pango_markup.html)).
+ * Replaces the current text and attribute list.
+ *
+ * This is the Same as [method@Pango.Layout.set_markup_with_accel],
* but the markup text isn't scanned for accelerators.
*/
void
@@ -1244,9 +1263,10 @@ pango_layout_set_markup (PangoLayout *layout,
* @accel_char: (out caller-allocates) (allow-none): return location
* for first located accelerator, or %NULL
*
- * Sets the layout text and attribute list from marked-up text (see
- * [Pango Markup](pango_markup.html)). Replaces the current text
- * and attribute list.
+ * Sets the layout text and attribute list from marked-up text.
+ *
+ * See [Pango Markup](pango_markup.html)).
+ * Replaces the current text and attribute list.
*
* If @accel_marker is nonzero, the given character will mark the
* character following it as an accelerator. For example, @accel_marker
@@ -1292,9 +1312,7 @@ pango_layout_set_markup_with_accel (PangoLayout *layout,
* pango_layout_get_unknown_glyphs_count:
* @layout: a `PangoLayout`
*
- * Counts the number unknown glyphs in @layout. That is, zero if
- * glyphs for all characters in the layout text were found, or more
- * than zero otherwise.
+ * Counts the number of unknown glyphs in @layout.
*
* This function can be used to determine if there are any fonts
* available to render all characters in a certain string, or when
@@ -1371,9 +1389,10 @@ layout_changed (PangoLayout *layout)
* @layout: a `PangoLayout`
*
* Forces recomputation of any state in the `PangoLayout` that
- * might depend on the layout's context. This function should
- * be called if you make changes to the context subsequent
- * to creating the layout.
+ * might depend on the layout's context.
+ *
+ * This function should be called if you make changes to the context
+ * subsequent to creating the layout.
*/
void
pango_layout_context_changed (PangoLayout *layout)
@@ -1388,12 +1407,13 @@ pango_layout_context_changed (PangoLayout *layout)
* pango_layout_get_serial:
* @layout: a `PangoLayout`
*
- * Returns the current serial number of @layout. The serial number is
- * initialized to an small number larger than zero when a new layout
- * is created and is increased whenever the layout is changed using any
- * of the setter functions, or the `PangoContext` it uses has changed.
- * The serial may wrap, but will never have the value 0. Since it
- * can wrap, never compare it with "less than", always use "not equals".
+ * Returns the current serial number of @layout.
+ *
+ * The serial number is initialized to an small number larger than zero
+ * when a new layout is created and is increased whenever the layout is
+ * changed using any of the setter functions, or the `PangoContext` it
+ * uses has changed. The serial may wrap, but will never have the value 0.
+ * Since it can wrap, never compare it with "less than", always use "not equals".
*
* This can be used to automatically detect changes to a `PangoLayout`,
* and is useful for example to decide whether a layout needs redrawing.
@@ -1804,7 +1824,8 @@ pango_layout_index_to_line_and_extents (PangoLayout *layout,
* (%PANGO_SCALE units per device unit), or %NULL
*
* Converts from byte @index_ within the @layout to line and X position.
- * (X position is measured from the left edge of the line)
+ *
+ * The X position is measured from the left edge of the line.
*/
void
pango_layout_index_to_line_x (PangoLayout *layout,
@@ -1869,10 +1890,12 @@ pango_layout_index_to_line_x (PangoLayout *layout,
* the cursor should be displayed.
*
* Computes a new cursor position from an old position and a count of
- * positions to move visually. If @direction is positive, then the new
- * strong cursor position will be one position to the right of the old
- * cursor position. If @direction is negative, then the new strong cursor
- * position will be one position to the left of the old cursor position.
+ * positions to move visually.
+ *
+ * If @direction is positive, then the new strong cursor position will be
+ * one position to the right of the old cursor position. If @direction is
+ * negative, then the new strong cursor position will be one position to
+ * the left of the old cursor position.
*
* In the presence of bidirectional text, the correspondence between
* logical and visual order will depend on the direction of the current
@@ -2042,7 +2065,9 @@ pango_layout_move_cursor_visually (PangoLayout *layout,
* of the grapheme.
*
* Converts from X and Y position within a layout to the byte index to the
- * character at that logical position. If the Y position is not inside the
+ * character at that logical position.
+ *
+ * If the Y position is not inside the
* layout, the closest position is chosen (the position will be clamped
* inside the layout). If the X position is not within the layout, then
* the start or the end of the line is chosen as described for
@@ -2142,11 +2167,12 @@ pango_layout_xy_to_index (PangoLayout *layout,
* @pos: (out): rectangle in which to store the position of the grapheme
*
* Converts from an index within a `PangoLayout` to the onscreen position
- * corresponding to the grapheme at that index, which is represented
- * as rectangle. Note that `pos->x` is always the leading edge of the
- * grapheme and `pos->x + pos->width` the trailing edge of the grapheme.
- * If the directionality of the grapheme is right-to-left, then `pos->width`
- * will be negative.
+ * corresponding to the grapheme at that index.
+ *
+ * The return value is represented as rectangle. Note that `pos->x` is
+ * always the leading edge of the grapheme and `pos->x + pos->width` the
+ * trailing edge of the grapheme. If the directionality of the grapheme
+ * is right-to-left, then `pos->width` will be negative.
*/
void
pango_layout_index_to_pos (PangoLayout *layout,
@@ -2401,12 +2427,13 @@ pango_layout_get_direction (PangoLayout *layout,
* position (may be %NULL)
*
* Given an index within a layout, determines the positions that of the
- * strong and weak cursors if the insertion point is at that index. The
- * position of each cursor is stored as a zero-width rectangle. The strong
- * cursor location is the location where characters of the directionality
- * equal to the base direction of the layout are inserted. The weak cursor
- * location is the location where characters of the directionality opposite
- * to the base direction of the layout are inserted.
+ * strong and weak cursors if the insertion point is at that index.
+ *
+ * The position of each cursor is stored as a zero-width rectangle.
+ * The strong cursor location is the location where characters of the
+ * directionality equal to the base direction of the layout are inserted.
+ * The weak cursor location is the location where characters of the
+ * directionality opposite to the base direction of the layout are inserted.
*/
void
pango_layout_get_cursor_pos (PangoLayout *layout,
@@ -2896,8 +2923,9 @@ pango_layout_get_pixel_extents (PangoLayout *layout,
* @height: (out) (allow-none): location to store the logical height, or %NULL
*
* Determines the logical width and height of a `PangoLayout` in Pango
- * units (device units scaled by %PANGO_SCALE). This is simply a
- * convenience function around [method@Pango.Layout.get_extents].
+ * units.
+ *
+ * This is simply a convenience function around [method@Pango.Layout.get_extents].
*/
void
pango_layout_get_size (PangoLayout *layout,
@@ -2921,8 +2949,10 @@ pango_layout_get_size (PangoLayout *layout,
* @height: (out) (allow-none): location to store the logical height, or %NULL
*
* Determines the logical width and height of a `PangoLayout` in device
- * units. ([method@Pango.Layout.get_size] returns the width and height
- * scaled by %PANGO_SCALE.) This is simply a convenience function around
+ * units.
+ *
+ * [method@Pango.Layout.get_size] returns the width and height
+ * scaled by %PANGO_SCALE. This is simply a convenience function around
* [method@Pango.Layout.get_pixel_extents].
*/
void
diff --git a/pango/pango-layout.h b/pango/pango-layout.h
index 6182d889..4a464230 100644
--- a/pango/pango-layout.h
+++ b/pango/pango-layout.h
@@ -36,10 +36,9 @@ typedef struct _PangoLayoutLine PangoLayoutLine;
/**
* PangoLayoutRun:
*
- * The `PangoLayoutRun` structure represents a single run within
- * a [struct@Pango.LayoutLine]; it is simply an alternate name for
- * [struct@Pango.GlyphItem].
+ * A `PangoLayoutRun` represents a single run within a `PangoLayoutLine`.
*
+ * It is simply an alternate name for [struct@Pango.GlyphItem].
* See the [struct@Pango.GlyphItem] docs for details on the fields.
*/
typedef PangoGlyphItem PangoLayoutRun;
@@ -50,10 +49,11 @@ typedef PangoGlyphItem PangoLayoutRun;
* @PANGO_ALIGN_CENTER: Center the line within the available space
* @PANGO_ALIGN_RIGHT: Put all available space on the left
*
- * A `PangoAlignment` describes how to align the lines of a `PangoLayout`
- * within the available space. If the `PangoLayout` is set to justify
- * using [method@Pango.Layout.set_justify], this only has effect for
- * partial lines.
+ * `PangoAlignment` describes how to align the lines of a `PangoLayout`
+ * within the available space.
+ *
+ * If the `PangoLayout` is set to justify using [method@Pango.Layout.set_justify],
+ * this only has effect for partial lines.
*/
typedef enum {
PANGO_ALIGN_LEFT,
@@ -68,7 +68,7 @@ typedef enum {
* @PANGO_WRAP_WORD_CHAR: wrap lines at word boundaries, but fall back to
* character boundaries if there is not enough space for a full word.
*
- * A `PangoWrapMode` describes how to wrap the lines of a `PangoLayout`
+ * `PangoWrapMode` describes how to wrap the lines of a `PangoLayout`
* to the desired width.
*/
typedef enum {
@@ -84,8 +84,8 @@ typedef enum {
* @PANGO_ELLIPSIZE_MIDDLE: Omit characters in the middle of the text
* @PANGO_ELLIPSIZE_END: Omit characters at the end of the text
*
- * The `PangoEllipsizeMode` type describes what sort of (if any)
- * ellipsization should be applied to a line of text.
+ * `PangoEllipsizeMode` describes what sort of ellipsization
+ * should be applied to text.
*
* In the ellipsization process characters are removed from the
* text in order to make it fit to a given width and replaced
@@ -108,11 +108,12 @@ typedef enum {
* @is_paragraph_start: #TRUE if this is the first line of the paragraph
* @resolved_dir: #Resolved PangoDirection of line
*
- * The `PangoLayoutLine` structure represents one of the lines resulting
- * from laying out a paragraph via [class@Pango.Layout]. `PangoLayoutLine`
- * structures are obtained by calling [method@Pango.Layout.get_line] and
- * are only valid until the text, attributes, or settings of the parent
- * `PangoLayout` are modified.
+ * A `PangoLayoutLine` represents one of the lines resulting from laying
+ * out a paragraph via `PangoLayout`.
+ *
+ * `PangoLayoutLine` structures are obtained by calling
+ * [method@Pango.Layout.get_line] and are only valid until the text,
+ * attributes, or settings of the parent `PangoLayout` are modified.
*/
struct _PangoLayoutLine
{