<?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="pango-Text-Processing">
<refmeta>
<refentrytitle role="top_of_page" id="pango-Text-Processing.top_of_page">Rendering</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>PANGO Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Rendering</refname>
<refpurpose>Functions to run the rendering pipeline</refpurpose>
</refnamediv>

<refsect1 id="pango-Text-Processing.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_return" colwidth="150px"/>
<colspec colname="functions_name"/>
<tbody>
<row><entry role="function_type"><link linkend="GList"><returnvalue>GList</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="pango-itemize">pango_itemize</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GList"><returnvalue>GList</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="pango-itemize-with-base-dir">pango_itemize_with_base_dir</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="pango-item-free">pango_item_free</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="PangoItem"><returnvalue>PangoItem</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="pango-item-copy">pango_item_copy</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="PangoItem"><returnvalue>PangoItem</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="pango-item-new">pango_item_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="PangoItem"><returnvalue>PangoItem</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="pango-item-split">pango_item_split</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="pango-item-apply-attrs">pango_item_apply_attrs</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GList"><returnvalue>GList</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="pango-reorder-items">pango_reorder_items</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="pango-break">pango_break</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="pango-get-log-attrs">pango_get_log_attrs</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="pango-find-paragraph-boundary">pango_find_paragraph_boundary</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="pango-default-break">pango_default_break</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="pango-tailor-break">pango_tailor_break</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="pango-shape">pango_shape</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="pango-shape-full">pango_shape_full</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="pango-shape-with-flags">pango_shape_with_flags</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<anchor id="PangoItem"/><refsect1 id="pango-Text-Processing.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="name" colwidth="150px"/>
<colspec colname="description"/>
<tbody>
<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="PangoItem-struct">PangoItem</link></entry></row>
<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="PangoAnalysis">PangoAnalysis</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="PANGO-ANALYSIS-FLAG-CENTERED-BASELINE:CAPS">PANGO_ANALYSIS_FLAG_CENTERED_BASELINE</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="PANGO-ANALYSIS-FLAG-IS-ELLIPSIS:CAPS">PANGO_ANALYSIS_FLAG_IS_ELLIPSIS</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="PANGO-ANALYSIS-FLAG-NEED-HYPHEN:CAPS">PANGO_ANALYSIS_FLAG_NEED_HYPHEN</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="PANGO-TYPE-DIRECTION:CAPS">PANGO_TYPE_DIRECTION</link></entry></row>


<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="PangoLogAttr">PangoLogAttr</link></entry></row>

<row><entry role="datatype_keyword">enum</entry><entry role="function_name"><link linkend="PangoShapeFlags">PangoShapeFlags</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="pango-Text-Processing.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<screen>    <link linkend="GBoxed">GBoxed</link>
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> PangoItem
    <link linkend="GFlags">GFlags</link>
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> PangoShapeFlags
</screen>
</refsect1>


<refsect1 id="pango-Text-Processing.description" role="desc">
<title role="desc.title">Description</title>
<para>The Pango rendering pipeline takes a string of
Unicode characters and converts it into glyphs.
The functions described in this section accomplish
various steps of this process.</para>
<para><inlinemediaobject><imageobject><imagedata fileref="pipeline.png"></imagedata></imageobject><textobject><phrase></phrase></textobject></inlinemediaobject></para>

</refsect1>
<refsect1 id="pango-Text-Processing.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="pango-itemize" role="function">
<title>pango_itemize&#160;()</title>
<indexterm zone="pango-itemize"><primary>pango_itemize</primary></indexterm>
<programlisting language="C"><link linkend="GList"><returnvalue>GList</returnvalue></link>&#160;*
pango_itemize (<parameter><link linkend="PangoContext"><type>PangoContext</type></link> *context</parameter>,
               <parameter>const <link linkend="char"><type>char</type></link> *text</parameter>,
               <parameter><link linkend="int"><type>int</type></link> start_index</parameter>,
               <parameter><link linkend="int"><type>int</type></link> length</parameter>,
               <parameter><link linkend="PangoAttrList"><type>PangoAttrList</type></link> *attrs</parameter>,
               <parameter><link linkend="PangoAttrIterator"><type>PangoAttrIterator</type></link> *cached_iter</parameter>);</programlisting>
<para>Breaks a piece of text into segments with consistent
directional level and shaping engine. Each byte of <parameter>text</parameter>
 will
be contained in exactly one of the items in the returned list;
the generated list of items will be in logical order (the start
offsets of the items are ascending).</para>
<para><parameter>cached_iter</parameter>
 should be an iterator over <parameter>attrs</parameter>
 currently positioned at a
range before or containing <parameter>start_index</parameter>
; <parameter>cached_iter</parameter>
 will be advanced to
the range covering the position just after <parameter>start_index</parameter>
 + <parameter>length</parameter>
