path: root/docs/reference/pygtk-pygtkgenerictreemodel.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-pygtkgenerictreemodel">
  <refnamediv>
    <refname>gtk.GenericTreeModel</refname>
    <refpurpose>a TreeView model that helps create tree models in
Python</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.GenericTreeModel</classname></ooclass>
      <ooclass><classname><link
linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <ooclass><classname><link
linkend="class-gtktreemodel">gtk.TreeModel</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkgenerictreemodel">gtk.GenericTreeModel</link></methodname>
	<methodparam></methodparam>  </constructorsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkgenerictreemodel--invalidate-iters">invalidate_iters</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkgenerictreemodel--iter-is-valid">iter_is_valid</link></methodname>
        <methodparam><parameter role="keyword">iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkgenerictreemodel--get-user-data">get_user_data</link></methodname>
        <methodparam><parameter role="keyword">iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkgenerictreemodel--create-tree-iter">create_tree_iter</link></methodname>
        <methodparam><parameter role="keyword">user_data</parameter></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-pygtkgenerictreemodel">gtk.GenericTreeModel</link> (implements <link linkend="class-gtktreemodel">gtk.TreeModel</link>)
</synopsis>

  </refsect1>

  <refsect1>
    <title>Properties</title>

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

	    <row valign="top">
	      <entry>"leak-references"</entry>
              <entry>Read-Write</entry>

	      <entry>If <literal>True</literal>, creating a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> will
bump the reference count of the object used as the internal row
reference. This may cause a memory leak but will prevent problems with
objects being destroyed while still in use in a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>. Set
this to <literal>False</literal> only if the model saves the objects used in
tree iters.</entry>
	    </row>

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

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The <link
linkend="class-pygtkgenerictreemodel"><classname>gtk.GenericTreeModel</classname></link> 
helps in the creation of <link
linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link> tree
models in Python. The <link
linkend="class-pygtkgenerictreemodel"><classname>gtk.GenericTreeModel</classname></link> 
is subclassed to provide a new tree model that provides the tree model
behavior using methods with predefined names that are called by the <link
linkend="class-pygtkgenerictreemodel"><classname>gtk.GenericTreeModel</classname></link> 
methods as required to provide the various tree model operations. The
methods that need to be defined by the programmer in Python are:</para>

    <methodsynopsis language="python">
      <methodname>on_get_flags</methodname>
      <methodparam><parameter>self</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
      <methodname>on_get_n_columns</methodname>
      <methodparam><parameter>self</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
      <methodname>on_get_column_type</methodname>
      <methodparam><parameter>self</parameter></methodparam>
      <methodparam><parameter>index</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
      <methodname>on_get_iter</methodname>
      <methodparam><parameter>self</parameter></methodparam>
      <methodparam><parameter>path</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
      <methodname>on_get_path</methodname>
      <methodparam><parameter>self</parameter></methodparam>
      <methodparam><parameter>rowref</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
      <methodname>on_get_value</methodname>
      <methodparam><parameter>self</parameter></methodparam>
      <methodparam><parameter>rowref</parameter></methodparam>
      <methodparam><parameter>column</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
      <methodname>on_iter_next</methodname>
      <methodparam><parameter>self</parameter></methodparam>
      <methodparam><parameter>rowref</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
      <methodname>on_iter_children</methodname>
      <methodparam><parameter>self</parameter></methodparam>
      <methodparam><parameter>parent</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
      <methodname>on_iter_has_child</methodname>
      <methodparam><parameter>self</parameter></methodparam>
      <methodparam><parameter>rowref</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
      <methodname>on_iter_n_children</methodname>
      <methodparam><parameter>self</parameter></methodparam>
      <methodparam><parameter>rowref</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
      <methodname>on_iter_nth_child</methodname>
      <methodparam><parameter>self</parameter></methodparam>
      <methodparam><parameter>parent</parameter></methodparam>
      <methodparam><parameter>n</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
      <methodname>on_iter_parent</methodname>
      <methodparam><parameter>self</parameter></methodparam>
      <methodparam><parameter>child</parameter></methodparam>
    </methodsynopsis>

    <para>See the <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
description for details of the above methods.</para>

    <para>In PyGTK 2.4 and above the <link
