path: root/docs/reference/pygtk-gtktreemodelfilter.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-gtktreemodelfilter">
  <refnamediv>
    <refname>gtk.TreeModelFilter</refname>

    <refpurpose>a <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
which hides parts of an underlying tree (new in PyGTK 2.4)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.TreeModelFilter</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>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreemodelfilter--set-visible-func">set_visible_func</link></methodname>
	<methodparam><parameter role="keyword">func</parameter></methodparam>
	<methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreemodelfilter--set-modify-func">set_modify_func</link></methodname>
	<methodparam><parameter role="keyword">types</parameter></methodparam>
	<methodparam><parameter role="keyword">func</parameter></methodparam>
	<methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreemodelfilter--set-visible-column">set_visible_column</link></methodname>
	<methodparam><parameter role="keyword">column</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreemodelfilter--get-model">get_model</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreemodelfilter--convert-child-iter-to-iter">convert_child_iter_to_iter</link></methodname>
	<methodparam><parameter role="keyword">child_iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreemodelfilter--convert-iter-to-child-iter">convert_iter_to_child_iter</link></methodname>
	<methodparam><parameter role="keyword">filter_iter</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreemodelfilter--convert-child-path-to-path">convert_child_path_to_path</link></methodname>
	<methodparam><parameter role="keyword">child_path</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreemodelfilter--convert-path-to-child-path">convert_path_to_child_path</link></methodname>
	<methodparam><parameter role="keyword">filter_path</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreemodelfilter--refilter">refilter</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreemodelfilter--clear-cache">clear_cache</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtktreemodelfilter">gtk.TreeModelFilter</link> (implements <link linkend="class-gtktreemodel">gtk.TreeModel</link>, <link linkend="class-gtktreedragsource">gtk.TreeDragSource</link>)
</synopsis>

  </refsect1>

  <refsect1 id="properties-gtktreemodelfilter">
    <title>gtk.TreeModelFilter 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>"child-model"</entry>
	      <entry>Read-Write-Construct Only</entry>

	      <entry>The <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link> for
the filtermodel to filter. Available in GTK+ 2.4 and above.</entry>
	    </row>

	    <row valign="top">
	      <entry>"virtual-root"</entry>
	      <entry>Read-Write-Construct Only</entry>

	      <entry>The virtual root (relative to the child model) for this
filtermodel. Available in GTK+ 2.4 and above.</entry>
	    </row>

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

  </refsect1>

  <refsect1 id="signal-prototypes-gtktreemodelfilter">
    <title>gtk.TreeModelFilter Signal Prototypes</title>

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

  <refsect1>
    <title>Description</title>

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

    <para>A <link
linkend="class-gtktreemodelfilter"><classname>gtk.TreeModelFilter</classname></link>
is a tree model which wraps another tree model, and can do the following
things:</para>

    <itemizedlist>
      <listitem>
	<simpara>Filter specific rows, based on data from a "visible
column", a column storing booleans indicating whether the row should be
filtered or not, or based on the return value of a "visible function", which
gets a <parameter>model</parameter>, <parameter>iter</parameter> and
<parameter>user_data</parameter> and returns a boolean indicating whether
the row should be filtered or not.</simpara>
      </listitem>
      <listitem>
	<simpara>Modify the "appearance" of the model, using a modify
function. This is extremely powerful and allows for just changing some
values and also for creating a completely different synthetic model based on
the child model. For example, you can create a model with columns
synthesized from the data in the child model.</simpara>
      </listitem>
      <listitem>
	<simpara>Set a different root node, also known as a "virtual
root". You can pass in a tree path indicating the root node for the filter
at construction time.</simpara>
      </listitem>
    </itemizedlist>

    <para>A <link linkend="class-gtktreemodelfilter"><classname>gtk.TreeModelFilter</classname></link> is 
created using the <link linkend="method-gtktreemodel--filter-new"><methodname>gtk.TreeModel.filter_new</methodname>()</link> method. For example:</para>

    <programlisting>
  liststore = gtk.ListStore(gobject.TYPE_INT, gobject.TYPE_STRING)
  modelfilter = liststore.filter_new()
