<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
<!ENTITY pi "&#960;">
<!ENTITY solidus "&#8260;">
]>
<refentry id="GtkTreeModelFilter">
<refmeta>
<refentrytitle role="top_of_page" id="GtkTreeModelFilter.top_of_page">GtkTreeModelFilter</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GtkTreeModelFilter</refname>
<refpurpose>A GtkTreeModel which hides parts of an underlying tree model</refpurpose>
</refnamediv>

<refsect1 id="GtkTreeModelFilter.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="GtkTreeModelFilterVisibleFunc">*GtkTreeModelFilterVisibleFunc</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="GtkTreeModelFilterModifyFunc">*GtkTreeModelFilterModifyFunc</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GtkTreeModel"><returnvalue>GtkTreeModel</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-tree-model-filter-new">gtk_tree_model_filter_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-tree-model-filter-set-visible-func">gtk_tree_model_filter_set_visible_func</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-tree-model-filter-set-modify-func">gtk_tree_model_filter_set_modify_func</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-tree-model-filter-set-visible-column">gtk_tree_model_filter_set_visible_column</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GtkTreeModel"><returnvalue>GtkTreeModel</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-tree-model-filter-get-model">gtk_tree_model_filter_get_model</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-tree-model-filter-convert-child-iter-to-iter">gtk_tree_model_filter_convert_child_iter_to_iter</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-tree-model-filter-convert-iter-to-child-iter">gtk_tree_model_filter_convert_iter_to_child_iter</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GtkTreePath"><returnvalue>GtkTreePath</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-tree-model-filter-convert-child-path-to-path">gtk_tree_model_filter_convert_child_path_to_path</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GtkTreePath"><returnvalue>GtkTreePath</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-tree-model-filter-convert-path-to-child-path">gtk_tree_model_filter_convert_path_to_child_path</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-tree-model-filter-refilter">gtk_tree_model_filter_refilter</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-tree-model-filter-clear-cache">gtk_tree_model_filter_clear_cache</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkTreeModelFilter.properties" role="properties">
<title role="properties.title">Properties</title>
<informaltable frame="none">
<tgroup cols="3">
<colspec colname="properties_type" colwidth="150px"/>
<colspec colname="properties_name" colwidth="300px"/>
<colspec colname="properties_flags" colwidth="200px"/>
<tbody>
<row><entry role="property_type"><link linkend="GtkTreeModel"><type>GtkTreeModel</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkTreeModelFilter--child-model">child-model</link></entry><entry role="property_flags">Read / Write / Construct&#160;Only</entry></row>
<row><entry role="property_type"><link linkend="GtkTreePath"><type>GtkTreePath</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkTreeModelFilter--virtual-root">virtual-root</link></entry><entry role="property_flags">Read / Write / Construct&#160;Only</entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkTreeModelFilter.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GtkTreeModelFilter-struct">GtkTreeModelFilter</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkTreeModelFilter.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<screen>    <link linkend="GObject">GObject</link>
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> GtkTreeModelFilter
</screen>
</refsect1>
<refsect1 id="GtkTreeModelFilter.implemented-interfaces" role="impl_interfaces">
<title role="impl_interfaces.title">Implemented Interfaces</title>
<para>
GtkTreeModelFilter implements
 <link linkend="GtkTreeModel">GtkTreeModel</link> and  <link linkend="GtkTreeDragSource">GtkTreeDragSource</link>.</para>

</refsect1>

<refsect1 id="GtkTreeModelFilter.includes"><title>Includes</title><synopsis>#include &lt;gtk/gtk.h&gt;
</synopsis></refsect1>

