path: root/docs/reference/pygtk-pangolayoutiter.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="class-pangolayoutiter">
  <refnamediv>
    <refname>pango.LayoutIter</refname>
    <refpurpose>an object used to iterate over the visual extents of a
<link
linkend="class-pangolayout"><classname>pango.Layout</classname></link>
(new in PyGTK 2.6)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>pango.LayoutIter</classname></ooclass>
      <ooclass><classname><link
linkend="class-gobjectgboxed">gobject.GBoxed</link></classname></ooclass>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolayoutiter--free">free</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolayoutiter--next-char">next_char</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolayoutiter--next-cluster">next_cluster</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolayoutiter--next-line">next_line</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolayoutiter--next-run">next_run</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolayoutiter--at-last-line">at_last_line</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolayoutiter--get-index">get_index</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolayoutiter--get-baseline">get_baseline</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolayoutiter--get-char-extents">get_char_extents</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolayoutiter--get-cluster-extents">get_cluster_extents</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolayoutiter--get-layout-extents">get_layout_extents</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolayoutiter--get-line-extents">get_line_extents</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolayoutiter--get-run-extents">get_run_extents</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolayoutiter--get-line-yrange">get_line_yrange</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolayoutiter--get-line-yrange">get_line</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>

    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobjectgboxed">gobject.GBoxed</link>
  +-- <link linkend="class-pangolayoutiter">pango.LayoutIter</link>
</synopsis>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>A <link
linkend="class-pangolayoutiter"><classname>pango.LayoutIter</classname></link>
object can be used to iterate over the visual elements of a <link
linkend="class-pangolayout"><classname>pango.Layout</classname></link>. A
<link
linkend="class-pangolayoutiter"><classname>pango.LayoutIter</classname></link>
is created using the <link
linkend="method-pangolayout--get-iter"><methodname>pango.Layout.get_iter</methodname>()</link>
method.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

  <refsect2 id="method-pangolayoutiter--free">
      <title>pango.LayoutIter.free</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>free</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-pangolayout"><classname>pango.Layout</classname></link> that
is a copy of the layout</simpara></listitem>
	</varlistentry>
      </variablelist>

      <warning>
        <para>This method is deprecated and should not be used since it may
crash your application.</para>
      </warning>

      <para>The <methodname>free</methodname>() method frees the <link
linkend="class-pangolayoutiter"><classname>pango.LayoutIter</classname></link>
object.</para>

    </refsect2>

    <refsect2 id="method-pangolayoutiter--next-char">
      <title>pango.LayoutIter.next_char</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>next_char</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>TRUE</literal> if the iter was
moved.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>next_char</methodname>() method returns
<literal>TRUE</literal> if the <link
linkend="class-pangolayoutiter"><classname>pango.LayoutIter</classname></link>
is moved to the next character in visual order. If the iter was already at
the end of the layout this method returns <literal>FALSE</literal>.</para>

    </refsect2>

    <refsect2 id="method-pangolayoutiter--next-cluster">
      <title>pango.LayoutIter.next_cluster</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>next_cluster</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>TRUE</literal> if the iter was
moved.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>next_cluster</methodname>() method returns
<literal>TRUE</literal> if the <link
linkend="class-pangolayoutiter"><classname>pango.LayoutIter</classname></link>
is moved to the next cluster in visual order. If the iter was already at the
end of the layout this method returns <literal>FALSE</literal>.</para>

    </refsect2>

    <refsect2 id="method-pangolayoutiter--next-line">
      <title>pango.LayoutIter.next_line</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>next_line</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>TRUE</literal> if the iter was
moved.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>next_line</methodname>() method returns
<literal>TRUE</literal> if the <link
linkend="class-pangolayoutiter"><classname>pango.LayoutIter</classname></link>
is moved to the next line in visual order. If the iter was already at the
end of the layout this method returns <literal>FALSE</literal>.</para>

    </refsect2>

    <refsect2 id="method-pangolayoutiter--next-run">
      <title>pango.LayoutIter.next_run</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>next_run</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>TRUE</literal> if the iter was
moved.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>next_run</methodname>() method returns
<literal>TRUE</literal> if the <link
linkend="class-pangolayoutiter"><classname>pango.LayoutIter</classname></link>
is moved to the next run in visual order. If the iter was already at the end
of the layout this method returns <literal>FALSE</literal>.</para>

    </refsect2>

    <refsect2 id="method-pangolayoutiter--at-last-line">
      <title>pango.LayoutIter.at_last_line</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>at_last_line</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>TRUE</literal> if the iter is in the
