← Back to branch summary

~ubuntu-branches/ubuntu/lucid/pango1.0/lucid-security

« back to all changes in this revision

Viewing changes to docs/xml/glyphs.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2010-03-31 13:45:57 UTC
  • mfrom: (1.5.10 upstream)
  • Revision ID: james.westby@ubuntu.com-20100331134557-ls7q7w9n62sif2qa
Tags: 1.28.0-0ubuntu1
* New upstream version:
  - [HB] Fix leak when duplicating blob
  - Misc bug fixes
  - Bugs fixed:
  Bug 611033 - Layout using ATSUI fontmap treats absolute font sizes a...
  Bug 605655 - Pango 1.26.2 introduces kerning bug
  Bug 611229 - Pango reads from uninitialized memory
  Bug 594101 - [Indic] needed character class data updates to support unicode 5.1
  Bug 345066 - backspace changes independent indic characters
  Bug 609326 - Complex script shaping failed in the FT2 backend on Windows
  Bug 604128 - Applications crash when displaying Hebrew characters
  Bug 608923 - Incorrect/broken ligatures on MacOS
  Bug 610791 - checks fail for unused documented symbols
* debian/patches/13_fix-gobject-introspection-build.patch,
  debian/patches/90_autoreconf.patch:
  - the new version doesn't require those

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/xml/glyphs.xml
1
 
<refentry id="pango-Glyph-Storage">
2
 
<refmeta>
3
 
<refentrytitle role="top_of_page" id="pango-Glyph-Storage.top_of_page">Glyph Storage</refentrytitle>
4
 
<manvolnum>3</manvolnum>
5
 
<refmiscinfo>PANGO Library</refmiscinfo>
6
 
</refmeta>
7
 
 
8
 
<refnamediv>
9
 
<refname>Glyph Storage</refname>
10
 
<refpurpose>Structures for storing information about glyphs</refpurpose>
11
 
</refnamediv>
12
 
 
13
 
<refsynopsisdiv id="pango-Glyph-Storage.synopsis" role="synopsis">
14
 
<title role="synopsis.title">Synopsis</title>
15
 
 
16
 
<synopsis>
17
 
#define             <link linkend="PANGO-SCALE--CAPS">PANGO_SCALE</link>
18
 
#define             <link linkend="PANGO-PIXELS--CAPS">PANGO_PIXELS</link>                        (d)
19
 
#define             <link linkend="PANGO-PIXELS-FLOOR--CAPS">PANGO_PIXELS_FLOOR</link>                  (d)
20
 
#define             <link linkend="PANGO-PIXELS-CEIL--CAPS">PANGO_PIXELS_CEIL</link>                   (d)
21
 
#define             <link linkend="PANGO-UNITS-ROUND--CAPS">PANGO_UNITS_ROUND</link>                   (d)
22
 
<link linkend="double">double</link>              <link linkend="pango-units-to-double">pango_units_to_double</link>               (<link linkend="int">int</link> i);
23
 
<link linkend="int">int</link>                 <link linkend="pango-units-from-double">pango_units_from_double</link>             (<link linkend="double">double</link> d);
24
 
                    <link linkend="PangoRectangle">PangoRectangle</link>;
25
 
#define             <link linkend="PANGO-ASCENT--CAPS">PANGO_ASCENT</link>                        (rect)
26
 
#define             <link linkend="PANGO-DESCENT--CAPS">PANGO_DESCENT</link>                       (rect)
27
 
#define             <link linkend="PANGO-LBEARING--CAPS">PANGO_LBEARING</link>                      (rect)
28
 
#define             <link linkend="PANGO-RBEARING--CAPS">PANGO_RBEARING</link>                      (rect)
29
 
<link linkend="void">void</link>                <link linkend="pango-extents-to-pixels">pango_extents_to_pixels</link>             (<link linkend="PangoRectangle">PangoRectangle</link> *inclusive,
30
 
                                                         <link linkend="PangoRectangle">PangoRectangle</link> *nearest);
31
 
                    <link linkend="PangoMatrix">PangoMatrix</link>;
32
 
#define             <link linkend="PANGO-TYPE-MATRIX--CAPS">PANGO_TYPE_MATRIX</link>
33
 
#define             <link linkend="PANGO-MATRIX-INIT--CAPS">PANGO_MATRIX_INIT</link>
34
 
<link linkend="PangoMatrix">PangoMatrix</link> *       <link linkend="pango-matrix-copy">pango_matrix_copy</link>                   (const <link linkend="PangoMatrix">PangoMatrix</link> *matrix);
35
 
<link linkend="void">void</link>                <link linkend="pango-matrix-free">pango_matrix_free</link>                   (<link linkend="PangoMatrix">PangoMatrix</link> *matrix);
36
 
<link linkend="void">void</link>                <link linkend="pango-matrix-translate">pango_matrix_translate</link>              (<link linkend="PangoMatrix">PangoMatrix</link> *matrix,
37
 
                                                         <link linkend="double">double</link> tx,
38
 
                                                         <link linkend="double">double</link> ty);
39
 
<link linkend="void">void</link>                <link linkend="pango-matrix-scale">pango_matrix_scale</link>                  (<link linkend="PangoMatrix">PangoMatrix</link> *matrix,
40
 
                                                         <link linkend="double">double</link> scale_x,
41
 
                                                         <link linkend="double">double</link> scale_y);
42
 
<link linkend="void">void</link>                <link linkend="pango-matrix-rotate">pango_matrix_rotate</link>                 (<link linkend="PangoMatrix">PangoMatrix</link> *matrix,
43
 
                                                         <link linkend="double">double</link> degrees);
44
 
<link linkend="void">void</link>                <link linkend="pango-matrix-concat">pango_matrix_concat</link>                 (<link linkend="PangoMatrix">PangoMatrix</link> *matrix,
45
 
                                                         const <link linkend="PangoMatrix">PangoMatrix</link> *new_matrix);
46
 
<link linkend="void">void</link>                <link linkend="pango-matrix-transform-point">pango_matrix_transform_point</link>        (const <link linkend="PangoMatrix">PangoMatrix</link> *matrix,
47
 
                                                         <link linkend="double">double</link> *x,
48
 
                                                         <link linkend="double">double</link> *y);
49
 
<link linkend="void">void</link>                <link linkend="pango-matrix-transform-distance">pango_matrix_transform_distance</link>     (const <link linkend="PangoMatrix">PangoMatrix</link> *matrix,
50
 
                                                         <link linkend="double">double</link> *dx,
51
 
                                                         <link linkend="double">double</link> *dy);
52
 
<link linkend="void">void</link>                <link linkend="pango-matrix-transform-rectangle">pango_matrix_transform_rectangle</link>    (const <link linkend="PangoMatrix">PangoMatrix</link> *matrix,
53
 
                                                         <link linkend="PangoRectangle">PangoRectangle</link> *rect);
54
 
<link linkend="void">void</link>                <link linkend="pango-matrix-transform-pixel-rectangle">pango_matrix_transform_pixel_rectangle</link>
55
 
                                                        (const <link linkend="PangoMatrix">PangoMatrix</link> *matrix,
56
 
                                                         <link linkend="PangoRectangle">PangoRectangle</link> *rect);
57
 
<link linkend="double">double</link>              <link linkend="pango-matrix-get-font-scale-factor">pango_matrix_get_font_scale_factor</link>  (const <link linkend="PangoMatrix">PangoMatrix</link> *matrix);
58
 
typedef             <link linkend="PangoGlyph">PangoGlyph</link>;
59
 
#define             <link linkend="PANGO-GLYPH-EMPTY--CAPS">PANGO_GLYPH_EMPTY</link>
60
 
#define             <link linkend="PANGO-GLYPH-INVALID-INPUT--CAPS">PANGO_GLYPH_INVALID_INPUT</link>
61
 
#define             <link linkend="PANGO-GLYPH-UNKNOWN-FLAG--CAPS">PANGO_GLYPH_UNKNOWN_FLAG</link>
62
 
#define             <link linkend="PANGO-GET-UNKNOWN-GLYPH--CAPS">PANGO_GET_UNKNOWN_GLYPH</link>             (wc)
63
 
                    <link linkend="PangoGlyphInfo">PangoGlyphInfo</link>;
64
 
                    <link linkend="PangoGlyphGeometry">PangoGlyphGeometry</link>;
65
 
typedef             <link linkend="PangoGlyphUnit">PangoGlyphUnit</link>;
66
 
                    <link linkend="PangoGlyphVisAttr">PangoGlyphVisAttr</link>;
67
 
                    <link linkend="PangoGlyphString">PangoGlyphString</link>;
68
 
                    <link linkend="PangoGlyphItem">PangoGlyphItem</link>;
69
 
                    <link linkend="PangoGlyphItemIter">PangoGlyphItemIter</link>;
70
 
#define             <link linkend="PANGO-TYPE-GLYPH-STRING--CAPS">PANGO_TYPE_GLYPH_STRING</link>
71
 
<link linkend="PangoGlyphString">PangoGlyphString</link> *  <link linkend="pango-glyph-string-new">pango_glyph_string_new</link>              (void);
72
 
<link linkend="PangoGlyphString">PangoGlyphString</link> *  <link linkend="pango-glyph-string-copy">pango_glyph_string_copy</link>             (<link linkend="PangoGlyphString">PangoGlyphString</link> *string);
73
 
<link linkend="void">void</link>                <link linkend="pango-glyph-string-set-size">pango_glyph_string_set_size</link>         (<link linkend="PangoGlyphString">PangoGlyphString</link> *string,
74
 
                                                         <link linkend="gint">gint</link> new_len);
75
 
<link linkend="void">void</link>                <link linkend="pango-glyph-string-free">pango_glyph_string_free</link>             (<link linkend="PangoGlyphString">PangoGlyphString</link> *string);
76
 
<link linkend="void">void</link>                <link linkend="pango-glyph-string-extents">pango_glyph_string_extents</link>          (<link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs,
77
 
                                                         <link linkend="PangoFont">PangoFont</link> *font,
78
 
                                                         <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
79
 
                                                         <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);
80
 
<link linkend="void">void</link>                <link linkend="pango-glyph-string-extents-range">pango_glyph_string_extents_range</link>    (<link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs,
81
 
                                                         <link linkend="int">int</link> start,
82
 
                                                         <link linkend="int">int</link> end,
83
 
                                                         <link linkend="PangoFont">PangoFont</link> *font,
84
 
                                                         <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
85
 
                                                         <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);
86
 
<link linkend="int">int</link>                 <link linkend="pango-glyph-string-get-width">pango_glyph_string_get_width</link>        (<link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs);
87
 
<link linkend="void">void</link>                <link linkend="pango-glyph-string-index-to-x">pango_glyph_string_index_to_x</link>       (<link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs,
88
 
                                                         <link linkend="char">char</link> *text,
89
 
                                                         <link linkend="int">int</link> length,
90
 
                                                         <link linkend="PangoAnalysis">PangoAnalysis</link> *analysis,
91
 
                                                         <link linkend="int">int</link> index_,
92
 
                                                         <link linkend="gboolean">gboolean</link> trailing,
93
 
                                                         <link linkend="int">int</link> *x_pos);
94
 
<link linkend="void">void</link>                <link linkend="pango-glyph-string-x-to-index">pango_glyph_string_x_to_index</link>       (<link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs,
95
 
                                                         <link linkend="char">char</link> *text,
96
 
                                                         <link linkend="int">int</link> length,
97
 
                                                         <link linkend="PangoAnalysis">PangoAnalysis</link> *analysis,
98
 
                                                         <link linkend="int">int</link> x_pos,
99
 
                                                         <link linkend="int">int</link> *index_,
100
 
                                                         <link linkend="int">int</link> *trailing);
101
 
<link linkend="void">void</link>                <link linkend="pango-glyph-string-get-logical-widths">pango_glyph_string_get_logical_widths</link>
102
 
                                                        (<link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs,
103
 
                                                         const <link linkend="char">char</link> *text,
104
 
                                                         <link linkend="int">int</link> length,
105
 
                                                         <link linkend="int">int</link> embedding_level,
106
 
                                                         <link linkend="int">int</link> *logical_widths);
107
 
#define             <link linkend="PANGO-TYPE-GLYPH-ITEM--CAPS">PANGO_TYPE_GLYPH_ITEM</link>
108
 
<link linkend="PangoGlyphItem">PangoGlyphItem</link> *    <link linkend="pango-glyph-item-copy">pango_glyph_item_copy</link>               (<link linkend="PangoGlyphItem">PangoGlyphItem</link> *orig);
109
 
<link linkend="void">void</link>                <link linkend="pango-glyph-item-free">pango_glyph_item_free</link>               (<link linkend="PangoGlyphItem">PangoGlyphItem</link> *glyph_item);
110
 
<link linkend="PangoGlyphItem">PangoGlyphItem</link> *    <link linkend="pango-glyph-item-split">pango_glyph_item_split</link>              (<link linkend="PangoGlyphItem">PangoGlyphItem</link> *orig,
111
 
                                                         const <link linkend="char">char</link> *text,
112
 
                                                         <link linkend="int">int</link> split_index);
113
 
<link linkend="GSList">GSList</link> *            <link linkend="pango-glyph-item-apply-attrs">pango_glyph_item_apply_attrs</link>        (<link linkend="PangoGlyphItem">PangoGlyphItem</link> *glyph_item,
114
 
                                                         const <link linkend="char">char</link> *text,
115
 
                                                         <link linkend="PangoAttrList">PangoAttrList</link> *list);
116
 
<link linkend="void">void</link>                <link linkend="pango-glyph-item-letter-space">pango_glyph_item_letter_space</link>       (<link linkend="PangoGlyphItem">PangoGlyphItem</link> *glyph_item,
117
 
                                                         const <link linkend="char">char</link> *text,
118
 
                                                         <link linkend="PangoLogAttr">PangoLogAttr</link> *log_attrs,
119
 
                                                         <link linkend="int">int</link> letter_spacing);
120
 
<link linkend="void">void</link>                <link linkend="pango-glyph-item-get-logical-widths">pango_glyph_item_get_logical_widths</link> (<link linkend="PangoGlyphItem">PangoGlyphItem</link> *glyph_item,
121
 
                                                         const <link linkend="char">char</link> *text,
122
 
                                                         <link linkend="int">int</link> *logical_widths);
123
 