.
(i.e. if itemizing in a loop, just keep passing in the same <parameter>cached_iter</parameter>
).</para>
<refsect3 id="pango-itemize.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>context</para></entry>
<entry role="parameter_description"><para>a structure holding information that affects
the itemization process.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>text</para></entry>
<entry role="parameter_description"><para>the text to itemize. Must be valid UTF-8</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>start_index</para></entry>
<entry role="parameter_description"><para>first byte in <parameter>text</parameter>
to process</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>length</para></entry>
<entry role="parameter_description"><para>the number of bytes (not characters) to process
after <parameter>start_index</parameter>
.
This must be &gt;= 0.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>attrs</para></entry>
<entry role="parameter_description"><para>the set of attributes that apply to <parameter>text</parameter>
.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>cached_iter</para></entry>
<entry role="parameter_description"><para>Cached attribute iterator, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="pango-itemize.returns" role="returns">
<title>Returns</title>
<para>a <link linkend="GList"><type>GList</type></link> of <link linkend="PangoItem"><type>PangoItem</type></link>
structures. The items should be freed using <link linkend="pango-item-free"><function>pango_item_free()</function></link>
probably in combination with <link linkend="g-list-foreach"><function>g_list_foreach()</function></link>, and the list itself
using <link linkend="g-list-free"><function>g_list_free()</function></link>. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>][<acronym>element-type</acronym> Pango.Item]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="pango-itemize-with-base-dir" role="function" condition="since:1.4">
<title>pango_itemize_with_base_dir&#160;()</title>
<indexterm zone="pango-itemize-with-base-dir" role="1.4"><primary>pango_itemize_with_base_dir</primary></indexterm>
<programlisting language="C"><link linkend="GList"><returnvalue>GList</returnvalue></link>&#160;*
pango_itemize_with_base_dir (<parameter><link linkend="PangoContext"><type>PangoContext</type></link> *context</parameter>,
                             <parameter><link linkend="PangoDirection"><type>PangoDirection</type></link> base_dir</parameter>,
                             <parameter>const <link linkend="char"><type>char</type></link> *text</parameter>,
                             <parameter><link linkend="int"><type>int</type></link> start_index</parameter>,
                             <parameter><link linkend="int"><type>int</type></link> length</parameter>,
                             <parameter><link linkend="PangoAttrList"><type>PangoAttrList</type></link> *attrs</parameter>,
                             <parameter><link linkend="PangoAttrIterator"><type>PangoAttrIterator</type></link> *cached_iter</parameter>);</programlisting>
<para>Like <link linkend="pango-itemize"><function>pango_itemize()</function></link>, but the base direction to use when
computing bidirectional levels (see <link linkend="pango-context-set-base-dir"><function>pango_context_set_base_dir()</function></link>),
is specified explicitly rather than gotten from the <link linkend="PangoContext"><type>PangoContext</type></link>.</para>
<refsect3 id="pango-itemize-with-base-dir.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>context</para></entry>
<entry role="parameter_description"><para>a structure holding information that affects
the itemization process.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>base_dir</para></entry>
<entry role="parameter_description"><para>base direction to use for bidirectional processing</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>text</para></entry>
<entry role="parameter_description"><para>the text to itemize.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>start_index</para></entry>
<entry role="parameter_description"><para>first byte in <parameter>text</parameter>
to process</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>length</para></entry>
<entry role="parameter_description"><para>the number of bytes (not characters) to process
after <parameter>start_index</parameter>
. This must be &gt;= 0.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>attrs</para></entry>
<entry role="parameter_description"><para>the set of attributes that apply to <parameter>text</parameter>
.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>cached_iter</para></entry>
<entry role="parameter_description"><para>Cached attribute iterator, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="pango-itemize-with-base-dir.returns" role="returns">
<title>Returns</title>
<para>a <link linkend="GList"><type>GList</type></link> of
<link linkend="PangoItem"><type>PangoItem</type></link> structures.  The items should be freed using
<link linkend="pango-item-free"><function>pango_item_free()</function></link> probably in combination with
<link linkend="g-list-foreach"><function>g_list_foreach()</function></link>, and the list itself using <link linkend="g-list-free"><function>g_list_free()</function></link>. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>][<acronym>element-type</acronym> Pango.Item]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-1.4">1.4</link></para></refsect2>
<refsect2 id="pango-item-free" role="function">
<title>pango_item_free&#160;()</title>
<indexterm zone="pango-item-free"><primary>pango_item_free</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
pango_item_free (<parameter><link linkend="PangoItem"><type>PangoItem</type></link> *item</parameter>);</programlisting>
<para>Free a <link linkend="PangoItem"><type>PangoItem</type></link> and all associated memory.</para>
<refsect3 id="pango-item-free.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>item</para></entry>
<entry role="parameter_description"><para>a <link linkend="PangoItem"><type>PangoItem</type></link>, may be <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="pango-item-copy" role="function">
<title>pango_item_copy&#160;()</title>
<indexterm zone="pango-item-copy"><primary>pango_item_copy</primary></indexterm>
<programlisting language="C"><link linkend="PangoItem"><returnvalue>PangoItem</returnvalue></link>&#160;*
pango_item_copy (<parameter><link linkend="PangoItem"><type>PangoItem</type></link> *item</parameter>);</programlisting>
<para>Copy an existing <link linkend="PangoItem"><type>PangoItem</type></link> structure.</para>
<refsect3 id="pango-item-copy.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>item</para></entry>
<entry role="parameter_description"><para>a <link linkend="PangoItem"><type>PangoItem</type></link>, may be <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="pango-item-copy.returns" role="returns">
<title>Returns</title>
<para>the newly allocated <link linkend="PangoItem"><type>PangoItem</type></link>, which
should be freed with <link linkend="pango-item-free"><function>pango_item_free()</function></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if
<parameter>item</parameter>
was <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="pango-item-new" role="function">
<title>pango_item_new&#160;()</title>
<indexterm zone="pango-item-new"><primary>pango_item_new</primary></indexterm>
<programlisting language="C"><link linkend="PangoItem"><returnvalue>PangoItem</returnvalue></link>&#160;*
pango_item_new (<parameter><type>void</type></parameter>);</programlisting>
<para>Creates a new <link linkend="PangoItem"><type>PangoItem</type></link> structure initialized to default values.</para>
<refsect3 id="pango-item-new.returns" role="returns">
<title>Returns</title>
<para> the newly allocated <link linkend="PangoItem"><type>PangoItem</type></link>, which should
be freed with <link linkend="pango-item-free"><function>pango_item_free()</function></link>.</para>
</refsect3></refsect2>
<refsect2 id="pango-item-split" role="function">
<title>pango_item_split&#160;()</title>
<indexterm zone="pango-item-split"><primary>pango_item_split</primary></indexterm>
<programlisting language="C"><link linkend="PangoItem"><returnvalue>PangoItem</returnvalue></link>&#160;*
pango_item_split (<parameter><link linkend="PangoItem"><type>PangoItem</type></link> *orig</parameter>,
                  <parameter><link linkend="int"><type>int</type></link> split_index</parameter>,
                  <parameter><link linkend="int"><type>int</type></link> split_offset</parameter>);</programlisting>
