layout.sgml

Pango is a library for layout and rendering of text, with an emphasis on internationalization. Pang

<!-- ##### SECTION Title ##### -->
Layout Objects

<!-- ##### SECTION Short_Description ##### -->
High-level layout driver objects

<!-- ##### SECTION Long_Description ##### -->
<para>
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.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### STRUCT PangoLayout ##### -->
<para>
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.
</para>

<para>
There are also a number of parameters to adjust the formatting
of a #PangoLayout, which are illustrated in <xref linkend="parameters"/>.
It is possible, as well, to ignore the 2-D setup, and simply
treat the results of a #PangoLayout as a list of lines.
</para>

<figure id="parameters">
<title>Adjustable parameters for a PangoLayout</title>
<graphic fileref="layout.gif" format="GIF"></graphic>
</figure>

<para>
The #PangoLayout structure is opaque, and has no user-visible
fields.
</para>


<!-- ##### STRUCT PangoLayoutIter ##### -->
<para>
A #PangoLayoutIter structure can be used to
iterate over the visual extents of a #PangoLayout. 
</para>
<para>
The #PangoLayoutIter structure is opaque, and 
has no user-visible fields.
</para>


<!-- ##### FUNCTION pango_layout_new ##### -->
<para>

</para>

@context: 
@Returns: 


<!-- ##### FUNCTION pango_layout_copy ##### -->
<para>

</para>

@src: 
@Returns: 


<!-- ##### FUNCTION pango_layout_get_context ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_context_changed ##### -->
<para>

</para>

@layout: 


<!-- ##### FUNCTION pango_layout_set_text ##### -->
<para>

</para>

@layout: 
@text: 
@length: 


<!-- ##### FUNCTION pango_layout_get_text ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_set_markup ##### -->
<para>

</para>

@layout: 
@markup: 
@length: 


<!-- ##### FUNCTION pango_layout_set_markup_with_accel ##### -->
<para>

</para>

@layout: 
@markup: 
@length: 
@accel_marker: 
@accel_char: 


<!-- ##### FUNCTION pango_layout_set_attributes ##### -->
<para>

</para>

@layout: 
@attrs: 


<!-- ##### FUNCTION pango_layout_get_attributes ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_set_font_description ##### -->
<para>

</para>

@layout: 
@desc: 


<!-- ##### FUNCTION pango_layout_get_font_description ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_set_width ##### -->
<para>

</para>

@layout: 
@width: 


<!-- ##### FUNCTION pango_layout_get_width ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_set_height ##### -->
<para>

</para>

@layout: 
@height: 


<!-- ##### FUNCTION pango_layout_get_height ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_set_wrap ##### -->
<para>

</para>

@layout: 
@wrap: 


<!-- ##### FUNCTION pango_layout_get_wrap ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_is_wrapped ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### ENUM PangoWrapMode ##### -->
<para>
A #PangoWrapMode describes how to wrap the lines of a #PangoLayout to the desired width.
</para>

@PANGO_WRAP_WORD: wrap lines at word boundaries.
@PANGO_WRAP_CHAR: wrap lines at character boundaries.
@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.

<!-- ##### MACRO PANGO_TYPE_WRAP_MODE ##### -->
<para>
The #GObject type for #PangoWrapMode.
</para>



<!-- ##### FUNCTION pango_layout_set_ellipsize ##### -->
<para>

</para>

@layout: 
@ellipsize: 


<!-- ##### FUNCTION pango_layout_get_ellipsize ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_is_ellipsized ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### ENUM PangoEllipsizeMode ##### -->
<para>

</para>

@PANGO_ELLIPSIZE_NONE: 
@PANGO_ELLIPSIZE_START: 
@PANGO_ELLIPSIZE_MIDDLE: 
@PANGO_ELLIPSIZE_END: 

<!-- ##### MACRO PANGO_TYPE_ELLIPSIZE_MODE ##### -->
<para>
The #GObject type for #PangoEllipsizeMode.
</para>



<!-- ##### FUNCTION pango_layout_set_indent ##### -->
<para>

</para>

@layout: 
@indent: 


<!-- ##### FUNCTION pango_layout_get_indent ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_get_spacing ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_set_spacing ##### -->
<para>

</para>

@layout: 
@spacing: 