<refsect1 id="GtkTreeModelFilter.description" role="desc">
<title role="desc.title">Description</title>
<para>A <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link> is a tree model which wraps another tree model,
and can do the following things:</para>
<itemizedlist>
<listitem>
<para>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
model, iter and user_data and returns a boolean indicating whether the
row should be filtered or not.</para>
</listitem>
<listitem>
<para>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 model based
on the given child model.</para>
</listitem>
<listitem>
<para>Set a different root node, also known as a “virtual root”. You can pass
in a <link linkend="GtkTreePath"><type>GtkTreePath</type></link> indicating the root node for the filter at construction
time.</para>
</listitem>
</itemizedlist>
<para>The basic API is similar to <link linkend="GtkTreeModelSort"><type>GtkTreeModelSort</type></link>. For an example on its usage,
see the section on <link linkend="GtkTreeModelSort"><type>GtkTreeModelSort</type></link>.</para>
<para>When using <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link>, it is important to realize that
<link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link> maintains an internal cache of all nodes which are
visible in its clients. The cache is likely to be a subtree of the tree
exposed by the child model. <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link> will not cache the entire
child model when unnecessary to not compromise the caching mechanism
that is exposed by the reference counting scheme. If the child model
implements reference counting, unnecessary signals may not be emitted
because of reference counting rule 3, see the <link linkend="GtkTreeModel"><type>GtkTreeModel</type></link>
documentation. (Note that e.g. <link linkend="GtkTreeStore"><type>GtkTreeStore</type></link> does not implement
reference counting and will always emit all signals, even when
the receiving node is not visible).</para>
<para>Because of this, limitations for possible visible functions do apply.
In general, visible functions should only use data or properties from
the node for which the visibility state must be determined, its siblings
or its parents. Usually, having a dependency on the state of any child
node is not possible, unless references are taken on these explicitly.
When no such reference exists, no signals may be received for these child
nodes (see reference couting rule number 3 in the <link linkend="GtkTreeModel"><type>GtkTreeModel</type></link> section).</para>
<para>Determining the visibility state of a given node based on the state
of its child nodes is a frequently occurring use case. Therefore,
<link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link> explicitly supports this. For example, when a node
does not have any children, you might not want the node to be visible.
As soon as the first row is added to the node’s child level (or the
last row removed), the node’s visibility should be updated.</para>
<para>This introduces a dependency from the node on its child nodes. In order
to accommodate this, <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link> must make sure the necessary
signals are received from the child model. This is achieved by building,
for all nodes which are exposed as visible nodes to <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link>'s
clients, the child level (if any) and take a reference on the first node
in this level. Furthermore, for every row-inserted, row-changed or
row-deleted signal (also these which were not handled because the node
was not cached), <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link> will check if the visibility state
of any parent node has changed.</para>
<para>Beware, however, that this explicit support is limited to these two
cases. For example, if you want a node to be visible only if two nodes
in a child’s child level (2 levels deeper) are visible, you are on your
own. In this case, either rely on <link linkend="GtkTreeStore"><type>GtkTreeStore</type></link> to emit all signals
because it does not implement reference counting, or for models that
do implement reference counting, obtain references on these child levels
yourself.</para>

</refsect1>
<refsect1 id="GtkTreeModelFilter.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="GtkTreeModelFilterVisibleFunc" role="function">
<title>GtkTreeModelFilterVisibleFunc&#160;()</title>
<indexterm zone="GtkTreeModelFilterVisibleFunc"><primary>GtkTreeModelFilterVisibleFunc</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
<phrase role="c_punctuation">(</phrase>*GtkTreeModelFilterVisibleFunc<phrase role="c_punctuation">)</phrase> (<parameter><link linkend="GtkTreeModel"><type>GtkTreeModel</type></link> *model</parameter>,
                                  <parameter><link linkend="GtkTreeIter"><type>GtkTreeIter</type></link> *iter</parameter>,
                                  <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>);</programlisting>
<para>A function which decides whether the row indicated by <parameter>iter</parameter>
 is visible.</para>