#define             <link linkend="PANGO-TYPE-GLYPH-ITEM-ITER--CAPS">PANGO_TYPE_GLYPH_ITEM_ITER</link>
124
 
<link linkend="PangoGlyphItemIter">PangoGlyphItemIter</link> * <link linkend="pango-glyph-item-iter-copy">pango_glyph_item_iter_copy</link>         (<link linkend="PangoGlyphItemIter">PangoGlyphItemIter</link> *orig);
125
 
<link linkend="void">void</link>                <link linkend="pango-glyph-item-iter-free">pango_glyph_item_iter_free</link>          (<link linkend="PangoGlyphItemIter">PangoGlyphItemIter</link> *iter);
126
 
<link linkend="gboolean">gboolean</link>            <link linkend="pango-glyph-item-iter-init-start">pango_glyph_item_iter_init_start</link>    (<link linkend="PangoGlyphItemIter">PangoGlyphItemIter</link> *iter,
127
 
                                                         <link linkend="PangoGlyphItem">PangoGlyphItem</link> *glyph_item,
128
 
                                                         const <link linkend="char">char</link> *text);
129
 
<link linkend="gboolean">gboolean</link>            <link linkend="pango-glyph-item-iter-init-end">pango_glyph_item_iter_init_end</link>      (<link linkend="PangoGlyphItemIter">PangoGlyphItemIter</link> *iter,
130
 
                                                         <link linkend="PangoGlyphItem">PangoGlyphItem</link> *glyph_item,
131
 
                                                         const <link linkend="char">char</link> *text);
132
 
<link linkend="gboolean">gboolean</link>            <link linkend="pango-glyph-item-iter-next-cluster">pango_glyph_item_iter_next_cluster</link>  (<link linkend="PangoGlyphItemIter">PangoGlyphItemIter</link> *iter);
133
 
<link linkend="gboolean">gboolean</link>            <link linkend="pango-glyph-item-iter-prev-cluster">pango_glyph_item_iter_prev_cluster</link>  (<link linkend="PangoGlyphItemIter">PangoGlyphItemIter</link> *iter);
134
 
</synopsis>
135
 
</refsynopsisdiv>
136
 
 
137
 
 
138
 
 
139
 
 
140
 
 
141
 
 
142
 
 
143
 
 
144
 
 
145
 
<refsect1 id="pango-Glyph-Storage.description" role="desc">
146
 
<title role="desc.title">Description</title>
147
 
<para>
148
 
<link linkend="pango-shape"><function>pango_shape()</function></link> produces a string of glyphs which
149
 
can be measured or drawn to the screen. The following
150
 
structures are used to store information about
151
 
glyphs.
152
 
</para>
153
 
</refsect1>
154
 
 
155
 
<refsect1 id="pango-Glyph-Storage.details" role="details">
156
 
<title role="details.title">Details</title>
157
 
<refsect2 id="PANGO-SCALE--CAPS" role="macro">
158
 
<title>PANGO_SCALE</title>
159
 
<indexterm zone="PANGO-SCALE--CAPS"><primary sortas="PANGO_SCALE">PANGO_SCALE</primary></indexterm><programlisting>#define PANGO_SCALE 1024
160
 
</programlisting>
161
 
<para>
162
 
The <link linkend="PANGO-SCALE--CAPS"><literal>PANGO_SCALE</literal></link> macro represents the scale between dimensions used
163
 
for Pango distances and device units. (The definition of device
164
 
units is dependent on the output device; it will typically be pixels
165
 
for a screen, and points for a printer.) <link linkend="PANGO-SCALE--CAPS"><literal>PANGO_SCALE</literal></link> is currently
166
 
1024, but this may be changed in the future.
167
 
</para>
168
 
<para>
169
 
When setting font sizes, device units are always considered to be
170
 
points (as in "12 point font"), rather than pixels.
171
 
</para></refsect2>
172
 
<refsect2 id="PANGO-PIXELS--CAPS" role="macro">
173
 
<title>PANGO_PIXELS()</title>
174
 
<indexterm zone="PANGO-PIXELS--CAPS"><primary sortas="PANGO_PIXELS">PANGO_PIXELS</primary></indexterm><programlisting>#define PANGO_PIXELS(d) (((int)(d) + 512) &gt;&gt; 10)
175
 
</programlisting>
176
 
<para>
177
 
Converts a dimension to device units by rounding.
178
 
</para><variablelist role="params">
179
 
<varlistentry><term><parameter>d</parameter>&#160;:</term>
180
 
<listitem><simpara>a dimension in Pango units.
181
 
</simpara></listitem></varlistentry>
182
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>rounded dimension in device units.
183
 
</simpara></listitem></varlistentry>
184
 
</variablelist></refsect2>
185
 
<refsect2 id="PANGO-PIXELS-FLOOR--CAPS" role="macro" condition="since:1.14">
186
 
<title>PANGO_PIXELS_FLOOR()</title>
187
 
<indexterm zone="PANGO-PIXELS-FLOOR--CAPS" role="1.14"><primary sortas="PANGO_PIXELS_FLOOR">PANGO_PIXELS_FLOOR</primary></indexterm><programlisting>#define PANGO_PIXELS_FLOOR(d) (((int)(d)) &gt;&gt; 10)
188
 
</programlisting>
189
 
<para>
190
 
Converts a dimension to device units by flooring.
191
 
</para><variablelist role="params">
192
 
<varlistentry><term><parameter>d</parameter>&#160;:</term>
193
 
<listitem><simpara>a dimension in Pango units.
194
 
</simpara></listitem></varlistentry>
195
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>floored dimension in device units.
196
 
</simpara></listitem></varlistentry>
197
 
</variablelist><para role="since">Since 1.14</para></refsect2>
198
 
<refsect2 id="PANGO-PIXELS-CEIL--CAPS" role="macro" condition="since:1.14">
199
 
<title>PANGO_PIXELS_CEIL()</title>
200
 
<indexterm zone="PANGO-PIXELS-CEIL--CAPS" role="1.14"><primary sortas="PANGO_PIXELS_CEIL">PANGO_PIXELS_CEIL</primary></indexterm><programlisting>#define PANGO_PIXELS_CEIL(d) (((int)(d) + 1023) &gt;&gt; 10)
201
 
</programlisting>
202
 
<para>
203
 
Converts a dimension to device units by ceiling.
204
 
</para><variablelist role="params">
205
 
<varlistentry><term><parameter>d</parameter>&#160;:</term>
206
 
<listitem><simpara>a dimension in Pango units.
207
 
</simpara></listitem></varlistentry>
208
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>ceiled dimension in device units.
209
 
</simpara></listitem></varlistentry>
210
 
</variablelist><para role="since">Since 1.14</para></refsect2>
211
 
<refsect2 id="PANGO-UNITS-ROUND--CAPS" role="macro" condition="since:1.18">
212
 
<title>PANGO_UNITS_ROUND()</title>
213
 
<indexterm zone="PANGO-UNITS-ROUND--CAPS" role="1.18"><primary sortas="PANGO_UNITS_ROUND">PANGO_UNITS_ROUND</primary></indexterm><programlisting>#define             PANGO_UNITS_ROUND(d)</programlisting>
214
 
<para>
215
 
Rounds a dimension to whole device units, but does not
216
 
convert it to device units.
217
 
</para><variablelist role="params">
218
 
<varlistentry><term><parameter>d</parameter>&#160;:</term>
219
 
<listitem><simpara>a dimension in Pango units.
220
 
</simpara></listitem></varlistentry>
221
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>rounded dimension in Pango units.
222
 
</simpara></listitem></varlistentry>
223
 
</variablelist><para role="since">Since 1.18</para></refsect2>
224
 
<refsect2 id="pango-units-to-double" role="function" condition="since:1.16">
225
 
<title>pango_units_to_double ()</title>
226
 
<indexterm zone="pango-units-to-double" role="1.16"><primary sortas="pango_units_to_double">pango_units_to_double</primary></indexterm><programlisting><link linkend="double">double</link>              pango_units_to_double               (<link linkend="int">int</link> i);</programlisting>
227
 
<para>
228
 
Converts a number in Pango units to floating-point: divides
229
 
it by <link linkend="PANGO-SCALE--CAPS"><literal>PANGO_SCALE</literal></link>.</para>
230
 
<para>
231
 
</para><variablelist role="params">
232
 
<varlistentry><term><parameter>i</parameter>&#160;:</term>
233
 
<listitem><simpara> value in Pango units
234
 
</simpara></listitem></varlistentry>
235
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the double value.
236
 
 
237
 
</simpara></listitem></varlistentry>
238
 
</variablelist><para role="since">Since 1.16</para></refsect2>
239
 
<refsect2 id="pango-units-from-double" role="function" condition="since:1.16">
240
 
<title>pango_units_from_double ()</title>
241
 
<indexterm zone="pango-units-from-double" role="1.16"><primary sortas="pango_units_from_double">pango_units_from_double</primary></indexterm><programlisting><link linkend="int">int</link>                 pango_units_from_double             (<link linkend="double">double</link> d);</programlisting>
242
 
<para>
243
 
Converts a floating-point number to Pango units: multiplies
244
 
it by <link linkend="PANGO-SCALE--CAPS"><literal>PANGO_SCALE</literal></link> and rounds to nearest integer.</para>
245
 
<para>
246
 
</para><variablelist role="params">
247
 
<varlistentry><term><parameter>d</parameter>&#160;:</term>
248
 
<listitem><simpara> double floating-point value
249
 
</simpara></listitem></varlistentry>
250
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the value in Pango units.
251
 
 
252
 
</simpara></listitem></varlistentry>
253
 
</variablelist><para role="since">Since 1.16</para></refsect2>
254
 
<refsect2 id="PangoRectangle" role="struct">
255
 
<title>PangoRectangle</title>
256
 
<indexterm zone="PangoRectangle"><primary sortas="PangoRectangle">PangoRectangle</primary></indexterm><programlisting>typedef struct {
257
 
  int x;
258
 
  int y;
259
 
  int width;
260
 
  int height;
261
 
} PangoRectangle;
262
 
</programlisting>
263
 
<para>
264
 
The <link linkend="PangoRectangle"><type>PangoRectangle</type></link> structure represents a rectangle. It is frequently
265
 
used to represent the logical or ink extents of a single glyph or section
266
 
of text. (See, for instance, <link linkend="pango-font-get-glyph-extents"><function>pango_font_get_glyph_extents()</function></link>)
267
 
</para><variablelist role="struct">
268
 
<varlistentry>
269
 
<term><link linkend="int">int</link>&#160;<structfield>x</structfield>;</term>
270
 
<listitem><simpara>X coordinate of the left side of the rectangle.
271
 
</simpara></listitem>
272
 
</varlistentry>
273
 
<varlistentry>
274
 
<term><link linkend="int">int</link>&#160;<structfield>y</structfield>;</term>
275
 
<listitem><simpara>Y coordinate of the the top side of the rectangle.
276
 
</simpara></listitem>
277
 
</varlistentry>
278
 
<varlistentry>
279
 
<term><link linkend="int">int</link>&#160;<structfield>width</structfield>;</term>
280
 
<listitem><simpara>width of the rectangle.
281
 
</simpara></listitem>
282
 
</varlistentry>
283
 
<varlistentry>
284
 
<term><link linkend="int">int</link>&#160;<structfield>height</structfield>;</term>
285
 
<listitem><simpara>height of the rectangle.
286
 
</simpara></listitem>
287
 
</varlistentry>
288
 
</variablelist></refsect2>
289
 
<refsect2 id="PANGO-ASCENT--CAPS" role="macro">
290
 
<title>PANGO_ASCENT()</title>
291
 
<indexterm zone="PANGO-ASCENT--CAPS"><primary sortas="PANGO_ASCENT">PANGO_ASCENT</primary></indexterm><programlisting>#define PANGO_ASCENT(rect) (-(rect).y)
292
 
</programlisting>
293
 
<para>
294
 
Extracts the <firstterm>ascent</firstterm> from a <link linkend="PangoRectangle"><type>PangoRectangle</type></link>
295
 
representing glyph extents. The ascent is the distance from the
296
 
baseline to the highest point of the character. This is positive if the
297
 
glyph ascends above the baseline.
298
 
</para><variablelist role="params">
299
 
<varlistentry><term><parameter>rect</parameter>&#160;:</term>
300
 
<listitem><simpara>a <link linkend="PangoRectangle"><type>PangoRectangle</type></link>
301
 
</simpara></listitem></varlistentry>
302
 
</variablelist></refsect2>
303
 
<refsect2 id="PANGO-DESCENT--CAPS" role="macro">
304
 
<title>PANGO_DESCENT()</title>
305
 
<indexterm zone="PANGO-DESCENT--CAPS"><primary sortas="PANGO_DESCENT">PANGO_DESCENT</primary></indexterm><programlisting>#define PANGO_DESCENT(rect) ((rect).y + (rect).height)
306
 
</programlisting>
307
 
<para>
308
 
Extracts the <firstterm>descent</firstterm> from a <link linkend="PangoRectangle"><type>PangoRectangle</type></link>
309
 
representing glyph extents. The descent is the distance from the
310
 
baseline to the lowest point of the character. This is positive if the
311
 
glyph descends below the baseline.
312
 
</para><variablelist role="params">
313
 
<varlistentry><term><parameter>rect</parameter>&#160;:</term>
314
 
<listitem><simpara>a <link linkend="PangoRectangle"><type>PangoRectangle</type></link>
315
 
</simpara></listitem></varlistentry>
316
 
</variablelist></refsect2>
317
 
<refsect2 id="PANGO-LBEARING--CAPS" role="macro">
318
 
<title>PANGO_LBEARING()</title>
319
 
<indexterm zone="PANGO-LBEARING--CAPS"><primary sortas="PANGO_LBEARING">PANGO_LBEARING</primary></indexterm><programlisting>#define PANGO_LBEARING(rect) ((rect).x)
320
 
</programlisting>
321
 
<para>
322
 
Extracts the <firstterm>left bearing</firstterm> from a <link linkend="PangoRectangle"><type>PangoRectangle</type></link>
323
 
representing glyph extents. The left bearing is the distance from the
324
 
horizontal origin to the farthest left point of the character.
325
 
This is positive for characters drawn completely to the right of the
326
 
glyph origin.
327
 
</para><variablelist role="params">
328
 
<varlistentry><term><parameter>rect</parameter>&#160;:</term>
329
 
<listitem><simpara>a <link linkend="PangoRectangle"><type>PangoRectangle</type></link>
330
 
