docs/xml/pangocairo.xml

   1 <refentry id="pango-Cairo-Rendering">
   2 <refmeta>
   3 <refentrytitle role="top_of_page" id="pango-Cairo-Rendering.top_of_page">Cairo Rendering</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>PANGO Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Cairo Rendering</refname>
  10 <refpurpose>Rendering with the Cairo backend</refpurpose>
  11 </refnamediv>
  12
  13 <refsynopsisdiv id="pango-Cairo-Rendering.synopsis" role="synopsis">
  14 <title role="synopsis.title">Synopsis</title>
  15 <anchor id="PangoCairoFont"/><anchor id="PangoCairoFontMap"/>
  16 <synopsis>
  17                     <link linkend="PangoCairoFont-struct">PangoCairoFont</link>;
  18                     <link linkend="PangoCairoFontMap-struct">PangoCairoFontMap</link>;
  19 <link linkend="PangoFontMap">PangoFontMap</link> *      <link linkend="pango-cairo-font-map-get-default">pango_cairo_font_map_get_default</link>    (void);
  20 <link linkend="void">void</link>                <link linkend="pango-cairo-font-map-set-default">pango_cairo_font_map_set_default</link>    (<link linkend="PangoCairoFontMap">PangoCairoFontMap</link> *fontmap);
  21 <link linkend="PangoFontMap">PangoFontMap</link> *      <link linkend="pango-cairo-font-map-new">pango_cairo_font_map_new</link>            (void);
  22 <link linkend="PangoFontMap">PangoFontMap</link> *      <link linkend="pango-cairo-font-map-new-for-font-type">pango_cairo_font_map_new_for_font_type</link>
  23                                                         (<link linkend="cairo-font-type-t">cairo_font_type_t</link> fonttype);
  24 <link linkend="cairo-font-type-t">cairo_font_type_t</link>   <link linkend="pango-cairo-font-map-get-font-type">pango_cairo_font_map_get_font_type</link>  (<link linkend="PangoCairoFontMap">PangoCairoFontMap</link> *fontmap);
  25 <link linkend="void">void</link>                <link linkend="pango-cairo-font-map-set-resolution">pango_cairo_font_map_set_resolution</link> (<link linkend="PangoCairoFontMap">PangoCairoFontMap</link> *fontmap,
  26                                                          <link linkend="double">double</link> dpi);
  27 <link linkend="double">double</link>              <link linkend="pango-cairo-font-map-get-resolution">pango_cairo_font_map_get_resolution</link> (<link linkend="PangoCairoFontMap">PangoCairoFontMap</link> *fontmap);
  28 <link linkend="PangoContext">PangoContext</link> *      <link linkend="pango-cairo-font-map-create-context">pango_cairo_font_map_create_context</link> (<link linkend="PangoCairoFontMap">PangoCairoFontMap</link> *fontmap);
  29 <link linkend="cairo-scaled-font-t">cairo_scaled_font_t</link> * <link linkend="pango-cairo-font-get-scaled-font">pango_cairo_font_get_scaled_font</link>  (<link linkend="PangoCairoFont">PangoCairoFont</link> *font);
  30 <link linkend="void">void</link>                <link linkend="pango-cairo-context-set-resolution">pango_cairo_context_set_resolution</link>  (<link linkend="PangoContext">PangoContext</link> *context,
  31                                                          <link linkend="double">double</link> dpi);
  32 <link linkend="double">double</link>              <link linkend="pango-cairo-context-get-resolution">pango_cairo_context_get_resolution</link>  (<link linkend="PangoContext">PangoContext</link> *context);
  33 <link linkend="void">void</link>                <link linkend="pango-cairo-context-set-font-options">pango_cairo_context_set_font_options</link>
  34                                                         (<link linkend="PangoContext">PangoContext</link> *context,
  35                                                          const <link linkend="cairo-font-options-t">cairo_font_options_t</link> *options);
  36 const <link linkend="cairo-font-options-t">cairo_font_options_t</link> * <link linkend="pango-cairo-context-get-font-options">pango_cairo_context_get_font_options</link>
  37                                                         (<link linkend="PangoContext">PangoContext</link> *context);
  38 <link linkend="void">void</link>                (<link linkend="PangoCairoShapeRendererFunc">*PangoCairoShapeRendererFunc</link>)      (<link linkend="cairo-t">cairo_t</link> *cr,
  39                                                          <link linkend="PangoAttrShape">PangoAttrShape</link> *attr,
  40                                                          <link linkend="gboolean">gboolean</link> do_path,
  41                                                          <link linkend="gpointer">gpointer</link> data);
  42 <link linkend="void">void</link>                <link linkend="pango-cairo-context-set-shape-renderer">pango_cairo_context_set_shape_renderer</link>
  43                                                         (<link linkend="PangoContext">PangoContext</link> *context,
  44                                                          <link linkend="PangoCairoShapeRendererFunc">PangoCairoShapeRendererFunc</link> func,
  45                                                          <link linkend="gpointer">gpointer</link> data,
  46                                                          <link linkend="GDestroyNotify">GDestroyNotify</link> dnotify);
  47 <link linkend="PangoCairoShapeRendererFunc">PangoCairoShapeRendererFunc</link>  <link linkend="pango-cairo-context-get-shape-renderer">pango_cairo_context_get_shape_renderer</link>
  48                                                         (<link linkend="PangoContext">PangoContext</link> *context,
  49                                                          <link linkend="gpointer">gpointer</link> *data);
  50 <link linkend="PangoContext">PangoContext</link> *      <link linkend="pango-cairo-create-context">pango_cairo_create_context</link>          (<link linkend="cairo-t">cairo_t</link> *cr);
  51 <link linkend="void">void</link>                <link linkend="pango-cairo-update-context">pango_cairo_update_context</link>          (<link linkend="cairo-t">cairo_t</link> *cr,
  52                                                          <link linkend="PangoContext">PangoContext</link> *context);
  53 <link linkend="PangoLayout">PangoLayout</link> *       <link linkend="pango-cairo-create-layout">pango_cairo_create_layout</link>           (<link linkend="cairo-t">cairo_t</link> *cr);
  54 <link linkend="void">void</link>                <link linkend="pango-cairo-update-layout">pango_cairo_update_layout</link>           (<link linkend="cairo-t">cairo_t</link> *cr,
  55                                                          <link linkend="PangoLayout">PangoLayout</link> *layout);
  56 <link linkend="void">void</link>                <link linkend="pango-cairo-show-glyph-string">pango_cairo_show_glyph_string</link>       (<link linkend="cairo-t">cairo_t</link> *cr,
  57                                                          <link linkend="PangoFont">PangoFont</link> *font,
  58                                                          <link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs);
  59 <link linkend="void">void</link>                <link linkend="pango-cairo-show-glyph-item">pango_cairo_show_glyph_item</link>         (<link linkend="cairo-t">cairo_t</link> *cr,
  60                                                          const <link linkend="char">char</link> *text,
  61                                                          <link linkend="PangoGlyphItem">PangoGlyphItem</link> *glyph_item);
  62 <link linkend="void">void</link>                <link linkend="pango-cairo-show-layout-line">pango_cairo_show_layout_line</link>        (<link linkend="cairo-t">cairo_t</link> *cr,
  63                                                          <link linkend="PangoLayoutLine">PangoLayoutLine</link> *line);
  64 <link linkend="void">void</link>                <link linkend="pango-cairo-show-layout">pango_cairo_show_layout</link>             (<link linkend="cairo-t">cairo_t</link> *cr,
  65                                                          <link linkend="PangoLayout">PangoLayout</link> *layout);
  66 <link linkend="void">void</link>                <link linkend="pango-cairo-show-error-underline">pango_cairo_show_error_underline</link>    (<link linkend="cairo-t">cairo_t</link> *cr,
  67                                                          <link linkend="double">double</link> x,
  68                                                          <link linkend="double">double</link> y,
  69                                                          <link linkend="double">double</link> width,
  70                                                          <link linkend="double">double</link> height);
  71 <link linkend="void">void</link>                <link linkend="pango-cairo-glyph-string-path">pango_cairo_glyph_string_path</link>       (<link linkend="cairo-t">cairo_t</link> *cr,
  72                                                          <link linkend="PangoFont">PangoFont</link> *font,
  73                                                          <link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs);
  74 <link linkend="void">void</link>                <link linkend="pango-cairo-layout-line-path">pango_cairo_layout_line_path</link>        (<link linkend="cairo-t">cairo_t</link> *cr,
  75                                                          <link linkend="PangoLayoutLine">PangoLayoutLine</link> *line);
  76 <link linkend="void">void</link>                <link linkend="pango-cairo-layout-path">pango_cairo_layout_path</link>             (<link linkend="cairo-t">cairo_t</link> *cr,
  77                                                          <link linkend="PangoLayout">PangoLayout</link> *layout);
  78 <link linkend="void">void</link>                <link linkend="pango-cairo-error-underline-path">pango_cairo_error_underline_path</link>    (<link linkend="cairo-t">cairo_t</link> *cr,
  79                                                          <link linkend="double">double</link> x,
  80                                                          <link linkend="double">double</link> y,
  81                                                          <link linkend="double">double</link> width,
  82                                                          <link linkend="double">double</link> height);
  83 </synopsis>
  84 </refsynopsisdiv>
  85
  86 <refsect1 id="pango-Cairo-Rendering.object-hierarchy" role="object_hierarchy">
  87 <title role="object_hierarchy.title">Object Hierarchy</title>
  88 <synopsis>
  89   <link linkend="GInterface">GInterface</link>
  90    +----PangoCairoFont
  91 </synopsis>
  92 <synopsis>
  93   <link linkend="GInterface">GInterface</link>
  94    +----PangoCairoFontMap
  95 </synopsis>
  96 </refsect1>
  97
  98 <refsect1 id="pango-Cairo-Rendering.prerequisites" role="prerequisites">
  99 <title role="prerequisites.title">Prerequisites</title>
 100 <para>
 101 PangoCairoFont requires
 102  <link linkend="PangoFont">PangoFont</link>.</para>
 103 <para>
 104 PangoCairoFontMap requires
 105  <link linkend="PangoFontMap">PangoFontMap</link>.</para>
 106 </refsect1>
 107
 108
 109
 110
 111
 112
 113
 114 <refsect1 id="pango-Cairo-Rendering.description" role="desc">
 115 <title role="desc.title">Description</title>
 116 <para>
 117 The <ulink url="http://cairographics.org">Cairo library</ulink> is a
 118 vector graphics library with a powerful rendering model. It has such
 119 features as anti-aliased primitives, alpha-compositing, and
 120 gradients. Multiple backends for Cairo are available, to allow
 121 rendering to images, to PDF files, and to the screen on X and on other
 122 windowing systems. The functions in this section allow using Pango
 123 to render to Cairo surfaces.
 124 </para>
 125 <para>
 126 Using Pango with Cairo is straightforward. A <link linkend="PangoContext"><type>PangoContext</type></link> created
 127 with <link linkend="pango-cairo-font-map-create-context"><function>pango_cairo_font_map_create_context()</function></link> can be used on any
 128 Cairo context (cairo_t), but needs to be updated to match the
 129 current transformation matrix and target surface of the Cairo context
 130 using <link linkend="pango-cairo-update-context"><function>pango_cairo_update_context()</function></link>. The convenience functions
 131 <link linkend="pango-cairo-create-layout"><function>pango_cairo_create_layout()</function></link> and <link linkend="pango-cairo-update-layout"><function>pango_cairo_update_layout()</function></link> handle
 132 the common case where the program doesn't need to manipulate the
 133 properties of the <link linkend="PangoContext"><type>PangoContext</type></link>.
 134 </para>
 135 <para>
 136 When you get the metrics of a layout or of a piece of a layout using
 137 functions such as <link linkend="pango-layout-get-extents"><function>pango_layout_get_extents()</function></link>, the reported metrics
 138 are in user-space coordinates. If a piece of text is 10 units long,
 139 and you call cairo_scale (cr, 2.0), it still is more-or-less 10
 140 units long. However, the results will be affected by hinting
 141 (that is, the process of adjusting the text to look good on the
 142 pixel grid), so you shouldn't assume they are completely independent
 143 of the current transformation matrix. Note that the basic metrics
 144 functions in Pango report results in integer Pango units. To get
 145 to the floating point units used in Cairo divide by <link linkend="PANGO-SCALE--CAPS"><literal>PANGO_SCALE</literal></link>.
 146 </para>
 147 <example id="rotated-example">
 148 <title>Using Pango with Cairo</title>
 149 <programlisting>
 150 #<!-- -->include &lt;math.h>
 151 #<!-- -->include &lt;pango/pangocairo.h>
 152 static void
 153 draw_text (cairo_t *cr)
 154 {
 155 #<!-- -->define RADIUS 150
 156 #<!-- -->define N_WORDS 10
 157 #<!-- -->define FONT "Sans Bold 27"
 158   PangoLayout *layout;
 159   PangoFontDescription *desc;
 160   int i;
 161   /* Center coordinates on the middle of the region we are drawing
 162    */
 163   cairo_translate (cr, RADIUS, RADIUS);
 164   /* Create a PangoLayout, set the font and text */
 165   layout = pango_cairo_create_layout (cr);
 166   pango_layout_set_text (layout, "Text", -1);
 167   desc = pango_font_description_from_string (FONT);
 168   pango_layout_set_font_description (layout, desc);
 169   pango_font_description_free (desc);
 170   /* Draw the layout N_WORDS times in a circle */
 171   for (i = 0; i &lt; N_WORDS; i++)
 172     {
 173       int width, height;
 174       double angle = (360. * i) / N_WORDS;
 175       double red;
 176       cairo_save (cr);
 177       /* Gradient from red at angle == 60 to blue at angle == 240 */
 178       red   = (1 + cos ((angle - 60) * G_PI / 180.)) / 2;
 179       cairo_set_source_rgb (cr, red, 0, 1.0 - red);
 180       cairo_rotate (cr, angle * G_PI / 180.);
 181       /* Inform Pango to re-layout the text with the new transformation */
 182       pango_cairo_update_layout (cr, layout);
 183       pango_layout_get_size (layout, &amp;width, &amp;height);
 184       cairo_move_to (cr, - ((double)width / PANGO_SCALE) / 2, - RADIUS);
 185       pango_cairo_show_layout (cr, layout);
 186       cairo_restore (cr);
 187     }
 188   /* free the layout object */
 189   g_object_unref (layout);
 190 }
 191 int main (int argc, char **argv)
 192 {
 193   cairo_t *cr;
 194   char *filename;
 195   cairo_status_t status;
 196   cairo_surface_t *surface;
 197   if (argc != 2)
 198     {
 199       g_printerr ("Usage: cairosimple OUTPUT_FILENAME\n");
 200       return 1;
 201     }
 202   filename = argv[1];
 203   surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
 204                                         2 * RADIUS, 2 * RADIUS);
 205   cr = cairo_create (surface);
 206   cairo_set_source_rgb (cr, 1.0, 1.0, 1.0);
 207   cairo_paint (cr);
 208   draw_text (cr);
 209   cairo_destroy (cr);
 210   status = cairo_surface_write_to_png (surface, filename);
 211   cairo_surface_destroy (surface);
 212   if (status != CAIRO_STATUS_SUCCESS)
 213     {
 214       g_printerr ("Could not save png to '%s'\n", filename);
 215       return 1;
 216     }
 217   return 0;
 218 }
 219 </programlisting>
 220 </example>
 221 <figure id="rotated-example-output">
 222   <title>Output of <xref linkend="rotated-example"/></title>
 223   <graphic fileref="rotated-text.png" format="PNG"/>
 224 </figure>
 225 </refsect1>
 226
 227 <refsect1 id="pango-Cairo-Rendering.details" role="details">
 228 <title role="details.title">Details</title>
 229 <refsect2 id="PangoCairoFont-struct" role="struct">
 230 <title>PangoCairoFont</title>
 231 <indexterm zone="PangoCairoFont-struct" role="1.18"><primary sortas="PangoCairoFont">PangoCairoFont</primary></indexterm><programlisting>typedef struct _PangoCairoFont PangoCairoFont;</programlisting>
 232 <para>
 233 <link linkend="PangoCairoFont"><type>PangoCairoFont</type></link> is an interface exported by fonts for
 234 use with Cairo. The actual type of the font will depend
 235 on the particular font technology Cairo was compiled to use.</para>
 236 <para>
 237 </para><para role="since">Since 1.18</para></refsect2>
 238 <refsect2 id="PangoCairoFontMap-struct" role="struct">
 239 <title>PangoCairoFontMap</title>
 240 <indexterm zone="PangoCairoFontMap-struct" role="1.10"><primary sortas="PangoCairoFontMap">PangoCairoFontMap</primary></indexterm><programlisting>typedef struct _PangoCairoFontMap PangoCairoFontMap;</programlisting>
 241 <para>
 242 <link linkend="PangoCairoFontMap"><type>PangoCairoFontMap</type></link> is an interface exported by font maps for
 243 use with Cairo. The actual type of the font map will depend
 244 on the particular font technology Cairo was compiled to use.</para>
 245 <para>
 246 </para><para role="since">Since 1.10</para></refsect2>
 247 <refsect2 id="pango-cairo-font-map-get-default" role="function" condition="since:1.10">
 248 <title>pango_cairo_font_map_get_default ()</title>
 249 <indexterm zone="pango-cairo-font-map-get-default" role="1.10"><primary sortas="pango_cairo_font_map_get_default">pango_cairo_font_map_get_default</primary></indexterm><programlisting><link linkend="PangoFontMap">PangoFontMap</link> *      pango_cairo_font_map_get_default    (void);</programlisting>
 250 <para>
 251 Gets a default <link linkend="PangoCairoFontMap"><type>PangoCairoFontMap</type></link> to use with Cairo.
 252 </para>
 253 <para>
 254 Note that the type of the returned object will depend
 255 on the particular font backend Cairo was compiled to use;
 256 You generally should only use the <link linkend="PangoFontMap"><type>PangoFontMap</type></link> and
 257 <link linkend="PangoCairoFontMap"><type>PangoCairoFontMap</type></link> interfaces on the returned object.
 258 </para>
 259 <para>
 260 The default Cairo fontmap can be changed by using
 261 <link linkend="pango-cairo-font-map-set-default"><function>pango_cairo_font_map_set_default()</function></link>.  This can be used to
 262 change the Cairo font backend that the default fontmap
 263 uses for example.</para>
 264 <para>
 265 </para><variablelist role="params">
 266 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the default Cairo fontmap for Pango. This
 267  object is owned by Pango and must not be freed.
 268
 269 </simpara></listitem></varlistentry>
 270 </variablelist><para role="since">Since 1.10</para></refsect2>
 271 <refsect2 id="pango-cairo-font-map-set-default" role="function" condition="since:1.22">
 272 <title>pango_cairo_font_map_set_default ()</title>
 273 <indexterm zone="pango-cairo-font-map-set-default" role="1.22"><primary sortas="pango_cairo_font_map_set_default">pango_cairo_font_map_set_default</primary></indexterm><programlisting><link linkend="void">void</link>                pango_cairo_font_map_set_default    (<link linkend="PangoCairoFontMap">PangoCairoFontMap</link> *fontmap);</programlisting>
 274 <para>
 275 Sets a default <link linkend="PangoCairoFontMap"><type>PangoCairoFontMap</type></link> to use with Cairo.
 276 </para>
 277 <para>
 278 This can be used to change the Cairo font backend that the
 279 default fontmap uses for example.  The old default font map
 280 is unreffed and the new font map referenced.
 281 </para>
 282 <para>
 283 A value of <link linkend="NULL--CAPS"><literal>NULL</literal></link> for <parameter>fontmap</parameter> will cause the current default
 284 font map to be released and a new default font
 285 map to be created on demand, using <link linkend="pango-cairo-font-map-new"><function>pango_cairo_font_map_new()</function></link>.</para>
 286 <para>
 287 </para><variablelist role="params">
 288 <varlistentry><term><parameter>fontmap</parameter>&#160;:</term>
 289 <listitem><simpara> The new default font map, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 290 </simpara></listitem></varlistentry>
 291 </variablelist><para role="since">Since 1.22</para></refsect2>
 292 <refsect2 id="pango-cairo-font-map-new" role="function" condition="since:1.10">
 293 <title>pango_cairo_font_map_new ()</title>
 294 <indexterm zone="pango-cairo-font-map-new" role="1.10"><primary sortas="pango_cairo_font_map_new">pango_cairo_font_map_new</primary></indexterm><programlisting><link linkend="PangoFontMap">PangoFontMap</link> *      pango_cairo_font_map_new            (void);</programlisting>
 295 <para>
 296 Creates a new <link linkend="PangoCairoFontMap"><type>PangoCairoFontMap</type></link> object; a fontmap is used
 297 to cache information about available fonts, and holds
 298 certain global parameters such as the resolution.
 299 In most cases, you can use <link linkend="pango-cairo-font-map-get-default"><function>pango_cairo_font_map_get_default()</function></link>
 300 instead.
 301 </para>
 302 <para>
 303 Note that the type of the returned object will depend
 304 on the particular font backend Cairo was compiled to use;
 305 You generally should only use the <link linkend="PangoFontMap"><type>PangoFontMap</type></link> and
 306 <link linkend="PangoCairoFontMap"><type>PangoCairoFontMap</type></link> interfaces on the returned object.</para>
 307 <para>
 308 </para><variablelist role="params">
 309 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly allocated <link linkend="PangoFontMap"><type>PangoFontMap</type></link>, which should
 310               be freed with <link linkend="g-object-unref"><function>g_object_unref()</function></link>.
 311
 312 </simpara></listitem></varlistentry>
 313 </variablelist><para role="since">Since 1.10</para></refsect2>
 314 <refsect2 id="pango-cairo-font-map-new-for-font-type" role="function" condition="since:1.18">
 315 <title>pango_cairo_font_map_new_for_font_type ()</title>
 316 <indexterm zone="pango-cairo-font-map-new-for-font-type" role="1.18"><primary sortas="pango_cairo_font_map_new_for_font_type">pango_cairo_font_map_new_for_font_type</primary></indexterm><programlisting><link linkend="PangoFontMap">PangoFontMap</link> *      pango_cairo_font_map_new_for_font_type
 317                                                         (<link linkend="cairo-font-type-t">cairo_font_type_t</link> fonttype);</programlisting>
 318 <para>
 319 Creates a new <link linkend="PangoCairoFontMap"><type>PangoCairoFontMap</type></link> object of the type suitable
 320 to be used with cairo font backend of type <parameter>fonttype</parameter>.
 321 </para>
 322 <para>
 323 In most cases one should simply use @<link linkend="pango-cairo-font-map-new"><function>pango_cairo_font_map_new()</function></link>,
 324 or in fact in most of those cases, just use
 325 @<link linkend="pango-cairo-font-map-get-default"><function>pango_cairo_font_map_get_default()</function></link>.</para>
 326 <para>
 327 </para><variablelist role="params">
 328 <varlistentry><term><parameter>fonttype</parameter>&#160;:</term>
 329 <listitem><simpara> desired <link linkend="cairo-font-type-t"><type>cairo_font_type_t</type></link>
 330 </simpara></listitem></varlistentry>
 331 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly allocated <link linkend="PangoFontMap"><type>PangoFontMap</type></link> of suitable type
 332               which should be freed with <link linkend="g-object-unref"><function>g_object_unref()</function></link>,
 333               or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the requested cairo font backend is
 334               not supported / compiled in.
 335
 336 </simpara></listitem></varlistentry>
 337 </variablelist><para role="since">Since 1.18</para></refsect2>
 338 <refsect2 id="pango-cairo-font-map-get-font-type" role="function" condition="since:1.18">
 339 <title>pango_cairo_font_map_get_font_type ()</title>
 340 <indexterm zone="pango-cairo-font-map-get-font-type" role="1.18"><primary sortas="pango_cairo_font_map_get_font_type">pango_cairo_font_map_get_font_type</primary></indexterm><programlisting><link linkend="cairo-font-type-t">cairo_font_type_t</link>   pango_cairo_font_map_get_font_type  (<link linkend="PangoCairoFontMap">PangoCairoFontMap</link> *fontmap);</programlisting>
 341 <para>
 342 Gets the type of Cairo font backend that <parameter>fontmap</parameter> uses.</para>
 343 <para>
 344 </para><variablelist role="params">
 345 <varlistentry><term><parameter>fontmap</parameter>&#160;:</term>
 346 <listitem><simpara> a <link linkend="PangoCairoFontMap"><type>PangoCairoFontMap</type></link>
 347 </simpara></listitem></varlistentry>
 348 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="cairo-font-type-t"><type>cairo_font_type_t</type></link> cairo font backend type
 349
 350 </simpara></listitem></varlistentry>
 351 </variablelist><para role="since">Since 1.18</para></refsect2>
 352 <refsect2 id="pango-cairo-font-map-set-resolution" role="function" condition="since:1.10">
 353 <title>pango_cairo_font_map_set_resolution ()</title>
 354 <indexterm zone="pango-cairo-font-map-set-resolution" role="1.10"><primary sortas="pango_cairo_font_map_set_resolution">pango_cairo_font_map_set_resolution</primary></indexterm><programlisting><link linkend="void">void</link>                pango_cairo_font_map_set_resolution (<link linkend="PangoCairoFontMap">PangoCairoFontMap</link> *fontmap,
 355                                                          <link linkend="double">double</link> dpi);</programlisting>
 356 <para>
 357 Sets the resolution for the fontmap. This is a scale factor between
 358 points specified in a <link linkend="PangoFontDescription"><type>PangoFontDescription</type></link> and Cairo units. The
 359 default value is 96, meaning that a 10 point font will be 13
 360 units high. (10 * 96. / 72. = 13.3).</para>
 361 <para>
 362 </para><variablelist role="params">
 363 <varlistentry><term><parameter>fontmap</parameter>&#160;:</term>
 364 <listitem><simpara> a <link linkend="PangoCairoFontMap"><type>PangoCairoFontMap</type></link>
 365 </simpara></listitem></varlistentry>
 366 <varlistentry><term><parameter>dpi</parameter>&#160;:</term>
 367 <listitem><simpara> the resolution in "dots per inch". (Physical inches aren't actually
 368   involved; the terminology is conventional.)
 369 </simpara></listitem></varlistentry>
 370 </variablelist><para role="since">Since 1.10</para></refsect2>
 371 <refsect2 id="pango-cairo-font-map-get-resolution" role="function" condition="since:1.10">
 372 <title>pango_cairo_font_map_get_resolution ()</title>
 373 <indexterm zone="pango-cairo-font-map-get-resolution" role="1.10"><primary sortas="pango_cairo_font_map_get_resolution">pango_cairo_font_map_get_resolution</primary></indexterm><programlisting><link linkend="double">double</link>              pango_cairo_font_map_get_resolution (<link linkend="PangoCairoFontMap">PangoCairoFontMap</link> *fontmap);</programlisting>
 374 <para>
 375 Gets the resolution for the fontmap. See <link linkend="pango-cairo-font-map-set-resolution"><function>pango_cairo_font_map_set_resolution()</function></link></para>
 376 <para>
 377 </para><variablelist role="params">
 378 <varlistentry><term><parameter>fontmap</parameter>&#160;:</term>
 379 <listitem><simpara> a <link linkend="PangoCairoFontMap"><type>PangoCairoFontMap</type></link>
 380 </simpara></listitem></varlistentry>
 381 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the resolution in "dots per inch"
 382
 383 </simpara></listitem></varlistentry>
 384 </variablelist><para role="since">Since 1.10</para></refsect2>
 385 <refsect2 id="pango-cairo-font-map-create-context" role="function" condition="deprecated:1.22: Use pango_font_map_create_context() instead.|since:1.10">
 386 <title>pango_cairo_font_map_create_context ()</title>
 387 <indexterm zone="pango-cairo-font-map-create-context" role="deprecated"><primary sortas="pango_cairo_font_map_create_context">pango_cairo_font_map_create_context</primary></indexterm><indexterm zone="pango-cairo-font-map-create-context" role="1.10"><primary sortas="pango_cairo_font_map_create_context">pango_cairo_font_map_create_context</primary></indexterm><programlisting><link linkend="PangoContext">PangoContext</link> *      pango_cairo_font_map_create_context (<link linkend="PangoCairoFontMap">PangoCairoFontMap</link> *fontmap);</programlisting>
 388 <warning><para><literal>pango_cairo_font_map_create_context</literal> has been deprecated since version 1.22 and should not be used in newly-written code. Use <link linkend="pango-font-map-create-context"><function>pango_font_map_create_context()</function></link> instead.</para></warning>
 389 <para>
 390 Create a <link linkend="PangoContext"><type>PangoContext</type></link> for the given fontmap.</para>
 391 <para>
 392 </para><variablelist role="params">
 393 <varlistentry><term><parameter>fontmap</parameter>&#160;:</term>
 394 <listitem><simpara> a <link linkend="PangoCairoFontMap"><type>PangoCairoFontMap</type></link>
 395 </simpara></listitem></varlistentry>
 396 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly created context; free with <link linkend="g-object-unref"><function>g_object_unref()</function></link>.
 397
 398 </simpara></listitem></varlistentry>
 399 </variablelist><para role="since">Since 1.10</para></refsect2>
 400 <refsect2 id="pango-cairo-font-get-scaled-font" role="function" condition="since:1.18">
 401 <title>pango_cairo_font_get_scaled_font ()</title>
 402 <indexterm zone="pango-cairo-font-get-scaled-font" role="1.18"><primary sortas="pango_cairo_font_get_scaled_font">pango_cairo_font_get_scaled_font</primary></indexterm><programlisting><link linkend="cairo-scaled-font-t">cairo_scaled_font_t</link> * pango_cairo_font_get_scaled_font  (<link linkend="PangoCairoFont">PangoCairoFont</link> *font);</programlisting>
 403 <para>
 404 Gets the <link linkend="cairo-scaled-font-t"><type>cairo_scaled_font_t</type></link> used by <parameter>font</parameter>.
 405 The scaled font can be referenced and kept using
 406 <link linkend="cairo-scaled-font-reference"><function>cairo_scaled_font_reference()</function></link>.</para>
 407 <para>
 408 </para><variablelist role="params">
 409 <varlistentry><term><parameter>font</parameter>&#160;:</term>
 410 <listitem><simpara> a <link linkend="PangoFont"><type>PangoFont</type></link> from a <link linkend="PangoCairoFontMap"><type>PangoCairoFontMap</type></link>
 411 </simpara></listitem></varlistentry>
 412 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="cairo-scaled-font-t"><type>cairo_scaled_font_t</type></link> used by <parameter>font</parameter>,
 413               or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if <parameter>font</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
 414
 415 </simpara></listitem></varlistentry>
 416 </variablelist><para role="since">Since 1.18</para></refsect2>
 417 <refsect2 id="pango-cairo-context-set-resolution" role="function" condition="since:1.10">
 418 <title>pango_cairo_context_set_resolution ()</title>
 419 <indexterm zone="pango-cairo-context-set-resolution" role="1.10"><primary sortas="pango_cairo_context_set_resolution">pango_cairo_context_set_resolution</primary></indexterm><programlisting><link linkend="void">void</link>                pango_cairo_context_set_resolution  (<link linkend="PangoContext">PangoContext</link> *context,
 420                                                          <link linkend="double">double</link> dpi);</programlisting>
 421 <para>
 422 Sets the resolution for the context. This is a scale factor between
 423 points specified in a <link linkend="PangoFontDescription"><type>PangoFontDescription</type></link> and Cairo units. The
 424 default value is 96, meaning that a 10 point font will be 13
 425 units high. (10 * 96. / 72. = 13.3).</para>
 426 <para>
 427 </para><variablelist role="params">
 428 <varlistentry><term><parameter>context</parameter>&#160;:</term>
 429 <listitem><simpara> a <link linkend="PangoContext"><type>PangoContext</type></link>, from a pangocairo font map
 430 </simpara></listitem></varlistentry>
 431 <varlistentry><term><parameter>dpi</parameter>&#160;:</term>
 432 <listitem><simpara> the resolution in "dots per inch". (Physical inches aren't actually
 433   involved; the terminology is conventional.) A 0 or negative value
 434   means to use the resolution from the font map.
 435 </simpara></listitem></varlistentry>
 436 </variablelist><para role="since">Since 1.10</para></refsect2>
 437 <refsect2 id="pango-cairo-context-get-resolution" role="function" condition="since:1.10">
 438 <title>pango_cairo_context_get_resolution ()</title>
 439 <indexterm zone="pango-cairo-context-get-resolution" role="1.10"><primary sortas="pango_cairo_context_get_resolution">pango_cairo_context_get_resolution</primary></indexterm><programlisting><link linkend="double">double</link>              pango_cairo_context_get_resolution  (<link linkend="PangoContext">PangoContext</link> *context);</programlisting>
 440 <para>
 441 Gets the resolution for the context. See <link linkend="pango-cairo-context-set-resolution"><function>pango_cairo_context_set_resolution()</function></link></para>
 442 <para>
 443 </para><variablelist role="params">
 444 <varlistentry><term><parameter>context</parameter>&#160;:</term>
 445 <listitem><simpara> a <link linkend="PangoContext"><type>PangoContext</type></link>, from a pangocairo font map
 446 </simpara></listitem></varlistentry>
 447 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the resolution in "dots per inch". A negative value will
 448  be returned if no resolution has previously been set.
 449
 450 </simpara></listitem></varlistentry>
 451 </variablelist><para role="since">Since 1.10</para></refsect2>
 452 <refsect2 id="pango-cairo-context-set-font-options" role="function" condition="since:1.10">
 453 <title>pango_cairo_context_set_font_options ()</title>
 454 <indexterm zone="pango-cairo-context-set-font-options" role="1.10"><primary sortas="pango_cairo_context_set_font_options">pango_cairo_context_set_font_options</primary></indexterm><programlisting><link linkend="void">void</link>                pango_cairo_context_set_font_options
 455                                                         (<link linkend="PangoContext">PangoContext</link> *context,
 456                                                          const <link linkend="cairo-font-options-t">cairo_font_options_t</link> *options);</programlisting>
 457 <para>
 458 Sets the font options used when rendering text with this context.
 459 These options override any options that <link linkend="pango-cairo-update-context"><function>pango_cairo_update_context()</function></link>
 460 derives from the target surface.</para>
 461 <para>
 462 </para><variablelist role="params">
 463 <varlistentry><term><parameter>context</parameter>&#160;:</term>
 464 <listitem><simpara> a <link linkend="PangoContext"><type>PangoContext</type></link>, from a pangocairo font map
 465 </simpara></listitem></varlistentry>
 466 <varlistentry><term><parameter>options</parameter>&#160;:</term>
 467 <listitem><simpara> a <link linkend="cairo-font-options-t"><type>cairo_font_options_t</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to unset any previously set
 468           options. A copy is made.
 469 </simpara></listitem></varlistentry>
 470 </variablelist><para role="since">Since 1.10</para></refsect2>
 471 <refsect2 id="pango-cairo-context-get-font-options" role="function" condition="since:1.10">
 472 <title>pango_cairo_context_get_font_options ()</title>
 473 <indexterm zone="pango-cairo-context-get-font-options" role="1.10"><primary sortas="pango_cairo_context_get_font_options">pango_cairo_context_get_font_options</primary></indexterm><programlisting>const <link linkend="cairo-font-options-t">cairo_font_options_t</link> * pango_cairo_context_get_font_options
 474                                                         (<link linkend="PangoContext">PangoContext</link> *context);</programlisting>
 475 <para>
 476 Retrieves any font rendering options previously set with
 477 <link linkend="pango-cairo-font-map-set-font-options"><function>pango_cairo_font_map_set_font_options()</function></link>. This function does not report options
 478 that are derived from the target surface by <link linkend="pango-cairo-update-context"><function>pango_cairo_update_context()</function></link></para>
 479 <para>
 480 </para><variablelist role="params">
 481 <varlistentry><term><parameter>context</parameter>&#160;:</term>
 482 <listitem><simpara> a <link linkend="PangoContext"><type>PangoContext</type></link>, from a pangocairo font map
 483 </simpara></listitem></varlistentry>
 484 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the font options previously set on the context, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 485   if no options have been set. This value is owned by the context
 486   and must not be modified or freed.
 487
 488 </simpara></listitem></varlistentry>
 489 </variablelist><para role="since">Since 1.10</para></refsect2>
 490 <refsect2 id="PangoCairoShapeRendererFunc" role="function">
 491 <title>PangoCairoShapeRendererFunc ()</title>
 492 <indexterm zone="PangoCairoShapeRendererFunc"><primary sortas="PangoCairoShapeRendererFunc">PangoCairoShapeRendererFunc</primary></indexterm><programlisting><link linkend="void">void</link>                (*PangoCairoShapeRendererFunc)      (<link linkend="cairo-t">cairo_t</link> *cr,
 493                                                          <link linkend="PangoAttrShape">PangoAttrShape</link> *attr,
 494                                                          <link linkend="gboolean">gboolean</link> do_path,
 495                                                          <link linkend="gpointer">gpointer</link> data);</programlisting>
 496 <para>
 497 Function type for rendering attributes of type <link linkend="PANGO-ATTR-SHAPE--CAPS"><literal>PANGO_ATTR_SHAPE</literal></link>
 498 with Pango's Cairo renderer.
 499 </para><variablelist role="params">
 500 <varlistentry><term><parameter>cr</parameter>&#160;:</term>
 501 <listitem><simpara>a Cairo context with current point set to where the shape should
 502      be rendered
 503 </simpara></listitem></varlistentry>
 504 <varlistentry><term><parameter>attr</parameter>&#160;:</term>
 505 <listitem><simpara>the <link linkend="PANGO-ATTR-SHAPE--CAPS"><literal>PANGO_ATTR_SHAPE</literal></link> to render
 506 </simpara></listitem></varlistentry>
 507 <varlistentry><term><parameter>do_path</parameter>&#160;:</term>
 508 <listitem><simpara>whether only the shape path should be appended to current
 509           path of <parameter>cr</parameter> and no filling/stroking done.  This will be set
 510           to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> when called from <link linkend="pango-cairo-layout-path"><function>pango_cairo_layout_path()</function></link> and
 511           <link linkend="pango-cairo-layout-line-path"><function>pango_cairo_layout_line_path()</function></link> rendering functions.
 512 </simpara></listitem></varlistentry>
 513 <varlistentry><term><parameter>data</parameter>&#160;:</term>
 514 <listitem><simpara>user data passed to <link linkend="pango-cairo-context-set-shape-renderer"><function>pango_cairo_context_set_shape_renderer()</function></link>
 515 </simpara></listitem></varlistentry>
 516 </variablelist></refsect2>
 517 <refsect2 id="pango-cairo-context-set-shape-renderer" role="function" condition="since:1.18">
 518 <title>pango_cairo_context_set_shape_renderer ()</title>
 519 <indexterm zone="pango-cairo-context-set-shape-renderer" role="1.18"><primary sortas="pango_cairo_context_set_shape_renderer">pango_cairo_context_set_shape_renderer</primary></indexterm><programlisting><link linkend="void">void</link>                pango_cairo_context_set_shape_renderer
 520                                                         (<link linkend="PangoContext">PangoContext</link> *context,
 521                                                          <link linkend="PangoCairoShapeRendererFunc">PangoCairoShapeRendererFunc</link> func,
 522                                                          <link linkend="gpointer">gpointer</link> data,
 523                                                          <link linkend="GDestroyNotify">GDestroyNotify</link> dnotify);</programlisting>
 524 <para>
 525 Sets callback function for context to use for rendering attributes
 526 of type <link linkend="PANGO-ATTR-SHAPE--CAPS"><literal>PANGO_ATTR_SHAPE</literal></link>.  See <link linkend="PangoCairoShapeRendererFunc"><type>PangoCairoShapeRendererFunc</type></link> for
 527 details.</para>
 528 <para>
 529 </para><variablelist role="params">
 530 <varlistentry><term><parameter>context</parameter>&#160;:</term>
 531 <listitem><simpara> a <link linkend="PangoContext"><type>PangoContext</type></link>, from a pangocairo font map
 532 </simpara></listitem></varlistentry>
 533 <varlistentry><term><parameter>func</parameter>&#160;:</term>
 534 <listitem><simpara> Callback function for rendering attributes of type
 535 <link linkend="PANGO-ATTR-SHAPE--CAPS"><literal>PANGO_ATTR_SHAPE</literal></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to disable shape rendering.
 536 </simpara></listitem></varlistentry>
 537 <varlistentry><term><parameter>data</parameter>&#160;:</term>
 538 <listitem><simpara> User data that will be passed to <parameter>func</parameter>.
 539 </simpara></listitem></varlistentry>
 540 <varlistentry><term><parameter>dnotify</parameter>&#160;:</term>
 541 <listitem><simpara> Callback that will be called when the
 542           context is freed to release <parameter>data</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
 543 </simpara></listitem></varlistentry>
 544 </variablelist><para role="since">Since 1.18</para></refsect2>
 545 <refsect2 id="pango-cairo-context-get-shape-renderer" role="function" condition="since:1.18">
 546 <title>pango_cairo_context_get_shape_renderer ()</title>
 547 <indexterm zone="pango-cairo-context-get-shape-renderer" role="1.18"><primary sortas="pango_cairo_context_get_shape_renderer">pango_cairo_context_get_shape_renderer</primary></indexterm><programlisting><link linkend="PangoCairoShapeRendererFunc">PangoCairoShapeRendererFunc</link>  pango_cairo_context_get_shape_renderer
 548                                                         (<link linkend="PangoContext">PangoContext</link> *context,
 549                                                          <link linkend="gpointer">gpointer</link> *data);</programlisting>
 550 <para>
 551 Sets callback function for context to use for rendering attributes
 552 of type <link linkend="PANGO-ATTR-SHAPE--CAPS"><literal>PANGO_ATTR_SHAPE</literal></link>.  See <link linkend="PangoCairoShapeRendererFunc"><type>PangoCairoShapeRendererFunc</type></link> for
 553 details.
 554 </para>
 555 <para>
 556 Retrieves callback function and associated user data for rendering
 557 attributes of type <link linkend="PANGO-ATTR-SHAPE--CAPS"><literal>PANGO_ATTR_SHAPE</literal></link> as set by
 558 <link linkend="pango-cairo-context-set-shape-renderer"><function>pango_cairo_context_set_shape_renderer()</function></link>, if any.</para>
 559 <para>
 560 </para><variablelist role="params">
 561 <varlistentry><term><parameter>context</parameter>&#160;:</term>
 562 <listitem><simpara> a <link linkend="PangoContext"><type>PangoContext</type></link>, from a pangocairo font map
 563 </simpara></listitem></varlistentry>
 564 <varlistentry><term><parameter>data</parameter>&#160;:</term>
 565 <listitem><simpara> Pointer to <link linkend="gpointer"><type>gpointer</type></link> to return user data
 566 </simpara></listitem></varlistentry>
 567 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the shape rendering callback previously set on the context, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 568   if no shape rendering callback have been set.
 569
 570 </simpara></listitem></varlistentry>
 571 </variablelist><para role="since">Since 1.18</para></refsect2>
 572 <refsect2 id="pango-cairo-create-context" role="function" condition="since:1.22">
 573 <title>pango_cairo_create_context ()</title>
 574 <indexterm zone="pango-cairo-create-context" role="1.22"><primary sortas="pango_cairo_create_context">pango_cairo_create_context</primary></indexterm><programlisting><link linkend="PangoContext">PangoContext</link> *      pango_cairo_create_context          (<link linkend="cairo-t">cairo_t</link> *cr);</programlisting>
 575 <para>
 576 Creates a context object set up to match the current transformation
 577 and target surface of the Cairo context.  This context can then be
 578 used to create a layout using <link linkend="pango-layout-new"><function>pango_layout_new()</function></link>.
 579 </para>
 580 <para>
 581 This function is a convenience function that creates a context using
 582 the default font map, then updates it to <parameter>cr</parameter>.  If you just need to
 583 create a layout for use with <parameter>cr</parameter> and do not need to access <link linkend="PangoContext"><type>PangoContext</type></link>
 584 directly, you can use <link linkend="pango-cairo-create-layout"><function>pango_cairo_create_layout()</function></link> instead.</para>
 585 <para>
 586 </para><variablelist role="params">
 587 <varlistentry><term><parameter>cr</parameter>&#160;:</term>
 588 <listitem><simpara> a Cairo context
 589 </simpara></listitem></varlistentry>
 590 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly created <link linkend="PangoContext"><type>PangoContext</type></link>. Free with
 591   <link linkend="g-object-unref"><function>g_object_unref()</function></link>.
 592
 593 </simpara></listitem></varlistentry>
 594 </variablelist><para role="since">Since 1.22</para></refsect2>
 595 <refsect2 id="pango-cairo-update-context" role="function" condition="since:1.10">
 596 <title>pango_cairo_update_context ()</title>
 597 <indexterm zone="pango-cairo-update-context" role="1.10"><primary sortas="pango_cairo_update_context">pango_cairo_update_context</primary></indexterm><programlisting><link linkend="void">void</link>                pango_cairo_update_context          (<link linkend="cairo-t">cairo_t</link> *cr,
 598                                                          <link linkend="PangoContext">PangoContext</link> *context);</programlisting>
 599 <para>
 600 Updates a <link linkend="PangoContext"><type>PangoContext</type></link> previously created for use with Cairo to
 601 match the current transformation and target surface of a Cairo
 602 context. If any layouts have been created for the context,
 603 it's necessary to call <link linkend="pango-layout-context-changed"><function>pango_layout_context_changed()</function></link> on those
 604 layouts.</para>
 605 <para>
 606 </para><variablelist role="params">
 607 <varlistentry><term><parameter>cr</parameter>&#160;:</term>
 608 <listitem><simpara> a Cairo context
 609 </simpara></listitem></varlistentry>
 610 <varlistentry><term><parameter>context</parameter>&#160;:</term>
 611 <listitem><simpara> a <link linkend="PangoContext"><type>PangoContext</type></link>, from a pangocairo font map
 612 </simpara></listitem></varlistentry>
 613 </variablelist><para role="since">Since 1.10</para></refsect2>
 614 <refsect2 id="pango-cairo-create-layout" role="function" condition="since:1.10">
 615 <title>pango_cairo_create_layout ()</title>
 616 <indexterm zone="pango-cairo-create-layout" role="1.10"><primary sortas="pango_cairo_create_layout">pango_cairo_create_layout</primary></indexterm><programlisting><link linkend="PangoLayout">PangoLayout</link> *       pango_cairo_create_layout           (<link linkend="cairo-t">cairo_t</link> *cr);</programlisting>
 617 <para>
 618 Creates a layout object set up to match the current transformation
 619 and target surface of the Cairo context.  This layout can then be
 620 used for text measurement with functions like
 621 <link linkend="pango-layout-get-size"><function>pango_layout_get_size()</function></link> or drawing with functions like
 622 <link linkend="pango-cairo-show-layout"><function>pango_cairo_show_layout()</function></link>. If you change the transformation
 623 or target surface for <parameter>cr</parameter>, you need to call <link linkend="pango-cairo-update-layout"><function>pango_cairo_update_layout()</function></link>
 624 </para>
 625 <para>
 626 This function is the most convenient way to use Cairo with Pango,
 627 however it is slightly inefficient since it creates a separate
 628 <link linkend="PangoContext"><type>PangoContext</type></link> object for each layout. This might matter in an
 629 application that was laying out large amounts of text.</para>
 630 <para>
 631 </para><variablelist role="params">
 632 <varlistentry><term><parameter>cr</parameter>&#160;:</term>
 633 <listitem><simpara> a Cairo context
 634 </simpara></listitem></varlistentry>
 635 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly created <link linkend="PangoLayout"><type>PangoLayout</type></link>. Free with
 636   <link linkend="g-object-unref"><function>g_object_unref()</function></link>.
 637
 638 </simpara></listitem></varlistentry>
 639 </variablelist><para role="since">Since 1.10</para></refsect2>
 640 <refsect2 id="pango-cairo-update-layout" role="function" condition="since:1.10">
 641 <title>pango_cairo_update_layout ()</title>
 642 <indexterm zone="pango-cairo-update-layout" role="1.10"><primary sortas="pango_cairo_update_layout">pango_cairo_update_layout</primary></indexterm><programlisting><link linkend="void">void</link>                pango_cairo_update_layout           (<link linkend="cairo-t">cairo_t</link> *cr,
 643                                                          <link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
 644 <para>
 645 Updates the private <link linkend="PangoContext"><type>PangoContext</type></link> of a <link linkend="PangoLayout"><type>PangoLayout</type></link> created with
 646 <link linkend="pango-cairo-create-layout"><function>pango_cairo_create_layout()</function></link> to match the current transformation
 647 and target surface of a Cairo context.</para>
 648 <para>
 649 </para><variablelist role="params">
 650 <varlistentry><term><parameter>cr</parameter>&#160;:</term>
 651 <listitem><simpara> a Cairo context
 652 </simpara></listitem></varlistentry>
 653 <varlistentry><term><parameter>layout</parameter>&#160;:</term>
 654 <listitem><simpara> a <link linkend="PangoLayout"><type>PangoLayout</type></link>, from <link linkend="pango-cairo-create-layout"><function>pango_cairo_create_layout()</function></link>
 655 </simpara></listitem></varlistentry>
 656 </variablelist><para role="since">Since 1.10</para></refsect2>
 657 <refsect2 id="pango-cairo-show-glyph-string" role="function" condition="since:1.10">
 658 <title>pango_cairo_show_glyph_string ()</title>
 659 <indexterm zone="pango-cairo-show-glyph-string" role="1.10"><primary sortas="pango_cairo_show_glyph_string">pango_cairo_show_glyph_string</primary></indexterm><programlisting><link linkend="void">void</link>                pango_cairo_show_glyph_string       (<link linkend="cairo-t">cairo_t</link> *cr,
 660                                                          <link linkend="PangoFont">PangoFont</link> *font,
 661                                                          <link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs);</programlisting>
 662 <para>
 663 Draws the glyphs in <parameter>glyphs</parameter> in the specified cairo context.
 664 The origin of the glyphs (the left edge of the baseline) will
 665 be drawn at the current point of the cairo context.</para>
 666 <para>
 667 </para><variablelist role="params">
 668 <varlistentry><term><parameter>cr</parameter>&#160;:</term>
 669 <listitem><simpara> a Cairo context
 670 </simpara></listitem></varlistentry>
 671 <varlistentry><term><parameter>font</parameter>&#160;:</term>
 672 <listitem><simpara> a <link linkend="PangoFont"><type>PangoFont</type></link> from a <link linkend="PangoCairoFontMap"><type>PangoCairoFontMap</type></link>
 673 </simpara></listitem></varlistentry>
 674 <varlistentry><term><parameter>glyphs</parameter>&#160;:</term>
 675 <listitem><simpara> a <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link>
 676 </simpara></listitem></varlistentry>
 677 </variablelist><para role="since">Since 1.10</para></refsect2>
 678 <refsect2 id="pango-cairo-show-glyph-item" role="function" condition="since:1.22">
 679 <title>pango_cairo_show_glyph_item ()</title>
 680 <indexterm zone="pango-cairo-show-glyph-item" role="1.22"><primary sortas="pango_cairo_show_glyph_item">pango_cairo_show_glyph_item</primary></indexterm><programlisting><link linkend="void">void</link>                pango_cairo_show_glyph_item         (<link linkend="cairo-t">cairo_t</link> *cr,
 681                                                          const <link linkend="char">char</link> *text,
 682                                                          <link linkend="PangoGlyphItem">PangoGlyphItem</link> *glyph_item);</programlisting>
 683 <para>
 684 Draws the glyphs in <parameter>glyph_item</parameter> in the specified cairo context,
 685 embedding the text associated with the glyphs in the output if the
 686 output format supports it (PDF for example), otherwise it acts
 687 similar to <link linkend="pango-cairo-show-glyph-string"><function>pango_cairo_show_glyph_string()</function></link>.
 688 </para>
 689 <para>
 690 The origin of the glyphs (the left edge of the baseline) will
 691 be drawn at the current point of the cairo context.
 692 </para>
 693 <para>
 694 Note that <parameter>text</parameter> is the start of the text for layout, which is then
 695 indexed by <literal><parameter>glyph_item->item->offset</parameter></literal>.</para>
 696 <para>
 697 </para><variablelist role="params">
 698 <varlistentry><term><parameter>cr</parameter>&#160;:</term>
 699 <listitem><simpara> a Cairo context
 700 </simpara></listitem></varlistentry>
 701 <varlistentry><term><parameter>text</parameter>&#160;:</term>
 702 <listitem><simpara> the UTF-8 text that <parameter>glyph_item</parameter> refers to
 703 </simpara></listitem></varlistentry>
 704 <varlistentry><term><parameter>glyph_item</parameter>&#160;:</term>
 705 <listitem><simpara> a <link linkend="PangoGlyphItem"><type>PangoGlyphItem</type></link>
 706 </simpara></listitem></varlistentry>
 707 </variablelist><para role="since">Since 1.22</para></refsect2>
 708 <refsect2 id="pango-cairo-show-layout-line" role="function" condition="since:1.10">
 709 <title>pango_cairo_show_layout_line ()</title>
 710 <indexterm zone="pango-cairo-show-layout-line" role="1.10"><primary sortas="pango_cairo_show_layout_line">pango_cairo_show_layout_line</primary></indexterm><programlisting><link linkend="void">void</link>                pango_cairo_show_layout_line        (<link linkend="cairo-t">cairo_t</link> *cr,
 711                                                          <link linkend="PangoLayoutLine">PangoLayoutLine</link> *line);</programlisting>
 712 <para>
 713 Draws a <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link> in the specified cairo context.
 714 The origin of the glyphs (the left edge of the line) will
 715 be drawn at the current point of the cairo context.</para>
 716 <para>
 717 </para><variablelist role="params">
 718 <varlistentry><term><parameter>cr</parameter>&#160;:</term>
 719 <listitem><simpara> a Cairo context
 720 </simpara></listitem></varlistentry>
 721 <varlistentry><term><parameter>line</parameter>&#160;:</term>
 722 <listitem><simpara> a <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link>
 723 </simpara></listitem></varlistentry>
 724 </variablelist><para role="since">Since 1.10</para></refsect2>
 725 <refsect2 id="pango-cairo-show-layout" role="function" condition="since:1.10">
 726 <title>pango_cairo_show_layout ()</title>
 727 <indexterm zone="pango-cairo-show-layout" role="1.10"><primary sortas="pango_cairo_show_layout">pango_cairo_show_layout</primary></indexterm><programlisting><link linkend="void">void</link>                pango_cairo_show_layout             (<link linkend="cairo-t">cairo_t</link> *cr,
 728                                                          <link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
 729 <para>
 730 Draws a <link linkend="PangoLayout"><type>PangoLayout</type></link> in the specified cairo context.
 731 The top-left corner of the <link linkend="PangoLayout"><type>PangoLayout</type></link> will be drawn
 732 at the current point of the cairo context.</para>
 733 <para>
 734 </para><variablelist role="params">
 735 <varlistentry><term><parameter>cr</parameter>&#160;:</term>
 736 <listitem><simpara> a Cairo context
 737 </simpara></listitem></varlistentry>
 738 <varlistentry><term><parameter>layout</parameter>&#160;:</term>
 739 <listitem><simpara> a Pango layout
 740 </simpara></listitem></varlistentry>
 741 </variablelist><para role="since">Since 1.10</para></refsect2>
 742 <refsect2 id="pango-cairo-show-error-underline" role="function" condition="since:1.14">
 743 <title>pango_cairo_show_error_underline ()</title>
 744 <indexterm zone="pango-cairo-show-error-underline" role="1.14"><primary sortas="pango_cairo_show_error_underline">pango_cairo_show_error_underline</primary></indexterm><programlisting><link linkend="void">void</link>                pango_cairo_show_error_underline    (<link linkend="cairo-t">cairo_t</link> *cr,
 745                                                          <link linkend="double">double</link> x,
 746                                                          <link linkend="double">double</link> y,
 747                                                          <link linkend="double">double</link> width,
 748                                                          <link linkend="double">double</link> height);</programlisting>
 749 <para>
 750 Draw a squiggly line in the specified cairo context that approximately
 751 covers the given rectangle in the style of an underline used to indicate a
 752 spelling error.  (The width of the underline is rounded to an integer
 753 number of up/down segments and the resulting rectangle is centered in the
 754 original rectangle)</para>
 755 <para>
 756 </para><variablelist role="params">
 757 <varlistentry><term><parameter>cr</parameter>&#160;:</term>
 758 <listitem><simpara> a Cairo context
 759 </simpara></listitem></varlistentry>
 760 <varlistentry><term><parameter>x</parameter>&#160;:</term>
 761 <listitem><simpara> The X coordinate of one corner of the rectangle
 762 </simpara></listitem></varlistentry>
 763 <varlistentry><term><parameter>y</parameter>&#160;:</term>
 764 <listitem><simpara> The Y coordinate of one corner of the rectangle
 765 </simpara></listitem></varlistentry>
 766 <varlistentry><term><parameter>width</parameter>&#160;:</term>
 767 <listitem><simpara> Non-negative width of the rectangle
 768 </simpara></listitem></varlistentry>
 769 <varlistentry><term><parameter>height</parameter>&#160;:</term>
 770 <listitem><simpara> Non-negative height of the rectangle
 771 </simpara></listitem></varlistentry>
 772 </variablelist><para role="since">Since 1.14</para></refsect2>
 773 <refsect2 id="pango-cairo-glyph-string-path" role="function" condition="since:1.10">
 774 <title>pango_cairo_glyph_string_path ()</title>
 775 <indexterm zone="pango-cairo-glyph-string-path" role="1.10"><primary sortas="pango_cairo_glyph_string_path">pango_cairo_glyph_string_path</primary></indexterm><programlisting><link linkend="void">void</link>                pango_cairo_glyph_string_path       (<link linkend="cairo-t">cairo_t</link> *cr,
 776                                                          <link linkend="PangoFont">PangoFont</link> *font,
 777                                                          <link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs);</programlisting>
 778 <para>
 779 Adds the glyphs in <parameter>glyphs</parameter> to the current path in the specified
 780 cairo context. The origin of the glyphs (the left edge of the baseline)
 781 will be at the current point of the cairo context.</para>
 782 <para>
 783 </para><variablelist role="params">
 784 <varlistentry><term><parameter>cr</parameter>&#160;:</term>
 785 <listitem><simpara> a Cairo context
 786 </simpara></listitem></varlistentry>
 787 <varlistentry><term><parameter>font</parameter>&#160;:</term>
 788 <listitem><simpara> a <link linkend="PangoFont"><type>PangoFont</type></link> from a <link linkend="PangoCairoFontMap"><type>PangoCairoFontMap</type></link>
 789 </simpara></listitem></varlistentry>
 790 <varlistentry><term><parameter>glyphs</parameter>&#160;:</term>
 791 <listitem><simpara> a <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link>
 792 </simpara></listitem></varlistentry>
 793 </variablelist><para role="since">Since 1.10</para></refsect2>
 794 <refsect2 id="pango-cairo-layout-line-path" role="function" condition="since:1.10">
 795 <title>pango_cairo_layout_line_path ()</title>
 796 <indexterm zone="pango-cairo-layout-line-path" role="1.10"><primary sortas="pango_cairo_layout_line_path">pango_cairo_layout_line_path</primary></indexterm><programlisting><link linkend="void">void</link>                pango_cairo_layout_line_path        (<link linkend="cairo-t">cairo_t</link> *cr,
 797                                                          <link linkend="PangoLayoutLine">PangoLayoutLine</link> *line);</programlisting>
 798 <para>
 799 Adds the text in <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link> to the current path in the
 800 specified cairo context.  The origin of the glyphs (the left edge
 801 of the line) will be at the current point of the cairo context.</para>
 802 <para>
 803 </para><variablelist role="params">
 804 <varlistentry><term><parameter>cr</parameter>&#160;:</term>
 805 <listitem><simpara> a Cairo context
 806 </simpara></listitem></varlistentry>
 807 <varlistentry><term><parameter>line</parameter>&#160;:</term>
 808 <listitem><simpara> a <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link>
 809 </simpara></listitem></varlistentry>
 810 </variablelist><para role="since">Since 1.10</para></refsect2>
 811 <refsect2 id="pango-cairo-layout-path" role="function" condition="since:1.10">
 812 <title>pango_cairo_layout_path ()</title>
 813 <indexterm zone="pango-cairo-layout-path" role="1.10"><primary sortas="pango_cairo_layout_path">pango_cairo_layout_path</primary></indexterm><programlisting><link linkend="void">void</link>                pango_cairo_layout_path             (<link linkend="cairo-t">cairo_t</link> *cr,
 814                                                          <link linkend="PangoLayout">PangoLayout</link> *layout);</programlisting>
 815 <para>
 816 Adds the text in a <link linkend="PangoLayout"><type>PangoLayout</type></link> to the current path in the
 817 specified cairo context.  The top-left corner of the <link linkend="PangoLayout"><type>PangoLayout</type></link>
 818 will be at the current point of the cairo context.</para>
 819 <para>
 820 </para><variablelist role="params">
 821 <varlistentry><term><parameter>cr</parameter>&#160;:</term>
 822 <listitem><simpara> a Cairo context
 823 </simpara></listitem></varlistentry>
 824 <varlistentry><term><parameter>layout</parameter>&#160;:</term>
 825 <listitem><simpara> a Pango layout
 826 </simpara></listitem></varlistentry>
 827 </variablelist><para role="since">Since 1.10</para></refsect2>
 828 <refsect2 id="pango-cairo-error-underline-path" role="function" condition="since:1.14">
 829 <title>pango_cairo_error_underline_path ()</title>
 830 <indexterm zone="pango-cairo-error-underline-path" role="1.14"><primary sortas="pango_cairo_error_underline_path">pango_cairo_error_underline_path</primary></indexterm><programlisting><link linkend="void">void</link>                pango_cairo_error_underline_path    (<link linkend="cairo-t">cairo_t</link> *cr,
 831                                                          <link linkend="double">double</link> x,
 832                                                          <link linkend="double">double</link> y,
 833                                                          <link linkend="double">double</link> width,
 834                                                          <link linkend="double">double</link> height);</programlisting>
 835 <para>
 836 Add a squiggly line to the current path in the specified cairo context that
 837 approximately covers the given rectangle in the style of an underline used
 838 to indicate a spelling error.  (The width of the underline is rounded to an
 839 integer number of up/down segments and the resulting rectangle is centered
 840 in the original rectangle)</para>
 841 <para>
 842 </para><variablelist role="params">
 843 <varlistentry><term><parameter>cr</parameter>&#160;:</term>
 844 <listitem><simpara> a Cairo context
 845 </simpara></listitem></varlistentry>
 846 <varlistentry><term><parameter>x</parameter>&#160;:</term>
 847 <listitem><simpara> The X coordinate of one corner of the rectangle
 848 </simpara></listitem></varlistentry>
 849 <varlistentry><term><parameter>y</parameter>&#160;:</term>
 850 <listitem><simpara> The Y coordinate of one corner of the rectangle
 851 </simpara></listitem></varlistentry>
 852 <varlistentry><term><parameter>width</parameter>&#160;:</term>
 853 <listitem><simpara> Non-negative width of the rectangle
 854 </simpara></listitem></varlistentry>
 855 <varlistentry><term><parameter>height</parameter>&#160;:</term>
 856 <listitem><simpara> Non-negative height of the rectangle
 857 </simpara></listitem></varlistentry>
 858 </variablelist><para role="since">Since 1.14</para></refsect2>
 859
 860 </refsect1>
 861
 862
 863
 864
 865 </refentry>