path: root/docs/reference/pygtk-gtktreemodelsort.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-gtktreemodelsort">
  <refnamediv>
    <refname>gtk.TreeModelSort</refname>
    <refpurpose>a tree model that is a sorted version of a child <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link></refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.TreeModelSort</classname></ooclass>
      <ooclass><classname><link
linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <ooclass><classname><link
linkend="class-gtktreemodel">gtk.TreeModel</link></classname></ooclass>
      <ooclass><classname><link
linkend="class-gtktreesortable">gtk.TreeSortable</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtktreemodelsort">gtk.TreeModelSort</link></methodname>
	<methodparam><parameter
		       role="keyword">child_model</parameter></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodelsort--get-model">get_model</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodelsort--convert-child-path-to-path">convert_child_path_to_path</link></methodname>
	<methodparam><parameter
		       role="keyword">child_path</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodelsort--convert-child-iter-to-iter">convert_child_iter_to_iter</link></methodname>
	<methodparam><parameter
		       role="keyword">sort_iter</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">child_iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodelsort--convert-path-to-child-path">convert_path_to_child_path</link></methodname>
	<methodparam><parameter
		       role="keyword">sorted_path</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodelsort--convert-iter-to-child-iter">convert_iter_to_child_iter</link></methodname>
	<methodparam><parameter
		       role="keyword">child_iter</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">sorted_iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodelsort--reset-default-sort-func">reset_default_sort_func</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodelsort--clear-cache">clear_cache</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreemodelsort--iter-is-valid">iter_is_valid</link></methodname>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtktreemodelsort">gtk.TreeModelSort</link> (implements <link linkend="class-gtktreemodel">gtk.TreeModel</link>, <link linkend="class-gtktreesortable">gtk.TreeSortable</link>)
</synopsis>

  </refsect1>

  <refsect1 id="properties-gtktreemodelsort">
    <title>gtk.TreeModelSort Properties</title>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"model"</entry>
	      <entry>Read-Write-Construct</entry>
	      <entry>The child model for the <link
linkend="class-gtktreemodelsort"><classname>gtk.TreeModelSort</classname></link> 
to sort.</entry>
	    </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="signal-prototypes-gtktreemodelsort">
    <title>gtk.TreeModelSort Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtktreesortable">gtk.TreeSortable Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtktreemodel">gtk.TreeModel Signal Prototypes</link></para>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>A <link
linkend="class-gtktreemodelsort"><classname>gtk.TreeModelSort</classname></link> 
is a sorted model of its child model. A <link
linkend="class-gtktreemodelsort"><classname>gtk.TreeModelSort</classname></link> 
implements the <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
interface and the <link
linkend="class-gtktreesortable"><classname>gtk.TreeSortable</classname></link> 
interface to manage the sort functions.</para>

    <para>The <link
linkend="class-gtktreemodelsort"><classname>gtk.TreeModelSort</classname></link>
objects support the Python mapping and iterator protocols. See the <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
Description and the <ulink
url="http://www.pygtk.org/pygtk2tutorial/sec-TreeModelInterface.html#sec-PythonProtocolSupport">PyGTK
tutorial</ulink> for more information.</para>

  </refsect1>

  <refsect1 id="constructor-gtktreemodelsort">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.TreeModelSort</methodname>
	<methodparam><parameter
		       role="keyword">child_model</parameter></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter
role="keyword">child_model</parameter>&nbsp;:</term>
	<listitem><simpara>a child <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link></simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>A new <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>.</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>,
with <parameter>child_model</parameter> as the child model.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtktreemodelsort--get-model">
      <title>gtk.TreeModelSort.get_model</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_model</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the "child model" being
sorted</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_model</methodname>() method returns the
model that the <link
linkend="class-gtktreemodelsort"><classname>gtk.TreeModelSort</classname></link> 
is sorting.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodelsort--convert-child-path-to-path">
      <title>gtk.TreeModelSort.convert_child_path_to_path</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>convert_child_path_to_path</methodname>
	  <methodparam><parameter
			 role="keyword">child_path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">child_path</parameter>&nbsp;:</term>
	  <listitem><simpara>A child tree path to
