<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="gdk4-Pango-Interaction">
<refmeta>
<refentrytitle role="top_of_page" id="gdk4-Pango-Interaction.top_of_page">Pango Interaction</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Pango Interaction</refname>
<refpurpose>Using Pango in GDK</refpurpose>
</refnamediv>

<refsect1 id="gdk4-Pango-Interaction.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="cairo-region-t"><returnvalue>cairo_region_t</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gdk-pango-layout-get-clip-region">gdk_pango_layout_get_clip_region</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="cairo-region-t"><returnvalue>cairo_region_t</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gdk-pango-layout-line-get-clip-region">gdk_pango_layout_line_get_clip_region</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="gdk4-Pango-Interaction.includes"><title>Includes</title><synopsis>#include &lt;gdk/gdk.h&gt;
</synopsis></refsect1>

<refsect1 id="gdk4-Pango-Interaction.description" role="desc">
<title role="desc.title">Description</title>
<para>Pango is the text layout system used by GDK and GTK. The functions
and types in this section are used to obtain clip regions for
<link linkend="PangoLayouts"><type>PangoLayouts</type></link>, and to get <link linkend="PangoContexts"><type>PangoContexts</type></link> that can be used with
GDK.</para>
<para>Creating a <link linkend="PangoLayout"><type>PangoLayout</type></link> object is the first step in rendering text,
and requires getting a handle to a <link linkend="PangoContext"><type>PangoContext</type></link>. For GTK programs,
you’ll usually want to use <link linkend="gtk-widget-get-pango-context"><function>gtk_widget_get_pango_context()</function></link>, or
<link linkend="gtk-widget-create-pango-layout"><function>gtk_widget_create_pango_layout()</function></link>. Once you have a <link linkend="PangoLayout"><type>PangoLayout</type></link>,
you can set the text and attributes of it with Pango functions like
<link linkend="pango-layout-set-text"><function>pango_layout_set_text()</function></link> and get its size with <link linkend="pango-layout-get-size"><function>pango_layout_get_size()</function></link>.
(Note that Pango uses a fixed point system internally, so converting
between Pango units and pixels using <link linkend="PANGO-SCALE-CAPS">PANGO_SCALE</link>
or the <link linkend="PANGO-PIXELS:CAPS"><function>PANGO_PIXELS()</function></link> macro.)</para>
<para>Rendering a Pango layout is done most simply with <link linkend="pango-cairo-show-layout"><function>pango_cairo_show_layout()</function></link>;
you can also draw pieces of the layout with <link linkend="pango-cairo-show-layout-line"><function>pango_cairo_show_layout_line()</function></link>.</para>
<refsect3 id="rotated-example"><title>Draw transformed text with Pango and cairo</title><informalexample><programlisting role="example"><![CDATA[
#define RADIUS 100
#define N_WORDS 10
#define FONT "Sans Bold 18"

PangoContext *context;
PangoLayout *layout;
PangoFontDescription *desc;

double radius;
int width, height;
int i;

// Set up a transformation matrix so that the user space coordinates for
// where we are drawing are [-RADIUS, RADIUS], [-RADIUS, RADIUS]
// We first center, then change the scale

width = gdk_surface_get_width (surface);
height = gdk_surface_get_height (surface);
radius = MIN (width, height) / 2.;

cairo_translate (cr,
                 radius + (width - 2 * radius) / 2,
                 radius + (height - 2 * radius) / 2);
                 cairo_scale (cr, radius / RADIUS, radius / RADIUS);

// Create a PangoLayout, set the font and text
context = gdk_pango_context_get_for_display (display);
layout = pango_layout_new (context);
pango_layout_set_text (layout, "Text", -1);
desc = pango_font_description_from_string (FONT);
pango_layout_set_font_description (layout, desc);
pango_font_description_free (desc);

// Draw the layout N_WORDS times in a circle
for (i = 0; i < N_WORDS; i++)
  {
    double red, green, blue;
    double angle = 2 * G_PI * i / n_words;

    cairo_save (cr);

    // Gradient from red at angle == 60 to blue at angle == 300
    red = (1 + cos (angle - 60)) / 2;
    green = 0;
    blue = 1 - red;

    cairo_set_source_rgb (cr, red, green, blue);
    cairo_rotate (cr, angle);

    // Inform Pango to re-layout the text with the new transformation matrix
    pango_cairo_update_layout (cr, layout);

    pango_layout_get_size (layout, &width, &height);

    cairo_move_to (cr, - width / 2 / PANGO_SCALE, - DEFAULT_TEXT_RADIUS);
    pango_cairo_show_layout (cr, layout);

    cairo_restore (cr);
  }

g_object_unref (layout);
g_object_unref (context);
]]></programlisting></informalexample>
<para></para>
</refsect3>
<refsect3><title>Output of the <link linkend="rotated-example">example</link> above.</title><para><inlinemediaobject><imageobject><imagedata fileref="rotated-text.png"></imagedata></imageobject><textobject><phrase></phrase></textobject></inlinemediaobject></para>
</refsect3>