linkend="method-gtkgenerictreemodel--invalidate-iters"><methodname>invalidate_iters</methodname>()</link>
and <link
linkend="method-gtkgenerictreemodel--iter-is-valid"><methodname>iter_is_valid</methodname>()</link>
methods are available to help manage the <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
objects and their Python object references. These are particularly useful
when the "leak-references" property is set to
<literal>False</literal>.</para>

    <para>The tree models derived from <link
linkend="class-pygtkgenerictreemodel"><classname>gtk.GenericTreeModel</classname></link>
are protected from problems with out of date <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
objects because <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
objects are automatically checked for validity with the tree model.</para>

    <para>If a custom tree model doesn't support persistent iters
(i.e. <literal>gtk.TREE_MODEL_ITERS_PERSIST</literal> is not set in the
return from the <link
linkend="method-gtktreemodel--get-flags"><methodname>gtk.TreeModel.get_flags</methodname>()</link>
method), it can call the <link
linkend="method-gtkgenerictreemodel--invalidate-iters"><methodname>invalidate_iters</methodname>()</link>
method to invalidate all its outstanding <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
objects when it changes the model (e.g. after inserting a new row). The tree
model can also dispose of any Python objects that it passed references to
<link linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
objects after calling the <link
linkend="method-gtkgenerictreemodel--invalidate-iters"><methodname>invalidate_iters</methodname>()</link>
method.</para>

    <para>Applications can use the <link
linkend="method-gtkgenerictreemodel--iter-is-valid"><methodname>iter_is_valid</methodname>()</link>
method to determine if a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link> is
still valid for the custom tree model.</para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.GenericTreeModel</methodname>
	<methodparam></methodparam>  </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
linkend="class-pygtkgenerictreemodel"><classname>gtk.GenericTreeModel</classname></link> 
object</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-pygtkgenerictreemodel"><classname>gtk.GenericTreeModel</classname></link> 
object</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkgenerictreemodel--invalidate-iters">
      <title>gtk.GenericTreeModel.invalidate_iters</title>

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

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

      <para>The <methodname>invalidate_iters</methodname>() method
invalidates all the <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
objects for the custom tree model.</para>

    </refsect2>

    <refsect2 id="method-gtkgenerictreemodel--iter-is-valid">
      <title>gtk.GenericTreeModel.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 model;
	  otherwise, <literal>False</literal> is
	  returned.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>iter_is_valid</methodname>() method returns
<literal>True</literal> if the <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
specified by <parameter>iter</parameter> is valid for the custom tree
model.</para>

    </refsect2>

    <refsect2 id="method-gtkgenerictreemodel--get-user-data">
      <title>gtk.GenericTreeModel.get_user_data</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_user_data</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>
	  created by this tree model.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>Python object reference that is wrapped by this
	      <classname>gtk.TreeIter</classname>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <warning>
        <para>This method should be treated as protected.  It should only
        be used by derived classes.</para>
      </warning>

      <para><classname>gtk.GenericTreeModel</classname> transparently wraps arbitrary Python objects to instances of <link linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>. E.g. you return anything from <methodname>on_get_iter</methodname> and the model wraps the value, so <methodname>get_iter</methodname> method returns a <classname>gtk.TreeIter</classname>. This method allows to retrieve the Python object used to construct given iterator.</para>

    </refsect2>

    <refsect2 id="method-gtkgenerictreemodel--create-tree-iter">
      <title>gtk.GenericTreeModel.create_tree_iter</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>create_tree_iter</methodname>
	  <methodparam><parameter
			 role="keyword">user_data</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">user_data</parameter>&nbsp;:</term>
	  <listitem><simpara>a Python object, the same you would return from
	      e.g. <methodname>on_get_iter</methodname>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <warning>
        <para>This method should be treated as protected.  It should only
        be used by derived classes.</para>
      </warning>

      <para><classname>gtk.GenericTreeModel</classname> transparently wraps arbitrary Python objects to instances of <link linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>. E.g. you return anything from <methodname>on_get_iter</methodname> and the model wraps the value, so <methodname>get_iter</methodname> method returns a <classname>gtk.TreeIter</classname>. This method allows you to perform this wrapping explicitly, not just from a predefined set of methods.</para>

    </refsect2>

  </refsect1>

</refentry>