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. `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 (on the
left) and font metrics (on the right):
<picture> <source srcset="layout-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Pango Layout Parameters"
src="layout-light.png"> </picture>
The following images demonstrate the effect of alignment and justification on the layout of text:
| | | | --- | --- | |  |  | |  |  | |  |  |
It is possible, as well, to ignore the 2-D setup, and simply treat the results of a `PangoLayout` as a list of lines.
- public void context_changed ()
Forces recomputation of any state in the `PangoLayout` that might
depend on the layout's context.
- public Layout copy ()
Creates a deep copy-by-value of the layout.
- public Alignment get_alignment ()
Gets the alignment for the layout: how partial lines are positioned
within the horizontal space available.
- public unowned AttrList? get_attributes ()
Gets the attribute list for the layout, if any.
- public bool get_auto_dir ()
Gets whether to calculate the base direction for the layout according
to its contents.
- public int get_baseline ()
Gets the Y position of baseline of the first line in
this.
- public void get_caret_pos (int index_, out Rectangle strong_pos, out Rectangle weak_pos)
Given an index within a layout, determines the positions that of the
strong and weak cursors if the insertion point is at that index.
- public int get_character_count ()
Returns the number of Unicode characters in the the text of
this.
- public unowned Context get_context ()
Retrieves the `PangoContext` used for this layout.
- public void get_cursor_pos (int index_, out Rectangle strong_pos, out Rectangle weak_pos)
Given an index within a layout, determines the positions that of the
strong and weak cursors if the insertion point is at that index.
- public Direction get_direction (int index)
Gets the text direction at the given character position in
this.
- public EllipsizeMode get_ellipsize ()
Gets the type of ellipsization being performed for
this.
- public void get_extents (out Rectangle ink_rect, out Rectangle logical_rect)
Computes the logical and ink extents of
this.
- public unowned FontDescription? get_font_description ()
Gets the font description for the layout, if any.
- public int get_height ()
Gets the height of layout used for ellipsization.
- public int get_indent ()
Gets the paragraph indent width in Pango units.
- public LayoutIter get_iter ()
Returns an iterator to iterate over the visual extents of the layout.
- public bool get_justify ()
Gets whether each complete line should be stretched to fill the entire
width of the layout.
- public bool get_justify_last_line ()
Gets whether the last line should be stretched to fill the entire
width of the layout.
- public unowned LayoutLine? get_line (int line)
Retrieves a particular line from a `PangoLayout`.
- public int get_line_count ()
Retrieves the count of lines for the this
.
- public unowned LayoutLine? get_line_readonly (int line)
Retrieves a particular line from a `PangoLayout`.
- public float get_line_spacing ()
Gets the line spacing factor of this
.
- public unowned SList<LayoutLine> get_lines ()
Returns the lines of the this as a
list.
- public unowned SList<LayoutLine> get_lines_readonly ()
Returns the lines of the this as a
list.
- public void get_log_attrs (out LogAttr[] attrs)
Retrieves an array of logical attributes for each character in the
this.
- public unowned LogAttr[] get_log_attrs_readonly ()
Retrieves an array of logical attributes for each character in the
this.
- public void get_pixel_extents (out Rectangle ink_rect, out Rectangle logical_rect)
Computes the logical and ink extents of
this in device units.
- public void get_pixel_size (out int width, out int height)
Determines the logical width and height of a `PangoLayout` in device
units.
- public uint get_serial ()
Returns the current serial number of this
.
- public bool get_single_paragraph_mode ()
Obtains whether this is in single
paragraph mode.
- public void get_size (out int width, out int height)
Determines the logical width and height of a `PangoLayout` in Pango
units.
- public int get_spacing ()
Gets the amount of spacing between the lines of the layout.
- public TabArray? get_tabs ()
Gets the current `PangoTabArray` used by this layout.
- public unowned string get_text ()
Gets the text in the layout.
- public int get_unknown_glyphs_count ()
Counts the number of unknown glyphs in this
.
- public int get_width ()
Gets the width to which the lines of the `PangoLayout` should wrap.
- public WrapMode get_wrap ()
Gets the wrap mode for the layout.
- public void index_to_line_x (int index_, bool trailing, out int line, out int x_pos)
Converts from byte index_ within the
this to line and X position.
- public Rectangle index_to_pos (int index_)
Converts from an index within a `PangoLayout` to the onscreen position
corresponding to the grapheme at that index.
- public bool is_ellipsized ()
Queries whether the layout had to ellipsize any paragraphs.
- public bool is_wrapped ()
Queries whether the layout had to wrap any paragraphs.
- public void move_cursor_visually (bool strong, int old_index, int old_trailing, int direction, out int new_index, out int new_trailing)
Computes a new cursor position from an old position and a direction.
- public Bytes serialize (LayoutSerializeFlags flags)
Serializes the this for later
deserialization via [func@Pango.
- public void set_alignment (Alignment alignment)
Sets the alignment for the layout: how partial lines are positioned
within the horizontal space available.
- public void set_attributes (AttrList? attrs)
Sets the text attributes for a layout object.
- public void set_auto_dir (bool auto_dir)
Sets whether to calculate the base direction for the layout according
to its contents.
- public void set_ellipsize (EllipsizeMode ellipsize)
Sets the type of ellipsization being performed for
this.
- public void set_font_description (FontDescription? desc)
Sets the default font description for the layout.
- public void set_height (int height)
Sets the height to which the `PangoLayout` should be ellipsized at.
- public void set_indent (int indent)
Sets the width in Pango units to indent each paragraph.
- public void set_justify (bool justify)
Sets whether each complete line should be stretched to fill the entire
width of the layout.
- public void set_justify_last_line (bool justify)
Sets whether the last line should be stretched to fill the entire
width of the layout.
- public void set_line_spacing (float factor)
Sets a factor for line spacing.
- public void set_markup (string markup, int length)
Sets the layout text and attribute list from marked-up text.
- public void set_markup_with_accel (string markup, int length, unichar accel_marker, out unichar accel_char)
Sets the layout text and attribute list from marked-up text.
- public void set_single_paragraph_mode (bool setting)
Sets the single paragraph mode of this
.
- public void set_spacing (int spacing)
Sets the amount of spacing in Pango units between the lines of the
layout.
- public void set_tabs (TabArray? tabs)
Sets the tabs to use for this,
overriding the default tabs.
- public void set_text (string text, int length)
Sets the text of the layout.
- public void set_width (int width)
Sets the width to which the lines of the `PangoLayout` should wrap or
ellipsized.
- public void set_wrap (WrapMode wrap)
Sets the wrap mode.
- public bool write_to_file (LayoutSerializeFlags flags, string filename) throws Error
A convenience method to serialize a layout to a file.
- public bool xy_to_index (int x, int y, out int index_, out int trailing)
Converts from X and Y position within a layout to the byte index to
the character at that logical position.