</refsect1>
<refsect1 id="gdk4-Pango-Interaction.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gdk-pango-layout-get-clip-region" role="function">
<title>gdk_pango_layout_get_clip_region&#160;()</title>
<indexterm zone="gdk-pango-layout-get-clip-region"><primary>gdk_pango_layout_get_clip_region</primary></indexterm>
<programlisting language="C"><link linkend="cairo-region-t"><returnvalue>cairo_region_t</returnvalue></link>&#160;*
gdk_pango_layout_get_clip_region (<parameter><link linkend="PangoLayout"><type>PangoLayout</type></link> *layout</parameter>,
                                  <parameter><link linkend="int"><type>int</type></link> x_origin</parameter>,
                                  <parameter><link linkend="int"><type>int</type></link> y_origin</parameter>,
                                  <parameter>const <link linkend="int"><type>int</type></link> *index_ranges</parameter>,
                                  <parameter><link linkend="int"><type>int</type></link> n_ranges</parameter>);</programlisting>
<para>Obtains a clip region which contains the areas where the given ranges
of text would be drawn. <parameter>x_origin</parameter>
 and <parameter>y_origin</parameter>
 are the top left point
to center the layout. <parameter>index_ranges</parameter>
 should contain
ranges of bytes in the layout’s text.</para>
<para>Note that the regions returned correspond to logical extents of the text
ranges, not ink extents. So the drawn layout may in fact touch areas out of
the clip region.  The clip region is mainly useful for highlightling parts
of text, such as when text is selected.</para>

<para><emphasis role="annotation">[<acronym>skip</acronym>]</emphasis></para><refsect3 id="gdk-pango-layout-get-clip-region.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>layout</para></entry>
<entry role="parameter_description"><para>a <link linkend="PangoLayout"><type>PangoLayout</type></link> </para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>x_origin</para></entry>
<entry role="parameter_description"><para>X pixel where you intend to draw the layout with this clip</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>y_origin</para></entry>
<entry role="parameter_description"><para>Y pixel where you intend to draw the layout with this clip</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>index_ranges</para></entry>
<entry role="parameter_description"><para>array of byte indexes into the layout, where even members of array are start indexes and odd elements are end indexes</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>n_ranges</para></entry>
<entry role="parameter_description"><para>number of ranges in <parameter>index_ranges</parameter>
, i.e. half the size of <parameter>index_ranges</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-pango-layout-get-clip-region.returns" role="returns">
<title>Returns</title>
<para> a clip region containing the given ranges</para>
</refsect3></refsect2>
<refsect2 id="gdk-pango-layout-line-get-clip-region" role="function">
<title>gdk_pango_layout_line_get_clip_region&#160;()</title>
<indexterm zone="gdk-pango-layout-line-get-clip-region"><primary>gdk_pango_layout_line_get_clip_region</primary></indexterm>
<programlisting language="C"><link linkend="cairo-region-t"><returnvalue>cairo_region_t</returnvalue></link>&#160;*
gdk_pango_layout_line_get_clip_region (<parameter><link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link> *line</parameter>,
                                       <parameter><link linkend="int"><type>int</type></link> x_origin</parameter>,
                                       <parameter><link linkend="int"><type>int</type></link> y_origin</parameter>,
                                       <parameter>const <link linkend="int"><type>int</type></link> *index_ranges</parameter>,
                                       <parameter><link linkend="int"><type>int</type></link> n_ranges</parameter>);</programlisting>
<para>Obtains a clip region which contains the areas where the given
ranges of text would be drawn. <parameter>x_origin</parameter>
 and <parameter>y_origin</parameter>
 are the top left
position of the layout. <parameter>index_ranges</parameter>

should contain ranges of bytes in the layout’s text. The clip
region will include space to the left or right of the line (to the
layout bounding box) if you have indexes above or below the indexes
contained inside the line. This is to draw the selection all the way
to the side of the layout. However, the clip region is in line coordinates,
not layout coordinates.</para>
<para>Note that the regions returned correspond to logical extents of the text
ranges, not ink extents. So the drawn line may in fact touch areas out of
the clip region.  The clip region is mainly useful for highlightling parts
of text, such as when text is selected.</para>

<para><emphasis role="annotation">[<acronym>skip</acronym>]</emphasis></para><refsect3 id="gdk-pango-layout-line-get-clip-region.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>line</para></entry>
<entry role="parameter_description"><para>a <link linkend="PangoLayoutLine"><type>PangoLayoutLine</type></link> </para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>x_origin</para></entry>
<entry role="parameter_description"><para>X pixel where you intend to draw the layout line with this clip</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>y_origin</para></entry>
<entry role="parameter_description"><para>baseline pixel where you intend to draw the layout line with this clip</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>index_ranges</para></entry>
<entry role="parameter_description"><para>array of byte indexes into the layout,
where even members of array are start indexes and odd elements
are end indexes. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>n_ranges</para></entry>
<entry role="parameter_description"><para>number of ranges in <parameter>index_ranges</parameter>
, i.e. half the size of <parameter>index_ranges</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-pango-layout-line-get-clip-region.returns" role="returns">
<title>Returns</title>
<para> a clip region containing the given ranges</para>
</refsect3></refsect2>

</refsect1>

</refentry>