<refsect3 id="GtkTreeModelFilterVisibleFunc.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>model</para></entry>
<entry role="parameter_description"><para>the child model of the <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>iter</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkTreeIter"><type>GtkTreeIter</type></link> pointing to the row in <parameter>model</parameter>
whose visibility
is determined</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>user data given to <link linkend="gtk-tree-model-filter-set-visible-func"><function>gtk_tree_model_filter_set_visible_func()</function></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>closure</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="GtkTreeModelFilterVisibleFunc.returns" role="returns">
<title>Returns</title>
<para> Whether the row indicated by <parameter>iter</parameter>
is visible.</para>
</refsect3></refsect2>
<refsect2 id="GtkTreeModelFilterModifyFunc" role="function">
<title>GtkTreeModelFilterModifyFunc&#160;()</title>
<indexterm zone="GtkTreeModelFilterModifyFunc"><primary>GtkTreeModelFilterModifyFunc</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
<phrase role="c_punctuation">(</phrase>*GtkTreeModelFilterModifyFunc<phrase role="c_punctuation">)</phrase> (<parameter><link linkend="GtkTreeModel"><type>GtkTreeModel</type></link> *model</parameter>,
                                 <parameter><link linkend="GtkTreeIter"><type>GtkTreeIter</type></link> *iter</parameter>,
                                 <parameter><link linkend="GValue"><type>GValue</type></link> *value</parameter>,
                                 <parameter><link linkend="gint"><type>gint</type></link> column</parameter>,
                                 <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>);</programlisting>
<para>A function which calculates display values from raw values in the model.
It must fill <parameter>value</parameter>
 with the display value for the column <parameter>column</parameter>
 in the
row indicated by <parameter>iter</parameter>
.</para>
<para>Since this function is called for each data access, it’s not a
particularly efficient operation.</para>
<refsect3 id="GtkTreeModelFilterModifyFunc.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>model</para></entry>
<entry role="parameter_description"><para>the <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>iter</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkTreeIter"><type>GtkTreeIter</type></link> pointing to the row whose display values are determined</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para>A <link linkend="GValue"><type>GValue</type></link> which is already initialized for
with the correct type for the column <parameter>column</parameter>
. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out caller-allocates</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>column</para></entry>
<entry role="parameter_description"><para>the column whose display value is determined</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>user data given to <link linkend="gtk-tree-model-filter-set-modify-func"><function>gtk_tree_model_filter_set_modify_func()</function></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>closure</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-tree-model-filter-new" role="function">
<title>gtk_tree_model_filter_new&#160;()</title>
<indexterm zone="gtk-tree-model-filter-new"><primary>gtk_tree_model_filter_new</primary></indexterm>
<programlisting language="C"><link linkend="GtkTreeModel"><returnvalue>GtkTreeModel</returnvalue></link>&#160;*
gtk_tree_model_filter_new (<parameter><link linkend="GtkTreeModel"><type>GtkTreeModel</type></link> *child_model</parameter>,
                           <parameter><link linkend="GtkTreePath"><type>GtkTreePath</type></link> *root</parameter>);</programlisting>
<para>Creates a new <link linkend="GtkTreeModel"><type>GtkTreeModel</type></link>, with <parameter>child_model</parameter>
 as the child_model
and <parameter>root</parameter>
 as the virtual root.</para>
<refsect3 id="gtk-tree-model-filter-new.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>child_model</para></entry>
<entry role="parameter_description"><para>A <link linkend="GtkTreeModel"><type>GtkTreeModel</type></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>root</para></entry>
<entry role="parameter_description"><para>A <link linkend="GtkTreePath"><type>GtkTreePath</type></link> or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-tree-model-filter-new.returns" role="returns">
<title>Returns</title>
<para>A new <link linkend="GtkTreeModel"><type>GtkTreeModel</type></link>. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-tree-model-filter-set-visible-func" role="function">
<title>gtk_tree_model_filter_set_visible_func&#160;()</title>
<indexterm zone="gtk-tree-model-filter-set-visible-func"><primary>gtk_tree_model_filter_set_visible_func</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_tree_model_filter_set_visible_func
                               (<parameter><link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link> *filter</parameter>,
                                <parameter><link linkend="GtkTreeModelFilterVisibleFunc"><type>GtkTreeModelFilterVisibleFunc</type></link> func</parameter>,
                                <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>,
                                <parameter><link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> destroy</parameter>);</programlisting>