last line.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>at_last_line</methodname>() method returns
<literal>TRUE</literal> if the <link
linkend="class-pangolayoutiter"><classname>pango.LayoutIter</classname></link>
points to a position in the last line of the layout.</para>

    </refsect2>

    <refsect2 id="method-pangolayoutiter--get-index">
      <title>pango.LayoutIter.get_index</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_index</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the current byte index</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_index</methodname>() method returns the
current byte index. Note that iterating forward by char moves in visual
order, not logical order, so indexes may not be sequential. Also, the index
may be equal to the length of the text in the layout.</para>

    </refsect2>

    <refsect2 id="method-pangolayoutiter--get-baseline">
      <title>pango.LayoutIter.get_baseline</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_baseline</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the baseline of the current
line.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_baseline</methodname>() method returns the y
position of the current line's baseline, in layout coordinates (origin at
top left of the entire layout).</para>

    </refsect2>

    <refsect2 id="method-pangolayoutiter--get-char-extents">
      <title>pango.LayoutIter.get_char_extents</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_char_extents</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a 4-tuple containing the logical extents of the
character at the iter position.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_char_extents</methodname>() method returns a
4-tuple (x, y, width, height) containing the logical extents of the current
character, in layout coordinates (origin is the top left of the entire
layout). Only logical extents can sensibly be obtained for characters; ink
extents make sense only down to the level of clusters.</para>

    </refsect2>

    <refsect2 id="method-pangolayoutiter--get-cluster-extents">
      <title>pango.LayoutIter.get_cluster_extents</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_cluster_extents</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a 2-tuple containing containing the
ink and logical extents as 4-tuples.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_cluster_extents</methodname>() method
returns a 2-tuple containing the ink and logical extents (as 4-tuples: x, y,
width, height) of the cluster at the iter position.</para>

    </refsect2>

    <refsect2 id="method-pangolayoutiter--get-layout-extents">
      <title>pango.LayoutIter.get_layout_extents</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_layout_extents</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a 2-tuple containing containing the
ink and logical extents as 4-tuples.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_layout_extents</methodname>() method returns
a 2-tuple containing the ink and logical extents (as 4-tuples: x, y, width,
height) of the layout at the iter position.</para>

    </refsect2>

    <refsect2 id="method-pangolayoutiter--get-line-extents">
      <title>pango.LayoutIter.get_line_extents</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_line_extents</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a 2-tuple containing containing the
ink and logical extents as 4-tuples.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_line_extents</methodname>() method returns a
2-tuple containing the ink and logical extents (as 4-tuples: x, y, width,
height) of the line at the iter position.</para>

    </refsect2>

    <refsect2 id="method-pangolayoutiter--get-run-extents">
      <title>pango.LayoutIter.get_run_extents</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_run_extents</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a 2-tuple containing containing the
ink and logical extents as 4-tuples.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_run_extents</methodname>() method returns a
2-tuple containing the ink and logical extents (as 4-tuples: x, y, width,
height) of the run at the iter position.</para>

    </refsect2>

    <refsect2 id="method-pangolayoutiter--get-line-yrange">
      <title>pango.LayoutIter.get_line_yrange</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_line_yrange</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a 2-tuple containing the start and end of the
layout line.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_line_yrange</methodname>() method returns a
2-tuple containing the start and end y positions of the layout line. The
vertical space in the <link
linkend="class-pangolayout"><classname>pango.Layout</classname></link>
associated with the iter is devided between the lines in the layout, the
space belonging to the current line is returned in the 2-tuple. A line's
range includes the line's logical extents, plus half of the spacing above
and below the line, if the <link
linkend="method-pangolayout--set-spacing"><methodname>pango.Layout.set_spacing</methodname>()</link>
method has been called to set the layout spacing. The y positions are in layout
coordinates (origin at top left of the entire layout).</para>

    </refsect2>

    <refsect2 id="method-pangolayoutiter--get-line">
      <title>pango.LayoutIter.get_line</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_line</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangolayoutline"><classname>pango.LayoutLine</classname></link>
containing the current line.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.8 and above.</para>
      </note>

      <para>The <methodname>get_line</methodname>() method returns a <link
linkend="class-pangolayoutline"><classname>pango.LayoutLine</classname></link>
containing the current line.</para>

    </refsect2>

  </refsect1>

</refentry>