<!-- ##### FUNCTION pango_layout_set_justify ##### -->
<para>

</para>

@layout: 
@justify: 


<!-- ##### FUNCTION pango_layout_get_justify ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_set_auto_dir ##### -->
<para>

</para>

@layout: 
@auto_dir: 


<!-- ##### FUNCTION pango_layout_get_auto_dir ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_set_alignment ##### -->
<para>

</para>

@layout: 
@alignment: 


<!-- ##### FUNCTION pango_layout_get_alignment ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_set_tabs ##### -->
<para>

</para>

@layout: 
@tabs: 


<!-- ##### FUNCTION pango_layout_get_tabs ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_set_single_paragraph_mode ##### -->
<para>

</para>

@layout: 
@setting: 


<!-- ##### FUNCTION pango_layout_get_single_paragraph_mode ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### ENUM PangoAlignment ##### -->
<para>
A #PangoAlignment describes how to align the lines of a #PangoLayout within the
available space. If the #PangoLayout is set to justify
using pango_layout_set_justify(), this only has effect for partial lines.
</para>

@PANGO_ALIGN_LEFT: Put all available space on the right
@PANGO_ALIGN_CENTER: Center the line within the available space
@PANGO_ALIGN_RIGHT: Put all available space on the left

<!-- ##### MACRO PANGO_TYPE_ALIGNMENT ##### -->
<para>
The #GObject type for #PangoAlignment.
</para>



<!-- ##### FUNCTION pango_layout_get_unknown_glyphs_count ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_get_log_attrs ##### -->
<para>

</para>

@layout: 
@attrs: 
@n_attrs: 


<!-- ##### FUNCTION pango_layout_index_to_pos ##### -->
<para>

</para>

@layout: 
@index_: 
@pos: 


<!-- ##### FUNCTION pango_layout_index_to_line_x ##### -->
<para>

</para>

@layout: 
@index_: 
@trailing: 
@line: 
@x_pos: 


<!-- ##### FUNCTION pango_layout_xy_to_index ##### -->
<para>

</para>

@layout: 
@x: 
@y: 
@index_: 
@trailing: 
@Returns: 


<!-- ##### FUNCTION pango_layout_get_cursor_pos ##### -->
<para>

</para>

@layout: 
@index_: 
@strong_pos: 
@weak_pos: 


<!-- ##### FUNCTION pango_layout_move_cursor_visually ##### -->
<para>

</para>

@layout: 
@strong: 
@old_index: 
@old_trailing: 
@direction: 
@new_index: 
@new_trailing: 


<!-- ##### FUNCTION pango_layout_get_extents ##### -->
<para>

</para>

@layout: 
@ink_rect: 
@logical_rect: 


<!-- ##### FUNCTION pango_layout_get_pixel_extents ##### -->
<para>

</para>

@layout: 
@ink_rect: 
@logical_rect: 


<!-- ##### FUNCTION pango_layout_get_size ##### -->
<para>

</para>

@layout: 
@width: 
@height: 


<!-- ##### FUNCTION pango_layout_get_pixel_size ##### -->
<para>

</para>

@layout: 
@width: 
@height: 


<!-- ##### FUNCTION pango_layout_get_line_count ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_get_line ##### -->
<para>

</para>

@layout: 
@line: 
@Returns: 


<!-- ##### FUNCTION pango_layout_get_line_readonly ##### -->
<para>

</para>

@layout: 
@line: 
@Returns: 


<!-- ##### FUNCTION pango_layout_get_lines ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_get_lines_readonly ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_get_iter ##### -->
<para>

</para>

@layout: 
@Returns: 


<!-- ##### FUNCTION pango_layout_iter_copy ##### -->
<para>

</para>

@iter: 
@Returns: 


<!-- ##### FUNCTION pango_layout_iter_free ##### -->
<para>

</para>

@iter: 


<!-- ##### FUNCTION pango_layout_iter_next_run ##### -->
<para>

</para>

@iter: 
@Returns: 


<!-- ##### FUNCTION pango_layout_iter_next_char ##### -->
<para>

</para>

@iter: 
@Returns: 


<!-- ##### FUNCTION pango_layout_iter_next_cluster ##### -->
<para>

</para>

@iter: 
@Returns: 


<!-- ##### FUNCTION pango_layout_iter_next_line ##### -->
<para>