</simpara></listitem></varlistentry>
331
 
</variablelist></refsect2>
332
 
<refsect2 id="PANGO-RBEARING--CAPS" role="macro">
333
 
<title>PANGO_RBEARING()</title>
334
 
<indexterm zone="PANGO-RBEARING--CAPS"><primary sortas="PANGO_RBEARING">PANGO_RBEARING</primary></indexterm><programlisting>#define PANGO_RBEARING(rect) ((rect).x + (rect).width)
335
 
</programlisting>
336
 
<para>
337
 
Extracts the <firstterm>right bearing</firstterm> from a <link linkend="PangoRectangle"><type>PangoRectangle</type></link>
338
 
representing glyph extents. The right bearing is the distance from the
339
 
horizontal origin to the farthest right point of the character.
340
 
This is positive except for characters drawn completely to the left of the
341
 
horizontal origin.
342
 
</para><variablelist role="params">
343
 
<varlistentry><term><parameter>rect</parameter>&#160;:</term>
344
 
<listitem><simpara>a <link linkend="PangoRectangle"><type>PangoRectangle</type></link>
345
 
</simpara></listitem></varlistentry>
346
 
</variablelist></refsect2>
347
 
<refsect2 id="pango-extents-to-pixels" role="function" condition="since:1.16">
348
 
<title>pango_extents_to_pixels ()</title>
349
 
<indexterm zone="pango-extents-to-pixels" role="1.16"><primary sortas="pango_extents_to_pixels">pango_extents_to_pixels</primary></indexterm><programlisting><link linkend="void">void</link>                pango_extents_to_pixels             (<link linkend="PangoRectangle">PangoRectangle</link> *inclusive,
350
 
                                                         <link linkend="PangoRectangle">PangoRectangle</link> *nearest);</programlisting>
351
 
<para>
352
 
Converts extents from Pango units to device units, dividing by the
353
 
<link linkend="PANGO-SCALE--CAPS"><literal>PANGO_SCALE</literal></link> factor and performing rounding.
354
 
</para>
355
 
<para>
356
 
The <parameter>inclusive</parameter> rectangle is converted by flooring the x/y coordinates and extending
357
 
width/height, such that the final rectangle completely includes the original
358
 
rectangle.
359
 
</para>
360
 
<para>
361
 
The <parameter>nearest</parameter> rectangle is converted by rounding the coordinates
362
 
of the rectangle to the nearest device unit (pixel).
363
 
</para>
364
 
<para>
365
 
The rule to which argument to use is: if you want the resulting device-space
366
 
rectangle to completely contain the original rectangle, pass it in as <parameter>inclusive</parameter>.
367
 
If you want two touching-but-not-overlapping rectangles stay
368
 
touching-but-not-overlapping after rounding to device units, pass them in
369
 
as <parameter>nearest</parameter>.</para>
370
 
<para>
371
 
</para><variablelist role="params">
372
 
<varlistentry><term><parameter>inclusive</parameter>&#160;:</term>
373
 
<listitem><simpara> rectangle to round to pixels inclusively, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
374
 
</simpara></listitem></varlistentry>
375
 
<varlistentry><term><parameter>nearest</parameter>&#160;:</term>
376
 
<listitem><simpara> rectangle to round to nearest pixels, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
377
 
</simpara></listitem></varlistentry>
378
 
</variablelist><para role="since">Since 1.16</para></refsect2>
379
 
<refsect2 id="PangoMatrix" role="struct" condition="since:1.6">
380
 
<title>PangoMatrix</title>
381
 
<indexterm zone="PangoMatrix" role="1.6"><primary sortas="PangoMatrix">PangoMatrix</primary></indexterm><programlisting>typedef struct {
382
 
  double xx;
383
 
  double xy;
384
 
  double yx;
385
 
  double yy;
386
 
  double x0;
387
 
  double y0;
388
 
} PangoMatrix;
389
 
</programlisting>
390
 
<para>
391
 
A structure specifying a transformation between user-space
392
 
coordinates and device coordinates. The transformation
393
 
is given by
394
 
</para>
395
 
<para>
396
 
<programlisting>
397
 
x_device = x_user * matrix->xx + y_user * matrix->xy + matrix->x0;
398
 
y_device = x_user * matrix->yx + y_user * matrix->yy + matrix->y0;
399
 
</programlisting></para>
400
 
<para>
401
 
</para><variablelist role="struct">
402
 
<varlistentry>
403
 
<term><link linkend="double">double</link>&#160;<structfield>xx</structfield>;</term>
404
 
<listitem><simpara> 1st component of the transformation matrix
405
 
</simpara></listitem>
406
 
</varlistentry>
407
 
<varlistentry>
408
 
<term><link linkend="double">double</link>&#160;<structfield>xy</structfield>;</term>
409
 
<listitem><simpara> 2nd component of the transformation matrix
410
 
</simpara></listitem>
411
 
</varlistentry>
412
 
<varlistentry>
413
 
<term><link linkend="double">double</link>&#160;<structfield>yx</structfield>;</term>
414
 
<listitem><simpara> 3rd component of the transformation matrix
415
 
</simpara></listitem>
416
 
</varlistentry>
417
 
<varlistentry>
418
 
<term><link linkend="double">double</link>&#160;<structfield>yy</structfield>;</term>
419
 
<listitem><simpara> 4th component of the transformation matrix
420
 
</simpara></listitem>
421
 
</varlistentry>
422
 
<varlistentry>
423
 
<term><link linkend="double">double</link>&#160;<structfield>x0</structfield>;</term>
424
 
<listitem><simpara> x translation
425
 
</simpara></listitem>
426
 
</varlistentry>
427
 
<varlistentry>
428
 
<term><link linkend="double">double</link>&#160;<structfield>y0</structfield>;</term>
429
 
<listitem><simpara> y translation
430
 
</simpara></listitem>
431
 
</varlistentry>
432
 
</variablelist><para role="since">Since 1.6</para></refsect2>
433
 
<refsect2 id="PANGO-TYPE-MATRIX--CAPS" role="macro">
434
 
<title>PANGO_TYPE_MATRIX</title>
435
 
<indexterm zone="PANGO-TYPE-MATRIX--CAPS"><primary sortas="PANGO_TYPE_MATRIX">PANGO_TYPE_MATRIX</primary></indexterm><programlisting>#define PANGO_TYPE_MATRIX (pango_matrix_get_type ())
436
 
</programlisting>
437
 
<para>
438
 
The GObject type for <link linkend="PangoMatrix"><type>PangoMatrix</type></link></para>
439
 
<para>
440
 
</para></refsect2>
441
 
<refsect2 id="PANGO-MATRIX-INIT--CAPS" role="macro" condition="since:1.6">
442
 
<title>PANGO_MATRIX_INIT</title>
443
 
<indexterm zone="PANGO-MATRIX-INIT--CAPS" role="1.6"><primary sortas="PANGO_MATRIX_INIT">PANGO_MATRIX_INIT</primary></indexterm><programlisting>#define PANGO_MATRIX_INIT { 1., 0., 0., 1., 0., 0. }
444
 
</programlisting>
445
 
<para>
446
 
Constant that can be used to initialize a PangoMatrix to
447
 
the identity transform.
448
 
</para>
449
 
<para>
450
 
<informalexample><programlisting>
451
 
PangoMatrix matrix = PANGO_MATRIX_INIT;
452
 
pango_matrix_rotate (&amp;matrix, 45.);
453
 
</programlisting></informalexample></para>
454
 
<para>
455
 
</para><para role="since">Since 1.6</para></refsect2>
456
 
<refsect2 id="pango-matrix-copy" role="function" condition="since:1.6">
457
 
<title>pango_matrix_copy ()</title>
458
 
<indexterm zone="pango-matrix-copy" role="1.6"><primary sortas="pango_matrix_copy">pango_matrix_copy</primary></indexterm><programlisting><link linkend="PangoMatrix">PangoMatrix</link> *       pango_matrix_copy                   (const <link linkend="PangoMatrix">PangoMatrix</link> *matrix);</programlisting>
459
 
<para>
460
 
Copies a <link linkend="PangoMatrix"><type>PangoMatrix</type></link>.</para>
461
 
<para>
462
 
</para><variablelist role="params">
463
 
<varlistentry><term><parameter>matrix</parameter>&#160;:</term>
464
 
<listitem><simpara> a <link linkend="PangoMatrix"><type>PangoMatrix</type></link>, may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>
465
 
</simpara></listitem></varlistentry>
466
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly allocated <link linkend="PangoMatrix"><type>PangoMatrix</type></link>, which should
467
 
              be freed with <link linkend="pango-matrix-free"><function>pango_matrix_free()</function></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if
468
 
              <parameter>matrix</parameter> was <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
469
 
 
470
 
</simpara></listitem></varlistentry>
471
 
</variablelist><para role="since">Since 1.6</para></refsect2>
472
 
<refsect2 id="pango-matrix-free" role="function" condition="since:1.6">
473
 
<title>pango_matrix_free ()</title>
474
 
<indexterm zone="pango-matrix-free" role="1.6"><primary sortas="pango_matrix_free">pango_matrix_free</primary></indexterm><programlisting><link linkend="void">void</link>                pango_matrix_free                   (<link linkend="PangoMatrix">PangoMatrix</link> *matrix);</programlisting>
475
 
<para>
476
 
Free a <link linkend="PangoMatrix"><type>PangoMatrix</type></link> created with <link linkend="pango-matrix-copy"><function>pango_matrix_copy()</function></link>.</para>
477
 
<para>
478
 
</para><variablelist role="params">
479
 
<varlistentry><term><parameter>matrix</parameter>&#160;:</term>
480
 
<listitem><simpara> a <link linkend="PangoMatrix"><type>PangoMatrix</type></link>, may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>
481
 
</simpara></listitem></varlistentry>
482
 
</variablelist><para role="since">Since 1.6</para></refsect2>
483
 
<refsect2 id="pango-matrix-translate" role="function" condition="since:1.6">
484
 
<title>pango_matrix_translate ()</title>
485
 
<indexterm zone="pango-matrix-translate" role="1.6"><primary sortas="pango_matrix_translate">pango_matrix_translate</primary></indexterm><programlisting><link linkend="void">void</link>                pango_matrix_translate              (<link linkend="PangoMatrix">PangoMatrix</link> *matrix,
486
 
                                                         <link linkend="double">double</link> tx,
487
 
                                                         <link linkend="double">double</link> ty);</programlisting>
488
 
<para>
489
 
Changes the transformation represented by <parameter>matrix</parameter> to be the
490
 
transformation given by first translating by (<parameter>tx</parameter>, <parameter>ty</parameter>)
491
 
then applying the original transformation.</para>
492
 
<para>
493
 
</para><variablelist role="params">
494
 
<varlistentry><term><parameter>matrix</parameter>&#160;:</term>
495
 
<listitem><simpara> a <link linkend="PangoMatrix"><type>PangoMatrix</type></link>
496
 
</simpara></listitem></varlistentry>
497
 
<varlistentry><term><parameter>tx</parameter>&#160;:</term>
498
 
<listitem><simpara> amount to translate in the X direction
499
 
</simpara></listitem></varlistentry>
500
 
<varlistentry><term><parameter>ty</parameter>&#160;:</term>
501
 
<listitem><simpara> amount to translate in the Y direction
502
 
</simpara></listitem></varlistentry>
503
 
</variablelist><para role="since">Since 1.6</para></refsect2>
504
 
<refsect2 id="pango-matrix-scale" role="function" condition="since:1.6">
505
 
<title>pango_matrix_scale ()</title>
506
 
<indexterm zone="pango-matrix-scale" role="1.6"><primary sortas="pango_matrix_scale">pango_matrix_scale</primary></indexterm><programlisting><link linkend="void">void</link>                pango_matrix_scale                  (<link linkend="PangoMatrix">PangoMatrix</link> *matrix,
507
 
                                                         <link linkend="double">double</link> scale_x,
508
 
                                                         <link linkend="double">double</link> scale_y);</programlisting>
509
 
<para>
510
 
Changes the transformation represented by <parameter>matrix</parameter> to be the
511
 
transformation given by first scaling by <parameter>sx</parameter> in the X direction
512
 
and <parameter>sy</parameter> in the Y direction then applying the original
513
 
transformation.</para>
514
 
<para>
515
 
</para><variablelist role="params">
516
 
<varlistentry><term><parameter>matrix</parameter>&#160;:</term>
517
 
<listitem><simpara> a <link linkend="PangoMatrix"><type>PangoMatrix</type></link>
518
 
</simpara></listitem></varlistentry>
519
 
<varlistentry><term><parameter>scale_x</parameter>&#160;:</term>
520
 
<listitem><simpara> amount to scale by in X direction
521
 
</simpara></listitem></varlistentry>
522
 
<varlistentry><term><parameter>scale_y</parameter>&#160;:</term>
523
 
<listitem><simpara> amount to scale by in Y direction
524
 
</simpara></listitem></varlistentry>
525
 
</variablelist><para role="since">Since 1.6</para></refsect2>
526
 
<refsect2 id="pango-matrix-rotate" role="function" condition="since:1.6">
527
 
<title>pango_matrix_rotate ()</title>
528
 
<indexterm zone="pango-matrix-rotate" role="1.6"><primary sortas="pango_matrix_rotate">pango_matrix_rotate</primary></indexterm><programlisting><link linkend="void">void</link>                pango_matrix_rotate                 (<link linkend="PangoMatrix">PangoMatrix</link> *matrix,
529
 
                                                         <link linkend="double">double</link> degrees);</programlisting>
530
 
<para>
531
 
Changes the transformation represented by <parameter>matrix</parameter> to be the
532
 
transformation given by first rotating by <parameter>degrees</parameter> degrees
533
 
counter-clockwise then applying the original transformation.</para>
534
 
<para>
535
 
</para><variablelist role="params">
536
 
<varlistentry><term><parameter>matrix</parameter>&#160;:</term>
537
 
<listitem><simpara> a <link linkend="PangoMatrix"><type>PangoMatrix</type></link>
538
 
</simpara></listitem></varlistentry>
539
 
<varlistentry><term><parameter>degrees</parameter>&#160;:</term>
540
 
<listitem><simpara> degrees to rotate counter-clockwise
541
 
</simpara></listitem></varlistentry>
542
 
</variablelist><para role="since">Since 1.6</para></refsect2>
543
 
<refsect2 id="pango-matrix-concat" role="function" condition="since:1.6">
544
 
<title>pango_matrix_concat ()</title>
545
 
<indexterm zone="pango-matrix-concat" role="1.6"><primary sortas="pango_matrix_concat">pango_matrix_concat</primary></indexterm><programlisting><link linkend="void">void</link>                pango_matrix_concat                 (<link linkend="PangoMatrix">PangoMatrix</link> *matrix,
546
 
                                                         const <link linkend="PangoMatrix">PangoMatrix</link> *new_matrix);</programlisting>
547
 
<para>
548
 
Changes the transformation represented by <parameter>matrix</parameter> to be the
549
 
transformation given by first applying transformation
550
 
given by <parameter>new_matrix</parameter> then applying the original transformation.</para>
551
 
<para>
552
 
</para><variablelist role="params">
553
 
<varlistentry><term><parameter>matrix</parameter>&#160;:</term>
554
 
<listitem><simpara> a <link linkend="PangoMatrix"><type>PangoMatrix</type></link>
555
 
</simpara></listitem></varlistentry>
556
 
<varlistentry><term><parameter>new_matrix</parameter>&#160;:</term>
557
 
<listitem><simpara> a <link linkend="PangoMatrix"><type>PangoMatrix</type></link>
558
 
</simpara></listitem></varlistentry>
559
 
</variablelist><para role="since">Since 1.6</para></refsect2>
560
 
<refsect2 id="pango-matrix-transform-point" role="function" condition="since:1.16">
561
 
<title>pango_matrix_transform_point ()</title>
562
 
<indexterm zone="pango-matrix-transform-point" role="1.16"><primary sortas="pango_matrix_transform_point">pango_matrix_transform_point</primary></indexterm><programlisting><link linkend="void">void</link>                pango_matrix_transform_point        (const <link linkend="PangoMatrix">PangoMatrix</link> *matrix,
563
 
                                                         <link linkend="double">double</link> *x,
564
 
                                                         <link linkend="double">double</link> *y);</programlisting>
565
 
<para>
566
 
Transforms the point (<parameter>x</parameter>, <parameter>y</parameter>) by <parameter>matrix</parameter>.</para>
567
 
<para>
568
 
</para><variablelist role="params">
569
 
<varlistentry><term><parameter>matrix</parameter>&#160;:</term>
570
 
<listitem><simpara> a <link linkend="PangoMatrix"><type>PangoMatrix</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
571
 
</simpara></listitem></varlistentry>
572
 
<varlistentry><term><parameter>x</parameter>&#160;:</term>
573
 
<listitem><simpara> in/out X position
574
 
</simpara></listitem></varlistentry>
575
 
<varlistentry><term><parameter>y</parameter>&#160;:</term>
576
 
<listitem><simpara> in/out Y position
577
 
</simpara></listitem></varlistentry>
578
 
</variablelist><para role="since">Since 1.16</para></refsect2>
579
 
<refsect2 id="pango-matrix-transform-distance" role="function" condition="since:1.16">
580
 
<title>pango_matrix_transform_distance ()</title>
581
 
<indexterm zone="pango-matrix-transform-distance" role="1.16"><primary sortas="pango_matrix_transform_distance">pango_matrix_transform_distance</primary></indexterm><programlisting><link linkend="void">void</link>                pango_matrix_transform_distance     (const <link linkend="PangoMatrix">PangoMatrix</link> *matrix,
582
 
                                                         <link linkend="double">double</link> *dx,
583
 
                                                         <link linkend="double">double</link> *dy);</programlisting>
584
 
<para>
585
 
Transforms the distance vector (<parameter>dx</parameter>,<parameter>dy</parameter>) by <parameter>matrix</parameter>. This is
586
 
similar to <link linkend="pango-matrix-transform-point"><function>pango_matrix_transform_point()</function></link> except that the translation
587
 
components of the transformation are ignored. The calculation of
588
 
the returned vector is as follows:
589
 
</para>
590
 
<para>
591
 
<programlisting>
592
 
dx2 = dx1 * xx + dy1 * xy;
593
 
dy2 = dx1 * yx + dy1 * yy;
594
 
</programlisting>
595
 
</para>
596
 
<para>
597
 
Affine transformations are position invariant, so the same vector
598
 
always transforms to the same vector. If (<parameter>x1</parameter>,<parameter>y1</parameter>) transforms
599
 
to (<parameter>x2</parameter>,<parameter>y2</parameter>) then (<parameter>x1</parameter>+<parameter>dx1</parameter>,<parameter>y1</parameter>+<parameter>dy1</parameter>) will transform to
600
 
(<parameter>x1</parameter>+<parameter>dx2</parameter>,<parameter>y1</parameter>+<parameter>dy2</parameter>) for all values of <parameter>x1</parameter> and <parameter>x2</parameter>.</para>
601
 
<para>
602
 
</para><variablelist role="params">
603
 
<varlistentry><term><parameter>matrix</parameter>&#160;:</term>
604
 
<listitem><simpara> a <link linkend="PangoMatrix"><type>PangoMatrix</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
605
 
</simpara></listitem></varlistentry>
606
 
<varlistentry><term><parameter>dx</parameter>&#160;:</term>
607
 
<listitem><simpara> in/out X component of a distance vector
608
 
</simpara></listitem></varlistentry>
609
 
<varlistentry><term><parameter>dy</parameter>&#160;:</term>
610
 
<listitem><simpara> yn/out Y component of a distance vector
611
 
</simpara></listitem></varlistentry>
612
 
</variablelist><para role="since">Since 1.16</para></refsect2>
613
 
<refsect2 id="pango-matrix-transform-rectangle" role="function" condition="since:1.16">
614
 
<title>pango_matrix_transform_rectangle ()</title>
615
 
<indexterm zone="pango-matrix-transform-rectangle" role="1.16"><primary sortas="pango_matrix_transform_rectangle">pango_matrix_transform_rectangle</primary></indexterm><programlisting><link linkend="void">void</link>                pango_matrix_transform_rectangle    (const <link linkend="PangoMatrix">PangoMatrix</link> *matrix,
616
 
                                                         <link linkend="PangoRectangle">PangoRectangle</link> *rect);</programlisting>
617
 
<para>
618
 
First transforms <parameter>rect</parameter> using <parameter>matrix</parameter>, then calculates the bounding box
619
 
of the transformed rectangle.  The rectangle should be in Pango units.
620
 
</para>
621
 
<para>
622
 
This function is useful for example when you want to draw a rotated
623
 
<parameter>PangoLayout</parameter> to an image buffer, and want to know how large the image
624
 
should be and how much you should shift the layout when rendering.
625
 
</para>
626
 
<para>
627
 
If you have a rectangle in device units (pixels), use
628
 
<link linkend="pango-matrix-transform-pixel-rectangle"><function>pango_matrix_transform_pixel_rectangle()</function></link>.
629
 
</para>
630
 
<para>
631
 
If you have the rectangle in Pango units and want to convert to
632
 
transformed pixel bounding box, it is more accurate to transform it first
633
 
(using this function) and pass the result to <link linkend="pango-extents-to-pixels"><function>pango_extents_to_pixels()</function></link>,
634
 
first argument, for an inclusive rounded rectangle.
635
 
However, there are valid reasons that you may want to convert
636
 
to pixels first and then transform, for example when the transformed
637
 
coordinates may overflow in Pango units (large matrix translation for
638
 
example).</para>
639
 
<para>
640
 
</para><variablelist role="params">
641
 
<varlistentry><term><parameter>matrix</parameter>&#160;:</term>
642
 
<listitem><simpara> a <link linkend="PangoMatrix"><type>PangoMatrix</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
643
 
</simpara></listitem></varlistentry>
644
 
<varlistentry><term><parameter>rect</parameter>&#160;:</term>
645
 
<listitem><simpara> in/out bounding box in Pango units, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
646
 
</simpara></listitem></varlistentry>
647
 
</variablelist><para role="since">Since 1.16</para></refsect2>
648
 
<refsect2 id="pango-matrix-transform-pixel-rectangle" role="function" condition="since:1.16">
649
 
<title>pango_matrix_transform_pixel_rectangle ()</title>
650
 
<indexterm zone="pango-matrix-transform-pixel-rectangle" role="1.16"><primary sortas="pango_matrix_transform_pixel_rectangle">pango_matrix_transform_pixel_rectangle</primary></indexterm><programlisting><link linkend="void">void</link>                pango_matrix_transform_pixel_rectangle
651
 
                                                        (const <link linkend="PangoMatrix">PangoMatrix</link> *matrix,
652
 
                                                         <link linkend="PangoRectangle">PangoRectangle</link> *rect);</programlisting>
653
 
<para>
654
 
First transforms the <parameter>rect</parameter> using <parameter>matrix</parameter>, then calculates the bounding box
655
 
of the transformed rectangle.  The rectangle should be in device units
656
 
(pixels).
657
 
</para>
658
 
<para>
659
 
This function is useful for example when you want to draw a rotated
660
 
<parameter>PangoLayout</parameter> to an image buffer, and want to know how large the image
661
 
should be and how much you should shift the layout when rendering.
662
 
</para>
663
 
<para>
664
 
For better accuracy, you should use <link linkend="pango-matrix-transform-rectangle"><function>pango_matrix_transform_rectangle()</function></link> on
665
 
original rectangle in Pango units and convert to pixels afterward
666
 
using <link linkend="pango-extents-to-pixels"><function>pango_extents_to_pixels()</function></link>'s first argument.</para>
667
 
<para>
668
 
</para><variablelist role="params">
669
 
<varlistentry><term><parameter>matrix</parameter>&#160;:</term>
670
 
<listitem><simpara> a <link linkend="PangoMatrix"><type>PangoMatrix</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
671
 
</simpara></listitem></varlistentry>
672
 
<varlistentry><term><parameter>rect</parameter>&#160;:</term>
673
 
<listitem><simpara> in/out bounding box in device units, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
674
 
</simpara></listitem></varlistentry>
675
 
</variablelist><para role="since">Since 1.16</para></refsect2>
676
 
<refsect2 id="pango-matrix-get-font-scale-factor" role="function" condition="since:1.12">
677
 
<title>pango_matrix_get_font_scale_factor ()</title>
678
 
<indexterm zone="pango-matrix-get-font-scale-factor" role="1.12"><primary sortas="pango_matrix_get_font_scale_factor">pango_matrix_get_font_scale_factor</primary></indexterm><programlisting><link linkend="double">double</link>              pango_matrix_get_font_scale_factor  (const <link linkend="PangoMatrix">PangoMatrix</link> *matrix);</programlisting>
679
 
<para>
680
 
Returns the scale factor of a matrix on the height of the font.
681
 
That is, the scale factor in the direction perpendicular to the
682
 
vector that the X coordinate is mapped to.</para>
683
 
<para>
684
 
</para><variablelist role="params">
685
 
<varlistentry><term><parameter>matrix</parameter>&#160;:</term>
686
 
<listitem><simpara> a <link linkend="PangoMatrix"><type>PangoMatrix</type></link>, may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>
687
 
</simpara></listitem></varlistentry>
688
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the scale factor of <parameter>matrix</parameter> on the height of the font,
689
 
or 1.0 if <parameter>matrix</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
690
 
 
691
 
</simpara></listitem></varlistentry>
692
 
</variablelist><para role="since">Since 1.12</para></refsect2>
693
 
<refsect2 id="PangoGlyph" role="typedef">
694
 
<title>PangoGlyph</title>
695
 
<indexterm zone="PangoGlyph"><primary sortas="PangoGlyph">PangoGlyph</primary></indexterm><programlisting>typedef guint32 PangoGlyph;
696
 
</programlisting>
697
 
<para>
698
 
A <link linkend="PangoGlyph"><type>PangoGlyph</type></link> represents a single glyph in the output form of a string.
699
 
</para></refsect2>
700
 
<refsect2 id="PANGO-GLYPH-EMPTY--CAPS" role="macro">
701
 
<title>PANGO_GLYPH_EMPTY</title>
702
 
<indexterm zone="PANGO-GLYPH-EMPTY--CAPS"><primary sortas="PANGO_GLYPH_EMPTY">PANGO_GLYPH_EMPTY</primary></indexterm><programlisting>#define PANGO_GLYPH_EMPTY           ((PangoGlyph)0x0FFFFFFF)
703
 
</programlisting>
704
 
<para>
705
 
The <link linkend="PANGO-GLYPH-EMPTY--CAPS"><literal>PANGO_GLYPH_EMPTY</literal></link> macro represents a <link linkend="PangoGlyph"><type>PangoGlyph</type></link> value that has a
706
 
special meaning, which is a zero-width empty glyph.  This is useful for
707
 
example in shaper modules, to use as the glyph for various zero-width
708
 
Unicode characters (those passing <link linkend="pango-is-zero-width"><function>pango_is_zero_width()</function></link>).
709
 
</para></refsect2>
710
 
<refsect2 id="PANGO-GLYPH-INVALID-INPUT--CAPS" role="macro" condition="since:1.20">
711
 
<title>PANGO_GLYPH_INVALID_INPUT</title>
712
 
<indexterm zone="PANGO-GLYPH-INVALID-INPUT--CAPS" role="1.20"><primary sortas="PANGO_GLYPH_INVALID_INPUT">PANGO_GLYPH_INVALID_INPUT</primary></indexterm><programlisting>#define PANGO_GLYPH_INVALID_INPUT   ((PangoGlyph)0xFFFFFFFF)
713
 
</programlisting>
714
 
<para>
715
 
The <link linkend="PANGO-GLYPH-EMPTY--CAPS"><literal>PANGO_GLYPH_EMPTY</literal></link> macro represents a <link linkend="PangoGlyph"><type>PangoGlyph</type></link> value that has a
716
 
special meaning of invalid input.  <link linkend="PangoLayout"><type>PangoLayout</type></link> produces one such glyph
717
 
per invalid input UTF-8 byte and such a glyph is rendered as a crossed
718
 
box.
719
 
Note that this value is defined such that it has the <link linkend="PANGO-GLYPH-UNKNOWN-FLAG--CAPS"><literal>PANGO_GLYPH_UNKNOWN_FLAG</literal></link>
720
 
on.
721
 
</para><para role="since">Since 1.20</para></refsect2>
722
 
<refsect2 id="PANGO-GLYPH-UNKNOWN-FLAG--CAPS" role="macro">
723
 
<title>PANGO_GLYPH_UNKNOWN_FLAG</title>
724
 
<indexterm zone="PANGO-GLYPH-UNKNOWN-FLAG--CAPS"><primary sortas="PANGO_GLYPH_UNKNOWN_FLAG">PANGO_GLYPH_UNKNOWN_FLAG</primary></indexterm><programlisting>#define PANGO_GLYPH_UNKNOWN_FLAG    ((PangoGlyph)0x10000000)
725
 
</programlisting>
726
 
<para>
727
 
The <link linkend="PANGO-GLYPH-UNKNOWN-FLAG--CAPS"><literal>PANGO_GLYPH_UNKNOWN_FLAG</literal></link> macro is a flag value that can be added to
728
 
a <link linkend="gunichar"><type>gunichar</type></link> value of a valid Unicode character, to produce a <link linkend="PangoGlyph"><type>PangoGlyph</type></link>
729
 
value, representing an unknown-character glyph for the respective <link linkend="gunichar"><type>gunichar</type></link>.
730
 
</para></refsect2>
731
 
<refsect2 id="PANGO-GET-UNKNOWN-GLYPH--CAPS" role="macro">
732
 
<title>PANGO_GET_UNKNOWN_GLYPH()</title>
733
 
<indexterm zone="PANGO-GET-UNKNOWN-GLYPH--CAPS"><primary sortas="PANGO_GET_UNKNOWN_GLYPH">PANGO_GET_UNKNOWN_GLYPH</primary></indexterm><programlisting>#define PANGO_GET_UNKNOWN_GLYPH(wc) ((PangoGlyph)(wc)|PANGO_GLYPH_UNKNOWN_FLAG)
734
 
</programlisting>
735
 
<para>
736
 
Returns a <link linkend="PangoGlyph"><type>PangoGlyph</type></link> value that means no glyph was found for <parameter>wc</parameter>.
737
 
The way this unknown glyphs are rendered is backend specific.  For example,
738
 
a box with the hexadecimal Unicode code-point of the character written in it
739
 
is what is done in the most common backends.
740
 
</para><variablelist role="params">
741
 
<varlistentry><term><parameter>wc</parameter>&#160;:</term>
742
 
<listitem><simpara>a Unicode character
743
 
</simpara></listitem></varlistentry>
744
 
</variablelist></refsect2>
745
 
<refsect2 id="PangoGlyphInfo" role="struct">
746
 
<title>PangoGlyphInfo</title>
747
 
<indexterm zone="PangoGlyphInfo"><primary sortas="PangoGlyphInfo">PangoGlyphInfo</primary></indexterm><programlisting>typedef struct {
748
 
  PangoGlyph    glyph;
749
 
  PangoGlyphGeometry geometry;
750
 
  PangoGlyphVisAttr  attr;
751
 
} PangoGlyphInfo;
752
 
</programlisting>
753
 
<para>
754
 
The <link linkend="PangoGlyphInfo"><type>PangoGlyphInfo</type></link> structure represents a single glyph together with
755
 
positioning information and visual attributes.
756
 
It contains the following fields.
757
 
</para><variablelist role="struct">
758
 
<varlistentry>
759
 
<term><link linkend="PangoGlyph">PangoGlyph</link>&#160;<structfield>glyph</structfield>;</term>
760
 
<listitem><simpara>the glyph itself.
761
 
</simpara></listitem>
762
 
</varlistentry>
763
 
<varlistentry>
764
 
<term><link linkend="PangoGlyphGeometry">PangoGlyphGeometry</link>&#160;<structfield>geometry</structfield>;</term>
765
 
<listitem><simpara>the positional information about the glyph.
766
 
</simpara></listitem>
767
 
</varlistentry>
768
 
<varlistentry>
769
 
<term><link linkend="PangoGlyphVisAttr">PangoGlyphVisAttr</link>&#160;<structfield>attr</structfield>;</term>
770
 
<listitem><simpara>the visual attributes of the glyph.
771
 
</simpara></listitem>
772
 
</varlistentry>
773
 
</variablelist></refsect2>
774
 
<refsect2 id="PangoGlyphGeometry" role="struct">
775
 
<title>PangoGlyphGeometry</title>
776
 
<indexterm zone="PangoGlyphGeometry"><primary sortas="PangoGlyphGeometry">PangoGlyphGeometry</primary></indexterm><programlisting>typedef struct {
777
 
  PangoGlyphUnit width;
778
 
  PangoGlyphUnit x_offset;
779
 
  PangoGlyphUnit y_offset;
780
 
} PangoGlyphGeometry;
781
 
</programlisting>
782
 
<para>
783
 
The <link linkend="PangoGlyphGeometry"><type>PangoGlyphGeometry</type></link> structure contains width and positioning
784
 
information for a single glyph.
785
 
</para><variablelist role="struct">
786
 
<varlistentry>
787
 
<term><link linkend="PangoGlyphUnit">PangoGlyphUnit</link>&#160;<structfield>width</structfield>;</term>
788
 
<listitem><simpara>the logical width to use for the the character.
789
 
</simpara></listitem>
790
 
</varlistentry>
791
 
<varlistentry>
792
 
<term><link linkend="PangoGlyphUnit">PangoGlyphUnit</link>&#160;<structfield>x_offset</structfield>;</term>
793
 
<listitem><simpara>horizontal offset from nominal character position.
794
 
</simpara></listitem>
795
 
</varlistentry>
796
 
<varlistentry>
797
 
<term><link linkend="PangoGlyphUnit">PangoGlyphUnit</link>&#160;<structfield>y_offset</structfield>;</term>
798
 
<listitem><simpara>vertical offset from nominal character position.
799
 
</simpara></listitem>
800
 
</varlistentry>
801
 
</variablelist></refsect2>
802
 
<refsect2 id="PangoGlyphUnit" role="typedef">
803
 
<title>PangoGlyphUnit</title>
804
 
<indexterm zone="PangoGlyphUnit"><primary sortas="PangoGlyphUnit">PangoGlyphUnit</primary></indexterm><programlisting>typedef gint32 PangoGlyphUnit;
805
 
</programlisting>
806
 
<para>
807
 
The <link linkend="PangoGlyphUnit"><type>PangoGlyphUnit</type></link> type is used to store dimensions within
808
 
Pango. Dimensions are stored in 1/<link linkend="PANGO-SCALE--CAPS"><literal>PANGO_SCALE</literal></link> of a device unit.
809
 
(A device unit might be a pixel for screen display, or
810
 
a point on a printer.) <link linkend="PANGO-SCALE--CAPS"><literal>PANGO_SCALE</literal></link> is currently 1024, and
811
 
may change in the future (unlikely though), but you should not
812
 
depend on its exact value. The <link linkend="PANGO-PIXELS--CAPS"><function>PANGO_PIXELS()</function></link> macro can be used
813
 
to convert from glyph units into device units with correct rounding.
814
 
</para></refsect2>
815
 
<refsect2 id="PangoGlyphVisAttr" role="struct">
816
 
<title>PangoGlyphVisAttr</title>
817
 
<indexterm zone="PangoGlyphVisAttr"><primary sortas="PangoGlyphVisAttr">PangoGlyphVisAttr</primary></indexterm><programlisting>typedef struct {
818
 
  guint is_cluster_start : 1;
819
 
} PangoGlyphVisAttr;
820
 
</programlisting>
821
 
<para>
822
 
The PangoGlyphVisAttr is used to communicate information between
823
 
the shaping phase and the rendering phase.  More attributes may be
824
 
added in the future.
825
 
</para><variablelist role="struct">
826
 
<varlistentry>
827
 
<term><link linkend="guint">guint</link>&#160;<structfield>is_cluster_start</structfield>&#160;:&#160;1;</term>
828
 
<listitem><simpara>set for the first logical glyph in each cluster. (Clusters
829
 
                   are stored in visual order, within the cluster, glyphs
830
 
                   are always ordered in logical order, since visual
831
 
                   order is meaningless; that is, in Arabic text, accent glyphs
832
 
                   follow the glyphs for the base character.)
833
 
</simpara></listitem>
834
 
</varlistentry>
835
 
</variablelist></refsect2>
836
 
<refsect2 id="PangoGlyphString" role="struct">
837
 
<title>PangoGlyphString</title>
838
 
<indexterm zone="PangoGlyphString"><primary sortas="PangoGlyphString">PangoGlyphString</primary></indexterm><programlisting>typedef struct {
839
 
  gint num_glyphs;
840
 
 
841
 
  PangoGlyphInfo *glyphs;
842
 
 
843
 
  /* This is a memory inefficient way of representing the information
844
 
   * here - each value gives the byte index within the text
845
 
   * corresponding to the glyph string of the start of the cluster to
846
 
   * which the glyph belongs.
847
 
   */
848
 
  gint *log_clusters;
849
 
} PangoGlyphString;
850
 
</programlisting>
851
 
<para>
852
 
The <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link> structure is used to store strings
853
 
of glyphs with geometry and visual attribute information.
854
 
The storage for the glyph information is owned
855
 
by the structure which simplifies memory management.
856
 
</para><variablelist role="struct">
857
 
<varlistentry>
858
 
<term><link linkend="gint">gint</link>&#160;<structfield>num_glyphs</structfield>;</term>
859
 
<listitem><simpara>the number of glyphs in the string.
860
 
</simpara></listitem>
861
 
</varlistentry>
862
 
<varlistentry>
863
 
<term><link linkend="PangoGlyphInfo">PangoGlyphInfo</link>&#160;*<structfield>glyphs</structfield>;</term>
864
 
<listitem><simpara>an array of <link linkend="PangoGlyphInfo"><type>PangoGlyphInfo</type></link> structures of length <structfield>num_glyphs</structfield>.
865
 
</simpara></listitem>
866
 
</varlistentry>
867
 
<varlistentry>
868
 
<term><link linkend="gint">gint</link>&#160;*<structfield>log_clusters</structfield>;</term>
869
 
<listitem><simpara>for each glyph, byte index of the starting character for the
870
 
cluster. The indices are relative to the start of the text
871
 
corresponding to the PangoGlyphString.
872
 
</simpara></listitem>
873
 
</varlistentry>
874
 
</variablelist></refsect2>
875
 
<refsect2 id="PangoGlyphItem" role="struct">
876
 
<title>PangoGlyphItem</title>
877
 
<indexterm zone="PangoGlyphItem"><primary sortas="PangoGlyphItem">PangoGlyphItem</primary></indexterm><programlisting>typedef struct {
878
 
  PangoItem        *item;
879
 
  PangoGlyphString *glyphs;
880
 
} PangoGlyphItem;
881
 
</programlisting>
882
 
<para>
883
 
A <link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link> is a pair of a <link linkend="PangoItem"><type>PangoItem</type></link> and the glyphs
884
 
resulting from shaping the text corresponding to an item.
885
 
As an example of the usage of <link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link>, the results
886
 
of shaping text with <link linkend="PangoLayout"><type>PangoLayout</type></link> is a list of <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link>,
887
 
each of which contains a list of <link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link>.
888
 
</para><variablelist role="struct">
889
 
<varlistentry>
890
 
<term><link linkend="PangoItem">PangoItem</link>&#160;*<structfield>item</structfield>;</term>
891
 
<listitem><simpara>a <link linkend="PangoItem"><type>PangoItem</type></link> structure that provides information
892
 
       about a segment of text.
893
 
</simpara></listitem>
894
 
</varlistentry>
895
 
<varlistentry>
896
 
<term><link linkend="PangoGlyphString">PangoGlyphString</link>&#160;*<structfield>glyphs</structfield>;</term>
897
 
<listitem><simpara>the glyphs obtained by shaping the text
898
 
         corresponding to <parameter>item</parameter>.
899
 
</simpara></listitem>
900
 
</varlistentry>
901
 
</variablelist></refsect2>
902
 
<refsect2 id="PangoGlyphItemIter" role="struct" condition="since:1.22">
903
 
<title>PangoGlyphItemIter</title>
904
 
<indexterm zone="PangoGlyphItemIter" role="1.22"><primary sortas="PangoGlyphItemIter">PangoGlyphItemIter</primary></indexterm><programlisting>typedef struct {
905
 
  PangoGlyphItem *glyph_item;
906
 
  const gchar *text;
907
 
 
908
 
  int start_glyph;
909
 
  int start_index;
910
 
  int start_char;
911
 
 
912
 
  int end_glyph;
913
 
  int end_index;
914
 
  int end_char;
915
 
} PangoGlyphItemIter;
916
 
</programlisting>
917
 
<para>
918
 
A <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link> is an iterator over the clusters in a
919
 
<link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link>.  The <firstterm>forward direction</firstterm> of the
920
 
iterator is the logical direction of text.  That is, with increasing
921
 
<parameter>start_index</parameter> and <parameter>start_char</parameter> values.  If <parameter>glyph_item</parameter> is right-to-left
922
 
(that is, if <literal><parameter>glyph_item->item->analysis.level</parameter></literal> is odd),
923
 
then <parameter>start_glyph</parameter> decreases as the iterator moves forward.  Moreover,
924
 
in right-to-left cases, <parameter>start_glyph</parameter> is greater than <parameter>end_glyph</parameter>.
925
 
An iterator should be initialized using either of
926
 
<link linkend="pango-glyph-item-iter-init-start"><function>pango_glyph_item_iter_init_start()</function></link> and
927
 
<link linkend="pango-glyph-item-iter-init-end"><function>pango_glyph_item_iter_init_end()</function></link>, for forward and backward iteration
928
 
respectively, and walked over using any desired mixture of
929
 
<link linkend="pango-glyph-item-iter-next-cluster"><function>pango_glyph_item_iter_next_cluster()</function></link> and
930
 
<link linkend="pango-glyph-item-iter-prev-cluster"><function>pango_glyph_item_iter_prev_cluster()</function></link>.  A common idiom for doing a
931
 
forward iteration over the clusters is:
932
 
<programlisting>
933
 
PangoGlyphItemIter cluster_iter;
934
 
gboolean have_cluster;
935
 
for (have_cluster = pango_glyph_item_iter_init_start (&amp;cluster_iter,
936
 
                                                      glyph_item, text);
937
 
     have_cluster;
938
 
     have_cluster = pango_glyph_item_iter_next_cluster (&amp;cluster_iter))
939
 
{
940
 
  ...
941
 
}
942
 
</programlisting>
943
 
Note that <parameter>text</parameter> is the start of the text for layout, which is then
944
 
indexed by <literal><parameter>glyph_item->item->offset</parameter></literal> to get to the
945
 
text of <parameter>glyph_item</parameter>.  The <parameter>start_index</parameter> and <parameter>end_index</parameter> values can directly
946
 
index into <parameter>text</parameter>.  The <parameter>start_glyph</parameter>, <parameter>end_glyph</parameter>, <parameter>start_char</parameter>, and <parameter>end_char</parameter>
947
 
values however are zero-based for the <parameter>glyph_item</parameter>.  For each cluster, the
948
 
item pointed at by the start variables is included in the cluster while
949
 
the one pointed at by end variables is not.
950
 
None of the members of a <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link> should be modified manually.
951
 
</para><variablelist role="struct">
952
 
<varlistentry>
953
 
<term><link linkend="PangoGlyphItem">PangoGlyphItem</link>&#160;*<structfield>glyph_item</structfield>;</term>
954
 
<listitem><simpara>the <link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link> this iterator iterates over
955
 
</simpara></listitem>
956
 
</varlistentry>
957
 
<varlistentry>
958
 
<term>const&#160;<link linkend="gchar">gchar</link>&#160;*<structfield>text</structfield>;</term>
959
 
<listitem><simpara>the UTF-8 text that <parameter>glyph_item</parameter> refers to
960
 
</simpara></listitem>
961
 
</varlistentry>
962
 
<varlistentry>
963
 
<term><link linkend="int">int</link>&#160;<structfield>start_glyph</structfield>;</term>
964
 
<listitem><simpara>starting glyph of the cluster
965
 
</simpara></listitem>
966
 
</varlistentry>
967
 
<varlistentry>
968
 
<term><link linkend="int">int</link>&#160;<structfield>start_index</structfield>;</term>
969
 
<listitem><simpara>starting text index of the cluster
970
 
</simpara></listitem>
971
 
</varlistentry>
972
 
<varlistentry>
973
 
<term><link linkend="int">int</link>&#160;<structfield>start_char</structfield>;</term>
974
 
<listitem><simpara>starting number of characters of the cluster
975
 
</simpara></listitem>
976
 
</varlistentry>
977
 
<varlistentry>
978
 
<term><link linkend="int">int</link>&#160;<structfield>end_glyph</structfield>;</term>
979
 
<listitem><simpara>ending glyph of the cluster
980
 
</simpara></listitem>
981
 
</varlistentry>
982
 
<varlistentry>
983
 
<term><link linkend="int">int</link>&#160;<structfield>end_index</structfield>;</term>
984
 
<listitem><simpara>ending text index of the cluster
985
 
</simpara></listitem>
986
 
</varlistentry>
987
 
<varlistentry>
988
 
<term><link linkend="int">int</link>&#160;<structfield>end_char</structfield>;</term>
989
 
<listitem><simpara>ending number of characters of the cluster
990
 
</simpara></listitem>
991
 
</varlistentry>
992
 
</variablelist><para role="since">Since 1.22</para></refsect2>
993
 
<refsect2 id="PANGO-TYPE-GLYPH-STRING--CAPS" role="macro">
994
 
<title>PANGO_TYPE_GLYPH_STRING</title>
995
 
<indexterm zone="PANGO-TYPE-GLYPH-STRING--CAPS"><primary sortas="PANGO_TYPE_GLYPH_STRING">PANGO_TYPE_GLYPH_STRING</primary></indexterm><programlisting>#define PANGO_TYPE_GLYPH_STRING (pango_glyph_string_get_type ())
996
 
</programlisting>
997
 
<para>
998
 
The <link linkend="GObject"><type>GObject</type></link> type for <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link>.
999
 
</para></refsect2>
1000
 
<refsect2 id="pango-glyph-string-new" role="function">
1001
 
<title>pango_glyph_string_new ()</title>
1002
 
<indexterm zone="pango-glyph-string-new"><primary sortas="pango_glyph_string_new">pango_glyph_string_new</primary></indexterm><programlisting><link linkend="PangoGlyphString">PangoGlyphString</link> *  pango_glyph_string_new              (void);</programlisting>
1003
 
<para>
1004
 
Create a new <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link>.</para>
1005
 
<para>
1006
 
</para><variablelist role="params">
1007
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly allocated <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link>, which
1008
 
              should be freed with <link linkend="pango-glyph-string-free"><function>pango_glyph_string_free()</function></link>.
1009
 
</simpara></listitem></varlistentry>
1010
 
</variablelist></refsect2>
1011
 
<refsect2 id="pango-glyph-string-copy" role="function">
1012
 
<title>pango_glyph_string_copy ()</title>
1013
 
<indexterm zone="pango-glyph-string-copy"><primary sortas="pango_glyph_string_copy">pango_glyph_string_copy</primary></indexterm><programlisting><link linkend="PangoGlyphString">PangoGlyphString</link> *  pango_glyph_string_copy             (<link linkend="PangoGlyphString">PangoGlyphString</link> *string);</programlisting>
1014
 
<para>
1015
 
Copy a glyph string and associated storage.</para>
1016
 
<para>
1017
 
</para><variablelist role="params">
1018
 
<varlistentry><term><parameter>string</parameter>&#160;:</term>
1019
 
<listitem><simpara> a <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link>, may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1020
 
</simpara></listitem></varlistentry>
1021
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly allocated <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link>, which
1022
 
              should be freed with <link linkend="pango-glyph-string-free"><function>pango_glyph_string_free()</function></link>,
1023
 
              or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if <parameter>string</parameter> was <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
1024
 
</simpara></listitem></varlistentry>
1025
 
</variablelist></refsect2>
1026
 
<refsect2 id="pango-glyph-string-set-size" role="function">
1027
 
<title>pango_glyph_string_set_size ()</title>
1028
 
<indexterm zone="pango-glyph-string-set-size"><primary sortas="pango_glyph_string_set_size">pango_glyph_string_set_size</primary></indexterm><programlisting><link linkend="void">void</link>                pango_glyph_string_set_size         (<link linkend="PangoGlyphString">PangoGlyphString</link> *string,
1029
 
                                                         <link linkend="gint">gint</link> new_len);</programlisting>
1030
 
<para>
1031
 
Resize a glyph string to the given length.</para>
1032
 
<para>
1033
 
</para><variablelist role="params">
1034
 
<varlistentry><term><parameter>string</parameter>&#160;:</term>
1035
 
<listitem><simpara>    a <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link>.
1036
 
</simpara></listitem></varlistentry>
1037
 
<varlistentry><term><parameter>new_len</parameter>&#160;:</term>
1038
 
<listitem><simpara>   the new length of the string.
1039
 
</simpara></listitem></varlistentry>
1040
 
</variablelist></refsect2>
1041
 
<refsect2 id="pango-glyph-string-free" role="function">
1042
 
<title>pango_glyph_string_free ()</title>
1043
 
<indexterm zone="pango-glyph-string-free"><primary sortas="pango_glyph_string_free">pango_glyph_string_free</primary></indexterm><programlisting><link linkend="void">void</link>                pango_glyph_string_free             (<link linkend="PangoGlyphString">PangoGlyphString</link> *string);</programlisting>
1044
 
<para>
1045
 
Free a glyph string and associated storage.</para>
1046
 
<para>
1047
 
</para><variablelist role="params">
1048
 
<varlistentry><term><parameter>string</parameter>&#160;:</term>
1049
 
<listitem><simpara> a <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link>, may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1050
 
</simpara></listitem></varlistentry>
1051
 
</variablelist></refsect2>
1052
 
<refsect2 id="pango-glyph-string-extents" role="function">
1053
 
<title>pango_glyph_string_extents ()</title>
1054
 
<indexterm zone="pango-glyph-string-extents"><primary sortas="pango_glyph_string_extents">pango_glyph_string_extents</primary></indexterm><programlisting><link linkend="void">void</link>                pango_glyph_string_extents          (<link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs,
1055
 
                                                         <link linkend="PangoFont">PangoFont</link> *font,
1056
 
                                                         <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
1057
 
                                                         <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);</programlisting>
1058
 
<para>
1059
 
Compute the logical and ink extents of a glyph string. See the documentation
1060
 
for <link linkend="pango-font-get-glyph-extents"><function>pango_font_get_glyph_extents()</function></link> for details about the interpretation
1061
 
of the rectangles.</para>
1062
 
<para>
1063
 
</para><variablelist role="params">
1064
 
<varlistentry><term><parameter>glyphs</parameter>&#160;:</term>
1065
 
<listitem><simpara>   a <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link>
1066
 
</simpara></listitem></varlistentry>
1067
 
<varlistentry><term><parameter>font</parameter>&#160;:</term>
1068
 
<listitem><simpara>     a <link linkend="PangoFont"><type>PangoFont</type></link>
1069
 
</simpara></listitem></varlistentry>
1070
 
<varlistentry><term><parameter>ink_rect</parameter>&#160;:</term>
1071
 
<listitem><simpara> rectangle used to store the extents of the glyph string as drawn
1072
 
           or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to indicate that the result is not needed.
1073
 
</simpara></listitem></varlistentry>
1074
 
<varlistentry><term><parameter>logical_rect</parameter>&#160;:</term>
1075
 
<listitem><simpara> rectangle used to store the logical extents of the glyph string
1076
 
           or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to indicate that the result is not needed.
1077
 
</simpara></listitem></varlistentry>
1078
 
</variablelist></refsect2>
1079
 
<refsect2 id="pango-glyph-string-extents-range" role="function">
1080
 
<title>pango_glyph_string_extents_range ()</title>
1081
 
<indexterm zone="pango-glyph-string-extents-range"><primary sortas="pango_glyph_string_extents_range">pango_glyph_string_extents_range</primary></indexterm><programlisting><link linkend="void">void</link>                pango_glyph_string_extents_range    (<link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs,
1082
 
                                                         <link linkend="int">int</link> start,
1083
 
                                                         <link linkend="int">int</link> end,
1084
 
                                                         <link linkend="PangoFont">PangoFont</link> *font,
1085
 
                                                         <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
1086
 
                                                         <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);</programlisting>
1087
 
<para>
1088
 
Computes the extents of a sub-portion of a glyph string. The extents are
1089
 
relative to the start of the glyph string range (the origin of their
1090
 
coordinate system is at the start of the range, not at the start of the entire
1091
 
glyph string).</para>
1092
 
<para>
1093
 
</para><variablelist role="params">
1094
 
<varlistentry><term><parameter>glyphs</parameter>&#160;:</term>
1095
 
<listitem><simpara>   a <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link>
1096
 
</simpara></listitem></varlistentry>
1097
 
<varlistentry><term><parameter>start</parameter>&#160;:</term>
1098
 
<listitem><simpara>    start index
1099
 
</simpara></listitem></varlistentry>
1100
 
<varlistentry><term><parameter>end</parameter>&#160;:</term>
1101
 
<listitem><simpara>      end index (the range is the set of bytes with
1102
 
              indices such that start &lt;= index &lt; end)
1103
 
</simpara></listitem></varlistentry>
1104
 
<varlistentry><term><parameter>font</parameter>&#160;:</term>
1105
 
<listitem><simpara>     a <link linkend="PangoFont"><type>PangoFont</type></link>
1106
 
</simpara></listitem></varlistentry>
1107
 
<varlistentry><term><parameter>ink_rect</parameter>&#160;:</term>
1108
 
<listitem><simpara> rectangle used to store the extents of the glyph string range as drawn
1109
 
           or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to indicate that the result is not needed.
1110
 
</simpara></listitem></varlistentry>
1111
 
<varlistentry><term><parameter>logical_rect</parameter>&#160;:</term>
1112
 
<listitem><simpara> rectangle used to store the logical extents of the glyph string range
1113
 
           or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to indicate that the result is not needed.
1114
 
</simpara></listitem></varlistentry>
1115
 
</variablelist></refsect2>
1116
 
<refsect2 id="pango-glyph-string-get-width" role="function" condition="since:1.14">
1117
 
<title>pango_glyph_string_get_width ()</title>
1118
 
<indexterm zone="pango-glyph-string-get-width" role="1.14"><primary sortas="pango_glyph_string_get_width">pango_glyph_string_get_width</primary></indexterm><programlisting><link linkend="int">int</link>                 pango_glyph_string_get_width        (<link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs);</programlisting>
1119
 
<para>
1120
 
Computes the logical width of the glyph string as can also be computed
1121
 
using <link linkend="pango-glyph-string-extents"><function>pango_glyph_string_extents()</function></link>.  However, since this only computes the
1122
 
width, it's much faster.  This is in fact only a convenience function that
1123
 
computes the sum of geometry.width for each glyph in the <parameter>glyphs</parameter>.</para>
1124
 
<para>
1125
 
</para><variablelist role="params">
1126
 
<varlistentry><term><parameter>glyphs</parameter>&#160;:</term>
1127
 
<listitem><simpara>   a <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link>
1128
 
</simpara></listitem></varlistentry>
1129
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the logical width of the glyph string.
1130
 
 
1131
 
</simpara></listitem></varlistentry>
1132
 
</variablelist><para role="since">Since 1.14</para></refsect2>
1133
 
<refsect2 id="pango-glyph-string-index-to-x" role="function">
1134
 
<title>pango_glyph_string_index_to_x ()</title>
1135
 
<indexterm zone="pango-glyph-string-index-to-x"><primary sortas="pango_glyph_string_index_to_x">pango_glyph_string_index_to_x</primary></indexterm><programlisting><link linkend="void">void</link>                pango_glyph_string_index_to_x       (<link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs,
1136
 
                                                         <link linkend="char">char</link> *text,
1137
 
                                                         <link linkend="int">int</link> length,
1138
 
                                                         <link linkend="PangoAnalysis">PangoAnalysis</link> *analysis,
1139
 
                                                         <link linkend="int">int</link> index_,
1140
 
                                                         <link linkend="gboolean">gboolean</link> trailing,
1141
 
                                                         <link linkend="int">int</link> *x_pos);</programlisting>
1142
 
<para>
1143
 
Converts from character position to x position. (X position
1144
 
is measured from the left edge of the run). Character positions
1145
 
are computed by dividing up each cluster into equal portions.</para>
1146
 
<para>
1147
 
</para><variablelist role="params">
1148
 
<varlistentry><term><parameter>glyphs</parameter>&#160;:</term>
1149
 
<listitem><simpara>    the glyphs return from <link linkend="pango-shape"><function>pango_shape()</function></link>
1150
 