<para>Modifies <parameter>orig</parameter>
 to cover only the text after <parameter>split_index</parameter>
, and
returns a new item that covers the text before <parameter>split_index</parameter>
 that
used to be in <parameter>orig</parameter>
. You can think of <parameter>split_index</parameter>
 as the length of
the returned item. <parameter>split_index</parameter>
 may not be 0, and it may not be
greater than or equal to the length of <parameter>orig</parameter>
 (that is, there must
be at least one byte assigned to each item, you can't create a
zero-length item). <parameter>split_offset</parameter>
 is the length of the first item in
chars, and must be provided because the text used to generate the
item isn't available, so <link linkend="pango-item-split"><function>pango_item_split()</function></link> can't count the char
length of the split items itself.</para>
<refsect3 id="pango-item-split.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>orig</para></entry>
<entry role="parameter_description"><para>a <link linkend="PangoItem"><type>PangoItem</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>split_index</para></entry>
<entry role="parameter_description"><para>byte index of position to split item, relative to the start of the item</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>split_offset</para></entry>
<entry role="parameter_description"><para>number of chars between start of <parameter>orig</parameter>
and <parameter>split_index</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="pango-item-split.returns" role="returns">
<title>Returns</title>
<para> new item representing text before <parameter>split_index</parameter>
, which
should be freed with <link linkend="pango-item-free"><function>pango_item_free()</function></link>.</para>
</refsect3></refsect2>
<refsect2 id="pango-item-apply-attrs" role="function" condition="since:1.44">
<title>pango_item_apply_attrs&#160;()</title>
<indexterm zone="pango-item-apply-attrs" role="1.44"><primary>pango_item_apply_attrs</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
pango_item_apply_attrs (<parameter><link linkend="PangoItem"><type>PangoItem</type></link> *item</parameter>,
                        <parameter><link linkend="PangoAttrIterator"><type>PangoAttrIterator</type></link> *iter</parameter>);</programlisting>
<para>Add attributes to a PangoItem. The idea is that you have
attributes that don't affect itemization, such as font features,
so you filter them out using <link linkend="pango-attr-list-filter"><function>pango_attr_list_filter()</function></link>, itemize
your text, then reapply the attributes to the resulting items
using this function.</para>
<para>The <parameter>iter</parameter>
 should be positioned before the range of the item,
and will be advanced past it. This function is meant to be called
in a loop over the items resulting from itemization, while passing
the iter to each call.</para>
<refsect3 id="pango-item-apply-attrs.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>item</para></entry>
<entry role="parameter_description"><para>a <link linkend="PangoItem"><type>PangoItem</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>iter</para></entry>
<entry role="parameter_description"><para>a <link linkend="PangoAttrIterator"><type>PangoAttrIterator</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-1.44">1.44</link></para></refsect2>
<refsect2 id="pango-reorder-items" role="function">
<title>pango_reorder_items&#160;()</title>
<indexterm zone="pango-reorder-items"><primary>pango_reorder_items</primary></indexterm>
<programlisting language="C"><link linkend="GList"><returnvalue>GList</returnvalue></link>&#160;*
pango_reorder_items (<parameter><link linkend="GList"><type>GList</type></link> *logical_items</parameter>);</programlisting>
<para>From a list of items in logical order and the associated
directional levels, produce a list in visual order.
The original list is unmodified.</para>
<refsect3 id="pango-reorder-items.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>logical_items</para></entry>
<entry role="parameter_description"><para>a <link linkend="GList"><type>GList</type></link> of <link linkend="PangoItem"><type>PangoItem</type></link> in logical order. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>element-type</acronym> Pango.Item]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="pango-reorder-items.returns" role="returns">
<title>Returns</title>
<para>a <link linkend="GList"><type>GList</type></link>
of <link linkend="PangoItem"><type>PangoItem</type></link> structures in visual order.</para>
<para>(Please open a bug if you use this function.
It is not a particularly convenient interface, and the code
is duplicated elsewhere in Pango for that reason.). </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>][<acronym>element-type</acronym> Pango.Item]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="pango-break" role="function" condition="deprecated:1.44: Use pango_default_break() and pango_tailor_break()">
<title>pango_break&#160;()</title>
<indexterm zone="pango-break" role="deprecated"><primary>pango_break</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
pango_break (<parameter>const <link linkend="gchar"><type>gchar</type></link> *text</parameter>,
             <parameter><link linkend="int"><type>int</type></link> length</parameter>,
             <parameter><link linkend="PangoAnalysis"><type>PangoAnalysis</type></link> *analysis</parameter>,
             <parameter><link linkend="PangoLogAttr"><type>PangoLogAttr</type></link> *attrs</parameter>,
             <parameter><link linkend="int"><type>int</type></link> attrs_len</parameter>);</programlisting>