<para>Sets the visible function used when filtering the <parameter>filter</parameter>
 to be <parameter>func</parameter>
.
The function should return <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the given row should be visible and
<link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.</para>
<para>If the condition calculated by the function changes over time (e.g.
because it depends on some global parameters), you must call 
<link linkend="gtk-tree-model-filter-refilter"><function>gtk_tree_model_filter_refilter()</function></link> to keep the visibility information
of the model up-to-date.</para>
<para>Note that <parameter>func</parameter>
 is called whenever a row is inserted, when it may still
be empty. The visible function should therefore take special care of empty
rows, like in the example below.</para>
<informalexample><programlisting role="example"><![CDATA[
static gboolean
visible_func (GtkTreeModel *model,
              GtkTreeIter  *iter,
              gpointer      data)
{
  // Visible if row is non-empty and first column is “HI”
  gchar *str;
  gboolean visible = FALSE;

  gtk_tree_model_get (model, iter, 0, &str, -1);
  if (str && strcmp (str, "HI") == 0)
    visible = TRUE;
  g_free (str);

  return visible;
}
]]></programlisting></informalexample>
<para></para>
<para>Note that <link linkend="gtk-tree-model-filter-set-visible-func"><function>gtk_tree_model_filter_set_visible_func()</function></link> or
<link linkend="gtk-tree-model-filter-set-visible-column"><function>gtk_tree_model_filter_set_visible_column()</function></link> can only be called
once for a given filter model.</para>
<refsect3 id="gtk-tree-model-filter-set-visible-func.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>filter</para></entry>
<entry role="parameter_description"><para>A <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>func</para></entry>
<entry role="parameter_description"><para>A <link linkend="GtkTreeModelFilterVisibleFunc"><type>GtkTreeModelFilterVisibleFunc</type></link>, the visible function</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>User data to pass to the visible function, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>destroy</para></entry>
<entry role="parameter_description"><para>Destroy notifier of <parameter>data</parameter>
, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-tree-model-filter-set-modify-func" role="function">
<title>gtk_tree_model_filter_set_modify_func&#160;()</title>
<indexterm zone="gtk-tree-model-filter-set-modify-func"><primary>gtk_tree_model_filter_set_modify_func</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_tree_model_filter_set_modify_func (<parameter><link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link> *filter</parameter>,
                                       <parameter><link linkend="gint"><type>gint</type></link> n_columns</parameter>,
                                       <parameter><link linkend="GType"><type>GType</type></link> *types</parameter>,
                                       <parameter><link linkend="GtkTreeModelFilterModifyFunc"><type>GtkTreeModelFilterModifyFunc</type></link> func</parameter>,
                                       <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>,
                                       <parameter><link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> destroy</parameter>);</programlisting>
<para>With the <parameter>n_columns</parameter>
 and <parameter>types</parameter>
 parameters, you give an array of column
types for this model (which will be exposed to the parent model/view).
The <parameter>func</parameter>
, <parameter>data</parameter>
 and <parameter>destroy</parameter>
 parameters are for specifying the modify
function. The modify function will get called for each
data access, the goal of the modify function is to return the data which 
should be displayed at the location specified using the parameters of the 
modify function.</para>
<para>Note that <link linkend="gtk-tree-model-filter-set-modify-func"><function>gtk_tree_model_filter_set_modify_func()</function></link>
can only be called once for a given filter model.</para>
<refsect3 id="gtk-tree-model-filter-set-modify-func.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>filter</para></entry>
<entry role="parameter_description"><para>A <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>n_columns</para></entry>
<entry role="parameter_description"><para>The number of columns in the filter model.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>types</para></entry>
<entry role="parameter_description"><para>The <link linkend="GTypes"><type>GTypes</type></link> of the columns. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> length=n_columns]</emphasis></entry></row>
<row><entry role="parameter_name"><para>func</para></entry>
<entry role="parameter_description"><para>A <link linkend="GtkTreeModelFilterModifyFunc"><type>GtkTreeModelFilterModifyFunc</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>User data to pass to the modify function, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>destroy</para></entry>
<entry role="parameter_description"><para>Destroy notifier of <parameter>data</parameter>
, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-tree-model-filter-set-visible-column" role="function">
<title>gtk_tree_model_filter_set_visible_column&#160;()</title>
<indexterm zone="gtk-tree-model-filter-set-visible-column"><primary>gtk_tree_model_filter_set_visible_column</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_tree_model_filter_set_visible_column
                               (<parameter><link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link> *filter</parameter>,
                                <parameter><link linkend="gint"><type>gint</type></link> column</parameter>);</programlisting>