</simpara></listitem></varlistentry>
1151
 
<varlistentry><term><parameter>text</parameter>&#160;:</term>
1152
 
<listitem><simpara>      the text for the run
1153
 
</simpara></listitem></varlistentry>
1154
 
<varlistentry><term><parameter>length</parameter>&#160;:</term>
1155
 
<listitem><simpara>    the number of bytes (not characters) in <parameter>text</parameter>.
1156
 
</simpara></listitem></varlistentry>
1157
 
<varlistentry><term><parameter>analysis</parameter>&#160;:</term>
1158
 
<listitem><simpara>  the analysis information return from <link linkend="pango-itemize"><function>pango_itemize()</function></link>
1159
 
</simpara></listitem></varlistentry>
1160
 
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
1161
 
<listitem><simpara>    the byte index within <parameter>text</parameter>
1162
 
</simpara></listitem></varlistentry>
1163
 
<varlistentry><term><parameter>trailing</parameter>&#160;:</term>
1164
 
<listitem><simpara>  whether we should compute the result for the beginning (<link linkend="FALSE--CAPS"><literal>FALSE</literal></link>)
1165
 
            or end (<link linkend="TRUE--CAPS"><literal>TRUE</literal></link>) of the character.
1166
 
</simpara></listitem></varlistentry>
1167
 
<varlistentry><term><parameter>x_pos</parameter>&#160;:</term>
1168
 
<listitem><simpara>     location to store result
1169
 
</simpara></listitem></varlistentry>
1170
 
</variablelist></refsect2>
1171
 
<refsect2 id="pango-glyph-string-x-to-index" role="function">
1172
 
<title>pango_glyph_string_x_to_index ()</title>
1173
 
<indexterm zone="pango-glyph-string-x-to-index"><primary sortas="pango_glyph_string_x_to_index">pango_glyph_string_x_to_index</primary></indexterm><programlisting><link linkend="void">void</link>                pango_glyph_string_x_to_index       (<link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs,
1174
 
                                                         <link linkend="char">char</link> *text,
1175
 
                                                         <link linkend="int">int</link> length,
1176
 
                                                         <link linkend="PangoAnalysis">PangoAnalysis</link> *analysis,
1177
 
                                                         <link linkend="int">int</link> x_pos,
1178
 
                                                         <link linkend="int">int</link> *index_,
1179
 
                                                         <link linkend="int">int</link> *trailing);</programlisting>
1180
 
<para>
1181
 
Convert from x offset to character position. Character positions
1182
 
are computed by dividing up each cluster into equal portions.
1183
 
In scripts where positioning within a cluster is not allowed
1184
 
(such as Thai), the returned value may not be a valid cursor
1185
 
position; the caller must combine the result with the logical
1186
 
attributes for the text to compute the valid cursor position.</para>
1187
 
<para>
1188
 
</para><variablelist role="params">
1189
 
<varlistentry><term><parameter>glyphs</parameter>&#160;:</term>
1190
 
<listitem><simpara>    the glyphs returned from <link linkend="pango-shape"><function>pango_shape()</function></link>
1191
 
</simpara></listitem></varlistentry>
1192
 
<varlistentry><term><parameter>text</parameter>&#160;:</term>
1193
 
<listitem><simpara>      the text for the run
1194
 
</simpara></listitem></varlistentry>
1195
 
<varlistentry><term><parameter>length</parameter>&#160;:</term>
1196
 
<listitem><simpara>    the number of bytes (not characters) in text.
1197
 
</simpara></listitem></varlistentry>
1198
 
<varlistentry><term><parameter>analysis</parameter>&#160;:</term>
1199
 
<listitem><simpara>  the analysis information return from <link linkend="pango-itemize"><function>pango_itemize()</function></link>
1200
 
</simpara></listitem></varlistentry>
1201
 
<varlistentry><term><parameter>x_pos</parameter>&#160;:</term>
1202
 
<listitem><simpara>     the x offset (in Pango units)
1203
 
</simpara></listitem></varlistentry>
1204
 
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
1205
 
<listitem><simpara>    location to store calculated byte index within <parameter>text</parameter>
1206
 
</simpara></listitem></varlistentry>
1207
 
<varlistentry><term><parameter>trailing</parameter>&#160;:</term>
1208
 
<listitem><simpara>  location to store a boolean indicating
1209
 
            whether the user clicked on the leading or trailing
1210
 
            edge of the character.
1211
 
</simpara></listitem></varlistentry>
1212
 
</variablelist></refsect2>
1213
 
<refsect2 id="pango-glyph-string-get-logical-widths" role="function">
1214
 
<title>pango_glyph_string_get_logical_widths ()</title>
1215
 
<indexterm zone="pango-glyph-string-get-logical-widths"><primary sortas="pango_glyph_string_get_logical_widths">pango_glyph_string_get_logical_widths</primary></indexterm><programlisting><link linkend="void">void</link>                pango_glyph_string_get_logical_widths
1216
 
                                                        (<link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs,
1217
 
                                                         const <link linkend="char">char</link> *text,
1218
 
                                                         <link linkend="int">int</link> length,
1219
 
                                                         <link linkend="int">int</link> embedding_level,
1220
 
                                                         <link linkend="int">int</link> *logical_widths);</programlisting>
1221
 
<para>
1222
 
Given a <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link> resulting from <link linkend="pango-shape"><function>pango_shape()</function></link> and the corresponding
1223
 
text, determine the screen width corresponding to each character. When
1224
 
multiple characters compose a single cluster, the width of the entire
1225
 
cluster is divided equally among the characters.
1226
 
</para>
1227
 
<para>
1228
 
See also <link linkend="pango-glyph-item-get-logical-widths"><function>pango_glyph_item_get_logical_widths()</function></link>.</para>
1229
 
<para>
1230
 
</para><variablelist role="params">
1231
 
<varlistentry><term><parameter>glyphs</parameter>&#160;:</term>
1232
 
<listitem><simpara> a <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link>
1233
 
</simpara></listitem></varlistentry>
1234
 
<varlistentry><term><parameter>text</parameter>&#160;:</term>
1235
 
<listitem><simpara> the text corresponding to the glyphs
1236
 
</simpara></listitem></varlistentry>
1237
 
<varlistentry><term><parameter>length</parameter>&#160;:</term>
1238
 
<listitem><simpara> the length of <parameter>text</parameter>, in bytes
1239
 
</simpara></listitem></varlistentry>
1240
 
<varlistentry><term><parameter>embedding_level</parameter>&#160;:</term>
1241
 
<listitem><simpara> the embedding level of the string
1242
 
</simpara></listitem></varlistentry>
1243
 
<varlistentry><term><parameter>logical_widths</parameter>&#160;:</term>
1244
 
<listitem><simpara> an array whose length is the number of characters in
1245
 
                 text (equal to g_utf8_strlen (text, length) unless
1246
 
                 text has NUL bytes)
1247
 
                 to be filled in with the resulting character widths.
1248
 
</simpara></listitem></varlistentry>
1249
 
</variablelist></refsect2>
1250
 
<refsect2 id="PANGO-TYPE-GLYPH-ITEM--CAPS" role="macro" condition="since:1.20">
1251
 
<title>PANGO_TYPE_GLYPH_ITEM</title>
1252
 
<indexterm zone="PANGO-TYPE-GLYPH-ITEM--CAPS" role="1.20"><primary sortas="PANGO_TYPE_GLYPH_ITEM">PANGO_TYPE_GLYPH_ITEM</primary></indexterm><programlisting>#define PANGO_TYPE_GLYPH_ITEM (pango_glyph_item_get_type ())
1253
 
</programlisting>
1254
 
<para>
1255
 
The <link linkend="GObject"><type>GObject</type></link> type for <link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link>.
1256
 
</para><para role="since">Since 1.20</para></refsect2>
1257
 
<refsect2 id="pango-glyph-item-copy" role="function" condition="since:1.20">
1258
 
<title>pango_glyph_item_copy ()</title>
1259
 
<indexterm zone="pango-glyph-item-copy" role="1.20"><primary sortas="pango_glyph_item_copy">pango_glyph_item_copy</primary></indexterm><programlisting><link linkend="PangoGlyphItem">PangoGlyphItem</link> *    pango_glyph_item_copy               (<link linkend="PangoGlyphItem">PangoGlyphItem</link> *orig);</programlisting>
1260
 
<para>
1261
 
Make a deep copy of an existing <link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link> structure.</para>
1262
 
<para>
1263
 
</para><variablelist role="params">
1264
 
<varlistentry><term><parameter>orig</parameter>&#160;:</term>
1265
 
<listitem><simpara> a <link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link>, may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1266
 
</simpara></listitem></varlistentry>
1267
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly allocated <link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link>, which should
1268
 
              be freed with <link linkend="pango-glyph-item-free"><function>pango_glyph_item_free()</function></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1269
 
              if <parameter>orig</parameter> was <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
1270
 
 
1271
 
</simpara></listitem></varlistentry>
1272
 
</variablelist><para role="since">Since 1.20</para></refsect2>
1273
 
<refsect2 id="pango-glyph-item-free" role="function" condition="since:1.6">
1274
 
<title>pango_glyph_item_free ()</title>
1275
 
<indexterm zone="pango-glyph-item-free" role="1.6"><primary sortas="pango_glyph_item_free">pango_glyph_item_free</primary></indexterm><programlisting><link linkend="void">void</link>                pango_glyph_item_free               (<link linkend="PangoGlyphItem">PangoGlyphItem</link> *glyph_item);</programlisting>
1276
 
<para>
1277
 
Frees a <link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link> and resources to which it points.</para>
1278
 
<para>
1279
 
</para><variablelist role="params">
1280
 
<varlistentry><term><parameter>glyph_item</parameter>&#160;:</term>
1281
 
<listitem><simpara> a <link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link>, may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1282
 
</simpara></listitem></varlistentry>
1283
 
</variablelist><para role="since">Since 1.6</para></refsect2>
1284
 
<refsect2 id="pango-glyph-item-split" role="function" condition="since:1.2">
1285
 
<title>pango_glyph_item_split ()</title>
1286
 
<indexterm zone="pango-glyph-item-split" role="1.2"><primary sortas="pango_glyph_item_split">pango_glyph_item_split</primary></indexterm><programlisting><link linkend="PangoGlyphItem">PangoGlyphItem</link> *    pango_glyph_item_split              (<link linkend="PangoGlyphItem">PangoGlyphItem</link> *orig,
1287
 
                                                         const <link linkend="char">char</link> *text,
1288
 
                                                         <link linkend="int">int</link> split_index);</programlisting>
1289
 
<para>
1290
 
Modifies <parameter>orig</parameter> to cover only the text after <parameter>split_index</parameter>, and
1291
 
returns a new item that covers the text before <parameter>split_index</parameter> that
1292
 
used to be in <parameter>orig</parameter>. You can think of <parameter>split_index</parameter> as the length of
1293
 
the returned item. <parameter>split_index</parameter> may not be 0, and it may not be
1294
 
greater than or equal to the length of <parameter>orig</parameter> (that is, there must
1295
 
be at least one byte assigned to each item, you can't create a
1296
 
zero-length item).
1297
 
</para>
1298
 
<para>
1299
 
This function is similar in function to <link linkend="pango-item-split"><function>pango_item_split()</function></link> (and uses
1300
 
it internally.)</para>
1301
 
<para>
1302
 
</para><variablelist role="params">
1303
 
<varlistentry><term><parameter>orig</parameter>&#160;:</term>
1304
 
<listitem><simpara> a <link linkend="PangoItem"><type>PangoItem</type></link>
1305
 
</simpara></listitem></varlistentry>
1306
 
<varlistentry><term><parameter>text</parameter>&#160;:</term>
1307
 
<listitem><simpara> text to which positions in <parameter>orig</parameter> apply
1308
 
</simpara></listitem></varlistentry>
1309
 
<varlistentry><term><parameter>split_index</parameter>&#160;:</term>
1310
 
<listitem><simpara> byte index of position to split item, relative to the start of the item
1311
 
</simpara></listitem></varlistentry>
1312
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly allocated item representing text before
1313
 
              <parameter>split_index</parameter>, which should be freed
1314
 
              with <link linkend="pango-glyph-item-free"><function>pango_glyph_item_free()</function></link>.
1315
 
 
1316
 
</simpara></listitem></varlistentry>
1317
 
</variablelist><para role="since">Since 1.2</para></refsect2>
1318
 
<refsect2 id="pango-glyph-item-apply-attrs" role="function" condition="since:1.2">
1319
 
<title>pango_glyph_item_apply_attrs ()</title>
1320
 
<indexterm zone="pango-glyph-item-apply-attrs" role="1.2"><primary sortas="pango_glyph_item_apply_attrs">pango_glyph_item_apply_attrs</primary></indexterm><programlisting><link linkend="GSList">GSList</link> *            pango_glyph_item_apply_attrs        (<link linkend="PangoGlyphItem">PangoGlyphItem</link> *glyph_item,
1321
 
                                                         const <link linkend="char">char</link> *text,
1322
 
                                                         <link linkend="PangoAttrList">PangoAttrList</link> *list);</programlisting>
1323
 
<para>
1324
 
Splits a shaped item (PangoGlyphItem) into multiple items based
1325
 
on an attribute list. The idea is that if you have attributes
1326
 
that don't affect shaping, such as color or underline, to avoid
1327
 
affecting shaping, you filter them out (<link linkend="pango-attr-list-filter"><function>pango_attr_list_filter()</function></link>),
1328
 
apply the shaping process and then reapply them to the result using
1329
 
this function.
1330
 
</para>
1331
 
<para>
1332
 
All attributes that start or end inside a cluster are applied
1333
 
to that cluster; for instance, if half of a cluster is underlined
1334
 
and the other-half strikethrough, then the cluster will end
1335
 
up with both underline and strikethrough attributes. In these
1336
 
cases, it may happen that item->extra_attrs for some of the
1337
 
result items can have multiple attributes of the same type.
1338
 
</para>
1339
 
<para>
1340
 
This function takes ownership of <parameter>glyph_item</parameter>; it will be reused
1341
 
as one of the elements in the list.</para>
1342
 
<para>
1343
 
</para><variablelist role="params">
1344
 
<varlistentry><term><parameter>glyph_item</parameter>&#160;:</term>
1345
 
<listitem><simpara> a shaped item
1346
 
