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>