</para>

@iter: 
@Returns: 


<!-- ##### FUNCTION pango_layout_iter_at_last_line ##### -->
<para>

</para>

@iter: 
@Returns: 


<!-- ##### FUNCTION pango_layout_iter_get_index ##### -->
<para>

</para>

@iter: 
@Returns: 


<!-- ##### FUNCTION pango_layout_iter_get_baseline ##### -->
<para>

</para>

@iter: 
@Returns: 


<!-- ##### FUNCTION pango_layout_iter_get_run ##### -->
<para>

</para>

@iter: 
@Returns: 


<!-- ##### FUNCTION pango_layout_iter_get_run_readonly ##### -->
<para>

</para>

@iter: 
@Returns: 


<!-- ##### FUNCTION pango_layout_iter_get_line ##### -->
<para>

</para>

@iter: 
@Returns: 


<!-- ##### FUNCTION pango_layout_iter_get_line_readonly ##### -->
<para>

</para>

@iter: 
@Returns: 


<!-- ##### FUNCTION pango_layout_iter_get_layout ##### -->
<para>

</para>

@iter: 
@Returns: 


<!-- ##### FUNCTION pango_layout_iter_get_char_extents ##### -->
<para>

</para>

@iter: 
@logical_rect: 


<!-- ##### FUNCTION pango_layout_iter_get_cluster_extents ##### -->
<para>

</para>

@iter: 
@ink_rect: 
@logical_rect: 


<!-- ##### FUNCTION pango_layout_iter_get_run_extents ##### -->
<para>

</para>

@iter: 
@ink_rect: 
@logical_rect: 


<!-- ##### FUNCTION pango_layout_iter_get_line_yrange ##### -->
<para>

</para>

@iter: 
@y0_: 
@y1_: 


<!-- ##### FUNCTION pango_layout_iter_get_line_extents ##### -->
<para>

</para>

@iter: 
@ink_rect: 
@logical_rect: 


<!-- ##### FUNCTION pango_layout_iter_get_layout_extents ##### -->
<para>

</para>

@iter: 
@ink_rect: 
@logical_rect: 


<!-- ##### STRUCT PangoLayoutLine ##### -->
<para>
The #PangoLayoutLine structure represents one of the lines resulting
from laying out a paragraph via #PangoLayout. #PangoLayoutLine
structures are obtained by calling pango_layout_get_line() and
are only valid until the text, attributes, or settings of the
parent #PangoLayout are modified.
</para>
<para>
Routines for rendering PangoLayout objects are provided in
code specific to each rendering system.
</para>

@layout: the parent layout for this line
@start_index: the start of the line as byte index into @layout->text
@length: the length of the line in bytes
@runs: a list containing the runs of the line in visual order
@is_paragraph_start: %TRUE if this is the first line of the paragraph
@resolved_dir: the resolved #PangoDirection of the line

<!-- ##### TYPEDEF PangoLayoutRun ##### -->
<para>
The #PangoLayoutRun structure represents a single run within
a #PangoLayoutLine; it is simply an alternate name for
#PangoGlyphItem.
See the #PangoGlyphItem docs for details on the fields.
</para>


<!-- ##### FUNCTION pango_layout_line_ref ##### -->
<para>

</para>

@line: 
@Returns: 


<!-- ##### FUNCTION pango_layout_line_unref ##### -->
<para>

</para>

@line: 


<!-- ##### FUNCTION pango_layout_line_get_extents ##### -->
<para>

</para>

@line: 
@ink_rect: 
@logical_rect: 


<!-- ##### FUNCTION pango_layout_line_get_pixel_extents ##### -->
<para>

</para>

@layout_line: 
@ink_rect: 
@logical_rect: 


<!-- ##### FUNCTION pango_layout_line_index_to_x ##### -->
<para>

</para>

@line: 
@index_: 
@trailing: 
@x_pos: 


<!-- ##### FUNCTION pango_layout_line_x_to_index ##### -->
<para>

</para>

@line: 
@x_pos: 
@index_: 
@trailing: 
@Returns: 


<!-- ##### FUNCTION pango_layout_line_get_x_ranges ##### -->
<para>

</para>

@line: 
@start_index: 
@end_index: 
@ranges: 
@n_ranges: