path: root/docs/reference/pygtk-gtktreemodel.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-gtktreemodel">
  <refnamediv>
    <refname>gtk.TreeModel</refname>
    <refpurpose>the tree interface used by <link
linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link></refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.TreeModel</classname></ooclass>
      <ooclass><classname>gobject.GInterface</classname></ooclass>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--get-flags">get_flags</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--get-n-columns">get_n_columns</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--get-column-type">get_column_type</link></methodname>
	<methodparam><parameter
		       role="keyword">index</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--get-iter">get_iter</link></methodname>
	<methodparam><parameter
		       role="keyword">path</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--get-iter-from-string">get_iter_from_string</link></methodname>
	<methodparam><parameter
		       role="keyword">path_string</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreemodel--get-string-from-iter">get_string_from_iter</link></methodname>
	<methodparam><parameter>iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--get-iter-root">get_iter_root</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--get-iter-first">get_iter_first</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--get-path">get_path</link></methodname>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--get-value">get_value</link></methodname>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">column</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--iter-next">iter_next</link></methodname>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--iter-children">iter_children</link></methodname>
	<methodparam><parameter
		       role="keyword">parent</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--iter-has-child">iter_has_child</link></methodname>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--iter-n-children">iter_n_children</link></methodname>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--iter-nth-child">iter_nth_child</link></methodname>
	<methodparam><parameter
		       role="keyword">parent</parameter></methodparam>
	<methodparam><parameter role="keyword">n</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--iter-parent">iter_parent</link></methodname>
	<methodparam><parameter
		       role="keyword">child</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--ref-node">ref_node</link></methodname>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--unref-node">unref_node</link></methodname>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--get">get</link></methodname>
	<methodparam><parameter>iter</parameter></methodparam>
	<methodparam><parameter>column</parameter></methodparam>
	<methodparam><parameter>...</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--foreach">foreach</link></methodname>
	<methodparam><parameter>func</parameter></methodparam>
	<methodparam><parameter>user_data</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--row-changed">row_changed</link></methodname>
	<methodparam><parameter
		       role="keyword">path</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--row-inserted">row_inserted</link></methodname>
	<methodparam><parameter
		       role="keyword">path</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--row-has-child-toggled">row_has_child_toggled</link></methodname>
	<methodparam><parameter
		       role="keyword">path</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreemodel--row-deleted">row_deleted</link></methodname>
	<methodparam><parameter
		       role="keyword">path</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreemodel--rows-reordered">rows_reordered</link></methodname>
	<methodparam><parameter role="keyword">path</parameter></methodparam>
	<methodparam><parameter role="keyword">iter</parameter></methodparam>
	<methodparam><parameter role="keyword">new_order</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreemodel--filter-new">filter_new</link></methodname>
	<methodparam><parameter role="keyword">root</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>

    </classsynopsis>

    <programlisting>
<emphasis role="bold">Functions</emphasis>

<methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--tree-row-reference-inserted">gtk.tree_row_reference_inserted</link></methodname>
	<methodparam><parameter
		       role="keyword">proxy</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">path</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--tree-row-reference-deleted">gtk.tree_row_reference_deleted</link></methodname>
	<methodparam><parameter
		       role="keyword">proxy</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">path</parameter></methodparam>
      </methodsynopsis></programlisting>

  </refsect1>

  <refsect1 id="signal-prototypes-gtktreemodel">
    <title>gtk.TreeModel Signal Prototypes</title>

    <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gtktreemodel--row-changed">row-changed</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>treemodel</parameter></methodparam>
            <methodparam><parameter>path</parameter></methodparam>
            <methodparam><parameter>iter</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtktreemodel--row-deleted">row-deleted</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>treemodel</parameter></methodparam>
            <methodparam><parameter>path</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtktreemodel--row-has-child-toggled">row-has-child-toggled</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>treemodel</parameter></methodparam>
            <methodparam><parameter>path</parameter></methodparam>
            <methodparam><parameter>iter</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtktreemodel--row-inserted">row-inserted</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>treemodel</parameter></methodparam>
            <methodparam><parameter>path</parameter></methodparam>
            <methodparam><parameter>iter</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtktreemodel--rows-reordered">rows-reordered</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>treemodel</parameter></methodparam>
            <methodparam><parameter>path</parameter></methodparam>
            <methodparam><parameter>iter</parameter></methodparam>
            <methodparam><parameter>new_order</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