</simpara></listitem></varlistentry>
1347
 
<varlistentry><term><parameter>text</parameter>&#160;:</term>
1348
 
<listitem><simpara> text that <parameter>list</parameter> applies to
1349
 
</simpara></listitem></varlistentry>
1350
 
<varlistentry><term><parameter>list</parameter>&#160;:</term>
1351
 
<listitem><simpara> a <link linkend="PangoAttrList"><type>PangoAttrList</type></link>
1352
 
</simpara></listitem></varlistentry>
1353
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a list of glyph items resulting from splitting
1354
 
  <parameter>glyph_item</parameter>. Free the elements using <link linkend="pango-glyph-item-free"><function>pango_glyph_item_free()</function></link>,
1355
 
  the list using <link linkend="g-slist-free"><function>g_slist_free()</function></link>.
1356
 
 
1357
 
</simpara></listitem></varlistentry>
1358
 
</variablelist><para role="since">Since 1.2</para></refsect2>
1359
 
<refsect2 id="pango-glyph-item-letter-space" role="function" condition="since:1.6">
1360
 
<title>pango_glyph_item_letter_space ()</title>
1361
 
<indexterm zone="pango-glyph-item-letter-space" role="1.6"><primary sortas="pango_glyph_item_letter_space">pango_glyph_item_letter_space</primary></indexterm><programlisting><link linkend="void">void</link>                pango_glyph_item_letter_space       (<link linkend="PangoGlyphItem">PangoGlyphItem</link> *glyph_item,
1362
 
                                                         const <link linkend="char">char</link> *text,
1363
 
                                                         <link linkend="PangoLogAttr">PangoLogAttr</link> *log_attrs,
1364
 
                                                         <link linkend="int">int</link> letter_spacing);</programlisting>
1365
 
<para>
1366
 
Adds spacing between the graphemes of <parameter>glyph_item</parameter> to
1367
 
give the effect of typographic letter spacing.</para>
1368
 
<para>
1369
 
</para><variablelist role="params">
1370
 
<varlistentry><term><parameter>glyph_item</parameter>&#160;:</term>
1371
 
<listitem><simpara> a <link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link>
1372
 
</simpara></listitem></varlistentry>
1373
 
<varlistentry><term><parameter>text</parameter>&#160;:</term>
1374
 
<listitem><simpara> text that <parameter>glyph_item</parameter> corresponds to
1375
 
  (glyph_item->item->offset is an offset from the
1376
 
   start of <parameter>text</parameter>)
1377
 
</simpara></listitem></varlistentry>
1378
 
<varlistentry><term><parameter>log_attrs</parameter>&#160;:</term>
1379
 
<listitem><simpara> logical attributes for the item (the
1380
 
  first logical attribute refers to the position
1381
 
  before the first character in the item)
1382
 
</simpara></listitem></varlistentry>
1383
 
<varlistentry><term><parameter>letter_spacing</parameter>&#160;:</term>
1384
 
<listitem><simpara> amount of letter spacing to add
1385
 
  in Pango units. May be negative, though too large
1386
 
  negative values will give ugly results.
1387
 
</simpara></listitem></varlistentry>
1388
 
</variablelist><para role="since">Since 1.6</para></refsect2>
1389
 
<refsect2 id="pango-glyph-item-get-logical-widths" role="function" condition="since:1.26">
1390
 
<title>pango_glyph_item_get_logical_widths ()</title>
1391
 
<indexterm zone="pango-glyph-item-get-logical-widths" role="1.26"><primary sortas="pango_glyph_item_get_logical_widths">pango_glyph_item_get_logical_widths</primary></indexterm><programlisting><link linkend="void">void</link>                pango_glyph_item_get_logical_widths (<link linkend="PangoGlyphItem">PangoGlyphItem</link> *glyph_item,
1392
 
                                                         const <link linkend="char">char</link> *text,
1393
 
                                                         <link linkend="int">int</link> *logical_widths);</programlisting>
1394
 
<para>
1395
 
Given a <link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link> and the corresponding
1396
 
text, determine the screen width corresponding to each character. When
1397
 
multiple characters compose a single cluster, the width of the entire
1398
 
cluster is divided equally among the characters.
1399
 
</para>
1400
 
<para>
1401
 
See also <link linkend="pango-glyph-string-get-logical-widths"><function>pango_glyph_string_get_logical_widths()</function></link>.</para>
1402
 
<para>
1403
 
</para><variablelist role="params">
1404
 
<varlistentry><term><parameter>glyph_item</parameter>&#160;:</term>
1405
 
<listitem><simpara> a <link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link>
1406
 
</simpara></listitem></varlistentry>
1407
 
<varlistentry><term><parameter>text</parameter>&#160;:</term>
1408
 
<listitem><simpara> text that <parameter>glyph_item</parameter> corresponds to
1409
 
  (glyph_item->item->offset is an offset from the
1410
 
   start of <parameter>text</parameter>)
1411
 
</simpara></listitem></varlistentry>
1412
 
<varlistentry><term><parameter>logical_widths</parameter>&#160;:</term>
1413
 
<listitem><simpara> an array whose length is the number of characters in
1414
 
                 glyph_item (equal to glyph_item->item->num_chars)
1415
 
                 to be filled in with the resulting character widths.
1416
 
</simpara></listitem></varlistentry>
1417
 
</variablelist><para role="since">Since 1.26</para></refsect2>
1418
 
<refsect2 id="PANGO-TYPE-GLYPH-ITEM-ITER--CAPS" role="macro" condition="since:1.22">
1419
 
<title>PANGO_TYPE_GLYPH_ITEM_ITER</title>
1420
 
<indexterm zone="PANGO-TYPE-GLYPH-ITEM-ITER--CAPS" role="1.22"><primary sortas="PANGO_TYPE_GLYPH_ITEM_ITER">PANGO_TYPE_GLYPH_ITEM_ITER</primary></indexterm><programlisting>#define PANGO_TYPE_GLYPH_ITEM_ITER (pango_glyph_item_iter_get_type ())
1421
 
</programlisting>
1422
 
<para>
1423
 
The <link linkend="GObject"><type>GObject</type></link> type for <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link>.
1424
 
</para><para role="since">Since 1.22</para></refsect2>
1425
 
<refsect2 id="pango-glyph-item-iter-copy" role="function" condition="since:1.22">
1426
 
<title>pango_glyph_item_iter_copy ()</title>
1427
 
<indexterm zone="pango-glyph-item-iter-copy" role="1.22"><primary sortas="pango_glyph_item_iter_copy">pango_glyph_item_iter_copy</primary></indexterm><programlisting><link linkend="PangoGlyphItemIter">PangoGlyphItemIter</link> * pango_glyph_item_iter_copy         (<link linkend="PangoGlyphItemIter">PangoGlyphItemIter</link> *orig);</programlisting>
1428
 
<para>
1429
 
Make a shallow copy of an existing <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link> structure.</para>
1430
 
<para>
1431
 
</para><variablelist role="params">
1432
 
<varlistentry><term><parameter>orig</parameter>&#160;:</term>
1433
 
<listitem><simpara> a <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link>, may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1434
 
</simpara></listitem></varlistentry>
1435
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly allocated <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link>, which should
1436
 
              be freed with <link linkend="pango-glyph-item-iter-free"><function>pango_glyph_item_iter_free()</function></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1437
 
              if <parameter>orig</parameter> was <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
1438
 
 
1439
 
</simpara></listitem></varlistentry>
1440
 
</variablelist><para role="since">Since 1.22</para></refsect2>
1441
 
<refsect2 id="pango-glyph-item-iter-free" role="function" condition="since:1.22">
1442
 
<title>pango_glyph_item_iter_free ()</title>
1443
 
<indexterm zone="pango-glyph-item-iter-free" role="1.22"><primary sortas="pango_glyph_item_iter_free">pango_glyph_item_iter_free</primary></indexterm><programlisting><link linkend="void">void</link>                pango_glyph_item_iter_free          (<link linkend="PangoGlyphItemIter">PangoGlyphItemIter</link> *iter);</programlisting>
1444
 
<para>
1445
 
Frees a <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link> created by <link linkend="pango-glyph-item-iter-copy"><function>pango_glyph_item_iter_copy()</function></link>.</para>
1446
 
<para>
1447
 
</para><variablelist role="params">
1448
 
<varlistentry><term><parameter>iter</parameter>&#160;:</term>
1449
 
<listitem><simpara> a <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link>, may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1450
 
</simpara></listitem></varlistentry>
1451
 
</variablelist><para role="since">Since 1.22</para></refsect2>
1452
 
<refsect2 id="pango-glyph-item-iter-init-start" role="function" condition="since:1.22">
1453
 
<title>pango_glyph_item_iter_init_start ()</title>
1454
 
<indexterm zone="pango-glyph-item-iter-init-start" role="1.22"><primary sortas="pango_glyph_item_iter_init_start">pango_glyph_item_iter_init_start</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_glyph_item_iter_init_start    (<link linkend="PangoGlyphItemIter">PangoGlyphItemIter</link> *iter,
1455
 
                                                         <link linkend="PangoGlyphItem">PangoGlyphItem</link> *glyph_item,
1456
 
                                                         const <link linkend="char">char</link> *text);</programlisting>
1457
 
<para>
1458
 
Initializes a <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link> structure to point to the
1459
 
first cluster in a glyph item.
1460
 
See <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link> for details of cluster orders.</para>
1461
 
<para>
1462
 
</para><variablelist role="params">
1463
 
<varlistentry><term><parameter>iter</parameter>&#160;:</term>
1464
 
<listitem><simpara> a <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link>
1465
 
</simpara></listitem></varlistentry>
1466
 
<varlistentry><term><parameter>glyph_item</parameter>&#160;:</term>
1467
 
<listitem><simpara> the glyph item to iterate over
1468
 
</simpara></listitem></varlistentry>
1469
 
<varlistentry><term><parameter>text</parameter>&#160;:</term>
1470
 
<listitem><simpara> text corresponding to the glyph item
1471
 
</simpara></listitem></varlistentry>
1472
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if there are no clusters in the glyph item
1473
 
 
1474
 
</simpara></listitem></varlistentry>
1475
 
</variablelist><para role="since">Since 1.22</para></refsect2>
1476
 
<refsect2 id="pango-glyph-item-iter-init-end" role="function" condition="since:1.22">
1477
 
<title>pango_glyph_item_iter_init_end ()</title>
1478
 
<indexterm zone="pango-glyph-item-iter-init-end" role="1.22"><primary sortas="pango_glyph_item_iter_init_end">pango_glyph_item_iter_init_end</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_glyph_item_iter_init_end      (<link linkend="PangoGlyphItemIter">PangoGlyphItemIter</link> *iter,
1479
 
                                                         <link linkend="PangoGlyphItem">PangoGlyphItem</link> *glyph_item,
1480
 
                                                         const <link linkend="char">char</link> *text);</programlisting>
1481
 
<para>
1482
 
Initializes a <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link> structure to point to the
1483
 
last cluster in a glyph item.
1484
 
See <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link> for details of cluster orders.</para>
1485
 
<para>
1486
 
</para><variablelist role="params">
1487
 
<varlistentry><term><parameter>iter</parameter>&#160;:</term>
1488
 
<listitem><simpara> a <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link>
1489
 
</simpara></listitem></varlistentry>
1490
 
<varlistentry><term><parameter>glyph_item</parameter>&#160;:</term>
1491
 
<listitem><simpara> the glyph item to iterate over
1492
 
</simpara></listitem></varlistentry>
1493
 
<varlistentry><term><parameter>text</parameter>&#160;:</term>
1494
 
<listitem><simpara> text corresponding to the glyph item
1495
 
</simpara></listitem></varlistentry>
1496
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if there are no clusters in the glyph item
1497
 
 
1498
 
</simpara></listitem></varlistentry>
1499
 
</variablelist><para role="since">Since 1.22</para></refsect2>
1500
 
<refsect2 id="pango-glyph-item-iter-next-cluster" role="function" condition="since:1.22">
1501
 
<title>pango_glyph_item_iter_next_cluster ()</title>
1502
 
<indexterm zone="pango-glyph-item-iter-next-cluster" role="1.22"><primary sortas="pango_glyph_item_iter_next_cluster">pango_glyph_item_iter_next_cluster</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_glyph_item_iter_next_cluster  (<link linkend="PangoGlyphItemIter">PangoGlyphItemIter</link> *iter);</programlisting>
1503
 
<para>
1504
 
Advances the iterator to the next cluster in the glyph item.
1505
 
See <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link> for details of cluster orders.</para>
1506
 
<para>
1507
 
</para><variablelist role="params">
1508
 
<varlistentry><term><parameter>iter</parameter>&#160;:</term>
1509
 
<listitem><simpara> a <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link>
1510
 
</simpara></listitem></varlistentry>
1511
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the iterator was advanced, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if we were already on the
1512
 
 last cluster.
1513
 
 
1514
 
</simpara></listitem></varlistentry>
1515
 
</variablelist><para role="since">Since 1.22</para></refsect2>
1516
 
<refsect2 id="pango-glyph-item-iter-prev-cluster" role="function" condition="since:1.22">
1517
 
<title>pango_glyph_item_iter_prev_cluster ()</title>
1518
 
<indexterm zone="pango-glyph-item-iter-prev-cluster" role="1.22"><primary sortas="pango_glyph_item_iter_prev_cluster">pango_glyph_item_iter_prev_cluster</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_glyph_item_iter_prev_cluster  (<link linkend="PangoGlyphItemIter">PangoGlyphItemIter</link> *iter);</programlisting>
1519
 
<para>
1520
 
Moves the iterator to the preceding cluster in the glyph item.
1521
 
See <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link> for details of cluster orders.</para>
1522
 
<para>
1523
 
</para><variablelist role="params">
1524
 
<varlistentry><term><parameter>iter</parameter>&#160;:</term>
1525
 
<listitem><simpara> a <link linkend="PangoGlyphItemIter"><type>PangoGlyphItemIter</type></link>
1526
 
</simpara></listitem></varlistentry>
1527
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the iterator was moved, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if we were already on the
1528
 
 first cluster.
1529
 
 
1530
 
</simpara></listitem></varlistentry>
1531
 
</variablelist><para role="since">Since 1.22</para></refsect2>
1532
 
 
1533
 
</refsect1>
1534
 
 
1535
 
 
1536
 
 
1537
 
 
1538
 
</refentry>