<para>Sets <parameter>column</parameter>
 of the child_model to be the column where <parameter>filter</parameter>
 should
look for visibility information. <parameter>columns</parameter>
 should be a column of type
<link linkend="G-TYPE-BOOLEAN:CAPS"><literal>G_TYPE_BOOLEAN</literal></link>, where <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> means that a row is visible, and <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>
if not.</para>
<para>Note that <link linkend="gtk-tree-model-filter-set-visible-func"><function>gtk_tree_model_filter_set_visible_func()</function></link> or
<link linkend="gtk-tree-model-filter-set-visible-column"><function>gtk_tree_model_filter_set_visible_column()</function></link> can only be called
once for a given filter model.</para>
<refsect3 id="gtk-tree-model-filter-set-visible-column.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>filter</para></entry>
<entry role="parameter_description"><para>A <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>column</para></entry>
<entry role="parameter_description"><para>A <link linkend="gint"><type>gint</type></link> which is the column containing the visible information</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-tree-model-filter-get-model" role="function">
<title>gtk_tree_model_filter_get_model&#160;()</title>
<indexterm zone="gtk-tree-model-filter-get-model"><primary>gtk_tree_model_filter_get_model</primary></indexterm>
<programlisting language="C"><link linkend="GtkTreeModel"><returnvalue>GtkTreeModel</returnvalue></link>&#160;*
gtk_tree_model_filter_get_model (<parameter><link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link> *filter</parameter>);</programlisting>
<para>Returns a pointer to the child model of <parameter>filter</parameter>
.</para>
<refsect3 id="gtk-tree-model-filter-get-model.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>filter</para></entry>
<entry role="parameter_description"><para>A <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-tree-model-filter-get-model.returns" role="returns">
<title>Returns</title>
<para>A pointer to a <link linkend="GtkTreeModel"><type>GtkTreeModel</type></link>. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-tree-model-filter-convert-child-iter-to-iter" role="function">
<title>gtk_tree_model_filter_convert_child_iter_to_iter&#160;()</title>
<indexterm zone="gtk-tree-model-filter-convert-child-iter-to-iter"><primary>gtk_tree_model_filter_convert_child_iter_to_iter</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_tree_model_filter_convert_child_iter_to_iter
                               (<parameter><link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link> *filter</parameter>,
                                <parameter><link linkend="GtkTreeIter"><type>GtkTreeIter</type></link> *filter_iter</parameter>,
                                <parameter><link linkend="GtkTreeIter"><type>GtkTreeIter</type></link> *child_iter</parameter>);</programlisting>
<para>Sets <parameter>filter_iter</parameter>
 to point to the row in <parameter>filter</parameter>
 that corresponds to the
row pointed at by <parameter>child_iter</parameter>
.  If <parameter>filter_iter</parameter>
 was not set, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> is
