1 <refentry id="pango-Layout-Objects">
3 <refentrytitle role="top_of_page" id="pango-Layout-Objects.top_of_page">Layout Objects</refentrytitle>
4 <manvolnum>3</manvolnum>
5 <refmiscinfo>PANGO Library</refmiscinfo>
9 <refname>Layout Objects</refname>
10 <refpurpose>High-level layout driver objects</refpurpose>
13 <refsynopsisdiv id="pango-Layout-Objects.synopsis" role="synopsis">
14 <title role="synopsis.title">Synopsis</title>
15 <anchor id="PangoLayout"/>
17 <link linkend="PangoLayout-struct">PangoLayout</link>;
18 <link linkend="PangoLayoutIter">PangoLayoutIter</link>;
19 <link linkend="PangoLayout">PangoLayout</link> * <link linkend="pango-layout-new">pango_layout_new</link> (<link linkend="PangoContext">PangoContext</link> *context);
20 <link linkend="PangoLayout">PangoLayout</link> * <link linkend="pango-layout-copy">pango_layout_copy</link> (<link linkend="PangoLayout">PangoLayout</link> *src);
21 <link linkend="PangoContext">PangoContext</link> * <link linkend="pango-layout-get-context">pango_layout_get_context</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
22 <link linkend="void">void</link> <link linkend="pango-layout-context-changed">pango_layout_context_changed</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
23 <link linkend="void">void</link> <link linkend="pango-layout-set-text">pango_layout_set_text</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
24 const <link linkend="char">char</link> *text,
25 <link linkend="int">int</link> length);
26 const <link linkend="char">char</link> * <link linkend="pango-layout-get-text">pango_layout_get_text</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
27 <link linkend="void">void</link> <link linkend="pango-layout-set-markup">pango_layout_set_markup</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
28 const <link linkend="char">char</link> *markup,
29 <link linkend="int">int</link> length);
30 <link linkend="void">void</link> <link linkend="pango-layout-set-markup-with-accel">pango_layout_set_markup_with_accel</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
31 const <link linkend="char">char</link> *markup,
32 <link linkend="int">int</link> length,
33 <link linkend="gunichar">gunichar</link> accel_marker,
34 <link linkend="gunichar">gunichar</link> *accel_char);
35 <link linkend="void">void</link> <link linkend="pango-layout-set-attributes">pango_layout_set_attributes</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
36 <link linkend="PangoAttrList">PangoAttrList</link> *attrs);
37 <link linkend="PangoAttrList">PangoAttrList</link> * <link linkend="pango-layout-get-attributes">pango_layout_get_attributes</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
38 <link linkend="void">void</link> <link linkend="pango-layout-set-font-description">pango_layout_set_font_description</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
39 const <link linkend="PangoFontDescription">PangoFontDescription</link> *desc);
40 const <link linkend="PangoFontDescription">PangoFontDescription</link> * <link linkend="pango-layout-get-font-description">pango_layout_get_font_description</link>
41 (<link linkend="PangoLayout">PangoLayout</link> *layout);
42 <link linkend="void">void</link> <link linkend="pango-layout-set-width">pango_layout_set_width</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
43 <link linkend="int">int</link> width);
44 <link linkend="int">int</link> <link linkend="pango-layout-get-width">pango_layout_get_width</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
45 <link linkend="void">void</link> <link linkend="pango-layout-set-height">pango_layout_set_height</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
46 <link linkend="int">int</link> height);
47 <link linkend="int">int</link> <link linkend="pango-layout-get-height">pango_layout_get_height</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
48 <link linkend="void">void</link> <link linkend="pango-layout-set-wrap">pango_layout_set_wrap</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
49 <link linkend="PangoWrapMode">PangoWrapMode</link> wrap);
50 <link linkend="PangoWrapMode">PangoWrapMode</link> <link linkend="pango-layout-get-wrap">pango_layout_get_wrap</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
51 <link linkend="gboolean">gboolean</link> <link linkend="pango-layout-is-wrapped">pango_layout_is_wrapped</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
52 enum <link linkend="PangoWrapMode">PangoWrapMode</link>;
53 #define <link linkend="PANGO-TYPE-WRAP-MODE--CAPS">PANGO_TYPE_WRAP_MODE</link>
54 <link linkend="void">void</link> <link linkend="pango-layout-set-ellipsize">pango_layout_set_ellipsize</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
55 <link linkend="PangoEllipsizeMode">PangoEllipsizeMode</link> ellipsize);
56 <link linkend="PangoEllipsizeMode">PangoEllipsizeMode</link> <link linkend="pango-layout-get-ellipsize">pango_layout_get_ellipsize</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
57 <link linkend="gboolean">gboolean</link> <link linkend="pango-layout-is-ellipsized">pango_layout_is_ellipsized</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
58 enum <link linkend="PangoEllipsizeMode">PangoEllipsizeMode</link>;
59 #define <link linkend="PANGO-TYPE-ELLIPSIZE-MODE--CAPS">PANGO_TYPE_ELLIPSIZE_MODE</link>
60 <link linkend="void">void</link> <link linkend="pango-layout-set-indent">pango_layout_set_indent</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
61 <link linkend="int">int</link> indent);
62 <link linkend="int">int</link> <link linkend="pango-layout-get-indent">pango_layout_get_indent</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
63 <link linkend="int">int</link> <link linkend="pango-layout-get-spacing">pango_layout_get_spacing</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
64 <link linkend="void">void</link> <link linkend="pango-layout-set-spacing">pango_layout_set_spacing</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
65 <link linkend="int">int</link> spacing);
66 <link linkend="void">void</link> <link linkend="pango-layout-set-justify">pango_layout_set_justify</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
67 <link linkend="gboolean">gboolean</link> justify);
68 <link linkend="gboolean">gboolean</link> <link linkend="pango-layout-get-justify">pango_layout_get_justify</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
69 <link linkend="void">void</link> <link linkend="pango-layout-set-auto-dir">pango_layout_set_auto_dir</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
70 <link linkend="gboolean">gboolean</link> auto_dir);
71 <link linkend="gboolean">gboolean</link> <link linkend="pango-layout-get-auto-dir">pango_layout_get_auto_dir</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
72 <link linkend="void">void</link> <link linkend="pango-layout-set-alignment">pango_layout_set_alignment</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
73 <link linkend="PangoAlignment">PangoAlignment</link> alignment);
74 <link linkend="PangoAlignment">PangoAlignment</link> <link linkend="pango-layout-get-alignment">pango_layout_get_alignment</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
75 <link linkend="void">void</link> <link linkend="pango-layout-set-tabs">pango_layout_set_tabs</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
76 <link linkend="PangoTabArray">PangoTabArray</link> *tabs);
77 <link linkend="PangoTabArray">PangoTabArray</link>* <link linkend="pango-layout-get-tabs">pango_layout_get_tabs</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
78 <link linkend="void">void</link> <link linkend="pango-layout-set-single-paragraph-mode">pango_layout_set_single_paragraph_mode</link>
79 (<link linkend="PangoLayout">PangoLayout</link> *layout,
80 <link linkend="gboolean">gboolean</link> setting);
81 <link linkend="gboolean">gboolean</link> <link linkend="pango-layout-get-single-paragraph-mode">pango_layout_get_single_paragraph_mode</link>
82 (<link linkend="PangoLayout">PangoLayout</link> *layout);
83 enum <link linkend="PangoAlignment">PangoAlignment</link>;
84 #define <link linkend="PANGO-TYPE-ALIGNMENT--CAPS">PANGO_TYPE_ALIGNMENT</link>
85 <link linkend="int">int</link> <link linkend="pango-layout-get-unknown-glyphs-count">pango_layout_get_unknown_glyphs_count</link>
86 (<link linkend="PangoLayout">PangoLayout</link> *layout);
87 <link linkend="void">void</link> <link linkend="pango-layout-get-log-attrs">pango_layout_get_log_attrs</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
88 <link linkend="PangoLogAttr">PangoLogAttr</link> **attrs,
89 <link linkend="gint">gint</link> *n_attrs);
90 <link linkend="void">void</link> <link linkend="pango-layout-index-to-pos">pango_layout_index_to_pos</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
91 <link linkend="int">int</link> index_,
92 <link linkend="PangoRectangle">PangoRectangle</link> *pos);
93 <link linkend="void">void</link> <link linkend="pango-layout-index-to-line-x">pango_layout_index_to_line_x</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
94 <link linkend="int">int</link> index_,
95 <link linkend="gboolean">gboolean</link> trailing,
96 <link linkend="int">int</link> *line,
97 <link linkend="int">int</link> *x_pos);
98 <link linkend="gboolean">gboolean</link> <link linkend="pango-layout-xy-to-index">pango_layout_xy_to_index</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
99 <link linkend="int">int</link> x,
100 <link linkend="int">int</link> y,
101 <link linkend="int">int</link> *index_,
102 <link linkend="int">int</link> *trailing);
103 <link linkend="void">void</link> <link linkend="pango-layout-get-cursor-pos">pango_layout_get_cursor_pos</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
104 <link linkend="int">int</link> index_,
105 <link linkend="PangoRectangle">PangoRectangle</link> *strong_pos,
106 <link linkend="PangoRectangle">PangoRectangle</link> *weak_pos);
107 <link linkend="void">void</link> <link linkend="pango-layout-move-cursor-visually">pango_layout_move_cursor_visually</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
108 <link linkend="gboolean">gboolean</link> strong,
109 <link linkend="int">int</link> old_index,
110 <link linkend="int">int</link> old_trailing,
111 <link linkend="int">int</link> direction,
112 <link linkend="int">int</link> *new_index,
113 <link linkend="int">int</link> *new_trailing);
114 <link linkend="void">void</link> <link linkend="pango-layout-get-extents">pango_layout_get_extents</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
115 <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
116 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);
117 <link linkend="void">void</link> <link linkend="pango-layout-get-pixel-extents">pango_layout_get_pixel_extents</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
118 <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
119 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);
120 <link linkend="void">void</link> <link linkend="pango-layout-get-size">pango_layout_get_size</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
121 <link linkend="int">int</link> *width,
122 <link linkend="int">int</link> *height);
123 <link linkend="void">void</link> <link linkend="pango-layout-get-pixel-size">pango_layout_get_pixel_size</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
124 <link linkend="int">int</link> *width,
125 <link linkend="int">int</link> *height);
126 <link linkend="int">int</link> <link linkend="pango-layout-get-baseline">pango_layout_get_baseline</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
127 <link linkend="int">int</link> <link linkend="pango-layout-get-line-count">pango_layout_get_line_count</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
128 <link linkend="PangoLayoutLine">PangoLayoutLine</link> * <link linkend="pango-layout-get-line">pango_layout_get_line</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
129 <link linkend="int">int</link> line);
130 <link linkend="PangoLayoutLine">PangoLayoutLine</link> * <link linkend="pango-layout-get-line-readonly">pango_layout_get_line_readonly</link> (<link linkend="PangoLayout">PangoLayout</link> *layout,
131 <link linkend="int">int</link> line);
132 <link linkend="GSList">GSList</link> * <link linkend="pango-layout-get-lines">pango_layout_get_lines</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
133 <link linkend="GSList">GSList</link> * <link linkend="pango-layout-get-lines-readonly">pango_layout_get_lines_readonly</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
134 <link linkend="PangoLayoutIter">PangoLayoutIter</link> * <link linkend="pango-layout-get-iter">pango_layout_get_iter</link> (<link linkend="PangoLayout">PangoLayout</link> *layout);
135 <link linkend="PangoLayoutIter">PangoLayoutIter</link> * <link linkend="pango-layout-iter-copy">pango_layout_iter_copy</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);
136 <link linkend="void">void</link> <link linkend="pango-layout-iter-free">pango_layout_iter_free</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);
137 <link linkend="gboolean">gboolean</link> <link linkend="pango-layout-iter-next-run">pango_layout_iter_next_run</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);
138 <link linkend="gboolean">gboolean</link> <link linkend="pango-layout-iter-next-char">pango_layout_iter_next_char</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);
139 <link linkend="gboolean">gboolean</link> <link linkend="pango-layout-iter-next-cluster">pango_layout_iter_next_cluster</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);
140 <link linkend="gboolean">gboolean</link> <link linkend="pango-layout-iter-next-line">pango_layout_iter_next_line</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);
141 <link linkend="gboolean">gboolean</link> <link linkend="pango-layout-iter-at-last-line">pango_layout_iter_at_last_line</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);
142 <link linkend="int">int</link> <link linkend="pango-layout-iter-get-index">pango_layout_iter_get_index</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);
143 <link linkend="int">int</link> <link linkend="pango-layout-iter-get-baseline">pango_layout_iter_get_baseline</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);
144 <link linkend="PangoLayoutRun">PangoLayoutRun</link> * <link linkend="pango-layout-iter-get-run">pango_layout_iter_get_run</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);
145 <link linkend="PangoLayoutRun">PangoLayoutRun</link> * <link linkend="pango-layout-iter-get-run-readonly">pango_layout_iter_get_run_readonly</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);
146 <link linkend="PangoLayoutLine">PangoLayoutLine</link> * <link linkend="pango-layout-iter-get-line">pango_layout_iter_get_line</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);
147 <link linkend="PangoLayoutLine">PangoLayoutLine</link> * <link linkend="pango-layout-iter-get-line-readonly">pango_layout_iter_get_line_readonly</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);
148 <link linkend="PangoLayout">PangoLayout</link> * <link linkend="pango-layout-iter-get-layout">pango_layout_iter_get_layout</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);
149 <link linkend="void">void</link> <link linkend="pango-layout-iter-get-char-extents">pango_layout_iter_get_char_extents</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter,
150 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);
151 <link linkend="void">void</link> <link linkend="pango-layout-iter-get-cluster-extents">pango_layout_iter_get_cluster_extents</link>
152 (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter,
153 <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
154 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);
155 <link linkend="void">void</link> <link linkend="pango-layout-iter-get-run-extents">pango_layout_iter_get_run_extents</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter,
156 <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
157 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);
158 <link linkend="void">void</link> <link linkend="pango-layout-iter-get-line-yrange">pango_layout_iter_get_line_yrange</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter,
159 <link linkend="int">int</link> *y0_,
160 <link linkend="int">int</link> *y1_);
161 <link linkend="void">void</link> <link linkend="pango-layout-iter-get-line-extents">pango_layout_iter_get_line_extents</link> (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter,
162 <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
163 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);
164 <link linkend="void">void</link> <link linkend="pango-layout-iter-get-layout-extents">pango_layout_iter_get_layout_extents</link>
165 (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter,
166 <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
167 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);
169 <link linkend="PangoLayoutLine">PangoLayoutLine</link>;
170 typedef <link linkend="PangoLayoutRun">PangoLayoutRun</link>;
171 <link linkend="PangoLayoutLine">PangoLayoutLine</link> * <link linkend="pango-layout-line-ref">pango_layout_line_ref</link> (<link linkend="PangoLayoutLine">PangoLayoutLine</link> *line);
172 <link linkend="void">void</link> <link linkend="pango-layout-line-unref">pango_layout_line_unref</link> (<link linkend="PangoLayoutLine">PangoLayoutLine</link> *line);
173 <link linkend="void">void</link> <link linkend="pango-layout-line-get-extents">pango_layout_line_get_extents</link> (<link linkend="PangoLayoutLine">PangoLayoutLine</link> *line,
174 <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
175 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);
176 <link linkend="void">void</link> <link linkend="pango-layout-line-get-pixel-extents">pango_layout_line_get_pixel_extents</link> (<link linkend="PangoLayoutLine">PangoLayoutLine</link> *layout_line,
177 <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
178 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);
179 <link linkend="void">void</link> <link linkend="pango-layout-line-index-to-x">pango_layout_line_index_to_x</link> (<link linkend="PangoLayoutLine">PangoLayoutLine</link> *line,
180 <link linkend="int">int</link> index_,
181 <link linkend="gboolean">gboolean</link> trailing,
182 <link linkend="int">int</link> *x_pos);
183 <link linkend="gboolean">gboolean</link> <link linkend="pango-layout-line-x-to-index">pango_layout_line_x_to_index</link> (<link linkend="PangoLayoutLine">PangoLayoutLine</link> *line,
184 <link linkend="int">int</link> x_pos,
185 <link linkend="int">int</link> *index_,
186 <link linkend="int">int</link> *trailing);
187 <link linkend="void">void</link> <link linkend="pango-layout-line-get-x-ranges">pango_layout_line_get_x_ranges</link> (<link linkend="PangoLayoutLine">PangoLayoutLine</link> *line,
188 <link linkend="int">int</link> start_index,
189 <link linkend="int">int</link> end_index,
190 <link linkend="int">int</link> **ranges,
191 <link linkend="int">int</link> *n_ranges);
195 <refsect1 id="pango-Layout-Objects.object-hierarchy" role="object_hierarchy">
196 <title role="object_hierarchy.title">Object Hierarchy</title>
198 <link linkend="GObject">GObject</link>
210 <refsect1 id="pango-Layout-Objects.description" role="desc">
211 <title role="desc.title">Description</title>
213 While complete access to the layout capabilities of Pango is provided
214 using the detailed interfaces for itemization and shaping, using
215 that functionality directly involves writing a fairly large amount
216 of code. The objects and functions in this section provide a
217 high-level driver for formatting entire paragraphs of text
222 <refsect1 id="pango-Layout-Objects.details" role="details">
223 <title role="details.title">Details</title>
224 <refsect2 id="PangoLayout-struct" role="struct">
225 <title>PangoLayout</title>
226 <indexterm zone="PangoLayout-struct"><primary sortas="PangoLayout">PangoLayout</primary></indexterm><programlisting>typedef struct _PangoLayout PangoLayout;</programlisting>
228 The <link linkend="PangoLayout"><type>PangoLayout</type></link> structure represents an entire paragraph
229 of text. It is initialized with a <link linkend="PangoContext"><type>PangoContext</type></link>, UTF-8 string
230 and set of attributes for that string. Once that is done, the
231 set of formatted lines can be extracted from the object,
232 the layout can be rendered, and conversion between logical
233 character positions within the layout's text, and the physical
234 position of the resulting glyphs can be made.
237 There are also a number of parameters to adjust the formatting
238 of a <link linkend="PangoLayout"><type>PangoLayout</type></link>, which are illustrated in <xref linkend="parameters"/>.
239 It is possible, as well, to ignore the 2-D setup, and simply
240 treat the results of a <link linkend="PangoLayout"><type>PangoLayout</type></link> as a list of lines.
242 <figure id="parameters">
243 <title>Adjustable parameters for a PangoLayout</title>
244 <graphic fileref="layout.gif" format="GIF"></graphic>
247 The <link linkend="PangoLayout"><type>PangoLayout</type></link> structure is opaque, and has no user-visible
250 <refsect2 id="PangoLayoutIter" role="struct">
251 <title>PangoLayoutIter</title>
252 <indexterm zone="PangoLayoutIter"><primary sortas="PangoLayoutIter">PangoLayoutIter</primary></indexterm><programlisting>typedef struct _PangoLayoutIter PangoLayoutIter;</programlisting>
254 A <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link> structure can be used to
255 iterate over the visual extents of a <link linkend="PangoLayout"><type>PangoLayout</type></link>.
258 The <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link> structure is opaque, and
259 has no user-visible fields.
261 <refsect2 id="pango-layout-new" role="function">
262 <title>pango_layout_new ()</title>
263 <indexterm zone="pango-layout-new"><primary sortas="pango_layout_new">pango_layout_new</primary></indexterm><programlisting><link linkend="PangoLayout">PangoLayout</link> * pango_layout_new (<link linkend="PangoContext">PangoContext</link> *context);</programlisting>
265 Create a new <link linkend="PangoLayout"><type>PangoLayout</type></link> object with attributes initialized to
266 default values for a particular <link linkend="PangoContext"><type>PangoContext</type></link>.</para>
268 </para><variablelist role="params">
269 <varlistentry><term><parameter>context</parameter> :</term>
270 <listitem><simpara> a <link linkend="PangoContext"><type>PangoContext</type></link>
271 </simpara></listitem></varlistentry>
272 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the newly allocated <link linkend="PangoLayout"><type>PangoLayout</type></link>, with a reference
273 count of one, which should be freed with
274 <link linkend="g-object-unref"><function>g_object_unref()</function></link>.
275 </simpara></listitem></varlistentry>
276 </variablelist></refsect2>
277 <refsect2 id="pango-layout-copy" role="function">
278 <title>pango_layout_copy ()</title>
279 <indexterm zone="pango-layout-copy"><primary sortas="pango_layout_copy">pango_layout_copy</primary></indexterm><programlisting><link linkend="PangoLayout">PangoLayout</link> * pango_layout_copy (<link linkend="PangoLayout">PangoLayout</link> *src);</programlisting>
281 Does a deep copy-by-value of the <parameter>src</parameter> layout. The attribute list,
282 tab array, and text from the original layout are all copied by
285 </para><variablelist role="params">
286 <varlistentry><term><parameter>src</parameter> :</term>
287 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
288 </simpara></listitem></varlistentry>
289 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the newly allocated <link linkend="PangoLayout"><type>PangoLayout</type></link>, with a reference
290 count of one, which should be freed with
291 <link linkend="g-object-unref"><function>g_object_unref()</function></link>.
292 </simpara></listitem></varlistentry>
293 </variablelist></refsect2>
294 <refsect2 id="pango-layout-get-context" role="function">
295 <title>pango_layout_get_context ()</title>
296 <indexterm zone="pango-layout-get-context"><primary sortas="pango_layout_get_context">pango_layout_get_context</primary></indexterm><programlisting><link linkend="PangoContext">PangoContext</link> * pango_layout_get_context (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
298 Retrieves the <link linkend="PangoContext"><type>PangoContext</type></link> used for this layout.</para>
300 </para><variablelist role="params">
301 <varlistentry><term><parameter>layout</parameter> :</term>
302 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
303 </simpara></listitem></varlistentry>
304 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <link linkend="PangoContext"><type>PangoContext</type></link> for the layout. This does not
305 have an additional refcount added, so if you want to keep
306 a copy of this around, you must reference it yourself.
307 </simpara></listitem></varlistentry>
308 </variablelist></refsect2>
309 <refsect2 id="pango-layout-context-changed" role="function">
310 <title>pango_layout_context_changed ()</title>
311 <indexterm zone="pango-layout-context-changed"><primary sortas="pango_layout_context_changed">pango_layout_context_changed</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_context_changed (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
313 Forces recomputation of any state in the <link linkend="PangoLayout"><type>PangoLayout</type></link> that
314 might depend on the layout's context. This function should
315 be called if you make changes to the context subsequent
316 to creating the layout.</para>
318 </para><variablelist role="params">
319 <varlistentry><term><parameter>layout</parameter> :</term>
320 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
321 </simpara></listitem></varlistentry>
322 </variablelist></refsect2>
323 <refsect2 id="pango-layout-set-text" role="function">
324 <title>pango_layout_set_text ()</title>
325 <indexterm zone="pango-layout-set-text"><primary sortas="pango_layout_set_text">pango_layout_set_text</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_set_text (<link linkend="PangoLayout">PangoLayout</link> *layout,
326 const <link linkend="char">char</link> *text,
327 <link linkend="int">int</link> length);</programlisting>
329 Sets the text of the layout.
332 Note that if you have used
333 <link linkend="pango-layout-set-markup"><function>pango_layout_set_markup()</function></link> or <link linkend="pango-layout-set-markup-with-accel"><function>pango_layout_set_markup_with_accel()</function></link> on
334 <parameter>layout</parameter> before, you may want to call <link linkend="pango-layout-set-attributes"><function>pango_layout_set_attributes()</function></link> to clear
335 the attributes set on the layout from the markup as this function does not
336 clear attributes.</para>
338 </para><variablelist role="params">
339 <varlistentry><term><parameter>layout</parameter> :</term>
340 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
341 </simpara></listitem></varlistentry>
342 <varlistentry><term><parameter>text</parameter> :</term>
343 <listitem><simpara> a valid UTF-8 string
344 </simpara></listitem></varlistentry>
345 <varlistentry><term><parameter>length</parameter> :</term>
346 <listitem><simpara> maximum length of <parameter>text</parameter>, in bytes. -1 indicates that
347 the string is nul-terminated and the length should be
348 calculated. The text will also be truncated on
349 encountering a nul-termination even when <parameter>length</parameter> is
351 </simpara></listitem></varlistentry>
352 </variablelist></refsect2>
353 <refsect2 id="pango-layout-get-text" role="function">
354 <title>pango_layout_get_text ()</title>
355 <indexterm zone="pango-layout-get-text"><primary sortas="pango_layout_get_text">pango_layout_get_text</primary></indexterm><programlisting>const <link linkend="char">char</link> * pango_layout_get_text (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
357 Gets the text in the layout. The returned text should not
358 be freed or modified.</para>
360 </para><variablelist role="params">
361 <varlistentry><term><parameter>layout</parameter> :</term>
362 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
363 </simpara></listitem></varlistentry>
364 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the text in the <parameter>layout</parameter>.
365 </simpara></listitem></varlistentry>
366 </variablelist></refsect2>
367 <refsect2 id="pango-layout-set-markup" role="function">
368 <title>pango_layout_set_markup ()</title>
369 <indexterm zone="pango-layout-set-markup"><primary sortas="pango_layout_set_markup">pango_layout_set_markup</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_set_markup (<link linkend="PangoLayout">PangoLayout</link> *layout,
370 const <link linkend="char">char</link> *markup,
371 <link linkend="int">int</link> length);</programlisting>
373 Same as <link linkend="pango-layout-set-markup-with-accel"><function>pango_layout_set_markup_with_accel()</function></link>, but
374 the markup text isn't scanned for accelerators.</para>
376 </para><variablelist role="params">
377 <varlistentry><term><parameter>layout</parameter> :</term>
378 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
379 </simpara></listitem></varlistentry>
380 <varlistentry><term><parameter>markup</parameter> :</term>
381 <listitem><simpara> marked-up text
382 </simpara></listitem></varlistentry>
383 <varlistentry><term><parameter>length</parameter> :</term>
384 <listitem><simpara> length of marked-up text in bytes, or -1 if <parameter>markup</parameter> is
386 </simpara></listitem></varlistentry>
387 </variablelist></refsect2>
388 <refsect2 id="pango-layout-set-markup-with-accel" role="function">
389 <title>pango_layout_set_markup_with_accel ()</title>
390 <indexterm zone="pango-layout-set-markup-with-accel"><primary sortas="pango_layout_set_markup_with_accel">pango_layout_set_markup_with_accel</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_set_markup_with_accel (<link linkend="PangoLayout">PangoLayout</link> *layout,
391 const <link linkend="char">char</link> *markup,
392 <link linkend="int">int</link> length,
393 <link linkend="gunichar">gunichar</link> accel_marker,
394 <link linkend="gunichar">gunichar</link> *accel_char);</programlisting>
396 Sets the layout text and attribute list from marked-up text (see
397 <link linkend="PangoMarkupFormat">markup format</link>). Replaces
398 the current text and attribute list.
401 If <parameter>accel_marker</parameter> is nonzero, the given character will mark the
402 character following it as an accelerator. For example, <parameter>accel_marker</parameter>
403 might be an ampersand or underscore. All characters marked
404 as an accelerator will receive a <link linkend="PANGO-UNDERLINE-LOW--CAPS"><literal>PANGO_UNDERLINE_LOW</literal></link> attribute,
405 and the first character so marked will be returned in <parameter>accel_char</parameter>.
406 Two <parameter>accel_marker</parameter> characters following each other produce a single
407 literal <parameter>accel_marker</parameter> character.</para>
409 </para><variablelist role="params">
410 <varlistentry><term><parameter>layout</parameter> :</term>
411 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
412 </simpara></listitem></varlistentry>
413 <varlistentry><term><parameter>markup</parameter> :</term>
414 <listitem><simpara> marked-up text
415 (see <link linkend="PangoMarkupFormat">markup format</link>)
416 </simpara></listitem></varlistentry>
417 <varlistentry><term><parameter>length</parameter> :</term>
418 <listitem><simpara> length of marked-up text in bytes, or -1 if <parameter>markup</parameter> is
420 </simpara></listitem></varlistentry>
421 <varlistentry><term><parameter>accel_marker</parameter> :</term>
422 <listitem><simpara> marker for accelerators in the text
423 </simpara></listitem></varlistentry>
424 <varlistentry><term><parameter>accel_char</parameter> :</term>
425 <listitem><simpara> return location for first located accelerator, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
426 </simpara></listitem></varlistentry>
427 </variablelist></refsect2>
428 <refsect2 id="pango-layout-set-attributes" role="function">
429 <title>pango_layout_set_attributes ()</title>
430 <indexterm zone="pango-layout-set-attributes"><primary sortas="pango_layout_set_attributes">pango_layout_set_attributes</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_set_attributes (<link linkend="PangoLayout">PangoLayout</link> *layout,
431 <link linkend="PangoAttrList">PangoAttrList</link> *attrs);</programlisting>
433 Sets the text attributes for a layout object.
434 References <parameter>attrs</parameter>, so the caller can unref its reference.</para>
436 </para><variablelist role="params">
437 <varlistentry><term><parameter>layout</parameter> :</term>
438 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
439 </simpara></listitem></varlistentry>
440 <varlistentry><term><parameter>attrs</parameter> :</term>
441 <listitem><simpara> a <link linkend="PangoAttrList"><type>PangoAttrList</type></link>, can be <link linkend="NULL--CAPS"><literal>NULL</literal></link>
442 </simpara></listitem></varlistentry>
443 </variablelist></refsect2>
444 <refsect2 id="pango-layout-get-attributes" role="function">
445 <title>pango_layout_get_attributes ()</title>
446 <indexterm zone="pango-layout-get-attributes"><primary sortas="pango_layout_get_attributes">pango_layout_get_attributes</primary></indexterm><programlisting><link linkend="PangoAttrList">PangoAttrList</link> * pango_layout_get_attributes (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
448 Gets the attribute list for the layout, if any.</para>
450 </para><variablelist role="params">
451 <varlistentry><term><parameter>layout</parameter> :</term>
452 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
453 </simpara></listitem></varlistentry>
454 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="PangoAttrList"><type>PangoAttrList</type></link>.
455 </simpara></listitem></varlistentry>
456 </variablelist></refsect2>
457 <refsect2 id="pango-layout-set-font-description" role="function">
458 <title>pango_layout_set_font_description ()</title>
459 <indexterm zone="pango-layout-set-font-description"><primary sortas="pango_layout_set_font_description">pango_layout_set_font_description</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_set_font_description (<link linkend="PangoLayout">PangoLayout</link> *layout,
460 const <link linkend="PangoFontDescription">PangoFontDescription</link> *desc);</programlisting>
462 Sets the default font description for the layout. If no font
463 description is set on the layout, the font description from
464 the layout's context is used.</para>
466 </para><variablelist role="params">
467 <varlistentry><term><parameter>layout</parameter> :</term>
468 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
469 </simpara></listitem></varlistentry>
470 <varlistentry><term><parameter>desc</parameter> :</term>
471 <listitem><simpara> the new <link linkend="PangoFontDescription"><type>PangoFontDescription</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to unset the
472 current font description
473 </simpara></listitem></varlistentry>
474 </variablelist></refsect2>
475 <refsect2 id="pango-layout-get-font-description" role="function" condition="since:1.8">
476 <title>pango_layout_get_font_description ()</title>
477 <indexterm zone="pango-layout-get-font-description" role="1.8"><primary sortas="pango_layout_get_font_description">pango_layout_get_font_description</primary></indexterm><programlisting>const <link linkend="PangoFontDescription">PangoFontDescription</link> * pango_layout_get_font_description
478 (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
480 Gets the font description for the layout, if any.</para>
482 </para><variablelist role="params">
483 <varlistentry><term><parameter>layout</parameter> :</term>
484 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
485 </simpara></listitem></varlistentry>
486 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a pointer to the layout's font description,
487 or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the font description from the layout's
488 context is inherited. This value is owned by the layout
489 and must not be modified or freed.
491 </simpara></listitem></varlistentry>
492 </variablelist><para role="since">Since 1.8</para></refsect2>
493 <refsect2 id="pango-layout-set-width" role="function">
494 <title>pango_layout_set_width ()</title>
495 <indexterm zone="pango-layout-set-width"><primary sortas="pango_layout_set_width">pango_layout_set_width</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_set_width (<link linkend="PangoLayout">PangoLayout</link> *layout,
496 <link linkend="int">int</link> width);</programlisting>
498 Sets the width to which the lines of the <link linkend="PangoLayout"><type>PangoLayout</type></link> should wrap or
499 ellipsized. The default value is -1: no width set.</para>
501 </para><variablelist role="params">
502 <varlistentry><term><parameter>layout</parameter> :</term>
503 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>.
504 </simpara></listitem></varlistentry>
505 <varlistentry><term><parameter>width</parameter> :</term>
506 <listitem><simpara> the desired width in Pango units, or -1 to indicate that no
507 wrapping or ellipsization should be performed.
508 </simpara></listitem></varlistentry>
509 </variablelist></refsect2>
510 <refsect2 id="pango-layout-get-width" role="function">
511 <title>pango_layout_get_width ()</title>
512 <indexterm zone="pango-layout-get-width"><primary sortas="pango_layout_get_width">pango_layout_get_width</primary></indexterm><programlisting><link linkend="int">int</link> pango_layout_get_width (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
514 Gets the width to which the lines of the <link linkend="PangoLayout"><type>PangoLayout</type></link> should wrap.</para>
516 </para><variablelist role="params">
517 <varlistentry><term><parameter>layout</parameter> :</term>
518 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
519 </simpara></listitem></varlistentry>
520 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the width in Pango units, or -1 if no width set.
521 </simpara></listitem></varlistentry>
522 </variablelist></refsect2>
523 <refsect2 id="pango-layout-set-height" role="function" condition="since:1.20">
524 <title>pango_layout_set_height ()</title>
525 <indexterm zone="pango-layout-set-height" role="1.20"><primary sortas="pango_layout_set_height">pango_layout_set_height</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_set_height (<link linkend="PangoLayout">PangoLayout</link> *layout,
526 <link linkend="int">int</link> height);</programlisting>
528 Sets the height to which the <link linkend="PangoLayout"><type>PangoLayout</type></link> should be ellipsized at. There
529 are two different behaviors, based on whether <parameter>height</parameter> is positive or
533 If <parameter>height</parameter> is positive, it will be the maximum height of the layout. Only
534 lines would be shown that would fit, and if there is any text omitted,
535 an ellipsis added. At least one line is included in each paragraph regardless
536 of how small the height value is. A value of zero will render exactly one
537 line for the entire layout.
540 If <parameter>height</parameter> is negative, it will be the (negative of) maximum number of lines per
541 paragraph. That is, the total number of lines shown may well be more than
542 this value if the layout contains multiple paragraphs of text.
543 The default value of -1 means that first line of each paragraph is ellipsized.
544 This behvaior may be changed in the future to act per layout instead of per
545 paragraph. File a bug against pango at <ulink
546 url="http://bugzilla.gnome.org/">http://bugzilla.gnome.org/</ulink> if your
547 code relies on this behavior.
550 Height setting only has effect if a positive width is set on
551 <parameter>layout</parameter> and ellipsization mode of <parameter>layout</parameter> is not <link linkend="PANGO-ELLIPSIZE-NONE--CAPS"><literal>PANGO_ELLIPSIZE_NONE</literal></link>.
552 The behavior is undefined if a height other than -1 is set and
553 ellipsization mode is set to <link linkend="PANGO-ELLIPSIZE-NONE--CAPS"><literal>PANGO_ELLIPSIZE_NONE</literal></link>, and may change in the
556 </para><variablelist role="params">
557 <varlistentry><term><parameter>layout</parameter> :</term>
558 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>.
559 </simpara></listitem></varlistentry>
560 <varlistentry><term><parameter>height</parameter> :</term>
561 <listitem><simpara> the desired height of the layout in Pango units if positive,
562 or desired number of lines if negative.
563 </simpara></listitem></varlistentry>
564 </variablelist><para role="since">Since 1.20</para></refsect2>
565 <refsect2 id="pango-layout-get-height" role="function" condition="since:1.20">
566 <title>pango_layout_get_height ()</title>
567 <indexterm zone="pango-layout-get-height" role="1.20"><primary sortas="pango_layout_get_height">pango_layout_get_height</primary></indexterm><programlisting><link linkend="int">int</link> pango_layout_get_height (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
569 Gets the height of layout used for ellipsization. See
570 <link linkend="pango-layout-set-height"><function>pango_layout_set_height()</function></link> for details.</para>
572 </para><variablelist role="params">
573 <varlistentry><term><parameter>layout</parameter> :</term>
574 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
575 </simpara></listitem></varlistentry>
576 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the height, in Pango units if positive, or
577 number of lines if negative.
579 </simpara></listitem></varlistentry>
580 </variablelist><para role="since">Since 1.20</para></refsect2>
581 <refsect2 id="pango-layout-set-wrap" role="function">
582 <title>pango_layout_set_wrap ()</title>
583 <indexterm zone="pango-layout-set-wrap"><primary sortas="pango_layout_set_wrap">pango_layout_set_wrap</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_set_wrap (<link linkend="PangoLayout">PangoLayout</link> *layout,
584 <link linkend="PangoWrapMode">PangoWrapMode</link> wrap);</programlisting>
586 Sets the wrap mode; the wrap mode only has effect if a width
587 is set on the layout with <link linkend="pango-layout-set-width"><function>pango_layout_set_width()</function></link>.
588 To turn off wrapping, set the width to -1.</para>
590 </para><variablelist role="params">
591 <varlistentry><term><parameter>layout</parameter> :</term>
592 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
593 </simpara></listitem></varlistentry>
594 <varlistentry><term><parameter>wrap</parameter> :</term>
595 <listitem><simpara> the wrap mode
596 </simpara></listitem></varlistentry>
597 </variablelist></refsect2>
598 <refsect2 id="pango-layout-get-wrap" role="function">
599 <title>pango_layout_get_wrap ()</title>
600 <indexterm zone="pango-layout-get-wrap"><primary sortas="pango_layout_get_wrap">pango_layout_get_wrap</primary></indexterm><programlisting><link linkend="PangoWrapMode">PangoWrapMode</link> pango_layout_get_wrap (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
602 Gets the wrap mode for the layout.
605 Use <link linkend="pango-layout-is-wrapped"><function>pango_layout_is_wrapped()</function></link> to query whether any paragraphs
606 were actually wrapped.</para>
608 </para><variablelist role="params">
609 <varlistentry><term><parameter>layout</parameter> :</term>
610 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
611 </simpara></listitem></varlistentry>
612 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> active wrap mode.
613 </simpara></listitem></varlistentry>
614 </variablelist></refsect2>
615 <refsect2 id="pango-layout-is-wrapped" role="function" condition="since:1.16">
616 <title>pango_layout_is_wrapped ()</title>
617 <indexterm zone="pango-layout-is-wrapped" role="1.16"><primary sortas="pango_layout_is_wrapped">pango_layout_is_wrapped</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> pango_layout_is_wrapped (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
619 Queries whether the layout had to wrap any paragraphs.
622 This returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if a positive width is set on <parameter>layout</parameter>,
623 ellipsization mode of <parameter>layout</parameter> is set to <link linkend="PANGO-ELLIPSIZE-NONE--CAPS"><literal>PANGO_ELLIPSIZE_NONE</literal></link>,
624 and there are paragraphs exceeding the layout width that have
625 to be wrapped.</para>
627 </para><variablelist role="params">
628 <varlistentry><term><parameter>layout</parameter> :</term>
629 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
630 </simpara></listitem></varlistentry>
631 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if any paragraphs had to be wrapped, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>
634 </simpara></listitem></varlistentry>
635 </variablelist><para role="since">Since 1.16</para></refsect2>
636 <refsect2 id="PangoWrapMode" role="enum">
637 <title>enum PangoWrapMode</title>
638 <indexterm zone="PangoWrapMode"><primary sortas="PangoWrapMode">PangoWrapMode</primary></indexterm><programlisting>typedef enum {
645 A <link linkend="PangoWrapMode"><type>PangoWrapMode</type></link> describes how to wrap the lines of a <link linkend="PangoLayout"><type>PangoLayout</type></link> to the desired width.
646 </para><variablelist role="enum">
647 <varlistentry id="PANGO-WRAP-WORD--CAPS" role="constant">
648 <term><literal>PANGO_WRAP_WORD</literal></term>
649 <listitem><simpara>wrap lines at word boundaries.
650 </simpara></listitem>
652 <varlistentry id="PANGO-WRAP-CHAR--CAPS" role="constant">
653 <term><literal>PANGO_WRAP_CHAR</literal></term>
654 <listitem><simpara>wrap lines at character boundaries.
655 </simpara></listitem>
657 <varlistentry id="PANGO-WRAP-WORD-CHAR--CAPS" role="constant">
658 <term><literal>PANGO_WRAP_WORD_CHAR</literal></term>
659 <listitem><simpara>wrap lines at word boundaries, but fall back to character boundaries if there is not
660 enough space for a full word.
661 </simpara></listitem>
663 </variablelist></refsect2>
664 <refsect2 id="PANGO-TYPE-WRAP-MODE--CAPS" role="macro">
665 <title>PANGO_TYPE_WRAP_MODE</title>
666 <indexterm zone="PANGO-TYPE-WRAP-MODE--CAPS"><primary sortas="PANGO_TYPE_WRAP_MODE">PANGO_TYPE_WRAP_MODE</primary></indexterm><programlisting>#define PANGO_TYPE_WRAP_MODE (pango_wrap_mode_get_type())
669 The <link linkend="GObject"><type>GObject</type></link> type for <link linkend="PangoWrapMode"><type>PangoWrapMode</type></link>.
671 <refsect2 id="pango-layout-set-ellipsize" role="function" condition="since:1.6">
672 <title>pango_layout_set_ellipsize ()</title>
673 <indexterm zone="pango-layout-set-ellipsize" role="1.6"><primary sortas="pango_layout_set_ellipsize">pango_layout_set_ellipsize</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_set_ellipsize (<link linkend="PangoLayout">PangoLayout</link> *layout,
674 <link linkend="PangoEllipsizeMode">PangoEllipsizeMode</link> ellipsize);</programlisting>
676 Sets the type of ellipsization being performed for <parameter>layout</parameter>.
677 Depending on the ellipsization mode <parameter>ellipsize</parameter> text is
678 removed from the start, middle, or end of text so they
679 fit within the width and height of layout set with
680 <link linkend="pango-layout-set-width"><function>pango_layout_set_width()</function></link> and <link linkend="pango-layout-set-height"><function>pango_layout_set_height()</function></link>.
683 If the layout contains characters such as newlines that
684 force it to be layed out in multiple paragraphs, then whether
685 each paragraph is ellipsized separately or the entire layout
686 is ellipsized as a whole depends on the set height of the layout.
687 See <link linkend="pango-layout-set-height"><function>pango_layout_set_height()</function></link> for details.</para>
689 </para><variablelist role="params">
690 <varlistentry><term><parameter>layout</parameter> :</term>
691 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
692 </simpara></listitem></varlistentry>
693 <varlistentry><term><parameter>ellipsize</parameter> :</term>
694 <listitem><simpara> the new ellipsization mode for <parameter>layout</parameter>
695 </simpara></listitem></varlistentry>
696 </variablelist><para role="since">Since 1.6</para></refsect2>
697 <refsect2 id="pango-layout-get-ellipsize" role="function" condition="since:1.6">
698 <title>pango_layout_get_ellipsize ()</title>
699 <indexterm zone="pango-layout-get-ellipsize" role="1.6"><primary sortas="pango_layout_get_ellipsize">pango_layout_get_ellipsize</primary></indexterm><programlisting><link linkend="PangoEllipsizeMode">PangoEllipsizeMode</link> pango_layout_get_ellipsize (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
701 Gets the type of ellipsization being performed for <parameter>layout</parameter>.
702 See <link linkend="pango-layout-set-ellipsize"><function>pango_layout_set_ellipsize()</function></link></para>
704 </para><variablelist role="params">
705 <varlistentry><term><parameter>layout</parameter> :</term>
706 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
707 </simpara></listitem></varlistentry>
708 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the current ellipsization mode for <parameter>layout</parameter>.
710 Use <link linkend="pango-layout-is-ellipsized"><function>pango_layout_is_ellipsized()</function></link> to query whether any paragraphs
711 were actually ellipsized.
713 </simpara></listitem></varlistentry>
714 </variablelist><para role="since">Since 1.6</para></refsect2>
715 <refsect2 id="pango-layout-is-ellipsized" role="function" condition="since:1.16">
716 <title>pango_layout_is_ellipsized ()</title>
717 <indexterm zone="pango-layout-is-ellipsized" role="1.16"><primary sortas="pango_layout_is_ellipsized">pango_layout_is_ellipsized</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> pango_layout_is_ellipsized (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
719 Queries whether the layout had to ellipsize any paragraphs.
722 This returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the ellipsization mode for <parameter>layout</parameter>
723 is not <link linkend="PANGO-ELLIPSIZE-NONE--CAPS"><literal>PANGO_ELLIPSIZE_NONE</literal></link>, a positive width is set on <parameter>layout</parameter>,
724 and there are paragraphs exceeding that width that have to be
727 </para><variablelist role="params">
728 <varlistentry><term><parameter>layout</parameter> :</term>
729 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
730 </simpara></listitem></varlistentry>
731 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if any paragraphs had to be ellipsized, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>
734 </simpara></listitem></varlistentry>
735 </variablelist><para role="since">Since 1.16</para></refsect2>
736 <refsect2 id="PangoEllipsizeMode" role="enum">
737 <title>enum PangoEllipsizeMode</title>
738 <indexterm zone="PangoEllipsizeMode"><primary sortas="PangoEllipsizeMode">PangoEllipsizeMode</primary></indexterm><programlisting>typedef enum {
739 PANGO_ELLIPSIZE_NONE,
740 PANGO_ELLIPSIZE_START,
741 PANGO_ELLIPSIZE_MIDDLE,
743 } PangoEllipsizeMode;
746 The <link linkend="PangoEllipsizeMode"><type>PangoEllipsizeMode</type></link> type describes what sort of (if any)
747 ellipsization should be applied to a line of text. In
748 the ellipsization process characters are removed from the
749 text in order to make it fit to a given width and replaced
750 with an ellipsis.</para>
752 </para><variablelist role="enum">
753 <varlistentry id="PANGO-ELLIPSIZE-NONE--CAPS" role="constant">
754 <term><literal>PANGO_ELLIPSIZE_NONE</literal></term>
755 <listitem><simpara> No ellipsization
756 </simpara></listitem>
758 <varlistentry id="PANGO-ELLIPSIZE-START--CAPS" role="constant">
759 <term><literal>PANGO_ELLIPSIZE_START</literal></term>
760 <listitem><simpara> Omit characters at the start of the text
761 </simpara></listitem>
763 <varlistentry id="PANGO-ELLIPSIZE-MIDDLE--CAPS" role="constant">
764 <term><literal>PANGO_ELLIPSIZE_MIDDLE</literal></term>
765 <listitem><simpara> Omit characters in the middle of the text
766 </simpara></listitem>
768 <varlistentry id="PANGO-ELLIPSIZE-END--CAPS" role="constant">
769 <term><literal>PANGO_ELLIPSIZE_END</literal></term>
770 <listitem><simpara> Omit characters at the end of the text
771 </simpara></listitem>
773 </variablelist></refsect2>
774 <refsect2 id="PANGO-TYPE-ELLIPSIZE-MODE--CAPS" role="macro">
775 <title>PANGO_TYPE_ELLIPSIZE_MODE</title>
776 <indexterm zone="PANGO-TYPE-ELLIPSIZE-MODE--CAPS"><primary sortas="PANGO_TYPE_ELLIPSIZE_MODE">PANGO_TYPE_ELLIPSIZE_MODE</primary></indexterm><programlisting>#define PANGO_TYPE_ELLIPSIZE_MODE (pango_ellipsize_mode_get_type())
779 The <link linkend="GObject"><type>GObject</type></link> type for <link linkend="PangoEllipsizeMode"><type>PangoEllipsizeMode</type></link>.
781 <refsect2 id="pango-layout-set-indent" role="function">
782 <title>pango_layout_set_indent ()</title>
783 <indexterm zone="pango-layout-set-indent"><primary sortas="pango_layout_set_indent">pango_layout_set_indent</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_set_indent (<link linkend="PangoLayout">PangoLayout</link> *layout,
784 <link linkend="int">int</link> indent);</programlisting>
786 Sets the width in Pango units to indent each paragraph. A negative value
787 of <parameter>indent</parameter> will produce a hanging indentation. That is, the first line will
788 have the full width, and subsequent lines will be indented by the
789 absolute value of <parameter>indent</parameter>.
792 The indent setting is ignored if layout alignment is set to
793 <link linkend="PANGO-ALIGN-CENTER--CAPS"><literal>PANGO_ALIGN_CENTER</literal></link>.</para>
795 </para><variablelist role="params">
796 <varlistentry><term><parameter>layout</parameter> :</term>
797 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>.
798 </simpara></listitem></varlistentry>
799 <varlistentry><term><parameter>indent</parameter> :</term>
800 <listitem><simpara> the amount by which to indent.
801 </simpara></listitem></varlistentry>
802 </variablelist></refsect2>
803 <refsect2 id="pango-layout-get-indent" role="function">
804 <title>pango_layout_get_indent ()</title>
805 <indexterm zone="pango-layout-get-indent"><primary sortas="pango_layout_get_indent">pango_layout_get_indent</primary></indexterm><programlisting><link linkend="int">int</link> pango_layout_get_indent (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
807 Gets the paragraph indent width in Pango units. A negative value
808 indicates a hanging indentation.</para>
810 </para><variablelist role="params">
811 <varlistentry><term><parameter>layout</parameter> :</term>
812 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
813 </simpara></listitem></varlistentry>
814 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the indent in Pango units.
815 </simpara></listitem></varlistentry>
816 </variablelist></refsect2>
817 <refsect2 id="pango-layout-get-spacing" role="function">
818 <title>pango_layout_get_spacing ()</title>
819 <indexterm zone="pango-layout-get-spacing"><primary sortas="pango_layout_get_spacing">pango_layout_get_spacing</primary></indexterm><programlisting><link linkend="int">int</link> pango_layout_get_spacing (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
821 Gets the amount of spacing between the lines of the layout.</para>
823 </para><variablelist role="params">
824 <varlistentry><term><parameter>layout</parameter> :</term>
825 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
826 </simpara></listitem></varlistentry>
827 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the spacing in Pango units.
828 </simpara></listitem></varlistentry>
829 </variablelist></refsect2>
830 <refsect2 id="pango-layout-set-spacing" role="function">
831 <title>pango_layout_set_spacing ()</title>
832 <indexterm zone="pango-layout-set-spacing"><primary sortas="pango_layout_set_spacing">pango_layout_set_spacing</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_set_spacing (<link linkend="PangoLayout">PangoLayout</link> *layout,
833 <link linkend="int">int</link> spacing);</programlisting>
835 Sets the amount of spacing in Pango unit between the lines of the
838 </para><variablelist role="params">
839 <varlistentry><term><parameter>layout</parameter> :</term>
840 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>.
841 </simpara></listitem></varlistentry>
842 <varlistentry><term><parameter>spacing</parameter> :</term>
843 <listitem><simpara> the amount of spacing
844 </simpara></listitem></varlistentry>
845 </variablelist></refsect2>
846 <refsect2 id="pango-layout-set-justify" role="function">
847 <title>pango_layout_set_justify ()</title>
848 <indexterm zone="pango-layout-set-justify"><primary sortas="pango_layout_set_justify">pango_layout_set_justify</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_set_justify (<link linkend="PangoLayout">PangoLayout</link> *layout,
849 <link linkend="gboolean">gboolean</link> justify);</programlisting>
851 Sets whether each complete line should be stretched to
852 fill the entire width of the layout. This stretching is typically
853 done by adding whitespace, but for some scripts (such as Arabic),
854 the justification may be done in more complex ways, like extending
858 Note that this setting is not implemented and so is ignored in Pango
859 older than 1.18.</para>
861 </para><variablelist role="params">
862 <varlistentry><term><parameter>layout</parameter> :</term>
863 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
864 </simpara></listitem></varlistentry>
865 <varlistentry><term><parameter>justify</parameter> :</term>
866 <listitem><simpara> whether the lines in the layout should be justified.
867 </simpara></listitem></varlistentry>
868 </variablelist></refsect2>
869 <refsect2 id="pango-layout-get-justify" role="function">
870 <title>pango_layout_get_justify ()</title>
871 <indexterm zone="pango-layout-get-justify"><primary sortas="pango_layout_get_justify">pango_layout_get_justify</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> pango_layout_get_justify (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
873 Gets whether each complete line should be stretched to fill the entire
874 width of the layout.</para>
876 </para><variablelist role="params">
877 <varlistentry><term><parameter>layout</parameter> :</term>
878 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
879 </simpara></listitem></varlistentry>
880 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the justify.
881 </simpara></listitem></varlistentry>
882 </variablelist></refsect2>
883 <refsect2 id="pango-layout-set-auto-dir" role="function" condition="since:1.4">
884 <title>pango_layout_set_auto_dir ()</title>
885 <indexterm zone="pango-layout-set-auto-dir" role="1.4"><primary sortas="pango_layout_set_auto_dir">pango_layout_set_auto_dir</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_set_auto_dir (<link linkend="PangoLayout">PangoLayout</link> *layout,
886 <link linkend="gboolean">gboolean</link> auto_dir);</programlisting>
888 Sets whether to calculate the bidirectional base direction
889 for the layout according to the contents of the layout;
890 when this flag is on (the default), then paragraphs in
891 <parameter>layout</parameter> that begin with strong right-to-left characters
892 (Arabic and Hebrew principally), will have right-to-left
893 layout, paragraphs with letters from other scripts will
894 have left-to-right layout. Paragraphs with only neutral
895 characters get their direction from the surrounding paragraphs.
898 When <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>, the choice between left-to-right and
899 right-to-left layout is done according to the base direction
900 of the layout's <link linkend="PangoContext"><type>PangoContext</type></link>. (See <link linkend="pango-context-set-base-dir"><function>pango_context_set_base_dir()</function></link>).
903 When the auto-computed direction of a paragraph differs from the
904 base direction of the context, the interpretation of
905 <link linkend="PANGO-ALIGN-LEFT--CAPS"><literal>PANGO_ALIGN_LEFT</literal></link> and <link linkend="PANGO-ALIGN-RIGHT--CAPS"><literal>PANGO_ALIGN_RIGHT</literal></link> are swapped.</para>
907 </para><variablelist role="params">
908 <varlistentry><term><parameter>layout</parameter> :</term>
909 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
910 </simpara></listitem></varlistentry>
911 <varlistentry><term><parameter>auto_dir</parameter> :</term>
912 <listitem><simpara> if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, compute the bidirectional base direction
913 from the layout's contents.
914 </simpara></listitem></varlistentry>
915 </variablelist><para role="since">Since 1.4</para></refsect2>
916 <refsect2 id="pango-layout-get-auto-dir" role="function" condition="since:1.4">
917 <title>pango_layout_get_auto_dir ()</title>
918 <indexterm zone="pango-layout-get-auto-dir" role="1.4"><primary sortas="pango_layout_get_auto_dir">pango_layout_get_auto_dir</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> pango_layout_get_auto_dir (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
920 Gets whether to calculate the bidirectional base direction
921 for the layout according to the contents of the layout.
922 See <link linkend="pango-layout-set-auto-dir"><function>pango_layout_set_auto_dir()</function></link>.</para>
924 </para><variablelist role="params">
925 <varlistentry><term><parameter>layout</parameter> :</term>
926 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
927 </simpara></listitem></varlistentry>
928 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the bidirectional base direction
929 is computed from the layout's contents, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
931 </simpara></listitem></varlistentry>
932 </variablelist><para role="since">Since 1.4</para></refsect2>
933 <refsect2 id="pango-layout-set-alignment" role="function">
934 <title>pango_layout_set_alignment ()</title>
935 <indexterm zone="pango-layout-set-alignment"><primary sortas="pango_layout_set_alignment">pango_layout_set_alignment</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_set_alignment (<link linkend="PangoLayout">PangoLayout</link> *layout,
936 <link linkend="PangoAlignment">PangoAlignment</link> alignment);</programlisting>
938 Sets the alignment for the layout: how partial lines are
939 positioned within the horizontal space available.</para>
941 </para><variablelist role="params">
942 <varlistentry><term><parameter>layout</parameter> :</term>
943 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
944 </simpara></listitem></varlistentry>
945 <varlistentry><term><parameter>alignment</parameter> :</term>
946 <listitem><simpara> the alignment
947 </simpara></listitem></varlistentry>
948 </variablelist></refsect2>
949 <refsect2 id="pango-layout-get-alignment" role="function">
950 <title>pango_layout_get_alignment ()</title>
951 <indexterm zone="pango-layout-get-alignment"><primary sortas="pango_layout_get_alignment">pango_layout_get_alignment</primary></indexterm><programlisting><link linkend="PangoAlignment">PangoAlignment</link> pango_layout_get_alignment (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
953 Gets the alignment for the layout: how partial lines are
954 positioned within the horizontal space available.</para>
956 </para><variablelist role="params">
957 <varlistentry><term><parameter>layout</parameter> :</term>
958 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
959 </simpara></listitem></varlistentry>
960 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the alignment.
961 </simpara></listitem></varlistentry>
962 </variablelist></refsect2>
963 <refsect2 id="pango-layout-set-tabs" role="function">
964 <title>pango_layout_set_tabs ()</title>
965 <indexterm zone="pango-layout-set-tabs"><primary sortas="pango_layout_set_tabs">pango_layout_set_tabs</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_set_tabs (<link linkend="PangoLayout">PangoLayout</link> *layout,
966 <link linkend="PangoTabArray">PangoTabArray</link> *tabs);</programlisting>
968 Sets the tabs to use for <parameter>layout</parameter>, overriding the default tabs
969 (by default, tabs are every 8 spaces). If <parameter>tabs</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, the default
970 tabs are reinstated. <parameter>tabs</parameter> is copied into the layout; you must
971 free your copy of <parameter>tabs</parameter> yourself.</para>
973 </para><variablelist role="params">
974 <varlistentry><term><parameter>layout</parameter> :</term>
975 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
976 </simpara></listitem></varlistentry>
977 <varlistentry><term><parameter>tabs</parameter> :</term>
978 <listitem><simpara> a <link linkend="PangoTabArray"><type>PangoTabArray</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
979 </simpara></listitem></varlistentry>
980 </variablelist></refsect2>
981 <refsect2 id="pango-layout-get-tabs" role="function">
982 <title>pango_layout_get_tabs ()</title>
983 <indexterm zone="pango-layout-get-tabs"><primary sortas="pango_layout_get_tabs">pango_layout_get_tabs</primary></indexterm><programlisting><link linkend="PangoTabArray">PangoTabArray</link>* pango_layout_get_tabs (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
985 Gets the current <link linkend="PangoTabArray"><type>PangoTabArray</type></link> used by this layout. If no
986 <link linkend="PangoTabArray"><type>PangoTabArray</type></link> has been set, then the default tabs are in use
987 and <link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned. Default tabs are every 8 spaces.
988 The return value should be freed with <link linkend="pango-tab-array-free"><function>pango_tab_array_free()</function></link>.</para>
990 </para><variablelist role="params">
991 <varlistentry><term><parameter>layout</parameter> :</term>
992 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
993 </simpara></listitem></varlistentry>
994 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a copy of the tabs for this layout, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
995 </simpara></listitem></varlistentry>
996 </variablelist></refsect2>
997 <refsect2 id="pango-layout-set-single-paragraph-mode" role="function">
998 <title>pango_layout_set_single_paragraph_mode ()</title>
999 <indexterm zone="pango-layout-set-single-paragraph-mode"><primary sortas="pango_layout_set_single_paragraph_mode">pango_layout_set_single_paragraph_mode</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_set_single_paragraph_mode
1000 (<link linkend="PangoLayout">PangoLayout</link> *layout,
1001 <link linkend="gboolean">gboolean</link> setting);</programlisting>
1003 If <parameter>setting</parameter> is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, do not treat newlines and similar characters
1004 as paragraph separators; instead, keep all text in a single paragraph,
1005 and display a glyph for paragraph separator characters. Used when
1006 you want to allow editing of newlines on a single text line.</para>
1008 </para><variablelist role="params">
1009 <varlistentry><term><parameter>layout</parameter> :</term>
1010 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1011 </simpara></listitem></varlistentry>
1012 <varlistentry><term><parameter>setting</parameter> :</term>
1013 <listitem><simpara> new setting
1014 </simpara></listitem></varlistentry>
1015 </variablelist></refsect2>
1016 <refsect2 id="pango-layout-get-single-paragraph-mode" role="function">
1017 <title>pango_layout_get_single_paragraph_mode ()</title>
1018 <indexterm zone="pango-layout-get-single-paragraph-mode"><primary sortas="pango_layout_get_single_paragraph_mode">pango_layout_get_single_paragraph_mode</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> pango_layout_get_single_paragraph_mode
1019 (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
1021 Obtains the value set by <link linkend="pango-layout-set-single-paragraph-mode"><function>pango_layout_set_single_paragraph_mode()</function></link>.</para>
1023 </para><variablelist role="params">
1024 <varlistentry><term><parameter>layout</parameter> :</term>
1025 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1026 </simpara></listitem></varlistentry>
1027 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the layout does not break paragraphs at
1028 paragraph separator characters, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
1029 </simpara></listitem></varlistentry>
1030 </variablelist></refsect2>
1031 <refsect2 id="PangoAlignment" role="enum">
1032 <title>enum PangoAlignment</title>
1033 <indexterm zone="PangoAlignment"><primary sortas="PangoAlignment">PangoAlignment</primary></indexterm><programlisting>typedef enum {
1040 A <link linkend="PangoAlignment"><type>PangoAlignment</type></link> describes how to align the lines of a <link linkend="PangoLayout"><type>PangoLayout</type></link> within the
1041 available space. If the <link linkend="PangoLayout"><type>PangoLayout</type></link> is set to justify
1042 using <link linkend="pango-layout-set-justify"><function>pango_layout_set_justify()</function></link>, this only has effect for partial lines.
1043 </para><variablelist role="enum">
1044 <varlistentry id="PANGO-ALIGN-LEFT--CAPS" role="constant">
1045 <term><literal>PANGO_ALIGN_LEFT</literal></term>
1046 <listitem><simpara>Put all available space on the right
1047 </simpara></listitem>
1049 <varlistentry id="PANGO-ALIGN-CENTER--CAPS" role="constant">
1050 <term><literal>PANGO_ALIGN_CENTER</literal></term>
1051 <listitem><simpara>Center the line within the available space
1052 </simpara></listitem>
1054 <varlistentry id="PANGO-ALIGN-RIGHT--CAPS" role="constant">
1055 <term><literal>PANGO_ALIGN_RIGHT</literal></term>
1056 <listitem><simpara>Put all available space on the left
1057 </simpara></listitem>
1059 </variablelist></refsect2>
1060 <refsect2 id="PANGO-TYPE-ALIGNMENT--CAPS" role="macro">
1061 <title>PANGO_TYPE_ALIGNMENT</title>
1062 <indexterm zone="PANGO-TYPE-ALIGNMENT--CAPS"><primary sortas="PANGO_TYPE_ALIGNMENT">PANGO_TYPE_ALIGNMENT</primary></indexterm><programlisting>#define PANGO_TYPE_ALIGNMENT (pango_alignment_get_type())
1065 The <link linkend="GObject"><type>GObject</type></link> type for <link linkend="PangoAlignment"><type>PangoAlignment</type></link>.
1067 <refsect2 id="pango-layout-get-unknown-glyphs-count" role="function" condition="since:1.16">
1068 <title>pango_layout_get_unknown_glyphs_count ()</title>
1069 <indexterm zone="pango-layout-get-unknown-glyphs-count" role="1.16"><primary sortas="pango_layout_get_unknown_glyphs_count">pango_layout_get_unknown_glyphs_count</primary></indexterm><programlisting><link linkend="int">int</link> pango_layout_get_unknown_glyphs_count
1070 (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
1072 Counts the number unknown glyphs in <parameter>layout</parameter>. That is, zero if
1073 glyphs for all characters in the layout text were found, or more
1074 than zero otherwise.
1077 This function can be used to determine if there are any fonts
1078 available to render all characters in a certain string, or when
1079 used in combination with <link linkend="PANGO-ATTR-FALLBACK--CAPS"><literal>PANGO_ATTR_FALLBACK</literal></link>, to check if a
1080 certain font supports all the characters in the string.</para>
1082 </para><variablelist role="params">
1083 <varlistentry><term><parameter>layout</parameter> :</term>
1084 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1085 </simpara></listitem></varlistentry>
1086 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The number of unknown glyphs in <parameter>layout</parameter>.
1088 </simpara></listitem></varlistentry>
1089 </variablelist><para role="since">Since 1.16</para></refsect2>
1090 <refsect2 id="pango-layout-get-log-attrs" role="function">
1091 <title>pango_layout_get_log_attrs ()</title>
1092 <indexterm zone="pango-layout-get-log-attrs"><primary sortas="pango_layout_get_log_attrs">pango_layout_get_log_attrs</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_get_log_attrs (<link linkend="PangoLayout">PangoLayout</link> *layout,
1093 <link linkend="PangoLogAttr">PangoLogAttr</link> **attrs,
1094 <link linkend="gint">gint</link> *n_attrs);</programlisting>
1096 Retrieves an array of logical attributes for each character in
1097 the <parameter>layout</parameter>.</para>
1099 </para><variablelist role="params">
1100 <varlistentry><term><parameter>layout</parameter> :</term>
1101 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1102 </simpara></listitem></varlistentry>
1103 <varlistentry><term><parameter>attrs</parameter> :</term>
1104 <listitem><simpara> location to store a pointer to an array of logical attributes
1105 This value must be freed with <link linkend="g-free"><function>g_free()</function></link>.
1106 </simpara></listitem></varlistentry>
1107 <varlistentry><term><parameter>n_attrs</parameter> :</term>
1108 <listitem><simpara> location to store the number of the attributes in the
1109 array. (The stored value will be one more than the total number
1110 of characters in the layout, since there need to be attributes
1111 corresponding to both the position before the first character
1112 and the position after the last character.)
1113 </simpara></listitem></varlistentry>
1114 </variablelist></refsect2>
1115 <refsect2 id="pango-layout-index-to-pos" role="function">
1116 <title>pango_layout_index_to_pos ()</title>
1117 <indexterm zone="pango-layout-index-to-pos"><primary sortas="pango_layout_index_to_pos">pango_layout_index_to_pos</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_index_to_pos (<link linkend="PangoLayout">PangoLayout</link> *layout,
1118 <link linkend="int">int</link> index_,
1119 <link linkend="PangoRectangle">PangoRectangle</link> *pos);</programlisting>
1121 Converts from an index within a <link linkend="PangoLayout"><type>PangoLayout</type></link> to the onscreen position
1122 corresponding to the grapheme at that index, which is represented
1123 as rectangle. Note that <literal>pos->x</literal> is always the leading
1124 edge of the grapheme and <literal>pos->x + pos->width</literal> the trailing
1125 edge of the grapheme. If the directionality of the grapheme is right-to-left,
1126 then <literal>pos->width</literal> will be negative.</para>
1128 </para><variablelist role="params">
1129 <varlistentry><term><parameter>layout</parameter> :</term>
1130 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1131 </simpara></listitem></varlistentry>
1132 <varlistentry><term><parameter>index_</parameter> :</term>
1133 <listitem><simpara> byte index within <parameter>layout</parameter>
1134 </simpara></listitem></varlistentry>
1135 <varlistentry><term><parameter>pos</parameter> :</term>
1136 <listitem><simpara> rectangle in which to store the position of the grapheme
1137 </simpara></listitem></varlistentry>
1138 </variablelist></refsect2>
1139 <refsect2 id="pango-layout-index-to-line-x" role="function">
1140 <title>pango_layout_index_to_line_x ()</title>
1141 <indexterm zone="pango-layout-index-to-line-x"><primary sortas="pango_layout_index_to_line_x">pango_layout_index_to_line_x</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_index_to_line_x (<link linkend="PangoLayout">PangoLayout</link> *layout,
1142 <link linkend="int">int</link> index_,
1143 <link linkend="gboolean">gboolean</link> trailing,
1144 <link linkend="int">int</link> *line,
1145 <link linkend="int">int</link> *x_pos);</programlisting>
1147 Converts from byte <parameter>index_</parameter> within the <parameter>layout</parameter> to line and X position.
1148 (X position is measured from the left edge of the line)</para>
1150 </para><variablelist role="params">
1151 <varlistentry><term><parameter>layout</parameter> :</term>
1152 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1153 </simpara></listitem></varlistentry>
1154 <varlistentry><term><parameter>index_</parameter> :</term>
1155 <listitem><simpara> the byte index of a grapheme within the layout.
1156 </simpara></listitem></varlistentry>
1157 <varlistentry><term><parameter>trailing</parameter> :</term>
1158 <listitem><simpara> an integer indicating the edge of the grapheme to retrieve the
1159 position of. If 0, the trailing edge of the grapheme, if > 0,
1160 the leading of the grapheme.
1161 </simpara></listitem></varlistentry>
1162 <varlistentry><term><parameter>line</parameter> :</term>
1163 <listitem><simpara> location to store resulting line index. (which will
1164 between 0 and pango_layout_get_line_count(layout) - 1)
1165 </simpara></listitem></varlistentry>
1166 <varlistentry><term><parameter>x_pos</parameter> :</term>
1167 <listitem><simpara> location to store resulting position within line
1168 (<link linkend="PANGO-SCALE--CAPS"><literal>PANGO_SCALE</literal></link> units per device unit)
1169 </simpara></listitem></varlistentry>
1170 </variablelist></refsect2>
1171 <refsect2 id="pango-layout-xy-to-index" role="function">
1172 <title>pango_layout_xy_to_index ()</title>
1173 <indexterm zone="pango-layout-xy-to-index"><primary sortas="pango_layout_xy_to_index">pango_layout_xy_to_index</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> pango_layout_xy_to_index (<link linkend="PangoLayout">PangoLayout</link> *layout,
1174 <link linkend="int">int</link> x,
1175 <link linkend="int">int</link> y,
1176 <link linkend="int">int</link> *index_,
1177 <link linkend="int">int</link> *trailing);</programlisting>
1179 Converts from X and Y position within a layout to the byte
1180 index to the character at that logical position. If the
1181 Y position is not inside the layout, the closest position is chosen
1182 (the position will be clamped inside the layout). If the
1183 X position is not within the layout, then the start or the
1184 end of the line is chosen as described for <link linkend="pango-layout-x-to-index"><function>pango_layout_x_to_index()</function></link>.
1185 If either the X or Y positions were not inside the layout, then the
1186 function returns <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>; on an exact hit, it returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>.</para>
1188 </para><variablelist role="params">
1189 <varlistentry><term><parameter>layout</parameter> :</term>
1190 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1191 </simpara></listitem></varlistentry>
1192 <varlistentry><term><parameter>x</parameter> :</term>
1193 <listitem><simpara> the X offset (in Pango units)
1194 from the left edge of the layout.
1195 </simpara></listitem></varlistentry>
1196 <varlistentry><term><parameter>y</parameter> :</term>
1197 <listitem><simpara> the Y offset (in Pango units)
1198 from the top edge of the layout
1199 </simpara></listitem></varlistentry>
1200 <varlistentry><term><parameter>index_</parameter> :</term>
1201 <listitem><simpara> location to store calculated byte index
1202 </simpara></listitem></varlistentry>
1203 <varlistentry><term><parameter>trailing</parameter> :</term>
1204 <listitem><simpara> location to store a integer indicating where
1205 in the grapheme the user clicked. It will either
1206 be zero, or the number of characters in the
1207 grapheme. 0 represents the trailing edge of the grapheme.
1208 </simpara></listitem></varlistentry>
1209 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the coordinates were inside text, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
1210 </simpara></listitem></varlistentry>
1211 </variablelist></refsect2>
1212 <refsect2 id="pango-layout-get-cursor-pos" role="function">
1213 <title>pango_layout_get_cursor_pos ()</title>
1214 <indexterm zone="pango-layout-get-cursor-pos"><primary sortas="pango_layout_get_cursor_pos">pango_layout_get_cursor_pos</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_get_cursor_pos (<link linkend="PangoLayout">PangoLayout</link> *layout,
1215 <link linkend="int">int</link> index_,
1216 <link linkend="PangoRectangle">PangoRectangle</link> *strong_pos,
1217 <link linkend="PangoRectangle">PangoRectangle</link> *weak_pos);</programlisting>
1219 Given an index within a layout, determines the positions that of the
1220 strong and weak cursors if the insertion point is at that
1221 index. The position of each cursor is stored as a zero-width
1222 rectangle. The strong cursor location is the location where
1223 characters of the directionality equal to the base direction of the
1224 layout are inserted. The weak cursor location is the location
1225 where characters of the directionality opposite to the base
1226 direction of the layout are inserted.</para>
1228 </para><variablelist role="params">
1229 <varlistentry><term><parameter>layout</parameter> :</term>
1230 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1231 </simpara></listitem></varlistentry>
1232 <varlistentry><term><parameter>index_</parameter> :</term>
1233 <listitem><simpara> the byte index of the cursor
1234 </simpara></listitem></varlistentry>
1235 <varlistentry><term><parameter>strong_pos</parameter> :</term>
1236 <listitem><simpara> location to store the strong cursor position (may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>)
1237 </simpara></listitem></varlistentry>
1238 <varlistentry><term><parameter>weak_pos</parameter> :</term>
1239 <listitem><simpara> location to store the weak cursor position (may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>)
1240 </simpara></listitem></varlistentry>
1241 </variablelist></refsect2>
1242 <refsect2 id="pango-layout-move-cursor-visually" role="function">
1243 <title>pango_layout_move_cursor_visually ()</title>
1244 <indexterm zone="pango-layout-move-cursor-visually"><primary sortas="pango_layout_move_cursor_visually">pango_layout_move_cursor_visually</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_move_cursor_visually (<link linkend="PangoLayout">PangoLayout</link> *layout,
1245 <link linkend="gboolean">gboolean</link> strong,
1246 <link linkend="int">int</link> old_index,
1247 <link linkend="int">int</link> old_trailing,
1248 <link linkend="int">int</link> direction,
1249 <link linkend="int">int</link> *new_index,
1250 <link linkend="int">int</link> *new_trailing);</programlisting>
1252 Computes a new cursor position from an old position and
1253 a count of positions to move visually. If <parameter>direction</parameter> is positive,
1254 then the new strong cursor position will be one position
1255 to the right of the old cursor position. If <parameter>direction</parameter> is negative,
1256 then the new strong cursor position will be one position
1257 to the left of the old cursor position.
1260 In the presence of bidirectional text, the correspondence
1261 between logical and visual order will depend on the direction
1262 of the current run, and there may be jumps when the cursor
1263 is moved off of the end of a run.
1266 Motion here is in cursor positions, not in characters, so a
1267 single call to <link linkend="pango-layout-move-cursor-visually"><function>pango_layout_move_cursor_visually()</function></link> may move the
1268 cursor over multiple characters when multiple characters combine
1269 to form a single grapheme.</para>
1271 </para><variablelist role="params">
1272 <varlistentry><term><parameter>layout</parameter> :</term>
1273 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>.
1274 </simpara></listitem></varlistentry>
1275 <varlistentry><term><parameter>strong</parameter> :</term>
1276 <listitem><simpara> whether the moving cursor is the strong cursor or the
1277 weak cursor. The strong cursor is the cursor corresponding
1278 to text insertion in the base direction for the layout.
1279 </simpara></listitem></varlistentry>
1280 <varlistentry><term><parameter>old_index</parameter> :</term>
1281 <listitem><simpara> the byte index of the grapheme for the old index
1282 </simpara></listitem></varlistentry>
1283 <varlistentry><term><parameter>old_trailing</parameter> :</term>
1284 <listitem><simpara> if 0, the cursor was at the trailing edge of the
1285 grapheme indicated by <parameter>old_index</parameter>, if > 0, the cursor
1286 was at the leading edge.
1287 </simpara></listitem></varlistentry>
1288 <varlistentry><term><parameter>direction</parameter> :</term>
1289 <listitem><simpara> direction to move cursor. A negative
1290 value indicates motion to the left.
1291 </simpara></listitem></varlistentry>
1292 <varlistentry><term><parameter>new_index</parameter> :</term>
1293 <listitem><simpara> location to store the new cursor byte index. A value of -1
1294 indicates that the cursor has been moved off the beginning
1295 of the layout. A value of <link linkend="G-MAXINT--CAPS"><literal>G_MAXINT</literal></link> indicates that
1296 the cursor has been moved off the end of the layout.
1297 </simpara></listitem></varlistentry>
1298 <varlistentry><term><parameter>new_trailing</parameter> :</term>
1299 <listitem><simpara> number of characters to move forward from the location returned
1300 for <parameter>new_index</parameter> to get the position where the cursor should
1301 be displayed. This allows distinguishing the position at
1302 the beginning of one line from the position at the end
1303 of the preceding line. <parameter>new_index</parameter> is always on the line
1304 where the cursor should be displayed.
1305 </simpara></listitem></varlistentry>
1306 </variablelist></refsect2>
1307 <refsect2 id="pango-layout-get-extents" role="function">
1308 <title>pango_layout_get_extents ()</title>
1309 <indexterm zone="pango-layout-get-extents"><primary sortas="pango_layout_get_extents">pango_layout_get_extents</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_get_extents (<link linkend="PangoLayout">PangoLayout</link> *layout,
1310 <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
1311 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);</programlisting>
1313 Computes the logical and ink extents of <parameter>layout</parameter>. Logical extents
1314 are usually what you want for positioning things. Note that both extents
1315 may have non-zero x and y. You may want to use those to offset where you
1316 render the layout. Not doing that is a very typical bug that shows up as
1317 right-to-left layouts not being correctly positioned in a layout with
1321 The extents are given in layout coordinates and in Pango units; layout
1322 coordinates begin at the top left corner of the layout.</para>
1324 </para><variablelist role="params">
1325 <varlistentry><term><parameter>layout</parameter> :</term>
1326 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1327 </simpara></listitem></varlistentry>
1328 <varlistentry><term><parameter>ink_rect</parameter> :</term>
1329 <listitem><simpara> rectangle used to store the extents of the layout as drawn
1330 or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to indicate that the result is not needed.
1331 </simpara></listitem></varlistentry>
1332 <varlistentry><term><parameter>logical_rect</parameter> :</term>
1333 <listitem><simpara> rectangle used to store the logical extents of the layout
1334 or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to indicate that the result is not needed.
1335 </simpara></listitem></varlistentry>
1336 </variablelist></refsect2>
1337 <refsect2 id="pango-layout-get-pixel-extents" role="function">
1338 <title>pango_layout_get_pixel_extents ()</title>
1339 <indexterm zone="pango-layout-get-pixel-extents"><primary sortas="pango_layout_get_pixel_extents">pango_layout_get_pixel_extents</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_get_pixel_extents (<link linkend="PangoLayout">PangoLayout</link> *layout,
1340 <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
1341 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);</programlisting>
1343 Computes the logical and ink extents of <parameter>layout</parameter> in device units.
1344 This function just calls <link linkend="pango-layout-get-extents"><function>pango_layout_get_extents()</function></link> followed by
1345 two <link linkend="pango-extents-to-pixels"><function>pango_extents_to_pixels()</function></link> calls, rounding <parameter>ink_rect</parameter> and <parameter>logical_rect</parameter>
1346 such that the rounded rectangles fully contain the unrounded one (that is,
1347 passes them as first argument to <link linkend="pango-extents-to-pixels"><function>pango_extents_to_pixels()</function></link>).</para>
1349 </para><variablelist role="params">
1350 <varlistentry><term><parameter>layout</parameter> :</term>
1351 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1352 </simpara></listitem></varlistentry>
1353 <varlistentry><term><parameter>ink_rect</parameter> :</term>
1354 <listitem><simpara> rectangle used to store the extents of the layout as drawn
1355 or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to indicate that the result is not needed.
1356 </simpara></listitem></varlistentry>
1357 <varlistentry><term><parameter>logical_rect</parameter> :</term>
1358 <listitem><simpara> rectangle used to store the logical extents of the
1359 layout or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to indicate that the result is not needed.
1360 </simpara></listitem></varlistentry>
1361 </variablelist></refsect2>
1362 <refsect2 id="pango-layout-get-size" role="function">
1363 <title>pango_layout_get_size ()</title>
1364 <indexterm zone="pango-layout-get-size"><primary sortas="pango_layout_get_size">pango_layout_get_size</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_get_size (<link linkend="PangoLayout">PangoLayout</link> *layout,
1365 <link linkend="int">int</link> *width,
1366 <link linkend="int">int</link> *height);</programlisting>
1368 Determines the logical width and height of a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1369 in Pango units (device units scaled by <link linkend="PANGO-SCALE--CAPS"><literal>PANGO_SCALE</literal></link>). This
1370 is simply a convenience function around <link linkend="pango-layout-get-extents"><function>pango_layout_get_extents()</function></link>.</para>
1372 </para><variablelist role="params">
1373 <varlistentry><term><parameter>layout</parameter> :</term>
1374 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1375 </simpara></listitem></varlistentry>
1376 <varlistentry><term><parameter>width</parameter> :</term>
1377 <listitem><simpara> location to store the logical width, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1378 </simpara></listitem></varlistentry>
1379 <varlistentry><term><parameter>height</parameter> :</term>
1380 <listitem><simpara> location to store the logical height, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1381 </simpara></listitem></varlistentry>
1382 </variablelist></refsect2>
1383 <refsect2 id="pango-layout-get-pixel-size" role="function">
1384 <title>pango_layout_get_pixel_size ()</title>
1385 <indexterm zone="pango-layout-get-pixel-size"><primary sortas="pango_layout_get_pixel_size">pango_layout_get_pixel_size</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_get_pixel_size (<link linkend="PangoLayout">PangoLayout</link> *layout,
1386 <link linkend="int">int</link> *width,
1387 <link linkend="int">int</link> *height);</programlisting>
1389 Determines the logical width and height of a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1390 in device units. (<link linkend="pango-layout-get-size"><function>pango_layout_get_size()</function></link> returns the width
1391 and height scaled by <link linkend="PANGO-SCALE--CAPS"><literal>PANGO_SCALE</literal></link>.) This
1392 is simply a convenience function around
1393 <link linkend="pango-layout-get-pixel-extents"><function>pango_layout_get_pixel_extents()</function></link>.</para>
1395 </para><variablelist role="params">
1396 <varlistentry><term><parameter>layout</parameter> :</term>
1397 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1398 </simpara></listitem></varlistentry>
1399 <varlistentry><term><parameter>width</parameter> :</term>
1400 <listitem><simpara> location to store the logical width, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1401 </simpara></listitem></varlistentry>
1402 <varlistentry><term><parameter>height</parameter> :</term>
1403 <listitem><simpara> location to store the logical height, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1404 </simpara></listitem></varlistentry>
1405 </variablelist></refsect2>
1406 <refsect2 id="pango-layout-get-baseline" role="function" condition="since:1.22">
1407 <title>pango_layout_get_baseline ()</title>
1408 <indexterm zone="pango-layout-get-baseline" role="1.22"><primary sortas="pango_layout_get_baseline">pango_layout_get_baseline</primary></indexterm><programlisting><link linkend="int">int</link> pango_layout_get_baseline (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
1410 Gets the Y position of baseline of the first line in <parameter>layout</parameter>.</para>
1412 </para><variablelist role="params">
1413 <varlistentry><term><parameter>layout</parameter> :</term>
1414 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1415 </simpara></listitem></varlistentry>
1416 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> baseline of first line, from top of <parameter>layout</parameter>.
1418 </simpara></listitem></varlistentry>
1419 </variablelist><para role="since">Since 1.22</para></refsect2>
1420 <refsect2 id="pango-layout-get-line-count" role="function">
1421 <title>pango_layout_get_line_count ()</title>
1422 <indexterm zone="pango-layout-get-line-count"><primary sortas="pango_layout_get_line_count">pango_layout_get_line_count</primary></indexterm><programlisting><link linkend="int">int</link> pango_layout_get_line_count (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
1424 Retrieves the count of lines for the <parameter>layout</parameter>.</para>
1426 </para><variablelist role="params">
1427 <varlistentry><term><parameter>layout</parameter> :</term>
1428 <listitem><simpara> <link linkend="PangoLayout"><type>PangoLayout</type></link>
1429 </simpara></listitem></varlistentry>
1430 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the line count.
1431 </simpara></listitem></varlistentry>
1432 </variablelist></refsect2>
1433 <refsect2 id="pango-layout-get-line" role="function">
1434 <title>pango_layout_get_line ()</title>
1435 <indexterm zone="pango-layout-get-line"><primary sortas="pango_layout_get_line">pango_layout_get_line</primary></indexterm><programlisting><link linkend="PangoLayoutLine">PangoLayoutLine</link> * pango_layout_get_line (<link linkend="PangoLayout">PangoLayout</link> *layout,
1436 <link linkend="int">int</link> line);</programlisting>
1438 Retrieves a particular line from a <link linkend="PangoLayout"><type>PangoLayout</type></link>.
1441 Use the faster <link linkend="pango-layout-get-line-readonly"><function>pango_layout_get_line_readonly()</function></link> if you do not plan
1442 to modify the contents of the line (glyphs, glyph widths, etc.).</para>
1444 </para><variablelist role="params">
1445 <varlistentry><term><parameter>layout</parameter> :</term>
1446 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1447 </simpara></listitem></varlistentry>
1448 <varlistentry><term><parameter>line</parameter> :</term>
1449 <listitem><simpara> the index of a line, which must be between 0 and
1450 <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive.
1451 </simpara></listitem></varlistentry>
1452 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the requested <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the
1453 index is out of range. This layout line can
1454 be ref'ed and retained, but will become invalid
1455 if changes are made to the <link linkend="PangoLayout"><type>PangoLayout</type></link>.
1456 </simpara></listitem></varlistentry>
1457 </variablelist></refsect2>
1458 <refsect2 id="pango-layout-get-line-readonly" role="function" condition="since:1.16">
1459 <title>pango_layout_get_line_readonly ()</title>
1460 <indexterm zone="pango-layout-get-line-readonly" role="1.16"><primary sortas="pango_layout_get_line_readonly">pango_layout_get_line_readonly</primary></indexterm><programlisting><link linkend="PangoLayoutLine">PangoLayoutLine</link> * pango_layout_get_line_readonly (<link linkend="PangoLayout">PangoLayout</link> *layout,
1461 <link linkend="int">int</link> line);</programlisting>
1463 Retrieves a particular line from a <link linkend="PangoLayout"><type>PangoLayout</type></link>.
1466 This is a faster alternative to <link linkend="pango-layout-get-line"><function>pango_layout_get_line()</function></link>,
1467 but the user is not expected
1468 to modify the contents of the line (glyphs, glyph widths, etc.).</para>
1470 </para><variablelist role="params">
1471 <varlistentry><term><parameter>layout</parameter> :</term>
1472 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1473 </simpara></listitem></varlistentry>
1474 <varlistentry><term><parameter>line</parameter> :</term>
1475 <listitem><simpara> the index of a line, which must be between 0 and
1476 <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive.
1477 </simpara></listitem></varlistentry>
1478 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the requested <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the
1479 index is out of range. This layout line can
1480 be ref'ed and retained, but will become invalid
1481 if changes are made to the <link linkend="PangoLayout"><type>PangoLayout</type></link>.
1482 No changes should be made to the line.
1484 </simpara></listitem></varlistentry>
1485 </variablelist><para role="since">Since 1.16</para></refsect2>
1486 <refsect2 id="pango-layout-get-lines" role="function">
1487 <title>pango_layout_get_lines ()</title>
1488 <indexterm zone="pango-layout-get-lines"><primary sortas="pango_layout_get_lines">pango_layout_get_lines</primary></indexterm><programlisting><link linkend="GSList">GSList</link> * pango_layout_get_lines (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
1490 Returns the lines of the <parameter>layout</parameter> as a list.
1493 Use the faster <link linkend="pango-layout-get-lines-readonly"><function>pango_layout_get_lines_readonly()</function></link> if you do not plan
1494 to modify the contents of the lines (glyphs, glyph widths, etc.).</para>
1496 </para><variablelist role="params">
1497 <varlistentry><term><parameter>layout</parameter> :</term>
1498 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1499 </simpara></listitem></varlistentry>
1500 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>element-type Pango.LayoutLine): (transfer none. <acronym>element-type Pango.LayoutLine): (transfer</acronym> none. </simpara></listitem></varlistentry>
1501 </variablelist></refsect2>
1502 <refsect2 id="pango-layout-get-lines-readonly" role="function" condition="since:1.16">
1503 <title>pango_layout_get_lines_readonly ()</title>
1504 <indexterm zone="pango-layout-get-lines-readonly" role="1.16"><primary sortas="pango_layout_get_lines_readonly">pango_layout_get_lines_readonly</primary></indexterm><programlisting><link linkend="GSList">GSList</link> * pango_layout_get_lines_readonly (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
1506 Returns the lines of the <parameter>layout</parameter> as a list.
1509 This is a faster alternative to <link linkend="pango-layout-get-lines"><function>pango_layout_get_lines()</function></link>,
1510 but the user is not expected
1511 to modify the contents of the lines (glyphs, glyph widths, etc.).</para>
1513 </para><variablelist role="params">
1514 <varlistentry><term><parameter>layout</parameter> :</term>
1515 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1516 </simpara></listitem></varlistentry>
1517 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>element-type Pango.LayoutLine): (transfer none. <acronym>element-type Pango.LayoutLine): (transfer</acronym> none. </simpara></listitem></varlistentry>
1518 </variablelist><para role="since">Since 1.16</para></refsect2>
1519 <refsect2 id="pango-layout-get-iter" role="function">
1520 <title>pango_layout_get_iter ()</title>
1521 <indexterm zone="pango-layout-get-iter"><primary sortas="pango_layout_get_iter">pango_layout_get_iter</primary></indexterm><programlisting><link linkend="PangoLayoutIter">PangoLayoutIter</link> * pango_layout_get_iter (<link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
1523 Returns an iterator to iterate over the visual extents of the layout.</para>
1525 </para><variablelist role="params">
1526 <varlistentry><term><parameter>layout</parameter> :</term>
1527 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>
1528 </simpara></listitem></varlistentry>
1529 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the new <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link> that should be freed using
1530 <link linkend="pango-layout-iter-free"><function>pango_layout_iter_free()</function></link>.
1531 </simpara></listitem></varlistentry>
1532 </variablelist></refsect2>
1533 <refsect2 id="pango-layout-iter-copy" role="function" condition="since:1.20">
1534 <title>pango_layout_iter_copy ()</title>
1535 <indexterm zone="pango-layout-iter-copy" role="1.20"><primary sortas="pango_layout_iter_copy">pango_layout_iter_copy</primary></indexterm><programlisting><link linkend="PangoLayoutIter">PangoLayoutIter</link> * pango_layout_iter_copy (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);</programlisting>
1537 Copies a <link linkend="PangLayoutIter"><type>PangLayoutIter</type></link>.</para>
1539 </para><variablelist role="params">
1540 <varlistentry><term><parameter>iter</parameter> :</term>
1541 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>, may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1542 </simpara></listitem></varlistentry>
1543 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the newly allocated <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>, which should
1544 be freed with <link linkend="pango-layout-iter-free"><function>pango_layout_iter_free()</function></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if
1545 <parameter>iter</parameter> was <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
1547 </simpara></listitem></varlistentry>
1548 </variablelist><para role="since">Since 1.20</para></refsect2>
1549 <refsect2 id="pango-layout-iter-free" role="function">
1550 <title>pango_layout_iter_free ()</title>
1551 <indexterm zone="pango-layout-iter-free"><primary sortas="pango_layout_iter_free">pango_layout_iter_free</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_iter_free (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);</programlisting>
1553 Frees an iterator that's no longer in use.</para>
1555 </para><variablelist role="params">
1556 <varlistentry><term><parameter>iter</parameter> :</term>
1557 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>, may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1558 </simpara></listitem></varlistentry>
1559 </variablelist></refsect2>
1560 <refsect2 id="pango-layout-iter-next-run" role="function">
1561 <title>pango_layout_iter_next_run ()</title>
1562 <indexterm zone="pango-layout-iter-next-run"><primary sortas="pango_layout_iter_next_run">pango_layout_iter_next_run</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> pango_layout_iter_next_run (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);</programlisting>
1564 Moves <parameter>iter</parameter> forward to the next run in visual order. If <parameter>iter</parameter> was
1565 already at the end of the layout, returns <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>.</para>
1567 </para><variablelist role="params">
1568 <varlistentry><term><parameter>iter</parameter> :</term>
1569 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1570 </simpara></listitem></varlistentry>
1571 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> whether motion was possible.
1572 </simpara></listitem></varlistentry>
1573 </variablelist></refsect2>
1574 <refsect2 id="pango-layout-iter-next-char" role="function">
1575 <title>pango_layout_iter_next_char ()</title>
1576 <indexterm zone="pango-layout-iter-next-char"><primary sortas="pango_layout_iter_next_char">pango_layout_iter_next_char</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> pango_layout_iter_next_char (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);</programlisting>
1578 Moves <parameter>iter</parameter> forward to the next character in visual order. If <parameter>iter</parameter> was already at
1579 the end of the layout, returns <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>.</para>
1581 </para><variablelist role="params">
1582 <varlistentry><term><parameter>iter</parameter> :</term>
1583 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1584 </simpara></listitem></varlistentry>
1585 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> whether motion was possible.
1586 </simpara></listitem></varlistentry>
1587 </variablelist></refsect2>
1588 <refsect2 id="pango-layout-iter-next-cluster" role="function">
1589 <title>pango_layout_iter_next_cluster ()</title>
1590 <indexterm zone="pango-layout-iter-next-cluster"><primary sortas="pango_layout_iter_next_cluster">pango_layout_iter_next_cluster</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> pango_layout_iter_next_cluster (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);</programlisting>
1592 Moves <parameter>iter</parameter> forward to the next cluster in visual order. If <parameter>iter</parameter>
1593 was already at the end of the layout, returns <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>.</para>
1595 </para><variablelist role="params">
1596 <varlistentry><term><parameter>iter</parameter> :</term>
1597 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1598 </simpara></listitem></varlistentry>
1599 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> whether motion was possible.
1600 </simpara></listitem></varlistentry>
1601 </variablelist></refsect2>
1602 <refsect2 id="pango-layout-iter-next-line" role="function">
1603 <title>pango_layout_iter_next_line ()</title>
1604 <indexterm zone="pango-layout-iter-next-line"><primary sortas="pango_layout_iter_next_line">pango_layout_iter_next_line</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> pango_layout_iter_next_line (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);</programlisting>
1606 Moves <parameter>iter</parameter> forward to the start of the next line. If <parameter>iter</parameter> is
1607 already on the last line, returns <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>.</para>
1609 </para><variablelist role="params">
1610 <varlistentry><term><parameter>iter</parameter> :</term>
1611 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1612 </simpara></listitem></varlistentry>
1613 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> whether motion was possible.
1614 </simpara></listitem></varlistentry>
1615 </variablelist></refsect2>
1616 <refsect2 id="pango-layout-iter-at-last-line" role="function">
1617 <title>pango_layout_iter_at_last_line ()</title>
1618 <indexterm zone="pango-layout-iter-at-last-line"><primary sortas="pango_layout_iter_at_last_line">pango_layout_iter_at_last_line</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> pango_layout_iter_at_last_line (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);</programlisting>
1620 Determines whether <parameter>iter</parameter> is on the last line of the layout.</para>
1622 </para><variablelist role="params">
1623 <varlistentry><term><parameter>iter</parameter> :</term>
1624 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1625 </simpara></listitem></varlistentry>
1626 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>iter</parameter> is on the last line.
1627 </simpara></listitem></varlistentry>
1628 </variablelist></refsect2>
1629 <refsect2 id="pango-layout-iter-get-index" role="function">
1630 <title>pango_layout_iter_get_index ()</title>
1631 <indexterm zone="pango-layout-iter-get-index"><primary sortas="pango_layout_iter_get_index">pango_layout_iter_get_index</primary></indexterm><programlisting><link linkend="int">int</link> pango_layout_iter_get_index (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);</programlisting>
1633 Gets the current byte index. Note that iterating forward by char
1634 moves in visual order, not logical order, so indexes may not be
1635 sequential. Also, the index may be equal to the length of the text
1636 in the layout, if on the <link linkend="NULL--CAPS"><literal>NULL</literal></link> run (see <link linkend="pango-layout-iter-get-run"><function>pango_layout_iter_get_run()</function></link>).</para>
1638 </para><variablelist role="params">
1639 <varlistentry><term><parameter>iter</parameter> :</term>
1640 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1641 </simpara></listitem></varlistentry>
1642 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> current byte index.
1643 </simpara></listitem></varlistentry>
1644 </variablelist></refsect2>
1645 <refsect2 id="pango-layout-iter-get-baseline" role="function">
1646 <title>pango_layout_iter_get_baseline ()</title>
1647 <indexterm zone="pango-layout-iter-get-baseline"><primary sortas="pango_layout_iter_get_baseline">pango_layout_iter_get_baseline</primary></indexterm><programlisting><link linkend="int">int</link> pango_layout_iter_get_baseline (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);</programlisting>
1649 Gets the Y position of the current line's baseline, in layout
1650 coordinates (origin at top left of the entire layout).</para>
1652 </para><variablelist role="params">
1653 <varlistentry><term><parameter>iter</parameter> :</term>
1654 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1655 </simpara></listitem></varlistentry>
1656 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> baseline of current line.
1657 </simpara></listitem></varlistentry>
1658 </variablelist></refsect2>
1659 <refsect2 id="pango-layout-iter-get-run" role="function">
1660 <title>pango_layout_iter_get_run ()</title>
1661 <indexterm zone="pango-layout-iter-get-run"><primary sortas="pango_layout_iter_get_run">pango_layout_iter_get_run</primary></indexterm><programlisting><link linkend="PangoLayoutRun">PangoLayoutRun</link> * pango_layout_iter_get_run (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);</programlisting>
1663 Gets the current run. When iterating by run, at the end of each
1664 line, there's a position with a <link linkend="NULL--CAPS"><literal>NULL</literal></link> run, so this function can return
1665 <link linkend="NULL--CAPS"><literal>NULL</literal></link>. The <link linkend="NULL--CAPS"><literal>NULL</literal></link> run at the end of each line ensures that all lines have
1666 at least one run, even lines consisting of only a newline.
1669 Use the faster <link linkend="pango-layout-iter-get-run-readonly"><function>pango_layout_iter_get_run_readonly()</function></link> if you do not plan
1670 to modify the contents of the run (glyphs, glyph widths, etc.).</para>
1672 </para><variablelist role="params">
1673 <varlistentry><term><parameter>iter</parameter> :</term>
1674 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1675 </simpara></listitem></varlistentry>
1676 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the current run.
1677 </simpara></listitem></varlistentry>
1678 </variablelist></refsect2>
1679 <refsect2 id="pango-layout-iter-get-run-readonly" role="function" condition="since:1.16">
1680 <title>pango_layout_iter_get_run_readonly ()</title>
1681 <indexterm zone="pango-layout-iter-get-run-readonly" role="1.16"><primary sortas="pango_layout_iter_get_run_readonly">pango_layout_iter_get_run_readonly</primary></indexterm><programlisting><link linkend="PangoLayoutRun">PangoLayoutRun</link> * pango_layout_iter_get_run_readonly (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);</programlisting>
1683 Gets the current run. When iterating by run, at the end of each
1684 line, there's a position with a <link linkend="NULL--CAPS"><literal>NULL</literal></link> run, so this function can return
1685 <link linkend="NULL--CAPS"><literal>NULL</literal></link>. The <link linkend="NULL--CAPS"><literal>NULL</literal></link> run at the end of each line ensures that all lines have
1686 at least one run, even lines consisting of only a newline.
1689 This is a faster alternative to <link linkend="pango-layout-iter-get-run"><function>pango_layout_iter_get_run()</function></link>,
1690 but the user is not expected
1691 to modify the contents of the run (glyphs, glyph widths, etc.).</para>
1693 </para><variablelist role="params">
1694 <varlistentry><term><parameter>iter</parameter> :</term>
1695 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1696 </simpara></listitem></varlistentry>
1697 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the current run, that should not be modified.
1699 </simpara></listitem></varlistentry>
1700 </variablelist><para role="since">Since 1.16</para></refsect2>
1701 <refsect2 id="pango-layout-iter-get-line" role="function">
1702 <title>pango_layout_iter_get_line ()</title>
1703 <indexterm zone="pango-layout-iter-get-line"><primary sortas="pango_layout_iter_get_line">pango_layout_iter_get_line</primary></indexterm><programlisting><link linkend="PangoLayoutLine">PangoLayoutLine</link> * pango_layout_iter_get_line (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);</programlisting>
1705 Gets the current line.
1708 Use the faster <link linkend="pango-layout-iter-get-line-readonly"><function>pango_layout_iter_get_line_readonly()</function></link> if you do not plan
1709 to modify the contents of the line (glyphs, glyph widths, etc.).</para>
1711 </para><variablelist role="params">
1712 <varlistentry><term><parameter>iter</parameter> :</term>
1713 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1714 </simpara></listitem></varlistentry>
1715 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the current line.
1716 </simpara></listitem></varlistentry>
1717 </variablelist></refsect2>
1718 <refsect2 id="pango-layout-iter-get-line-readonly" role="function" condition="since:1.16">
1719 <title>pango_layout_iter_get_line_readonly ()</title>
1720 <indexterm zone="pango-layout-iter-get-line-readonly" role="1.16"><primary sortas="pango_layout_iter_get_line_readonly">pango_layout_iter_get_line_readonly</primary></indexterm><programlisting><link linkend="PangoLayoutLine">PangoLayoutLine</link> * pango_layout_iter_get_line_readonly (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);</programlisting>
1722 Gets the current line for read-only access.
1725 This is a faster alternative to <link linkend="pango-layout-iter-get-line"><function>pango_layout_iter_get_line()</function></link>,
1726 but the user is not expected
1727 to modify the contents of the line (glyphs, glyph widths, etc.).</para>
1729 </para><variablelist role="params">
1730 <varlistentry><term><parameter>iter</parameter> :</term>
1731 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1732 </simpara></listitem></varlistentry>
1733 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the current line, that should not be modified.
1735 </simpara></listitem></varlistentry>
1736 </variablelist><para role="since">Since 1.16</para></refsect2>
1737 <refsect2 id="pango-layout-iter-get-layout" role="function" condition="since:1.20">
1738 <title>pango_layout_iter_get_layout ()</title>
1739 <indexterm zone="pango-layout-iter-get-layout" role="1.20"><primary sortas="pango_layout_iter_get_layout">pango_layout_iter_get_layout</primary></indexterm><programlisting><link linkend="PangoLayout">PangoLayout</link> * pango_layout_iter_get_layout (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter);</programlisting>
1741 Gets the layout associated with a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>.</para>
1743 </para><variablelist role="params">
1744 <varlistentry><term><parameter>iter</parameter> :</term>
1745 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1746 </simpara></listitem></varlistentry>
1747 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the layout associated with <parameter>iter</parameter>.
1749 </simpara></listitem></varlistentry>
1750 </variablelist><para role="since">Since 1.20</para></refsect2>
1751 <refsect2 id="pango-layout-iter-get-char-extents" role="function">
1752 <title>pango_layout_iter_get_char_extents ()</title>
1753 <indexterm zone="pango-layout-iter-get-char-extents"><primary sortas="pango_layout_iter_get_char_extents">pango_layout_iter_get_char_extents</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_iter_get_char_extents (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter,
1754 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);</programlisting>
1756 Gets the extents of the current character, in layout coordinates
1757 (origin is the top left of the entire layout). Only logical extents
1758 can sensibly be obtained for characters; ink extents make sense only
1759 down to the level of clusters.</para>
1761 </para><variablelist role="params">
1762 <varlistentry><term><parameter>iter</parameter> :</term>
1763 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1764 </simpara></listitem></varlistentry>
1765 <varlistentry><term><parameter>logical_rect</parameter> :</term>
1766 <listitem><simpara> rectangle to fill with logical extents
1767 </simpara></listitem></varlistentry>
1768 </variablelist></refsect2>
1769 <refsect2 id="pango-layout-iter-get-cluster-extents" role="function">
1770 <title>pango_layout_iter_get_cluster_extents ()</title>
1771 <indexterm zone="pango-layout-iter-get-cluster-extents"><primary sortas="pango_layout_iter_get_cluster_extents">pango_layout_iter_get_cluster_extents</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_iter_get_cluster_extents
1772 (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter,
1773 <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
1774 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);</programlisting>
1776 Gets the extents of the current cluster, in layout coordinates
1777 (origin is the top left of the entire layout).</para>
1779 </para><variablelist role="params">
1780 <varlistentry><term><parameter>iter</parameter> :</term>
1781 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1782 </simpara></listitem></varlistentry>
1783 <varlistentry><term><parameter>ink_rect</parameter> :</term>
1784 <listitem><simpara> rectangle to fill with ink extents, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1785 </simpara></listitem></varlistentry>
1786 <varlistentry><term><parameter>logical_rect</parameter> :</term>
1787 <listitem><simpara> rectangle to fill with logical extents, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1788 </simpara></listitem></varlistentry>
1789 </variablelist></refsect2>
1790 <refsect2 id="pango-layout-iter-get-run-extents" role="function">
1791 <title>pango_layout_iter_get_run_extents ()</title>
1792 <indexterm zone="pango-layout-iter-get-run-extents"><primary sortas="pango_layout_iter_get_run_extents">pango_layout_iter_get_run_extents</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_iter_get_run_extents (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter,
1793 <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
1794 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);</programlisting>
1796 Gets the extents of the current run in layout coordinates
1797 (origin is the top left of the entire layout).</para>
1799 </para><variablelist role="params">
1800 <varlistentry><term><parameter>iter</parameter> :</term>
1801 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1802 </simpara></listitem></varlistentry>
1803 <varlistentry><term><parameter>ink_rect</parameter> :</term>
1804 <listitem><simpara> rectangle to fill with ink extents, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1805 </simpara></listitem></varlistentry>
1806 <varlistentry><term><parameter>logical_rect</parameter> :</term>
1807 <listitem><simpara> rectangle to fill with logical extents, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1808 </simpara></listitem></varlistentry>
1809 </variablelist></refsect2>
1810 <refsect2 id="pango-layout-iter-get-line-yrange" role="function">
1811 <title>pango_layout_iter_get_line_yrange ()</title>
1812 <indexterm zone="pango-layout-iter-get-line-yrange"><primary sortas="pango_layout_iter_get_line_yrange">pango_layout_iter_get_line_yrange</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_iter_get_line_yrange (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter,
1813 <link linkend="int">int</link> *y0_,
1814 <link linkend="int">int</link> *y1_);</programlisting>
1816 Divides the vertical space in the <link linkend="PangoLayout"><type>PangoLayout</type></link> being iterated over
1817 between the lines in the layout, and returns the space belonging to
1818 the current line. A line's range includes the line's logical
1819 extents, plus half of the spacing above and below the line, if
1820 <link linkend="pango-layout-set-spacing"><function>pango_layout_set_spacing()</function></link> has been called to set layout spacing.
1821 The Y positions are in layout coordinates (origin at top left of the
1822 entire layout).</para>
1824 </para><variablelist role="params">
1825 <varlistentry><term><parameter>iter</parameter> :</term>
1826 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1827 </simpara></listitem></varlistentry>
1828 <varlistentry><term><parameter>y0_</parameter> :</term>
1829 <listitem><simpara> start of line
1830 </simpara></listitem></varlistentry>
1831 <varlistentry><term><parameter>y1_</parameter> :</term>
1832 <listitem><simpara> end of line
1833 </simpara></listitem></varlistentry>
1834 </variablelist></refsect2>
1835 <refsect2 id="pango-layout-iter-get-line-extents" role="function">
1836 <title>pango_layout_iter_get_line_extents ()</title>
1837 <indexterm zone="pango-layout-iter-get-line-extents"><primary sortas="pango_layout_iter_get_line_extents">pango_layout_iter_get_line_extents</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_iter_get_line_extents (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter,
1838 <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
1839 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);</programlisting>
1841 Obtains the extents of the current line. <parameter>ink_rect</parameter> or <parameter>logical_rect</parameter>
1842 can be <link linkend="NULL--CAPS"><literal>NULL</literal></link> if you aren't interested in them. Extents are in layout
1843 coordinates (origin is the top-left corner of the entire
1844 <link linkend="PangoLayout"><type>PangoLayout</type></link>). Thus the extents returned by this function will be
1845 the same width/height but not at the same x/y as the extents
1846 returned from <link linkend="pango-layout-line-get-extents"><function>pango_layout_line_get_extents()</function></link>.</para>
1848 </para><variablelist role="params">
1849 <varlistentry><term><parameter>iter</parameter> :</term>
1850 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1851 </simpara></listitem></varlistentry>
1852 <varlistentry><term><parameter>ink_rect</parameter> :</term>
1853 <listitem><simpara> rectangle to fill with ink extents, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1854 </simpara></listitem></varlistentry>
1855 <varlistentry><term><parameter>logical_rect</parameter> :</term>
1856 <listitem><simpara> rectangle to fill with logical extents, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1857 </simpara></listitem></varlistentry>
1858 </variablelist></refsect2>
1859 <refsect2 id="pango-layout-iter-get-layout-extents" role="function">
1860 <title>pango_layout_iter_get_layout_extents ()</title>
1861 <indexterm zone="pango-layout-iter-get-layout-extents"><primary sortas="pango_layout_iter_get_layout_extents">pango_layout_iter_get_layout_extents</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_iter_get_layout_extents
1862 (<link linkend="PangoLayoutIter">PangoLayoutIter</link> *iter,
1863 <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
1864 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);</programlisting>
1866 Obtains the extents of the <link linkend="PangoLayout"><type>PangoLayout</type></link> being iterated
1867 over. <parameter>ink_rect</parameter> or <parameter>logical_rect</parameter> can be <link linkend="NULL--CAPS"><literal>NULL</literal></link> if you
1868 aren't interested in them.</para>
1870 </para><variablelist role="params">
1871 <varlistentry><term><parameter>iter</parameter> :</term>
1872 <listitem><simpara> a <link linkend="PangoLayoutIter"><type>PangoLayoutIter</type></link>
1873 </simpara></listitem></varlistentry>
1874 <varlistentry><term><parameter>ink_rect</parameter> :</term>
1875 <listitem><simpara> rectangle to fill with ink extents, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1876 </simpara></listitem></varlistentry>
1877 <varlistentry><term><parameter>logical_rect</parameter> :</term>
1878 <listitem><simpara> rectangle to fill with logical extents, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1879 </simpara></listitem></varlistentry>
1880 </variablelist></refsect2>
1881 <refsect2 id="PangoLayoutLine" role="struct">
1882 <title>PangoLayoutLine</title>
1883 <indexterm zone="PangoLayoutLine"><primary sortas="PangoLayoutLine">PangoLayoutLine</primary></indexterm><programlisting>typedef struct {
1884 PangoLayout *layout;
1885 gint start_index; /* start of line as byte index into layout->text */
1886 gint length; /* length of line in bytes */
1888 guint is_paragraph_start : 1; /* TRUE if this is the first line of the paragraph */
1889 guint resolved_dir : 3; /* Resolved PangoDirection of line */
1893 The <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link> structure represents one of the lines resulting
1894 from laying out a paragraph via <link linkend="PangoLayout"><type>PangoLayout</type></link>. <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link>
1895 structures are obtained by calling <link linkend="pango-layout-get-line"><function>pango_layout_get_line()</function></link> and
1896 are only valid until the text, attributes, or settings of the
1897 parent <link linkend="PangoLayout"><type>PangoLayout</type></link> are modified.
1900 Routines for rendering PangoLayout objects are provided in
1901 code specific to each rendering system.
1902 </para><variablelist role="struct">
1904 <term><link linkend="PangoLayout">PangoLayout</link> *<structfield>layout</structfield>;</term>
1905 <listitem><simpara>the parent layout for this line
1906 </simpara></listitem>
1909 <term><link linkend="gint">gint</link> <structfield>start_index</structfield>;</term>
1910 <listitem><simpara>the start of the line as byte index into <parameter>layout->text</parameter>
1911 </simpara></listitem>
1914 <term><link linkend="gint">gint</link> <structfield>length</structfield>;</term>
1915 <listitem><simpara>the length of the line in bytes
1916 </simpara></listitem>
1919 <term><link linkend="GSList">GSList</link> *<structfield>runs</structfield>;</term>
1920 <listitem><simpara>a list containing the runs of the line in visual order
1921 </simpara></listitem>
1924 <term><link linkend="guint">guint</link> <structfield>is_paragraph_start</structfield> : 1;</term>
1925 <listitem><simpara>%TRUE if this is the first line of the paragraph
1926 </simpara></listitem>
1929 <term><link linkend="guint">guint</link> <structfield>resolved_dir</structfield> : 3;</term>
1930 <listitem><simpara>the resolved <link linkend="PangoDirection"><type>PangoDirection</type></link> of the line
1931 </simpara></listitem>
1933 </variablelist></refsect2>
1934 <refsect2 id="PangoLayoutRun" role="typedef">
1935 <title>PangoLayoutRun</title>
1936 <indexterm zone="PangoLayoutRun"><primary sortas="PangoLayoutRun">PangoLayoutRun</primary></indexterm><programlisting>typedef PangoGlyphItem PangoLayoutRun;
1939 The <link linkend="PangoLayoutRun"><type>PangoLayoutRun</type></link> structure represents a single run within
1940 a <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link>; it is simply an alternate name for
1941 <link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link>.
1942 See the <link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link> docs for details on the fields.
1944 <refsect2 id="pango-layout-line-ref" role="function" condition="since:1.10">
1945 <title>pango_layout_line_ref ()</title>
1946 <indexterm zone="pango-layout-line-ref" role="1.10"><primary sortas="pango_layout_line_ref">pango_layout_line_ref</primary></indexterm><programlisting><link linkend="PangoLayoutLine">PangoLayoutLine</link> * pango_layout_line_ref (<link linkend="PangoLayoutLine">PangoLayoutLine</link> *line);</programlisting>
1948 Increase the reference count of a <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link> by one.</para>
1950 </para><variablelist role="params">
1951 <varlistentry><term><parameter>line</parameter> :</term>
1952 <listitem><simpara> a <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link>, may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1953 </simpara></listitem></varlistentry>
1954 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the line passed in.
1956 </simpara></listitem></varlistentry>
1957 </variablelist><para role="since">Since 1.10</para></refsect2>
1958 <refsect2 id="pango-layout-line-unref" role="function">
1959 <title>pango_layout_line_unref ()</title>
1960 <indexterm zone="pango-layout-line-unref"><primary sortas="pango_layout_line_unref">pango_layout_line_unref</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_line_unref (<link linkend="PangoLayoutLine">PangoLayoutLine</link> *line);</programlisting>
1962 Decrease the reference count of a <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link> by one.
1963 If the result is zero, the line and all associated memory
1964 will be freed.</para>
1966 </para><variablelist role="params">
1967 <varlistentry><term><parameter>line</parameter> :</term>
1968 <listitem><simpara> a <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link>
1969 </simpara></listitem></varlistentry>
1970 </variablelist></refsect2>
1971 <refsect2 id="pango-layout-line-get-extents" role="function">
1972 <title>pango_layout_line_get_extents ()</title>
1973 <indexterm zone="pango-layout-line-get-extents"><primary sortas="pango_layout_line_get_extents">pango_layout_line_get_extents</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_line_get_extents (<link linkend="PangoLayoutLine">PangoLayoutLine</link> *line,
1974 <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
1975 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);</programlisting>
1977 Computes the logical and ink extents of a layout line. See
1978 <link linkend="pango-font-get-glyph-extents"><function>pango_font_get_glyph_extents()</function></link> for details about the interpretation
1979 of the rectangles.</para>
1981 </para><variablelist role="params">
1982 <varlistentry><term><parameter>line</parameter> :</term>
1983 <listitem><simpara> a <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link>
1984 </simpara></listitem></varlistentry>
1985 <varlistentry><term><parameter>ink_rect</parameter> :</term>
1986 <listitem><simpara> rectangle used to store the extents of the glyph string
1987 as drawn, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1988 </simpara></listitem></varlistentry>
1989 <varlistentry><term><parameter>logical_rect</parameter> :</term>
1990 <listitem><simpara> rectangle used to store the logical extents of the glyph
1991 string, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1992 </simpara></listitem></varlistentry>
1993 </variablelist></refsect2>
1994 <refsect2 id="pango-layout-line-get-pixel-extents" role="function">
1995 <title>pango_layout_line_get_pixel_extents ()</title>
1996 <indexterm zone="pango-layout-line-get-pixel-extents"><primary sortas="pango_layout_line_get_pixel_extents">pango_layout_line_get_pixel_extents</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_line_get_pixel_extents (<link linkend="PangoLayoutLine">PangoLayoutLine</link> *layout_line,
1997 <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
1998 <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);</programlisting>
2000 Computes the logical and ink extents of <parameter>layout_line</parameter> in device units.
2001 This function just calls <link linkend="pango-layout-line-get-extents"><function>pango_layout_line_get_extents()</function></link> followed by
2002 two <link linkend="pango-extents-to-pixels"><function>pango_extents_to_pixels()</function></link> calls, rounding <parameter>ink_rect</parameter> and <parameter>logical_rect</parameter>
2003 such that the rounded rectangles fully contain the unrounded one (that is,
2004 passes them as first argument to <link linkend="pango-extents-to-pixels"><function>pango_extents_to_pixels()</function></link>).</para>
2006 </para><variablelist role="params">
2007 <varlistentry><term><parameter>layout_line</parameter> :</term>
2008 <listitem><simpara> a <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link>
2009 </simpara></listitem></varlistentry>
2010 <varlistentry><term><parameter>ink_rect</parameter> :</term>
2011 <listitem><simpara> rectangle used to store the extents of the glyph string
2012 as drawn, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
2013 </simpara></listitem></varlistentry>
2014 <varlistentry><term><parameter>logical_rect</parameter> :</term>
2015 <listitem><simpara> rectangle used to store the logical extents of the glyph
2016 string, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
2017 </simpara></listitem></varlistentry>
2018 </variablelist></refsect2>
2019 <refsect2 id="pango-layout-line-index-to-x" role="function">
2020 <title>pango_layout_line_index_to_x ()</title>
2021 <indexterm zone="pango-layout-line-index-to-x"><primary sortas="pango_layout_line_index_to_x">pango_layout_line_index_to_x</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_line_index_to_x (<link linkend="PangoLayoutLine">PangoLayoutLine</link> *line,
2022 <link linkend="int">int</link> index_,
2023 <link linkend="gboolean">gboolean</link> trailing,
2024 <link linkend="int">int</link> *x_pos);</programlisting>
2026 Converts an index within a line to a X position.</para>
2028 </para><variablelist role="params">
2029 <varlistentry><term><parameter>line</parameter> :</term>
2030 <listitem><simpara> a <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link>
2031 </simpara></listitem></varlistentry>
2032 <varlistentry><term><parameter>index_</parameter> :</term>
2033 <listitem><simpara> byte offset of a grapheme within the layout
2034 </simpara></listitem></varlistentry>
2035 <varlistentry><term><parameter>trailing</parameter> :</term>
2036 <listitem><simpara> an integer indicating the edge of the grapheme to retrieve
2037 the position of. If > 0, the trailing edge of the grapheme,
2038 if 0, the leading of the grapheme.
2039 </simpara></listitem></varlistentry>
2040 <varlistentry><term><parameter>x_pos</parameter> :</term>
2041 <listitem><simpara> location to store the x_offset (in Pango unit)
2042 </simpara></listitem></varlistentry>
2043 </variablelist></refsect2>
2044 <refsect2 id="pango-layout-line-x-to-index" role="function">
2045 <title>pango_layout_line_x_to_index ()</title>
2046 <indexterm zone="pango-layout-line-x-to-index"><primary sortas="pango_layout_line_x_to_index">pango_layout_line_x_to_index</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> pango_layout_line_x_to_index (<link linkend="PangoLayoutLine">PangoLayoutLine</link> *line,
2047 <link linkend="int">int</link> x_pos,
2048 <link linkend="int">int</link> *index_,
2049 <link linkend="int">int</link> *trailing);</programlisting>
2051 Converts from x offset to the byte index of the corresponding
2052 character within the text of the layout. If <parameter>x_pos</parameter> is outside the line,
2053 <parameter>index_</parameter> and <parameter>trailing</parameter> will point to the very first or very last position
2054 in the line. This determination is based on the resolved direction
2055 of the paragraph; for example, if the resolved direction is
2056 right-to-left, then an X position to the right of the line (after it)
2057 results in 0 being stored in <parameter>index_</parameter> and <parameter>trailing</parameter>. An X position to the
2058 left of the line results in <parameter>index_</parameter> pointing to the (logical) last
2059 grapheme in the line and <parameter>trailing</parameter> being set to the number of characters
2060 in that grapheme. The reverse is true for a left-to-right line.</para>
2062 </para><variablelist role="params">
2063 <varlistentry><term><parameter>line</parameter> :</term>
2064 <listitem><simpara> a <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link>
2065 </simpara></listitem></varlistentry>
2066 <varlistentry><term><parameter>x_pos</parameter> :</term>
2067 <listitem><simpara> the X offset (in Pango units)
2068 from the left edge of the line.
2069 </simpara></listitem></varlistentry>
2070 <varlistentry><term><parameter>index_</parameter> :</term>
2071 <listitem><simpara> location to store calculated byte index for
2072 the grapheme in which the user clicked.
2073 </simpara></listitem></varlistentry>
2074 <varlistentry><term><parameter>trailing</parameter> :</term>
2075 <listitem><simpara> location to store an integer indicating where
2076 in the grapheme the user clicked. It will either
2077 be zero, or the number of characters in the
2078 grapheme. 0 represents the leading edge of the grapheme.
2079 </simpara></listitem></varlistentry>
2080 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if <parameter>x_pos</parameter> was outside the line, <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if inside
2081 </simpara></listitem></varlistentry>
2082 </variablelist></refsect2>
2083 <refsect2 id="pango-layout-line-get-x-ranges" role="function">
2084 <title>pango_layout_line_get_x_ranges ()</title>
2085 <indexterm zone="pango-layout-line-get-x-ranges"><primary sortas="pango_layout_line_get_x_ranges">pango_layout_line_get_x_ranges</primary></indexterm><programlisting><link linkend="void">void</link> pango_layout_line_get_x_ranges (<link linkend="PangoLayoutLine">PangoLayoutLine</link> *line,
2086 <link linkend="int">int</link> start_index,
2087 <link linkend="int">int</link> end_index,
2088 <link linkend="int">int</link> **ranges,
2089 <link linkend="int">int</link> *n_ranges);</programlisting>
2091 Gets a list of visual ranges corresponding to a given logical range.
2092 This list is not necessarily minimal - there may be consecutive
2093 ranges which are adjacent. The ranges will be sorted from left to
2094 right. The ranges are with respect to the left edge of the entire
2095 layout, not with respect to the line.</para>
2097 </para><variablelist role="params">
2098 <varlistentry><term><parameter>line</parameter> :</term>
2099 <listitem><simpara> a <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link>
2100 </simpara></listitem></varlistentry>
2101 <varlistentry><term><parameter>start_index</parameter> :</term>
2102 <listitem><simpara> Start byte index of the logical range. If this value
2103 is less than the start index for the line, then
2104 the first range will extend all the way to the leading
2105 edge of the layout. Otherwise it will start at the
2106 leading edge of the first character.
2107 </simpara></listitem></varlistentry>
2108 <varlistentry><term><parameter>end_index</parameter> :</term>
2109 <listitem><simpara> Ending byte index of the logical range. If this value
2110 is greater than the end index for the line, then
2111 the last range will extend all the way to the trailing
2112 edge of the layout. Otherwise, it will end at the
2113 trailing edge of the last character.
2114 </simpara></listitem></varlistentry>
2115 <varlistentry><term><parameter>ranges</parameter> :</term>
2116 <listitem><simpara>out): (array length=n_ranges): (transfer=full. <acronym>out): (array length=n_ranges):</acronym> (transfer=full. </simpara></listitem></varlistentry>
2117 <varlistentry><term><parameter>n_ranges</parameter> :</term>
2118 <listitem><simpara> The number of ranges stored in <parameter>ranges</parameter>.
2119 </simpara></listitem></varlistentry>
2120 </variablelist></refsect2>
projects / external / pango1.0.git / blob