</programlisting>

    <para>The <link
linkend="class-gtktreemodelfilter"><classname>gtk.TreeModelFilter</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>
    <title>Methods</title>

    <refsect2 id="method-gtktreemodelfilter--set-visible-func">
      <title>gtk.TreeModelFilter.set_visible_func</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_visible_func</methodname>
	  <methodparam><parameter role="keyword">func</parameter></methodparam>
	  <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">func</parameter>&nbsp;:</term>
	  <listitem><simpara>a function called to determine the visibility
	  of a row</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">data</parameter>&nbsp;:</term>
	  <listitem><simpara>User data to pass to
	  <literal>func</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_visible_func</methodname>() method sets the
visible function used when filtering the rows of the treemodel filter to the
value of <parameter>func</parameter>. <parameter>data</parameter> is the
user data that is passed to func (see below). This method will fail if the
<link
linkend="method-gtktreemodelfilter--set-visible-column"><methodname>set_visible_column</methodname>()</link>
method has already been called. The visible function signature is:</para>

      <programlisting>
  def visible_func(model, iter, user_data):
</programlisting>

      <para>where <parameter>model</parameter> is the child <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>,
<parameter>iter</parameter> is a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing at a row in model and <parameter>user_data</parameter> is the data
parameter. The function should return <literal>True</literal> if the row
should be visible.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodelfilter--set-modify-func">
      <title>gtk.TreeModelFilter.set_modify_func</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_modify_func</methodname>
	  <methodparam><parameter role="keyword">types</parameter></methodparam>
	  <methodparam><parameter role="keyword">func</parameter></methodparam>
	  <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">types</parameter>&nbsp;:</term>
	  <listitem><simpara>a sequence containing the column
	  types</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">func</parameter>&nbsp;:</term>
	  <listitem><simpara>a function that is called to provide the data
	  for a specific row and column</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">data</parameter>&nbsp;:</term>
	  <listitem><simpara>user data to pass to the modify function, or
	  <literal>None</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_modify_func</methodname>() method uses the
list of column types specified by <parameter>types</parameter> and the
function specified by <parameter>func</parameter> to provide a synthetic
model based on the child model of the <link
linkend="class-gtktreemodelfilter"><classname>gtk.TreeModelFilter</classname></link>. <parameter>data</parameter>
is passed to <parameter>func</parameter> when it is
called. <parameter>func</parameter> is called for each data access to return
the data which should be displayed at the location specified using the
parameters of the modify function.</para>

      <para>The signature of func is:</para>

      <programlisting>
  def func(<parameter>model</parameter>, <parameter>iter</parameter>, <parameter>column</parameter>, <parameter>user_data</parameter>)
</programlisting>

      <para>where <parameter>model</parameter> is the <link
linkend="class-gtktreemodelfilter"><classname>gtk.TreeModelFilter</classname></link>,
<parameter>iter</parameter> is a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing at a row in <parameter>model</parameter>,
<parameter>column</parameter> is the column number to provide the value for
and <parameter>user_data</parameter> is
<parameter>data</parameter>. <parameter>func</parameter> should returns the
generated value for the specified location in
<parameter>model</parameter>.</para>

      <note>
        <para>This method must be called before the <link
linkend="class-gtktreemodelfilter"><classname>gtk.TreeModelFilter</classname></link>
is associated with a <link
linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link> and
before either of the <link
linkend="method-gtktreemodel--get-n-columns"><methodname>gtk.TreeModel.get_n_columns</methodname>()</link>
or <link
linkend="method-gtktreemodel--get-column-type"><methodname>gtk.TreeModel.get_column_type</methodname>()</link>
methods are called. Also this method can only be called once - there is no
way to change the modify function once it is set.</para>
      </note>

      <para>Since <parameter>func</parameter> is called for every access to
a value in <parameter>model</parameter>, it will be slow for models with a
large number of rows and/or columns.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodelfilter--set-visible-column">
      <title>gtk.TreeModelFilter.set_visible_column</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_visible_column</methodname>
	  <methodparam><parameter role="keyword">column</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">column</parameter>&nbsp;:</term>
	  <listitem><simpara>the number of the column containing the visible
	  information.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_visible_column</methodname>() method sets
