path: root/docs/reference/pygtk-gtktreestore.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-gtktreestore">
  <refnamediv>
    <refname>gtk.TreeStore</refname>
    <refpurpose>a model for tree widgets with columns</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.TreeStore</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-gtktreedragsource">gtk.TreeDragSource</link></classname></ooclass>
      <ooclass><classname><link
linkend="class-gtktreedragdest">gtk.TreeDragDest</link></classname></ooclass>
      <ooclass><classname><link
linkend="class-gtktreesortable">gtk.TreeSortable</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtktreestore">gtk.TreeStore</link></methodname>
	<methodparam><parameter>...</parameter></methodparam>
      </constructorsynopsis>

<!-- NOT IMPLEMENTED
<methodsynopsis language="python">
    <methodname><link linkend="method-gtktreestore- -set-column-types">set_column_types</link></methodname>
    <methodparam><parameter role="keyword">n_columns</parameter></methodparam>
    <methodparam><parameter role="keyword">types</parameter></methodparam>
  </methodsynopsis>
END NOT IMPLEMENTED -->

      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreestore--set-value">set_value</link></methodname>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">column</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">value</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreestore--set">set</link></methodname>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
	<methodparam><parameter role="keyword">...</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreestore--remove">remove</link></methodname>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreestore--insert">insert</link></methodname>
	<methodparam><parameter
		       role="keyword">parent</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">position</parameter></methodparam>
	<methodparam><parameter role="keyword">row</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreestore--insert-before">insert_before</link></methodname>
	<methodparam><parameter
		       role="keyword">parent</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">sibling</parameter></methodparam>
	<methodparam><parameter role="keyword">row</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreestore--insert-after">insert_after</link></methodname>
	<methodparam><parameter
		       role="keyword">parent</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">sibling</parameter></methodparam>
	<methodparam><parameter role="keyword">row</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreestore--prepend">prepend</link></methodname>
	<methodparam><parameter
		       role="keyword">parent</parameter></methodparam>
	<methodparam><parameter role="keyword">row</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreestore--append">append</link></methodname>
	<methodparam><parameter
		       role="keyword">parent</parameter></methodparam>
	<methodparam><parameter role="keyword">row</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreestore--is-ancestor">is_ancestor</link></methodname>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">descendant</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreestore--iter-depth">iter_depth</link></methodname>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktreestore--clear">clear</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreestore--iter-is-valid">iter_is_valid</link></methodname>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreestore--reorder">reorder</link></methodname>
	<methodparam><parameter
		       role="keyword">parent</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">new_order</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreestore--swap">swap</link></methodname>
	<methodparam><parameter
		       role="keyword">a</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">b</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreestore--move-after">move_after</link></methodname>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">position</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreestore--move-before">move_before</link></methodname>
	<methodparam><parameter
		       role="keyword">iter</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">position</parameter></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtktreestore">gtk.TreeStore</link> (implements <link linkend="class-gtktreemodel">gtk.TreeModel</link>, <link linkend="class-gtktreedragsource">gtk.TreeDragSource</link>, <link linkend="class-gtktreedragdest">gtk.TreeDragDest</link>, <link linkend="class-gtktreesortable">gtk.TreeSortable</link>)
</synopsis>

  </refsect1>

  <refsect1 id="signal-prototypes-gtktreestore">
    <title>gtk.TreeStore 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-gtktreestore"><classname>gtk.TreeStore</classname></link> is
a model for multi-columned tree widgets. A <link
linkend="class-gtktreestore"><classname>gtk.TreeStore</classname></link> is
a subclass of <link linkend="class-gobject">gobject.GObject</link> and
implements the <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>,
<link
linkend="class-gtktreedragsource"><classname>gtk.TreeDragSource</classname></link>,
<link
linkend="class-gtktreedragdest"><classname>gtk.TreeDragDest</classname></link>
and <link
linkend="class-gtktreesortable"><classname>gtk.TreeSortable</classname></link>
interfaces.</para>

    <para>The <link
linkend="class-gtktreestore"><classname>gtk.TreeStore</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-gtktreestore">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.TreeStore</methodname>
	<methodparam><parameter>...</parameter></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter>...</parameter>&nbsp;:</term>
	<listitem><simpara>one or more column types</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
linkend="class-gtktreestore"><classname>gtk.TreeStore</classname></link></simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new tree store as with one or more columns each of the
types passed in.  As an example:</para>

    <programlisting>
  gtk.TreeStore(gobject.TYPE_INT, gobject.TYPE_STRING, gtk.gdk.Pixbuf)
</programlisting>

    <para>will create a new <link
linkend="class-gtktreestore"><classname>gtk.TreeStore</classname></link>
with three columns, of type <type>int</type>, <type>string</type> and <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>
respectively.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

<!-- NOT IMPLEMENTED
    <refsect2 id="method-gtktreestore- -set-column-types">
    <title>gtk.TreeStore.set_column_types</title>

<programlisting><methodsynopsis language="python">
    <methodname>set_column_types</methodname>
    <methodparam><parameter role="keyword">n_columns</parameter></methodparam>
    <methodparam><parameter role="keyword">types</parameter></methodparam>
  </methodsynopsis></programlisting>
  <variablelist>
    <varlistentry>
      <term><parameter role="keyword">n_columns</parameter>&nbsp;:</term>
      <listitem><simpara>Number of columns for the tree store</simpara></listitem>
    </varlistentry>
    <varlistentry>
      <term><parameter role="keyword">types</parameter>&nbsp;:</term>
      <listitem><simpara>An array of <literal>GType</literal> types, one for each column</simpara></listitem>
    </varlistentry>
  </variablelist>
<para>
This function is meant primarily for <literal>GObjects</literal> that inherit from 
<link linkend="class-gtktreestore"><classname>gtk.TreeStore</classname></link>, and should only be used when constructing a new 
<link linkend="class-gtktreestore"><classname>gtk.TreeStore</classname></link>.  It will not function after a row has been added, 
or a method on the <link linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link> interface is called.
</para>  </refsect2>
END NOT IMPLEMENTED -->

    <refsect2 id="method-gtktreestore--set-value">
      <title>gtk.TreeStore.set_value</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_value</methodname>
	  <methodparam><parameter
			 role="keyword">iter</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">column</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">value</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> for
the row being modified</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">column</parameter>&nbsp;:</term>
	  <listitem><simpara>the column number to
modify</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">value</parameter>&nbsp;:</term>
	  <listitem><simpara>a new value for the cell</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_value</methodname>() method sets the data in
the cell specified by <parameter>iter</parameter> and
<parameter>column</parameter> to the value specified by
<parameter>value</parameter>. The type of <parameter>value</parameter> must
be convertible to the type of the column.</para>

    </refsect2>

  <refsect2 id="method-gtktreestore--set">
      <title>gtk.TreeStore.set</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set</methodname>
	  <methodparam><parameter>iter</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> for
the row being modified</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>one or more column ID-value
pairs</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set</methodname>() method sets the value of one
or more cells in the row referenced by <parameter>iter</parameter>. The
argument list following <parameter>iter</parameter> should contain pairs of
integer column numbers followed by the value to be set. For example, to set
column 0 with type <literal>gobject.TYPE_STRING</literal> to "Foo", you
would write:</para>

      <programlisting>
  store.set(iter, 0, "Foo")
</programlisting>

      <para></para>

    </refsect2>

    <refsect2 id="method-gtktreestore--remove">
      <title>gtk.TreeStore.remove</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>remove</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><literal>None</literal> in PyGTK 2.0. Returns
	  <literal>True</literal> in PyGTK 2.2 and above if
	  <parameter>iter</parameter> is still valid.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>remove</methodname>() method removes the row
pointed to by <parameter>iter</parameter> from the treestore.  After being
removed, <parameter>iter</parameter> is set to the next valid row at that
level, or invalidated if it previously pointed to the last one.</para>

    </refsect2>

    <refsect2 id="method-gtktreestore--insert">
      <title>gtk.TreeStore.insert</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>insert</methodname>
	  <methodparam><parameter
			 role="keyword">parent</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">position</parameter></methodparam>
	  <methodparam><parameter role="keyword">row</parameter>
	    <initializer>None</initializer></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>, or
<literal>None</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">position</parameter>&nbsp;:</term>
	  <listitem><simpara>the position to insert the new
row</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">row</parameter>&nbsp;:</term>
	  <listitem><simpara>an optional list or tuple containing column
values (in order) to set on the row or
<literal>None</literal></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 new row</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>insert</methodname>() method inserts a new row
at <parameter>position</parameter>. If <parameter>parent</parameter> is not
<literal>None</literal>, then the row will be made a child of
<parameter>parent</parameter>. Otherwise, the row will be created at the
toplevel. If <parameter>position</parameter> is larger than the number of
rows at that level, then the new row will be inserted to the end of the
list. This method returns a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing at the new row. If <parameter>row</parameter> is not
<literal>None</literal> it must be a tuple or list containing ordered column
values that are used to set values in the columns of the row.</para>

    </refsect2>

    <refsect2 id="method-gtktreestore--insert-before">
      <title>gtk.TreeStore.insert_before</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>insert_before</methodname>
	  <methodparam><parameter
			 role="keyword">parent</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">sibling</parameter></methodparam>
	  <methodparam><parameter role="keyword">row</parameter>
	    <initializer>None</initializer></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>, or
<literal>None</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">sibling</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>, or
<literal>None</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">row</parameter>&nbsp;:</term>
	  <listitem><simpara>an optional list or tuple containing ordered
column values to set on the row or
<literal>None</literal></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 new row</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>insert_before</methodname>() method inserts a
new row before the row pointed to by <parameter>sibling</parameter>.  If
<parameter>sibling</parameter> is <literal>None</literal>, then the row will
be appended to  the children of the row pointed to by
<parameter>parent</parameter>.  If <parameter>parent</parameter> and
<parameter>sibling</parameter> are <literal>None</literal>, the row will be
appended to the toplevel. If both <parameter>sibling</parameter> and
<parameter>parent</parameter> are set, then <parameter>parent</parameter>
must be the parent of <parameter>sibling</parameter>.  When
<parameter>sibling</parameter> is set, <parameter>parent</parameter> is
optional. This method returns a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing at the new row. If <parameter>row</parameter> is not
<literal>None</literal> it must be a tuple or list containing ordered column
values that are used to set values in the columns of the row.</para>

    </refsect2>

    <refsect2 id="method-gtktreestore--insert-after">
      <title>gtk.TreeStore.insert_after</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>insert_after</methodname>
	  <methodparam><parameter
			 role="keyword">parent</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">sibling</parameter></methodparam>
	  <methodparam><parameter role="keyword">row</parameter>
	    <initializer>None</initializer></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>, or
<literal>None</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">sibling</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>, or
<literal>None</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">row</parameter>&nbsp;:</term>
	  <listitem><simpara>a tuple or list containing ordered column
values to be set in the new row</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 new row</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>insert_after</methodname>() method inserts a new
row after the row pointed to by <parameter>sibling</parameter>.  If
<parameter>sibling</parameter> is <literal>None</literal>, then the row will
be prepended to the beginning of the  children of
<parameter>parent</parameter>. If <parameter>parent</parameter> and
<parameter>sibling</parameter> are <literal>None</literal>, then the row
will be prepended to the toplevel.  If both <parameter>sibling</parameter>
and <parameter>parent</parameter> are set, <parameter>parent</parameter>
must be the parent of <parameter>sibling</parameter>. When
<parameter>sibling</parameter> is set, <parameter>parent</parameter> is
optional. This method returns a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing at the new row. If <parameter>row</parameter> is not
<literal>None</literal> it must be a tuple or list containing ordered column
values that are used to set values in the columns of the row.</para>

    </refsect2>

    <refsect2 id="method-gtktreestore--prepend">
      <title>gtk.TreeStore.prepend</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>prepend</methodname>
	  <methodparam><parameter
			 role="keyword">parent</parameter></methodparam>
	  <methodparam><parameter role="keyword">row</parameter>
	    <initializer>None</initializer></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>, or
<literal>None</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">row</parameter>&nbsp;:</term>
	  <listitem><simpara>a tuple or list containing ordered column
values to be set in the new row</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 new row</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>prepend</methodname>() method prepends a new row
to the treestore.  If <parameter>parent</parameter> is not
<literal>None</literal>, the new row will be prepended before the first
child of <parameter>parent</parameter>, otherwise it will prepend a row to
the top level. This method returns a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing at the new row. If <parameter>row</parameter> is not
<literal>None</literal> it must be a tuple or list containing ordered column
values that are used to set values in the columns of the row.</para>

    </refsect2>

    <refsect2 id="method-gtktreestore--append">
      <title>gtk.TreeStore.append</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>append</methodname>
	  <methodparam><parameter
			 role="keyword">parent</parameter></methodparam>
	  <methodparam><parameter role="keyword">row</parameter>
	    <initializer>None</initializer></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>, or
<literal>None</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">row</parameter>&nbsp;:</term>
	  <listitem><simpara>a tuple or list containing ordered column