convert</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A new tree path in the treemodelsort, or
<literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>convert_child_path_to_path</methodname>() method
converts the path in the child model specified by
<parameter>child_path</parameter> to a path relative to the treemodelsort.
That is, <parameter>child_path</parameter> points to a path in the child
model.  The returned path will point to the same row in the sorted model.
If <parameter>child_path</parameter> isn't a valid path on the child model,
then <literal>None</literal> is returned.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodelsort--convert-child-iter-to-iter">
      <title>gtk.TreeModelSort.convert_child_iter_to_iter</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>convert_child_iter_to_iter</methodname>
	  <methodparam><parameter
			 role="keyword">sort_iter</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">child_iter</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">sort_iter</parameter>&nbsp;:</term>
	  <listitem><simpara><literal>None</literal> or a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> for
backward compatibility.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">child_iter</parameter>&nbsp;:</term>
	  <listitem><simpara>A valid <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing to a row on the child model</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing to the same path in the sorted model.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>convert_child_iter_to_iter</methodname>() method
returns a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> that
points to the row in the treemodelsort that corresponds to the row pointed
to by <parameter>child_iter</parameter>. <parameter>sort_iter</parameter>
parameter should be <literal>None</literal> but can specify a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> for
backward compatibility.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodelsort--convert-path-to-child-path">
      <title>gtk.TreeModelSort.convert_path_to_child_path</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>convert_path_to_child_path</methodname>
	  <methodparam><parameter
			 role="keyword">sorted_path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">sorted_path</parameter>&nbsp;:</term>
	  <listitem><simpara>a path in the sorted model</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new path in the child model, or
<literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>convert_path_to_child_path</methodname>() method
returns a path in the child model that refers to the same row as the path in
the sorted model specified by <parameter>sorted_path</parameter>. That is,
<parameter>sorted_path</parameter> points to a location in treemodelsort and
the returned path will point to the same location in the child model. If
<parameter>sorted_path</parameter> does not point to a location in the child
model, <literal>None</literal> is returned.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodelsort--convert-iter-to-child-iter">
      <title>gtk.TreeModelSort.convert_iter_to_child_iter</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>convert_iter_to_child_iter</methodname>
	  <methodparam><parameter
			 role="keyword">child_iter</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">sorted_iter</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">child_iter</parameter>&nbsp;:</term>
	  <listitem><simpara><literal>None</literal> or a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> for
backward compatibility.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">sorted_iter</parameter>&nbsp;:</term>
	  <listitem><simpara>A valid <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing to a row on
<parameter>tree_model_sort</parameter>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> that
points to a row in the child model</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>convert_iter_to_child_iter</methodname>() method
returns a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> that
points to the row in the child model that is the same row pointed to by
<parameter>sorted_iter</parameter> in the treemodelsort.
<parameter>child_iter</parameter> should be <literal>None</literal> but can
specify a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> for
backward compatibility.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodelsort--reset-default-sort-func">
      <title>gtk.TreeModelSort.reset_default_sort_func</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>reset_default_sort_func</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>reset_default_sort_func</methodname>() method
resets the default sort function to be in the 'unsorted' state.  That is, it
is in the same order as the child model. It will re-sort the model to be in
the same order as the child model only if the <link
linkend="class-gtktreemodelsort"><classname>gtk.TreeModelSort</classname></link> 
is in 'unsorted' state.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodelsort--clear-cache">
      <title>gtk.TreeModelSort.clear_cache</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>clear_cache</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>clear_cache</methodname>() method clears the
treemodelsort of any cached iterators that haven't been reffed with the
<link
linkend="method-gtktreemodel--ref-node"><methodname>ref_node</methodname>()</link>
method.  This might be useful if the child model being sorted is static (and
doesn't change often) and there has been a lot of unreffed access to nodes.
As a side effect of this function, all unreffed <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
objects will be invalid.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodelsort--iter-is-valid">
      <title>gtk.TreeModelSort.iter_is_valid</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>iter_is_valid</methodname>
	  <methodparam><parameter role="keyword">iter</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>iter</parameter>&nbsp;:</term>
	  <listitem><simpara>A <link
	  linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if
	  <parameter>iter</parameter> is valid</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>iter_is_valid</methodname>() method checks if
the <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
specified by <parameter>iter</parameter> is valid for the treemodel
sort.</para>

      <warning>
	<para>This method is slow. Only use it for debugging and/or testing
purposes.</para>
      </warning>

    </refsect2>

  </refsect1>

</refentry>