returned.</para>
<refsect3 id="gtk-tree-model-filter-convert-child-iter-to-iter.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>filter</para></entry>
<entry role="parameter_description"><para>A <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>filter_iter</para></entry>
<entry role="parameter_description"><para>An uninitialized <link linkend="GtkTreeIter"><type>GtkTreeIter</type></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>child_iter</para></entry>
<entry role="parameter_description"><para>A valid <link linkend="GtkTreeIter"><type>GtkTreeIter</type></link> pointing to a row on the child model.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-tree-model-filter-convert-child-iter-to-iter.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, if <parameter>filter_iter</parameter>
was set, i.e. if <parameter>child_iter</parameter>
is a
valid iterator pointing to a visible row in child model.</para>
</refsect3></refsect2>
<refsect2 id="gtk-tree-model-filter-convert-iter-to-child-iter" role="function">
<title>gtk_tree_model_filter_convert_iter_to_child_iter&#160;()</title>
<indexterm zone="gtk-tree-model-filter-convert-iter-to-child-iter"><primary>gtk_tree_model_filter_convert_iter_to_child_iter</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_tree_model_filter_convert_iter_to_child_iter
                               (<parameter><link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link> *filter</parameter>,
                                <parameter><link linkend="GtkTreeIter"><type>GtkTreeIter</type></link> *child_iter</parameter>,
                                <parameter><link linkend="GtkTreeIter"><type>GtkTreeIter</type></link> *filter_iter</parameter>);</programlisting>
<para>Sets <parameter>child_iter</parameter>
 to point to the row pointed to by <parameter>filter_iter</parameter>
.</para>
<refsect3 id="gtk-tree-model-filter-convert-iter-to-child-iter.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>filter</para></entry>
<entry role="parameter_description"><para>A <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>child_iter</para></entry>
<entry role="parameter_description"><para>An uninitialized <link linkend="GtkTreeIter"><type>GtkTreeIter</type></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>filter_iter</para></entry>
<entry role="parameter_description"><para>A valid <link linkend="GtkTreeIter"><type>GtkTreeIter</type></link> pointing to a row on <parameter>filter</parameter>
.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-tree-model-filter-convert-child-path-to-path" role="function">
<title>gtk_tree_model_filter_convert_child_path_to_path&#160;()</title>
<indexterm zone="gtk-tree-model-filter-convert-child-path-to-path"><primary>gtk_tree_model_filter_convert_child_path_to_path</primary></indexterm>
<programlisting language="C"><link linkend="GtkTreePath"><returnvalue>GtkTreePath</returnvalue></link>&#160;*
gtk_tree_model_filter_convert_child_path_to_path
                               (<parameter><link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link> *filter</parameter>,
                                <parameter><link linkend="GtkTreePath"><type>GtkTreePath</type></link> *child_path</parameter>);</programlisting>
<para>Converts <parameter>child_path</parameter>
 to a path relative to <parameter>filter</parameter>
. That is, <parameter>child_path</parameter>

points to a path in the child model. The rerturned path will point to the
same row in the filtered model. If <parameter>child_path</parameter>
 isn’t a valid path on the
child model or points to a row which is not visible in <parameter>filter</parameter>
, then <link linkend="NULL:CAPS"><literal>NULL</literal></link>
is returned.</para>
<refsect3 id="gtk-tree-model-filter-convert-child-path-to-path.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>filter</para></entry>
<entry role="parameter_description"><para>A <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>child_path</para></entry>
<entry role="parameter_description"><para>A <link linkend="GtkTreePath"><type>GtkTreePath</type></link> to convert.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-tree-model-filter-convert-child-path-to-path.returns" role="returns">
<title>Returns</title>
<para>A newly allocated <link linkend="GtkTreePath"><type>GtkTreePath</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>transfer full</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-tree-model-filter-convert-path-to-child-path" role="function">
<title>gtk_tree_model_filter_convert_path_to_child_path&#160;()</title>
<indexterm zone="gtk-tree-model-filter-convert-path-to-child-path"><primary>gtk_tree_model_filter_convert_path_to_child_path</primary></indexterm>
<programlisting language="C"><link linkend="GtkTreePath"><returnvalue>GtkTreePath</returnvalue></link>&#160;*
gtk_tree_model_filter_convert_path_to_child_path
                               (<parameter><link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link> *filter</parameter>,
                                <parameter><link linkend="GtkTreePath"><type>GtkTreePath</type></link> *filter_path</parameter>);</programlisting>
<para>Converts <parameter>filter_path</parameter>
 to a path on the child model of <parameter>filter</parameter>
. That is,
<parameter>filter_path</parameter>
 points to a location in <parameter>filter</parameter>