interface defines a generic tree interface for use by the <link
linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link>
widget. It is an abstract interface, and is designed to be usable with any
appropriate data structure. The programmer just has to implement this
interface on their own data type for it to be viewable by a <link
linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link>
widget.</para>

    <para>The model is represented as a hierarchical tree of strongly-typed,
columned data. In other words, the model can be seen as a tree where every
node has different values depending on which column is being queried. The
type of data found in a column is determined by using the Python or GObject
type system (i.e. gobject.TYPE_INT, gtk.BUTTON, gobject.TYPE_STRING, etc.).
The types are homogeneous per column across all nodes. It is important to
note that this interface only provides a way of examining a model and
observing changes. The implementation of each individual model decides how
and if changes are made.</para>

    <para>In order to make life simpler for programmers who do not need to
write their own specialized model, two generic models are provided: the
<link
linkend="class-gtktreestore"><classname>gtk.TreeStore</classname></link> and
the <link
linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>. To
use these, the developer simply pushes data into these models as necessary.
These models provide the data structure as well as all appropriate tree
interfaces. As a result, implementing drag and drop, sorting, and storing
data is trivial. For the vast majority of trees and lists, these two models
are sufficient.</para>

    <para>Models are accessed on a node-column level of granularity. One can
query for the value of a model at a certain node and a certain column on
that node. A particular node in a model is referenced using a path or a
<link linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
object. Most of the interface consists of operations on a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>.</para>

    <para>A path is essentially a potential node. It is a location on a
model that may or may not actually correspond to a node on a specific model.
A path can be converted into either an array of unsigned integers or a
string. The string form is a list of numbers separated by a colon. Each
number refers to the offset at that level. Thus, the path "0" refers to the
root node and the path "2:4" refers to the fifth child of the third
node.</para>

    <para>By contrast, a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> is a
reference to a specific node on a specific model. One can convert a path to
a treeiter by calling <link
linkend="method-gtktreemodel--get-iter"><methodname>get_iter</methodname>()</link>. 
These treeiters are the primary way of accessing a model and are similar to
the textiters used by <link
linkend="class-gtktextbuffer"><classname>gtk.TextBuffer</classname></link>.
The model interface defines a set of operations using them for navigating
the model.</para>

    <para>It is expected that models fill in the treeiter with private data.
For example, the <link
linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>
model, which is internally a simple linked list, stores a list node in one
of the pointers. The <link
linkend="class-gtktreemodelsort"><classname>gtk.TreeModelSort</classname></link> 
stores an array and an offset in two of the pointers. Additionally, there is
an integer field. This field is generally filled with a unique stamp per
model. This stamp is for catching errors resulting from using invalid
treeiters with a model.</para>

    <para>The lifecycle of a treeiter can be a little confusing at first.