values to be set in the new row</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 new row</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>append</methodname>() method appends a new row
to the treestore.  If <parameter>parent</parameter> is not
<literal>None</literal>, the new row will be prepended after the last child
of <parameter>parent</parameter>, otherwise it will append a row to the top
level. This method returns a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing at the new row. If <parameter>row</parameter> is not
<literal>None</literal> it must be a tuple or list containing ordered column
values that are used to set values in the columns of the row.</para>

    </refsect2>

    <refsect2 id="method-gtktreestore--is-ancestor">
      <title>gtk.TreeStore.is_ancestor</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>is_ancestor</methodname>
	  <methodparam><parameter
			 role="keyword">iter</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">descendant</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">descendant</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 an ancestor of
<parameter>descendant</parameter></simpara></listitem>
	</varlistentry>
      </variablelist>
      <para>The <methodname>is_ancestor</methodname>() method returns
<literal>True</literal> if the row pointed to by <parameter>iter</parameter>
is an ancestor of the row pointed to by <parameter>descendant</parameter>.
That is, <parameter>iter</parameter> is the parent (or grandparent or
great-grandparent) of <parameter>descendant</parameter>.</para>

    </refsect2>

  <refsect2 id="method-gtktreestore--iter-depth">
      <title>gtk.TreeStore.iter_depth</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>iter_depth</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 depth of
<parameter>iter</parameter></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>iter_depth</methodname>() method returns the
depth of the row pointed to by <parameter>iter</parameter>.  This will be 0
for anything on the root level, 1 for anything down a level, etc.</para>

    </refsect2>

    <refsect2 id="method-gtktreestore--clear">
      <title>gtk.TreeStore.clear</title>

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

      <para>The <methodname>clear</methodname>() method removes all rows
from the treestore.</para>

    </refsect2>

    <refsect2 id="method-gtktreestore--iter-is-valid">
      <title>gtk.TreeStore.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 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><literal>True</literal> if
	  <parameter>iter</parameter> is valid for the tree
	  store,</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 returns
<literal>True</literal> if <parameter>iter</parameter> is a valid <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> for
the tree store.</para>

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

    </refsect2>

    <refsect2 id="method-gtktreestore--reorder">
      <title>gtk.TreeStore.reorder</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>reorder</methodname>
	  <methodparam><parameter role="keyword">parent</parameter></methodparam>
	  <methodparam><parameter role="keyword">new_order</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>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
	  role="keyword">new_order</parameter>&nbsp;:</term>
	  <listitem><simpara>a list of integers mapping the new position of
	  each child to its old position before the re-ordering,
	  i.e. <parameter>new_order</parameter><literal>[newpos] =
	  oldpos</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>reorder</methodname>() method reorders the
children of the tree store node pointed to by <parameter>parent</parameter>
to match the order of the list of row numbers contained in
<parameter>new_order</parameter>. Note that this method only works with
unsorted stores.</para>

    </refsect2>

    <refsect2 id="method-gtktreestore--swap">
      <title>gtk.TreeStore.swap</title>

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

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

      <para>The <methodname>swap</methodname>() method swaps the tree store
nodes pointed to by <parameter>a</parameter> and <parameter>b</parameter> in
the same level of the tree store. Note that this method only works with
unsorted stores.</para>

    </refsect2>

    <refsect2 id="method-gtktreestore--move-after">
      <title>gtk.TreeStore.move_after</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>move_after</methodname>
	  <methodparam><parameter role="keyword">iter</parameter></methodparam>
	  <methodparam><parameter role="keyword">position</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">position</parameter>&nbsp;:</term>
	  <listitem><simpara>a second <link
	  linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
	  or <literal>None</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>move_after</methodname>() method moves the tree
store node specified by <parameter>iter</parameter> to the position after
the node specified by
<parameter>position</parameter>. <parameter>iter</parameter> and
<parameter>position</parameter> should be in the same level. Note that this
method only works with unsorted stores. If <parameter>position</parameter>
is <literal>None</literal>, <parameter>iter</parameter> will be moved to the
start of the level.</para>

    </refsect2>

    <refsect2 id="method-gtktreestore--move-before">
      <title>gtk.TreeStore.move_before</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>move_before</methodname>
	  <methodparam><parameter role="keyword">iter</parameter></methodparam>
	  <methodparam><parameter role="keyword">position</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">position</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
	  or <literal>None</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The move_before() method moves the tree store node pointed to by
<parameter>iter</parameter> to the position before the node specified by
<parameter>position</parameter>. <parameter>iter</parameter> and
<parameter>position</parameter> should be in the same level. Note that this
method only works with unsorted stores. If <parameter>position</parameter>
is <literal>None</literal>, <parameter>iter</parameter> will be moved to the
end of the level.</para>

    </refsect2>

  </refsect1>

</refentry>