<warning><para><literal>pango_break</literal> has been deprecated since version 1.44 and should not be used in newly-written code.</para> <para>Use <link linkend="pango-default-break"><function>pango_default_break()</function></link> and <link linkend="pango-tailor-break"><function>pango_tailor_break()</function></link></para>
</warning>
<para>Determines possible line, word, and character breaks
for a string of Unicode text with a single analysis.
For most purposes you may want to use <link linkend="pango-get-log-attrs"><function>pango_get_log_attrs()</function></link>.</para>
<refsect3 id="pango-break.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>text</para></entry>
<entry role="parameter_description"><para>the text to process. Must be valid UTF-8</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>length</para></entry>
<entry role="parameter_description"><para>length of <parameter>text</parameter>
in bytes (may be -1 if <parameter>text</parameter>
is nul-terminated)</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>analysis</para></entry>
<entry role="parameter_description"><para><link linkend="PangoAnalysis"><type>PangoAnalysis</type></link> structure from <link linkend="pango-itemize"><function>pango_itemize()</function></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>attrs</para></entry>
<entry role="parameter_description"><para>an array to store character
information in. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> length=attrs_len]</emphasis></entry></row>
<row><entry role="parameter_name"><para>attrs_len</para></entry>
<entry role="parameter_description"><para>size of the array passed as <parameter>attrs</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="pango-get-log-attrs" role="function">
<title>pango_get_log_attrs&#160;()</title>
<indexterm zone="pango-get-log-attrs"><primary>pango_get_log_attrs</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
pango_get_log_attrs (<parameter>const <link linkend="char"><type>char</type></link> *text</parameter>,
                     <parameter><link linkend="int"><type>int</type></link> length</parameter>,
                     <parameter><link linkend="int"><type>int</type></link> level</parameter>,
                     <parameter><link linkend="PangoLanguage"><type>PangoLanguage</type></link> *language</parameter>,
                     <parameter><link linkend="PangoLogAttr"><type>PangoLogAttr</type></link> *log_attrs</parameter>,
                     <parameter><link linkend="int"><type>int</type></link> attrs_len</parameter>);</programlisting>
<para>Computes a <link linkend="PangoLogAttr"><type>PangoLogAttr</type></link> for each character in <parameter>text</parameter>
. The <parameter>log_attrs</parameter>

array must have one <link linkend="PangoLogAttr"><type>PangoLogAttr</type></link> for each position in <parameter>text</parameter>
; if
<parameter>text</parameter>
 contains N characters, it has N+1 positions, including the
last position at the end of the text. <parameter>text</parameter>
 should be an entire
paragraph; logical attributes can't be computed without context
(for example you need to see spaces on either side of a word to know
the word is a word).</para>
<refsect3 id="pango-get-log-attrs.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>text</para></entry>
<entry role="parameter_description"><para>text to process. Must be valid UTF-8</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>length</para></entry>
<entry role="parameter_description"><para>length in bytes of <parameter>text</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>level</para></entry>
<entry role="parameter_description"><para>embedding level, or -1 if unknown</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>language</para></entry>
<entry role="parameter_description"><para>language tag</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>log_attrs</para></entry>
<entry role="parameter_description"><para>array with one <link linkend="PangoLogAttr"><type>PangoLogAttr</type></link>
per character in <parameter>text</parameter>
, plus one extra, to be filled in. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> length=attrs_len]</emphasis></entry></row>
<row><entry role="parameter_name"><para>attrs_len</para></entry>
<entry role="parameter_description"><para>length of <parameter>log_attrs</parameter>
array</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="pango-find-paragraph-boundary" role="function">
<title>pango_find_paragraph_boundary&#160;()</title>
<indexterm zone="pango-find-paragraph-boundary"><primary>pango_find_paragraph_boundary</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
pango_find_paragraph_boundary (<parameter>const <link linkend="gchar"><type>gchar</type></link> *text</parameter>,
                               <parameter><link linkend="gint"><type>gint</type></link> length</parameter>,
                               <parameter><link linkend="gint"><type>gint</type></link> *paragraph_delimiter_index</parameter>,
                               <parameter><link linkend="gint"><type>gint</type></link> *next_paragraph_start</parameter>);</programlisting>
<para>Locates a paragraph boundary in <parameter>text</parameter>
. A boundary is caused by
delimiter characters, such as a newline, carriage return, carriage
return-newline pair, or Unicode paragraph separator character.  The
index of the run of delimiters is returned in
<parameter>paragraph_delimiter_index</parameter>
. The index of the start of the paragraph
(index after all delimiters) is stored in <parameter>next_paragraph_start</parameter>
.</para>
<para>If no delimiters are found, both <parameter>paragraph_delimiter_index</parameter>
 and
<parameter>next_paragraph_start</parameter>
 are filled with the length of <parameter>text</parameter>
 (an index one
off the end).</para>
<refsect3 id="pango-find-paragraph-boundary.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>text</para></entry>
<entry role="parameter_description"><para>UTF-8 text</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>length</para></entry>
<entry role="parameter_description"><para>length of <parameter>text</parameter>
in bytes, or -1 if nul-terminated</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>paragraph_delimiter_index</para></entry>
<entry role="parameter_description"><para>return location for index of
delimiter. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>next_paragraph_start</para></entry>
<entry role="parameter_description"><para>return location for start of next
paragraph. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="pango-default-break" role="function">
<title>pango_default_break&#160;()</title>
<indexterm zone="pango-default-break"><primary>pango_default_break</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
pango_default_break (<parameter>const <link linkend="gchar"><type>gchar</type></link> *text</parameter>,
                     <parameter><link linkend="int"><type>int</type></link> length</parameter>,
                     <parameter><link linkend="PangoAnalysis"><type>PangoAnalysis</type></link> *analysis</parameter>,
                     <parameter><link linkend="PangoLogAttr"><type>PangoLogAttr</type></link> *attrs</parameter>,
                     <parameter><link linkend="int"><type>int</type></link> attrs_len</parameter>);</programlisting>
<para>This is the default break algorithm. It applies Unicode
rules without language-specific tailoring, therefore
the <parameter>analyis</parameter>
 argument is unused and can be <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para>