treeiters are expected to always be valid for as long as the model is
unchanged (and doesn't emit a signal). The model is considered to own all
outstanding treeiters and nothing needs to be done to free them from the
user's point of view. Additionally, some models guarantee that an treeiter
is valid for as long as the node it refers to is valid (most notably the
<link
linkend="class-gtktreestore"><classname>gtk.TreeStore</classname></link> and
<link
linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>).
Although generally uninteresting, as one always has to allow for the case
where treeiters do not persist beyond a signal, some very important
performance enhancements were made in the sort model. As a result, the
<literal>gtk.TREE_MODEL_ITERS_PERSIST</literal> flag was added to indicate
this behavior.</para>

    <para>A <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
object supports some of the Python Mapping protocol that allows you to
retrieve a <link
linkend="class-pygtktreemodelrow"><classname>gtk.TreeModelRow</classname></link>
object representing a row in the model. You can also set the values in a row
using the same protocol. For example, you can retrieve the second row of a
<link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
using any of:</para>

    <programlisting>
  treemodelrow = model[1]
  treemodelrow = model[(1,)]
  treemodelrow = model['1']
  treemodelrow = model["1"]
</programlisting>

    <para>Also if the model has two columns both containing strings then the
following will set the values of the third row.</para>

    <programlisting>
  model[(2,)] = ('new string value', 'string 2')
</programlisting>

    <para>You can also retrieve the number of top level items in the <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link> by
using the Python <function>len</function>() function:</para>

    <programlisting>
  n_rows = len(model)
</programlisting>

    <para>A <link
linkend="class-pygtktreemodelrowiter"><classname>gtk.TreeModelRowIter</classname></link>
object can be retrieved for iterating over the top level rows of a <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link> by
calling the Python <function>iter</function>() function:</para>

    <programlisting>
  treemodelrowiter = iter(model)
</programlisting>

    <para>See the <ulink
url="http://www.pygtk.org/pygtk2tutorial/sec-TreeModelInterface.html#sec-PythonProtocolSupport">PyGTK
tutorial</ulink> for more information.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtktreemodel--get-flags">
      <title>gtk.TreeModel.get_flags</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_flags</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the flags supported by this
interface.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_flags</methodname>() method returns a set of
flags supported by this interface.  The flags are a bitwise combination
of:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>gtk.TREE_MODEL_ITERS_PERSIST</literal></term>
	  <listitem>
	    <simpara>Treeiters survive all signals emitted by the
tree.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.TREE_MODEL_LIST_ONLY</literal></term>
	  <listitem>
	    <simpara>The model is a list only, and never has
children</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>The flags supported should not change during the lifecycle of
the tree_model.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--get-n-columns">
      <title>gtk.TreeModel.get_n_columns</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_n_columns</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>The number of columns.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_n_columns</methodname>() method returns the
number of columns supported by the treemodel.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--get-column-type">
      <title>gtk.TreeModel.get_column_type</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_column_type</methodname>
	  <methodparam><parameter
			 role="keyword">index</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">index</parameter>&nbsp;:</term>
	  <listitem><simpara>the column index.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the type of the column.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_column_type</methodname>() method returns
the type of the column.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--get-iter">
      <title>gtk.TreeModel.get_iter</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_iter</methodname>
	  <methodparam><parameter
			 role="keyword">path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">path</parameter>&nbsp;:</term>
	  <listitem><simpara>a path</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> that
points at <parameter>path</parameter>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_iter</methodname>() method returns a new
<link linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing to <parameter>path</parameter>. This method raises a
<literal>ValueError</literal> exception if <parameter>path</parameter> is
not a valid tree path.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--get-iter-from-string">
      <title>gtk.TreeModel.get_iter_from_string</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_iter_from_string</methodname>
	  <methodparam><parameter
			 role="keyword">path_string</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">path_string</parameter>&nbsp;:</term>
	  <listitem><simpara>a string representation of a
path.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> that
points at the path represented by
<parameter>path_string</parameter></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_iter_from_string</methodname>() method
returns a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing to the path represented by <parameter>path_string</parameter>, if
it exists. This method raises a <literal>ValueError</literal> exception if
<parameter>path_string</parameter> does not represent a valid tree
path.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--get-string-from-iter">
      <title>gtk.TreeModel.get_string_from_iter</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_string_from_iter</methodname>
	  <methodparam><parameter>iter</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>iter</parameter>&nbsp;:</term>
	  <listitem><simpara>An <link
	  linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A string representation of iter</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_string_from_iter</methodname>() method
returns a string representation of the path pointed to by
<parameter>iter</parameter>. This string is a ':' separated list of
numbers. For example, "4:10:0:3" would be an acceptable return value for
this string.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--get-iter-root">
      <title>gtk.TreeModel.get_iter_root</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_iter_root</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> that
points at the first path in the treemodel or
<literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_iter_root</methodname>() method returns a
<link linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing to the path "0" or <literal>None</literal> if the tree is
empty.</para>

    </refsect2>

  <refsect2 id="method-gtktreemodel--get-iter-first">
    <title>gtk.TreeModel.get_iter_first</title>

<programlisting><methodsynopsis language="python">
    <methodname>get_iter_first</methodname>
    <methodparam></methodparam>
  </methodsynopsis></programlisting>
  <variablelist>
    <varlistentry>
      <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> that points at the first path in the treemodel or <literal>None</literal></simpara></listitem>
    </varlistentry>
  </variablelist>

      <para>The <methodname>get_iter_first</methodname>() method returns a
<link linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing to the path "0" or <literal>None</literal> if the tree is
empty.</para>

</refsect2>

    <refsect2 id="method-gtktreemodel--get-path">
      <title>gtk.TreeModel.get_path</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_path</methodname>
	  <methodparam><parameter
			 role="keyword">iter</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">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>the tree path referenced by
<parameter>iter</parameter>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_path</methodname>() method returns the tree
path referenced by <parameter>iter</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--get-value">
      <title>gtk.TreeModel.get_value</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_value</methodname>
	  <methodparam><parameter
			 role="keyword">iter</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">column</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">iter</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">column</parameter>&nbsp;:</term>
	  <listitem><simpara>the column value to
retrieve.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a value.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_value</methodname>() method returns the
value at <parameter>column</parameter> at the path pointed to by
<parameter>iter</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--iter-next">
      <title>gtk.TreeModel.iter_next</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>iter_next</methodname>
	  <methodparam><parameter
			 role="keyword">iter</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">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>a <link
	  linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
	  pointing at the next row or <literal>None</literal> if there is no
	  next row.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>iter_next</methodname>() method returns a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing at the row at the current level after the row referenced by
<parameter>iter</parameter>. If there is no next row,
<literal>None</literal> is returned. <parameter>iter</parameter> is
unchanged.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--iter-children">
      <title>gtk.TreeModel.iter_children</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>iter_children</methodname>
	  <methodparam><parameter
			 role="keyword">parent</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">parent</parameter>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing to the parent or <literal>None</literal>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the new <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> to be
set to the first child or <literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>iter_children</methodname>() method returns a
new <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing to the first child of <parameter>parent</parameter>.  If
<parameter>parent</parameter> has no children, <literal>None</literal> is
returned. <parameter>parent</parameter> will remain a valid node after this
method has been called.</para>
      <para>If <parameter>parent</parameter> is <literal>None</literal> returns
      the first node, equivalent to
      <methodname><link linkend="method-gtktreemodel--get-iter-first">gtk.TreeModel.get_iter_first</link></methodname>().
      </para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--iter-has-child">
      <title>gtk.TreeModel.iter_has_child</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>iter_has_child</methodname>
	  <methodparam><parameter
			 role="keyword">iter</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">iter</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> to
test for children.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if
<parameter>iter</parameter> has children.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>iter_has_child</methodname>() method returns
<literal>True</literal> if <parameter>iter</parameter> has children, or
<literal>False</literal> otherwise.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--iter-n-children">
      <title>gtk.TreeModel.iter_n_children</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>iter_n_children</methodname>
	  <methodparam><parameter
			 role="keyword">iter</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">iter</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>, or
<literal>None</literal>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the number of children of
<parameter>iter</parameter>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>iter_n_children</methodname>() method returns
the number of children that <parameter>iter</parameter> has.  As a special
case, if <parameter>iter</parameter> is <literal>None</literal>, then the
number of top level nodes is returned.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--iter-nth-child">
      <title>gtk.TreeModel.iter_nth_child</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>iter_nth_child</methodname>
	  <methodparam><parameter
			 role="keyword">parent</parameter></methodparam>
	  <methodparam><parameter role="keyword">n</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">parent</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> to
get the child from, or <literal>None</literal>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">n</parameter>&nbsp;:</term>
	  <listitem><simpara>Then index of the desired
child.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> that
is set to the nth child or <literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>iter_nth_child</methodname>() method returns a
new <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing to the child of <parameter>parent</parameter>, with the index
specified by <parameter>n</parameter>. The first index is 0.  If
<parameter>n</parameter> is too big, or <parameter>parent</parameter> has no
children, this method returns <literal>None</literal>.
<parameter>parent</parameter> will remain a valid node after this function
has been called.  As a special case, if <parameter>parent</parameter> is
<literal>None</literal>, then the treeiter points to the
<parameter>n</parameter>th root node.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--iter-parent">
      <title>gtk.TreeModel.iter_parent</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>iter_parent</methodname>
	  <methodparam><parameter
			 role="keyword">child</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">child</parameter>&nbsp;:</term>
	  <listitem><simpara>The <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> set
to the parent of <parameter>child</parameter> or
<literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>iter_parent</methodname>() method returns a
<link linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing to the parent of <parameter>child</parameter>.  If
<parameter>child</parameter> is at the top level, and doesn't have a parent,
then <literal>None</literal> is returned.  <parameter>child</parameter> will
remain a valid node after this method has been called.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--ref-node">
      <title>gtk.TreeModel.ref_node</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>ref_node</methodname>
	  <methodparam><parameter
			 role="keyword">iter</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">iter</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>ref_node</methodname>() method lets the
treemodel ref the node that <parameter>iter</parameter> points to. This is
an optional method for models to implement.  To be more specific, models may
ignore this call as it exists primarily for performance reasons. This
function is primarily meant as a way for views to let the caching model know
when nodes are being displayed (and hence, whether or not to cache that
node.)  For example, a file-system based model would not want to keep the
entire file-hierarchy in memory, just the sections that are currently being
displayed by every current view. A model should be expected to be able to
get a treeiter independent of it's reffed state.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--unref-node">
      <title>gtk.TreeModel.unref_node</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>unref_node</methodname>
	  <methodparam><parameter
			 role="keyword">iter</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">iter</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>unref_node</methodname>() method lets the
treemodel unref the node that <parameter>iter</parameter> points to. This is
an optional method for models to implement.  To be more specific, models may
ignore this call as it exists primarily for performance reasons. For more
information on what this means, see the <link
linkend="method-gtktreemodel--ref-node"><methodname>ref_node</methodname>()</link> 
method. Please note that nodes that are deleted are not unreffed.</para>

    </refsect2>

  <refsect2 id="method-gtktreemodel--get">
    <title>gtk.TreeModel.get</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get</methodname>
	  <methodparam><parameter>iter</parameter></methodparam>
	  <methodparam><parameter>column</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>iter</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
	  pointing at the row to retrieve data value
	  from</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>column</parameter>&nbsp;:</term>
	  <listitem><simpara>a column number</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>zero or more column numbers</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the column
	  values</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get</methodname>() method returns a tuple
containing the values of one or more cells in the row referenced by the
<link linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
specified by <parameter>iter</parameter>. column specifies the first column
number to retrieve a value from. The additional arguments should contain
integer column numbers for additional column values. For example, to get
values from columns 0 and 3, you would write:</para>

      <programlisting>
  value0, value3 = treemodel_get(iter, 0, 3)
 </programlisting>

      <para></para>

    </refsect2>

<!-- NOT IMPLEMENTED
  <refsect2 id="method-gtktreemodel- -get-valist">
    <title>gtk.TreeModel.get_valist</title>

<programlisting><methodsynopsis language="python">
    <methodname>get_valist</methodname>
    <methodparam><parameter role="keyword">iter</parameter></methodparam>
    <methodparam><parameter role="keyword">var_args</parameter></methodparam>
  </methodsynopsis></programlisting>
  <variablelist>
    <varlistentry>
      <term><parameter role="keyword">iter</parameter>&nbsp;:</term>
      <listitem><simpara>a row in <parameter>tree_model</parameter></simpara></listitem>
    </varlistentry>
    <varlistentry>
      <term><parameter role="keyword">var_args</parameter>&nbsp;:</term>
      <listitem><simpara><type>va_list</type> of column/return location pairs</simpara></listitem>
    </varlistentry>
  </variablelist>
<para>
See <link linkend="method-gtktreemodel- -get"><function>gtk.TreeModel.get()</function></link>, this version takes a <type>va_list</type> 
for language bindings to use.
</para>  </refsect2>
END NOT IMPLEMENTED -->

    <refsect2 id="method-gtktreemodel--foreach">
      <title>gtk.TreeModel.foreach</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>foreach</methodname>
	  <methodparam><parameter>func</parameter></methodparam>
	  <methodparam><parameter>user_data</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>func</parameter>&nbsp;:</term>
	  <listitem><simpara>a function to be called on each
row</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_data</parameter>&nbsp;:</term>
	  <listitem><simpara>the user data to passed to
<parameter>func</parameter>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>foreach</methodname>() method calls
<parameter>func</parameter> on each node in model in a depth-first fashion.
<parameter>user_data</parameter> is passed to <parameter>func</parameter>
each time it is called. If <parameter>func</parameter> returns
<literal>True</literal>, then the operation ceases, and
<methodname>foreach</methodname>() returns.</para>
      <para>The signature of <parameter>func</parameter> is:</para>
      <programlisting>
  def func(model, path, iter, user_data)
</programlisting>
      <para>where <parameter>model</parameter> is the treemodel,
<parameter>path</parameter> is the current path, and
<parameter>iter</parameter> is a treeiter pointing to
<parameter>path</parameter>.</para>
      <para>If <parameter>func</parameter> is an object method its signature
will be:</para>
      <programlisting>
  def func(self, model, path, iter, user_data)
</programlisting>
      <para></para>
    </refsect2>

    <refsect2 id="method-gtktreemodel--row-changed">
      <title>gtk.TreeModel.row_changed</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>row_changed</methodname>
	  <methodparam><parameter
			 role="keyword">path</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">iter</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">path</parameter>&nbsp;:</term>
	  <listitem><simpara>a path pointing to the changed
row</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">iter</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing to the changed row</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>row_changed</methodname>() method emits the
"row-changed" signal on the treemodel with the parameters
<parameter>path</parameter> and <parameter>iter</parameter> that are the
path and a treeiter pointing to the path of the changed row.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--row-inserted">
      <title>gtk.TreeModel.row_inserted</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>row_inserted</methodname>
	  <methodparam><parameter
			 role="keyword">path</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">iter</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">path</parameter>&nbsp;:</term>
	  <listitem><simpara>a path pointing to the inserted
row</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">iter</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing to the inserted row</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>row_inserted</methodname>() method emits the
"row-inserted" signal on the treemodel with the parameters
<parameter>path</parameter> and <parameter>iter</parameter> that are the
path and a treeiter pointing to the path of the inserted row.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--row-has-child-toggled">
      <title>gtk.TreeModel.row_has_child_toggled</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>row_has_child_toggled</methodname>
	  <methodparam><parameter
			 role="keyword">path</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">iter</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">path</parameter>&nbsp;:</term>
	  <listitem><simpara>a path pointing to the changed
row</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">iter</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing to the changed row</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>row_has_child_toggled</methodname>() method
emits the "row-has-child-toggled" signal on the treemodel with the
parameters <parameter>path</parameter> and <parameter>iter</parameter> that
are the path and a treeiter pointing to the path of the changed row. This
should be called by models after the child state of a node changes.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--row-deleted">
      <title>gtk.TreeModel.row_deleted</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>row_deleted</methodname>
	  <methodparam><parameter
			 role="keyword">path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">path</parameter>&nbsp;:</term>
	  <listitem><simpara>a path pointing to the previous location of the
deleted row.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>row_deleted</methodname>() method emits the
"row-deleted" signal on the treemodel. This should be called by models after
a row has been removed. The location pointed to by
<parameter>path</parameter> should be the location that the deleted row was
at. It may not be a valid location anymore.</para>

    </refsect2>

  <refsect2 id="method-gtktreemodel--rows-reordered">
      <title>gtk.TreeModel.rows_reordered</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>rows_reordered</methodname>
	  <methodparam><parameter
			 role="keyword">path</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">iter</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">new_order</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">path</parameter>&nbsp;:</term>
	  <listitem><simpara>A tree path pointing to the tree node whose
	  children have been reordered, or <literal>None</literal> or () or
	  "" to indicate the top level node.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">iter</parameter>&nbsp;:</term>
	  <listitem><simpara>A valid <link
	  linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
	  pointing to the node whose children have been reordered, or
	  <literal>None</literal> to indicate the top level
	  node.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">new_order</parameter>&nbsp;:</term>
	  <listitem><simpara>a sequence of integers containing the old
	  indexes of the children in the new order, i.e. the child nodes
	  have been rearranged so that the <parameter>treemodel</parameter>
	  node that was at position index
	  <parameter>new_order</parameter><literal>[i]</literal> is now at
	  position index <literal>i</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>rows_reordered</methodname>() method emits the
"rows_reordered" signal on the tree model. This method should be called by a
tree model when its rows have been reordered. If <parameter>iter</parameter>
is <literal>None</literal> to indicate that the top level rows have been
reordered, <parameter>path</parameter> should be <literal>None</literal> or
() or "".</para>

    </refsect2>

    <refsect2 id="method-gtktreemodel--filter-new">
      <title>gtk.TreeModel.filter_new</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>filter_new</methodname>
	  <methodparam><parameter role="keyword">root</parameter><initializer>None</initializer></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">root</parameter>&nbsp;:</term>
	  <listitem><simpara>a tree path or
	  <literal>None</literal>.</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>

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

      <para>The <methodname>filter_new</methodname>() method creates a new
<link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>,
with the tree model as the child_model and the virtual root specified by
<parameter>root</parameter>.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gtk--tree-row-reference-inserted">
      <title>gtk.tree_row_reference_inserted</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.tree_row_reference_inserted</methodname>
	  <methodparam><parameter
			 role="keyword">proxy</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">proxy</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gobject"><classname>GObject</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">path</parameter>&nbsp;:</term>
	  <listitem><simpara>a row position that was
inserted</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.tree_row_reference_inserted</function>()
function lets a set of row references know that the model emitted the
"row_inserted" signal for the row specified by
<parameter>path</parameter>.</para>

    </refsect2>

    <refsect2 id="function-gtk--tree-row-reference-deleted">
      <title>gtk.tree_row_reference_deleted</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.tree_row_reference_deleted</methodname>
	  <methodparam><parameter
			 role="keyword">proxy</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">proxy</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gobject"><classname>GObject</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">path</parameter>&nbsp;:</term>
	  <listitem><simpara>a row position that was
deleted</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.tree_row_reference_deleted</function>()
function lets a set of row references know that the model emitted the
"row_deleted" signal for the row specified by
<parameter>path</parameter>.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtktreemodel--row-changed">
      <title>The "row-changed" gtk.TreeModel Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>treemodel</parameter></methodparam>
	  <methodparam><parameter>path</parameter></methodparam>
	  <methodparam><parameter>iter</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>treemodel</parameter>&nbsp;:</term>
	  <listitem><simpara>the treemodel that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>path</parameter>&nbsp;:</term>
	  <listitem><simpara>a path</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>iter</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing at <parameter>path</parameter></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "row-changed" signal is emitted when the row specified by
<parameter>path</parameter> and pointed to by <parameter>iter</parameter>
has changed in the <parameter>treemodel</parameter>. Usually, this means
that one or more column values have changed.</para>

    </refsect2>

    <refsect2 id="signal-gtktreemodel--row-deleted">
      <title>The "row-deleted" gtk.TreeModel Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>treemodel</parameter></methodparam>
	  <methodparam><parameter>path</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>treemodel</parameter>&nbsp;:</term>
	  <listitem><simpara>the treemodel that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>path</parameter>&nbsp;:</term>
	  <listitem><simpara>a path</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "row-deleted" signal is emitted when the row that was
specified by <parameter>path</parameter> is deleted from
<parameter>treemodel</parameter>.</para>

    </refsect2>

    <refsect2 id="signal-gtktreemodel--row-has-child-toggled">
      <title>The "row-has-child-toggled" gtk.TreeModel Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>treemodel</parameter></methodparam>
	  <methodparam><parameter>path</parameter></methodparam>
	  <methodparam><parameter>iter</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>treemodel</parameter>&nbsp;:</term>
	  <listitem><simpara>the treemodel that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>path</parameter>&nbsp;:</term>
	  <listitem><simpara>a path</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>iter</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing at <parameter>path</parameter></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "row-has-child-toggled" signal is emitted when the child
state of the row specified by <parameter>path</parameter> and pointed to by
<parameter>iter</parameter> has changed in
<parameter>treemodel</parameter>.</para>

    </refsect2>

    <refsect2 id="signal-gtktreemodel--row-inserted">
      <title>The "row-inserted" gtk.TreeModel Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>treemodel</parameter></methodparam>
	  <methodparam><parameter>path</parameter></methodparam>
	  <methodparam><parameter>iter</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>treemodel</parameter>&nbsp;:</term>
	  <listitem><simpara>the treemodel that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>path</parameter>&nbsp;:</term>
	  <listitem><simpara>a path</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>iter</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing at <parameter>path</parameter></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "row-inserted" signal is emitted when the row specified by
<parameter>path</parameter> and pointed to by <parameter>iter</parameter> is
inserted into <parameter>treemodel</parameter>. The row referenced by
<parameter>iter</parameter> will be empty so using the <link
linkend="method-gtktreemodel--get-value"><methodname>get_value</methodname>()</link>
method will always return <literal>None</literal>. Connect to the
"row-changed" signal if you want to track value changes.</para>

    </refsect2>

    <refsect2 id="signal-gtktreemodel--rows-reordered">
      <title>The "rows-reordered" gtk.TreeModel Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>treemodel</parameter></methodparam>
	  <methodparam><parameter>path</parameter></methodparam>
	  <methodparam><parameter>iter</parameter></methodparam>
	  <methodparam><parameter>new_order</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>treemodel</parameter>&nbsp;:</term>
	  <listitem><simpara>the treemodel that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>path</parameter>&nbsp;:</term>
	  <listitem><simpara>a path</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>iter</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing at <parameter>path</parameter></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>new_order</parameter>&nbsp;:</term>
	  <listitem><simpara>an array of reordered row
numbers</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "rows-reordered" signal is emitted when the
      <parameter>treemodel</parameter> child rows of the row specified by
      <parameter>path</parameter> and pointed to by
      <parameter>iter</parameter> are reordered. The child nodes have been
      rearranged so that the <parameter>treemodel</parameter> node that was
      at position index
      <parameter>new_order</parameter><literal>[i]</literal> is now at
      position index <literal>i</literal>. The value of
      <parameter>new_order</parameter> cannot be directly retrieved in PyGTK
      because it is passed as an opaque pointer (<link
      linkend="class-gobjectgpointer"><classname>gobject.GPointer</classname></link>)
      value. <parameter>iter</parameter> may be <literal>None</literal> and
      <parameter>path</parameter> an empty tuple to indicate that the top
      level rows were reordered.</para>

    </refsect2>

  </refsect1>

</refentry>