. The returned path will
point to the same location in the model not being filtered. If <parameter>filter_path</parameter>

does not point to a location in the child model, <link linkend="NULL:CAPS"><literal>NULL</literal></link> is returned.</para>
<refsect3 id="gtk-tree-model-filter-convert-path-to-child-path.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>filter</para></entry>
<entry role="parameter_description"><para>A <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>filter_path</para></entry>
<entry role="parameter_description"><para>A <link linkend="GtkTreePath"><type>GtkTreePath</type></link> to convert.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-tree-model-filter-convert-path-to-child-path.returns" role="returns">
<title>Returns</title>
<para>A newly allocated <link linkend="GtkTreePath"><type>GtkTreePath</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>transfer full</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-tree-model-filter-refilter" role="function">
<title>gtk_tree_model_filter_refilter&#160;()</title>
<indexterm zone="gtk-tree-model-filter-refilter"><primary>gtk_tree_model_filter_refilter</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_tree_model_filter_refilter (<parameter><link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link> *filter</parameter>);</programlisting>
<para>Emits ::row_changed for each row in the child model, which causes
the filter to re-evaluate whether a row is visible or not.</para>
<refsect3 id="gtk-tree-model-filter-refilter.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>filter</para></entry>
<entry role="parameter_description"><para>A <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-tree-model-filter-clear-cache" role="function">
<title>gtk_tree_model_filter_clear_cache&#160;()</title>
<indexterm zone="gtk-tree-model-filter-clear-cache"><primary>gtk_tree_model_filter_clear_cache</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_tree_model_filter_clear_cache (<parameter><link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link> *filter</parameter>);</programlisting>
<para>This function should almost never be called. It clears the <parameter>filter</parameter>

of any cached iterators that haven’t been reffed with
<link linkend="gtk-tree-model-ref-node"><function>gtk_tree_model_ref_node()</function></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.</para>
<refsect3 id="gtk-tree-model-filter-clear-cache.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>filter</para></entry>
<entry role="parameter_description"><para>A <link linkend="GtkTreeModelFilter"><type>GtkTreeModelFilter</type></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>

</refsect1>
<refsect1 id="GtkTreeModelFilter.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GtkTreeModelFilter-struct" role="struct">
<title>struct GtkTreeModelFilter</title>
<indexterm zone="GtkTreeModelFilter-struct"><primary>GtkTreeModelFilter</primary></indexterm>
<programlisting language="C">struct GtkTreeModelFilter;</programlisting>
</refsect2>

</refsect1>
<refsect1 id="GtkTreeModelFilter.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="GtkTreeModelFilter--child-model" role="property"><title>The <literal>“child-model”</literal> property</title>
<indexterm zone="GtkTreeModelFilter--child-model"><primary>GtkTreeModelFilter:child-model</primary></indexterm>
<programlisting>  “child-model”              <link linkend="GtkTreeModel"><type>GtkTreeModel</type></link>&#160;*</programlisting>
<para>The model for the filtermodel to filter.</para><para>Owner: GtkTreeModelFilter</para>
<para>Flags: Read / Write / Construct&#160;Only</para>
</refsect2>
<refsect2 id="GtkTreeModelFilter--virtual-root" role="property"><title>The <literal>“virtual-root”</literal> property</title>
<indexterm zone="GtkTreeModelFilter--virtual-root"><primary>GtkTreeModelFilter:virtual-root</primary></indexterm>
<programlisting>  “virtual-root”             <link linkend="GtkTreePath"><type>GtkTreePath</type></link>&#160;*</programlisting>
<para>The virtual root (relative to the child model) for this filtermodel.</para><para>Owner: GtkTreeModelFilter</para>
<para>Flags: Read / Write / Construct&#160;Only</para>
</refsect2>

</refsect1>
<refsect1 id="GtkTreeModelFilter.see-also">
<title>See Also</title>
<para><link linkend="GtkTreeModelSort"><type>GtkTreeModelSort</type></link></para>

</refsect1>

</refentry>