<para>See <link linkend="pango-tailor-break"><function>pango_tailor_break()</function></link> for language-specific breaks.</para>
<refsect3 id="pango-default-break.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>text</para></entry>
<entry role="parameter_description"><para>text to break. Must be valid UTF-8</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>length</para></entry>
<entry role="parameter_description"><para>length of text in bytes (may be -1 if <parameter>text</parameter>
is nul-terminated)</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>analysis</para></entry>
<entry role="parameter_description"><para>a <link linkend="PangoAnalysis"><type>PangoAnalysis</type></link> for the <parameter>text</parameter>
. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>attrs</para></entry>
<entry role="parameter_description"><para>logical attributes to fill in</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>attrs_len</para></entry>
<entry role="parameter_description"><para>size of the array passed as <parameter>attrs</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="pango-tailor-break" role="function" condition="since:1.44">
<title>pango_tailor_break&#160;()</title>
<indexterm zone="pango-tailor-break" role="1.44"><primary>pango_tailor_break</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
pango_tailor_break (<parameter>const <link linkend="char"><type>char</type></link> *text</parameter>,
                    <parameter><link linkend="int"><type>int</type></link> length</parameter>,
                    <parameter><link linkend="PangoAnalysis"><type>PangoAnalysis</type></link> *analysis</parameter>,
                    <parameter><link linkend="int"><type>int</type></link> offset</parameter>,
                    <parameter><link linkend="PangoLogAttr"><type>PangoLogAttr</type></link> *log_attrs</parameter>,
                    <parameter><link linkend="int"><type>int</type></link> log_attrs_len</parameter>);</programlisting>
<para>Apply language-specific tailoring to the breaks in
<parameter>log_attrs</parameter>
, which are assumed to have been produced
by <link linkend="pango-default-break"><function>pango_default_break()</function></link>.</para>
<para>If <parameter>offset</parameter>
 is not -1, it is used to apply attributes
from <parameter>analysis</parameter>
 that are relevant to line breaking.</para>
<refsect3 id="pango-tailor-break.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>text</para></entry>
<entry role="parameter_description"><para>text to process. Must be valid UTF-8</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>length</para></entry>
<entry role="parameter_description"><para>length in bytes of <parameter>text</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>analysis</para></entry>
<entry role="parameter_description"><para><link linkend="PangoAnalysis"><type>PangoAnalysis</type></link> structure from <link linkend="pango-itemize"><function>pango_itemize()</function></link> for <parameter>text</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>offset</para></entry>
<entry role="parameter_description"><para>Byte offset of <parameter>text</parameter>
from the beginning of the
paragraph, or -1 to ignore attributes from <parameter>analysis</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>log_attrs</para></entry>
<entry role="parameter_description"><para>array with one <link linkend="PangoLogAttr"><type>PangoLogAttr</type></link>
per character in <parameter>text</parameter>
, plus one extra, to be filled in. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> length=log_attrs_len]</emphasis></entry></row>
<row><entry role="parameter_name"><para>log_attrs_len</para></entry>
<entry role="parameter_description"><para>length of <parameter>log_attrs</parameter>
array</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-1.44">1.44</link></para></refsect2>
<refsect2 id="pango-shape" role="function">
<title>pango_shape&#160;()</title>
<indexterm zone="pango-shape"><primary>pango_shape</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
pango_shape (<parameter>const <link linkend="char"><type>char</type></link> *text</parameter>,
             <parameter><link linkend="int"><type>int</type></link> length</parameter>,
             <parameter>const <link linkend="PangoAnalysis"><type>PangoAnalysis</type></link> *analysis</parameter>,
             <parameter><link linkend="PangoGlyphString"><type>PangoGlyphString</type></link> *glyphs</parameter>);</programlisting>
<para>Given a segment of text and the corresponding
<link linkend="PangoAnalysis"><type>PangoAnalysis</type></link> structure returned from <link linkend="pango-itemize"><function>pango_itemize()</function></link>,
convert the characters into glyphs. You may also pass
in only a substring of the item from <link linkend="pango-itemize"><function>pango_itemize()</function></link>.</para>
<para>It is recommended that you use <link linkend="pango-shape-full"><function>pango_shape_full()</function></link> instead, since
that API allows for shaping interaction happening across text item
boundaries.</para>
<refsect3 id="pango-shape.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>text</para></entry>
<entry role="parameter_description"><para>the text to process</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>length</para></entry>
<entry role="parameter_description"><para>the length (in bytes) of <parameter>text</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>analysis</para></entry>
<entry role="parameter_description"><para><link linkend="PangoAnalysis"><type>PangoAnalysis</type></link> structure from <link linkend="pango-itemize"><function>pango_itemize()</function></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>glyphs</para></entry>
<entry role="parameter_description"><para>glyph string in which to store results</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="pango-shape-full" role="function" condition="since:1.32">
<title>pango_shape_full&#160;()</title>
<indexterm zone="pango-shape-full" role="1.32"><primary>pango_shape_full</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
pango_shape_full (<parameter>const <link linkend="char"><type>char</type></link> *item_text</parameter>,
                  <parameter><link linkend="int"><type>int</type></link> item_length</parameter>,
                  <parameter>const <link linkend="char"><type>char</type></link> *paragraph_text</parameter>,
                  <parameter><link linkend="int"><type>int</type></link> paragraph_length</parameter>,
                  <parameter>const <link linkend="PangoAnalysis"><type>PangoAnalysis</type></link> *analysis</parameter>,
                  <parameter><link linkend="PangoGlyphString"><type>PangoGlyphString</type></link> *glyphs</parameter>);</programlisting>
<para>Given a segment of text and the corresponding
<link linkend="PangoAnalysis"><type>PangoAnalysis</type></link> structure returned from <link linkend="pango-itemize"><function>pango_itemize()</function></link>,
convert the characters into glyphs. You may also pass
in only a substring of the item from <link linkend="pango-itemize"><function>pango_itemize()</function></link>.</para>
<para>This is similar to <link linkend="pango-shape"><function>pango_shape()</function></link>, except it also can optionally take
the full paragraph text as input, which will then be used to perform
certain cross-item shaping interactions.  If you have access to the broader
text of which <parameter>item_text</parameter>
 is part of, provide the broader text as
<parameter>paragraph_text</parameter>
.  If <parameter>paragraph_text</parameter>
 is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, item text is used instead.</para>