the visible column setting to the value of
<parameter>column</parameter>. The visible column setting contains the
number of the "child-model" column that is used to determine the visibility
of the model rows. The specified column should be a column of type
<literal>gobject.TYPE_BOOLEAN</literal>, where <literal>True</literal> means
that a row is visible, and <literal>False</literal>, not visible. This
method will fail if the <link
linkend="method-gtktreemodelfilter--set-visible-func"><methodname>set_visible_func</methodname>()</link>
method has already been called.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodelfilter--get-model">
      <title>gtk.TreeModelFilter.get_model</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_model</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the child <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>get_model</methodname>() method returns the
child <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link> of
the treemodel filter</para>

    </refsect2>

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

      <programlisting><methodsynopsis language="python">
	  <methodname>convert_child_iter_to_iter</methodname>
	  <methodparam><parameter role="keyword">child_iter</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
	  role="keyword">child_iter</parameter>&nbsp;:</term>
	  <listitem><simpara>A valid <link
	  linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
	  pointing to a row on the child model.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
	  pointing to a row in the treemodel filter.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>convert_child_iter_to_iter</methodname>() method
returns a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing to the row in the treemodel filter that corresponds to the child
treemodel row pointed to by the <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
specified by <parameter>child_iter</parameter>.</para>

    </refsect2>

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

      <programlisting><methodsynopsis language="python">
	  <methodname>convert_iter_to_child_iter</methodname>
	  <methodparam><parameter role="keyword">filter_iter</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
	  role="keyword">filter_iter</parameter>&nbsp;:</term>
	  <listitem><simpara>A valid <link
	  linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
	  pointing to a row in the treemodel filter.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
	  pointing to a row in the child treemodel.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>convert_iter_to_child_iter</methodname>() method
a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
pointing to the row in the child treemodel that corresponds to the treemodel
filter row pointed to by the <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
specified by <parameter>filter_iter</parameter>.</para>

    </refsect2>

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

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

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

      <para>The <methodname>convert_child_path_to_path</methodname>() method
returns a treemodel filter tree path that corresponds to the child treemodel
tree path specified by <parameter>child_path</parameter>. If
<parameter>child_path</parameter> isn't a valid path on the child model,
<literal>None</literal> is returned.</para>

    </refsect2>

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

      <programlisting><methodsynopsis language="python">
	  <methodname>convert_path_to_child_path</methodname>
	  <methodparam><parameter role="keyword">filter_path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
	  role="keyword">filter_path</parameter>&nbsp;:</term>
	  <listitem><simpara>a treemodel filter tree path to
	  convert.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a child treemodel tree path, or
	  <literal>None</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>convert_path_to_child_path</methodname>() method
returns a child treemodel tree path that corresponds to the treemodel filter
tree path specified by <parameter>filter_path</parameter>. If
<parameter>filter_path</parameter> does not point to a row in the child
model, <literal>None</literal> is returned.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodelfilter--refilter">
      <title>gtk.TreeModelFilter.refilter</title>

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

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

      <para>The <methodname>refilter</methodname>() method emits the <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
"<link linkend="signal-gtktreemodel--row-changed">row-changed</link>" signal
for each row in the child model, thereby causing the filter to re-evaluate
whether a row is visible or not.</para>

    </refsect2>

    <refsect2 id="method-gtktreemodelfilter--clear-cache">
      <title>gtk.TreeModelFilter.clear_cache</title>

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

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

      <para>The <methodname>clear_cache</methodname>() method clears the
treemodel filter of any cached iterators that haven't been reffed with the
<link
linkend="method-gtktreemodel--ref-node"><methodname>gtk.TreeModel.ref_node()</methodname></link>. This
might be useful if the child model being filtered is static (and doesn't
change often) and there has been a lot of unreffed access to nodes. As a
side effect of this function, all unreffed iters will be invalid. This
method should almost never be called by an application.</para>

    </refsect2>

  </refsect1>

</refentry>