<refsect3 id="pango-shape-full.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>item_text</para></entry>
<entry role="parameter_description"><para>valid UTF-8 text to shape.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>item_length</para></entry>
<entry role="parameter_description"><para>the length (in bytes) of <parameter>item_text</parameter>
. -1 means nul-terminated text.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>paragraph_text</para></entry>
<entry role="parameter_description"><para>text of the paragraph (see details).  May be <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>paragraph_length</para></entry>
<entry role="parameter_description"><para>the length (in bytes) of <parameter>paragraph_text</parameter>
. -1 means nul-terminated text.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>analysis</para></entry>
<entry role="parameter_description"><para><link linkend="PangoAnalysis"><type>PangoAnalysis</type></link> structure from <link linkend="pango-itemize"><function>pango_itemize()</function></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>glyphs</para></entry>
<entry role="parameter_description"><para>glyph string in which to store results.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-1.32">1.32</link></para></refsect2>
<refsect2 id="pango-shape-with-flags" role="function" condition="since:1.44">
<title>pango_shape_with_flags&#160;()</title>
<indexterm zone="pango-shape-with-flags" role="1.44"><primary>pango_shape_with_flags</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
pango_shape_with_flags (<parameter>const <link linkend="char"><type>char</type></link> *item_text</parameter>,
                        <parameter><link linkend="int"><type>int</type></link> item_length</parameter>,
                        <parameter>const <link linkend="char"><type>char</type></link> *paragraph_text</parameter>,
                        <parameter><link linkend="int"><type>int</type></link> paragraph_length</parameter>,
                        <parameter>const <link linkend="PangoAnalysis"><type>PangoAnalysis</type></link> *analysis</parameter>,
                        <parameter><link linkend="PangoGlyphString"><type>PangoGlyphString</type></link> *glyphs</parameter>,
                        <parameter><link linkend="PangoShapeFlags"><type>PangoShapeFlags</type></link> flags</parameter>);</programlisting>
<para>Given a segment of text and the corresponding
<link linkend="PangoAnalysis"><type>PangoAnalysis</type></link> structure returned from <link linkend="pango-itemize"><function>pango_itemize()</function></link>,
convert the characters into glyphs. You may also pass
in only a substring of the item from <link linkend="pango-itemize"><function>pango_itemize()</function></link>.</para>
<para>This is similar to <link linkend="pango-shape-full"><function>pango_shape_full()</function></link>, except it also takes
flags that can influence the shaping process.</para>
<refsect3 id="pango-shape-with-flags.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>item_text</para></entry>
<entry role="parameter_description"><para>valid UTF-8 text to shape</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>item_length</para></entry>
<entry role="parameter_description"><para>the length (in bytes) of <parameter>item_text</parameter>
.
-1 means nul-terminated text.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>paragraph_text</para></entry>
<entry role="parameter_description"><para>text of the paragraph (see details).
May be <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>paragraph_length</para></entry>
<entry role="parameter_description"><para>the length (in bytes) of <parameter>paragraph_text</parameter>
.
-1 means nul-terminated text.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>analysis</para></entry>
<entry role="parameter_description"><para><link linkend="PangoAnalysis"><type>PangoAnalysis</type></link> structure from <link linkend="pango-itemize"><function>pango_itemize()</function></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>glyphs</para></entry>
<entry role="parameter_description"><para>glyph string in which to store results</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>flags</para></entry>
<entry role="parameter_description"><para>flags influencing the shaping process</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-1.44">1.44</link></para></refsect2>

</refsect1>
<refsect1 id="pango-Text-Processing.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="PangoItem-struct" role="struct">
<title>struct PangoItem</title>
<indexterm zone="PangoItem-struct"><primary>PangoItem</primary></indexterm>
<programlisting language="C">struct PangoItem {
  gint offset;
  gint length;
  gint num_chars;
  PangoAnalysis analysis;
};
</programlisting>
<para>The <link linkend="PangoItem"><type>PangoItem</type></link> structure stores information about a segment of text.</para>
<refsect3 id="PangoItem.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para><link linkend="gint"><type>gint</type></link>&#160;<structfield id="PangoItem-struct.offset">offset</structfield>;</para></entry>
<entry role="struct_member_description"><para>byte offset of the start of this item in text.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="gint"><type>gint</type></link>&#160;<structfield id="PangoItem-struct.length">length</structfield>;</para></entry>
<entry role="struct_member_description"><para>length of this item in bytes.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="gint"><type>gint</type></link>&#160;<structfield id="PangoItem-struct.num-chars">num_chars</structfield>;</para></entry>
<entry role="struct_member_description"><para>number of Unicode characters in the item.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="PangoAnalysis"><type>PangoAnalysis</type></link>&#160;<structfield id="PangoItem-struct.analysis">analysis</structfield>;</para></entry>
<entry role="struct_member_description"><para>analysis results for the item.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3>
</refsect2>
<refsect2 id="PangoAnalysis" role="struct">
<title>struct PangoAnalysis</title>
<indexterm zone="PangoAnalysis"><primary>PangoAnalysis</primary></indexterm>
<programlisting language="C">struct PangoAnalysis {
  PangoEngineShape *shape_engine;
  PangoEngineLang  *lang_engine;
  PangoFont *font;

  guint8 level;
  guint8 gravity;
  guint8 flags;

  guint8 script;
  PangoLanguage *language;

  GSList *extra_attrs;
};
</programlisting>
<para>The <link linkend="PangoAnalysis"><type>PangoAnalysis</type></link> structure stores information about
the properties of a segment of text.</para>
<refsect3 id="PangoAnalysis.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para><link linkend="PangoEngineShape"><type>PangoEngineShape</type></link>&#160;*<structfield id="PangoAnalysis.shape-engine">shape_engine</structfield>;</para></entry>
<entry role="struct_member_description"><para>unused</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="PangoEngineLang"><type>PangoEngineLang</type></link>&#160;*<structfield id="PangoAnalysis.lang-engine">lang_engine</structfield>;</para></entry>
<entry role="struct_member_description"><para>unused</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="PangoFont"><type>PangoFont</type></link>&#160;*<structfield id="PangoAnalysis.font">font</structfield>;</para></entry>
<entry role="struct_member_description"><para>the font for this segment.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint8"><type>guint8</type></link>&#160;<structfield id="PangoAnalysis.level">level</structfield>;</para></entry>
<entry role="struct_member_description"><para>the bidirectional level for this segment.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint8"><type>guint8</type></link>&#160;<structfield id="PangoAnalysis.gravity">gravity</structfield>;</para></entry>
<entry role="struct_member_description"><para>the glyph orientation for this segment (A <link linkend="PangoGravity"><type>PangoGravity</type></link>).</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint8"><type>guint8</type></link>&#160;<structfield id="PangoAnalysis.flags">flags</structfield>;</para></entry>
<entry role="struct_member_description"><para>boolean flags for this segment (Since: 1.16).</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint8"><type>guint8</type></link>&#160;<structfield id="PangoAnalysis.script">script</structfield>;</para></entry>
<entry role="struct_member_description"><para>the detected script for this segment (A <link linkend="PangoScript"><type>PangoScript</type></link>) (Since: 1.18).</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="PangoLanguage"><type>PangoLanguage</type></link>&#160;*<structfield id="PangoAnalysis.language">language</structfield>;</para></entry>
<entry role="struct_member_description"><para>the detected language for this segment.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="GSList"><type>GSList</type></link>&#160;*<structfield id="PangoAnalysis.extra-attrs">extra_attrs</structfield>;</para></entry>
<entry role="struct_member_description"><para>extra attributes for this segment.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3>
</refsect2>
<refsect2 id="PANGO-ANALYSIS-FLAG-CENTERED-BASELINE:CAPS" role="macro" condition="since:1.16">
<title>PANGO_ANALYSIS_FLAG_CENTERED_BASELINE</title>
<indexterm zone="PANGO-ANALYSIS-FLAG-CENTERED-BASELINE:CAPS" role="1.16"><primary>PANGO_ANALYSIS_FLAG_CENTERED_BASELINE</primary></indexterm>
<programlisting language="C">#define PANGO_ANALYSIS_FLAG_CENTERED_BASELINE (1 &lt;&lt; 0)
</programlisting>
<para>Whether the segment should be shifted to center around the baseline.
Used in vertical writing directions mostly.</para>
<para role="since">Since: <link linkend="api-index-1.16">1.16</link></para></refsect2>
<refsect2 id="PANGO-ANALYSIS-FLAG-IS-ELLIPSIS:CAPS" role="macro" condition="since:1.36.7">
<title>PANGO_ANALYSIS_FLAG_IS_ELLIPSIS</title>
<indexterm zone="PANGO-ANALYSIS-FLAG-IS-ELLIPSIS:CAPS" role="1.36.7"><primary>PANGO_ANALYSIS_FLAG_IS_ELLIPSIS</primary></indexterm>
<programlisting language="C">#define PANGO_ANALYSIS_FLAG_IS_ELLIPSIS (1 &lt;&lt; 1)
</programlisting>
<para>This flag is used to mark runs that hold ellipsized text,
in an ellipsized layout.</para>
<para role="since">Since: <link linkend="api-index-1.36.7">1.36.7</link></para></refsect2>
<refsect2 id="PANGO-ANALYSIS-FLAG-NEED-HYPHEN:CAPS" role="macro" condition="since:1.44">
<title>PANGO_ANALYSIS_FLAG_NEED_HYPHEN</title>
<indexterm zone="PANGO-ANALYSIS-FLAG-NEED-HYPHEN:CAPS" role="1.44"><primary>PANGO_ANALYSIS_FLAG_NEED_HYPHEN</primary></indexterm>
<programlisting language="C">#define PANGO_ANALYSIS_FLAG_NEED_HYPHEN (1 &lt;&lt; 2)
</programlisting>
<para>This flag tells Pango to add a hyphen at the end of the
run during shaping.</para>
<para role="since">Since: <link linkend="api-index-1.44">1.44</link></para></refsect2>
<refsect2 id="PANGO-TYPE-DIRECTION:CAPS" role="macro">
<title>PANGO_TYPE_DIRECTION</title>
<indexterm zone="PANGO-TYPE-DIRECTION:CAPS"><primary>PANGO_TYPE_DIRECTION</primary></indexterm>
<programlisting language="C">#define PANGO_TYPE_DIRECTION (pango_direction_get_type ())
</programlisting>
</refsect2>
<refsect2 id="PangoLogAttr" role="struct">
<title>PangoLogAttr</title>
<indexterm zone="PangoLogAttr"><primary>PangoLogAttr</primary></indexterm>
<programlisting language="C">typedef struct {
  guint is_line_break               : 1;
  guint is_mandatory_break          : 1;
  guint is_char_break               : 1;
  guint is_white                    : 1;
  guint is_cursor_position          : 1;
  guint is_word_start               : 1;
  guint is_word_end                 : 1;
  guint is_sentence_boundary        : 1;
  guint is_sentence_start           : 1;
  guint is_sentence_end             : 1;
  guint backspace_deletes_character : 1;
  guint is_expandable_space         : 1;
  guint is_word_boundary            : 1;
} PangoLogAttr;
</programlisting>
<para>The <link linkend="PangoLogAttr"><type>PangoLogAttr</type></link> structure stores information
about the attributes of a single character.</para>
<refsect3 id="PangoLogAttr.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint"><type>guint</type></link>&#160;<structfield id="PangoLogAttr.is-line-break">is_line_break</structfield>&#160;:&#160;1;</para></entry>
<entry role="struct_member_description"><para>if set, can break line in front of character</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint"><type>guint</type></link>&#160;<structfield id="PangoLogAttr.is-mandatory-break">is_mandatory_break</structfield>&#160;:&#160;1;</para></entry>
<entry role="struct_member_description"><para>if set, must break line in front of character</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint"><type>guint</type></link>&#160;<structfield id="PangoLogAttr.is-char-break">is_char_break</structfield>&#160;:&#160;1;</para></entry>
<entry role="struct_member_description"><para>if set, can break here when doing character wrapping</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint"><type>guint</type></link>&#160;<structfield id="PangoLogAttr.is-white">is_white</structfield>&#160;:&#160;1;</para></entry>
<entry role="struct_member_description"><para>is whitespace character</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint"><type>guint</type></link>&#160;<structfield id="PangoLogAttr.is-cursor-position">is_cursor_position</structfield>&#160;:&#160;1;</para></entry>
<entry role="struct_member_description"><para>if set, cursor can appear in front of character.
i.e. this is a grapheme boundary, or the first character
in the text.
This flag implements Unicode's</para>
<ulink url="http://www.unicode.org/reports/tr29/">Grapheme
Cluster Boundaries</ulink> semantics.</entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint"><type>guint</type></link>&#160;<structfield id="PangoLogAttr.is-word-start">is_word_start</structfield>&#160;:&#160;1;</para></entry>
<entry role="struct_member_description"><para>is first character in a word</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint"><type>guint</type></link>&#160;<structfield id="PangoLogAttr.is-word-end">is_word_end</structfield>&#160;:&#160;1;</para></entry>
<entry role="struct_member_description"><para>is first non-word char after a word
Note that in degenerate cases, you could have both <parameter>is_word_start</parameter>
and <parameter>is_word_end</parameter>
set for some character.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint"><type>guint</type></link>&#160;<structfield id="PangoLogAttr.is-sentence-boundary">is_sentence_boundary</structfield>&#160;:&#160;1;</para></entry>
<entry role="struct_member_description"><para>is a sentence boundary.
There are two ways to divide sentences. The first assigns all
inter-sentence whitespace/control/format chars to some sentence,
so all chars are in some sentence; <parameter>is_sentence_boundary</parameter>
denotes
the boundaries there. The second way doesn't assign
between-sentence spaces, etc. to any sentence, so
<parameter>is_sentence_start</parameter>
/<parameter>is_sentence_end</parameter>
mark the boundaries of those sentences.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint"><type>guint</type></link>&#160;<structfield id="PangoLogAttr.is-sentence-start">is_sentence_start</structfield>&#160;:&#160;1;</para></entry>
<entry role="struct_member_description"><para>is first character in a sentence</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint"><type>guint</type></link>&#160;<structfield id="PangoLogAttr.is-sentence-end">is_sentence_end</structfield>&#160;:&#160;1;</para></entry>
<entry role="struct_member_description"><para>is first char after a sentence.
Note that in degenerate cases, you could have both <parameter>is_sentence_start</parameter>
and <parameter>is_sentence_end</parameter>
set for some character. (e.g. no space after a
period, so the next sentence starts right away)</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint"><type>guint</type></link>&#160;<structfield id="PangoLogAttr.backspace-deletes-character">backspace_deletes_character</structfield>&#160;:&#160;1;</para></entry>
<entry role="struct_member_description"><para>if set, backspace deletes one character
rather than the entire grapheme cluster. This
field is only meaningful on grapheme
boundaries (where <parameter>is_cursor_position</parameter>
is
set).  In some languages, the full grapheme
(e.g.  letter + diacritics) is considered a
unit, while in others, each decomposed
character in the grapheme is a unit. In the
default implementation of <link linkend="pango-break"><function>pango_break()</function></link>, this
bit is set on all grapheme boundaries except
those following Latin, Cyrillic or Greek base characters.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint"><type>guint</type></link>&#160;<structfield id="PangoLogAttr.is-expandable-space">is_expandable_space</structfield>&#160;:&#160;1;</para></entry>
<entry role="struct_member_description"><para>is a whitespace character that can possibly be
expanded for justification purposes. (Since: 1.18)</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint"><type>guint</type></link>&#160;<structfield id="PangoLogAttr.is-word-boundary">is_word_boundary</structfield>&#160;:&#160;1;</para></entry>
<entry role="struct_member_description"><para>is a word boundary, as defined by UAX<link linkend="29"><type>29</type></link>.
More specifically, means that this is not a position in the middle
of a word.  For example, both sides of a punctuation mark are
considered word boundaries.  This flag is particularly useful when
selecting text word-by-word.
This flag implements Unicode's</para>
<ulink url="http://www.unicode.org/reports/tr29/">Word
Boundaries</ulink> semantics. (Since: 1.22)</entry>
<entry role="struct_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3>
</refsect2>
<refsect2 id="PangoShapeFlags" role="enum">
<title>enum PangoShapeFlags</title>
<indexterm zone="PangoShapeFlags"><primary>PangoShapeFlags</primary></indexterm>
<para>Flags influencing the shaping process.
These can be passed to <link linkend="pango-shape-with-flags"><function>pango_shape_with_flags()</function></link>.</para>
<refsect3 id="PangoShapeFlags.members" role="enum_members">
<title>Members</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="enum_members_name" colwidth="300px"/>
<colspec colname="enum_members_description"/>
<colspec colname="enum_members_annotations" colwidth="200px"/>
<tbody>
<row role="constant"><entry role="enum_member_name"><para id="PANGO-SHAPE-NONE:CAPS">PANGO_SHAPE_NONE</para></entry>
<entry role="enum_member_description"><para>Default value.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="PANGO-SHAPE-ROUND-POSITIONS:CAPS">PANGO_SHAPE_ROUND_POSITIONS</para></entry>
<entry role="enum_member_description"><para>Round glyph positions
    and widths to whole device units. This option should
    be set if the target renderer can't do subpixel
    positioning of glyphs.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>

</refsect1>

</refentry>
