<?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="GtkFilterListModel">
<refmeta>
<refentrytitle role="top_of_page" id="GtkFilterListModel.top_of_page">GtkFilterListModel</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GtkFilterListModel</refname>
<refpurpose>A list model that filters its items</refpurpose>
</refnamediv>

<refsect1 id="GtkFilterListModel.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="GtkFilterListModel"><returnvalue>GtkFilterListModel</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-filter-list-model-new">gtk_filter_list_model_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-filter-list-model-set-model">gtk_filter_list_model_set_model</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GListModel"><returnvalue>GListModel</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-filter-list-model-get-model">gtk_filter_list_model_get_model</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-filter-list-model-set-filter">gtk_filter_list_model_set_filter</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GtkFilter"><returnvalue>GtkFilter</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-filter-list-model-get-filter">gtk_filter_list_model_get_filter</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-filter-list-model-set-incremental">gtk_filter_list_model_set_incremental</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-filter-list-model-get-incremental">gtk_filter_list_model_get_incremental</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-filter-list-model-get-pending">gtk_filter_list_model_get_pending</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkFilterListModel.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="GtkFilter"><type>GtkFilter</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkFilterListModel--filter">filter</link></entry><entry role="property_flags">Read / Write</entry></row>
<row><entry role="property_type"><link linkend="gboolean"><type>gboolean</type></link></entry><entry role="property_name"><link linkend="GtkFilterListModel--incremental">incremental</link></entry><entry role="property_flags">Read / Write</entry></row>
<row><entry role="property_type"><link linkend="GListModel"><type>GListModel</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkFilterListModel--model">model</link></entry><entry role="property_flags">Read / Write</entry></row>
<row><entry role="property_type"><link linkend="guint"><type>guint</type></link></entry><entry role="property_name"><link linkend="GtkFilterListModel--pending">pending</link></entry><entry role="property_flags">Read</entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkFilterListModel.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"></entry><entry role="function_name"><link linkend="GtkFilterListModel-struct">GtkFilterListModel</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkFilterListModel.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> GtkFilterListModel
</screen>
</refsect1>
<refsect1 id="GtkFilterListModel.implemented-interfaces" role="impl_interfaces">
<title role="impl_interfaces.title">Implemented Interfaces</title>
<para>
GtkFilterListModel implements
 <link linkend="GListModel">GListModel</link>.</para>

</refsect1>

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

<refsect1 id="GtkFilterListModel.description" role="desc">
<title role="desc.title">Description</title>
<para><link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link> is a list model that filters a given other
listmodel.
It hides some elements from the other model according to
criteria given by a <link linkend="GtkFilter"><type>GtkFilter</type></link>.</para>
<para>The model can be set up to do incremental searching, so that
filtering long lists doesn't block the UI. See
<link linkend="gtk-filter-list-model-set-incremental"><function>gtk_filter_list_model_set_incremental()</function></link> for details.</para>

</refsect1>
<refsect1 id="GtkFilterListModel.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gtk-filter-list-model-new" role="function">
<title>gtk_filter_list_model_new&#160;()</title>
<indexterm zone="gtk-filter-list-model-new"><primary>gtk_filter_list_model_new</primary></indexterm>
<programlisting language="C"><link linkend="GtkFilterListModel"><returnvalue>GtkFilterListModel</returnvalue></link>&#160;*
gtk_filter_list_model_new (<parameter><link linkend="GListModel"><type>GListModel</type></link> *model</parameter>,
                           <parameter><link linkend="GtkFilter"><type>GtkFilter</type></link> *filter</parameter>);</programlisting>
<para>Creates a new <link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link> that will filter <parameter>model</parameter>
 using the given
<parameter>filter</parameter>
.</para>
<refsect3 id="gtk-filter-list-model-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>model</para></entry>
<entry role="parameter_description"><para>the model to sort, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>][<acronym>transfer full</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>filter</para></entry>
<entry role="parameter_description"><para>filter or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to not filter items. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>][<acronym>transfer full</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-filter-list-model-new.returns" role="returns">
<title>Returns</title>
<para> a new <link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link></para>
</refsect3></refsect2>
<refsect2 id="gtk-filter-list-model-set-model" role="function">
<title>gtk_filter_list_model_set_model&#160;()</title>
<indexterm zone="gtk-filter-list-model-set-model"><primary>gtk_filter_list_model_set_model</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_filter_list_model_set_model (<parameter><link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link> *self</parameter>,
                                 <parameter><link linkend="GListModel"><type>GListModel</type></link> *model</parameter>);</programlisting>
<para>Sets the model to be filtered.</para>
<para>Note that GTK makes no effort to ensure that <parameter>model</parameter>
 conforms to
the item type of <parameter>self</parameter>
. It assumes that the caller knows what they
are doing and have set up an appropriate filter to ensure that item
types match.</para>
<refsect3 id="gtk-filter-list-model-set-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>self</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>model</para></entry>
<entry role="parameter_description"><para>The model to be filtered. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-filter-list-model-get-model" role="function">
<title>gtk_filter_list_model_get_model&#160;()</title>
<indexterm zone="gtk-filter-list-model-get-model"><primary>gtk_filter_list_model_get_model</primary></indexterm>
<programlisting language="C"><link linkend="GListModel"><returnvalue>GListModel</returnvalue></link>&#160;*
gtk_filter_list_model_get_model (<parameter><link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link> *self</parameter>);</programlisting>
<para>Gets the model currently filtered or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if none.</para>
<refsect3 id="gtk-filter-list-model-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>self</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-filter-list-model-get-model.returns" role="returns">
<title>Returns</title>
<para>The model that gets filtered. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-filter-list-model-set-filter" role="function">
<title>gtk_filter_list_model_set_filter&#160;()</title>
<indexterm zone="gtk-filter-list-model-set-filter"><primary>gtk_filter_list_model_set_filter</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_filter_list_model_set_filter (<parameter><link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link> *self</parameter>,
                                  <parameter><link linkend="GtkFilter"><type>GtkFilter</type></link> *filter</parameter>);</programlisting>
<para>Sets the filter used to filter items.</para>
<refsect3 id="gtk-filter-list-model-set-filter.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>self</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>filter</para></entry>
<entry role="parameter_description"><para>filter to use or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to not filter items. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>][<acronym>transfer none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-filter-list-model-get-filter" role="function">
<title>gtk_filter_list_model_get_filter&#160;()</title>
<indexterm zone="gtk-filter-list-model-get-filter"><primary>gtk_filter_list_model_get_filter</primary></indexterm>
<programlisting language="C"><link linkend="GtkFilter"><returnvalue>GtkFilter</returnvalue></link>&#160;*
gtk_filter_list_model_get_filter (<parameter><link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link> *self</parameter>);</programlisting>
<para>Gets the <link linkend="GtkFilter"><type>GtkFilter</type></link> currently set on <parameter>self</parameter>
.</para>
<refsect3 id="gtk-filter-list-model-get-filter.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>self</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-filter-list-model-get-filter.returns" role="returns">
<title>Returns</title>
<para>The filter currently in use
or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if the list isn't filtered. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-filter-list-model-set-incremental" role="function">
<title>gtk_filter_list_model_set_incremental&#160;()</title>
<indexterm zone="gtk-filter-list-model-set-incremental"><primary>gtk_filter_list_model_set_incremental</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_filter_list_model_set_incremental (<parameter><link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link> *self</parameter>,
                                       <parameter><link linkend="gboolean"><type>gboolean</type></link> incremental</parameter>);</programlisting>
<para>When incremental filtering is enabled, the GtkFilterListModel will not
run filters immediately, but will instead queue an idle handler that
incrementally filters the items and adds them to the list. This of course
means that items are not instantly added to the list, but only appear
incrementally.</para>
<para>When your filter blocks the UI while filtering, you might consider
turning this on. Depending on your model and filters, this may become
interesting around 10,000 to 100,000 items.</para>
<para>By default, incremental filtering is disabled.</para>
<para>See <link linkend="gtk-filter-list-model-get-pending"><function>gtk_filter_list_model_get_pending()</function></link> for progress information
about an ongoing incremental filtering operation.</para>
<refsect3 id="gtk-filter-list-model-set-incremental.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>self</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>incremental</para></entry>
<entry role="parameter_description"><para><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> to enable incremental filtering</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-filter-list-model-get-incremental" role="function">
<title>gtk_filter_list_model_get_incremental&#160;()</title>
<indexterm zone="gtk-filter-list-model-get-incremental"><primary>gtk_filter_list_model_get_incremental</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_filter_list_model_get_incremental (<parameter><link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link> *self</parameter>);</programlisting>
<para>Returns whether incremental filtering was enabled via
<link linkend="gtk-filter-list-model-set-incremental"><function>gtk_filter_list_model_set_incremental()</function></link>.</para>
<refsect3 id="gtk-filter-list-model-get-incremental.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>self</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-filter-list-model-get-incremental.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if incremental filtering is enabled</para>
</refsect3></refsect2>
<refsect2 id="gtk-filter-list-model-get-pending" role="function">
<title>gtk_filter_list_model_get_pending&#160;()</title>
<indexterm zone="gtk-filter-list-model-get-pending"><primary>gtk_filter_list_model_get_pending</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
gtk_filter_list_model_get_pending (<parameter><link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link> *self</parameter>);</programlisting>
<para>Returns the number of items that have not been filtered yet.</para>
<para>You can use this value to check if <parameter>self</parameter>
 is busy filtering by
comparing the return value to 0 or you can compute the percentage
of the filter remaining by dividing the return value by the total
number of items in the underlying model:</para>
<informalexample><programlisting role="example"><![CDATA[
  pending = gtk_filter_list_model_get_pending (self);
  model = gtk_filter_list_model_get_model (self);
  percentage = pending / (double) g_list_model_get_n_items (model);
]]></programlisting></informalexample>
<para></para>
<para>If no filter operation is ongoing - in particular when
<link linkend="GtkFilterListModel--incremental"><type>“incremental”</type></link> is <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> - this function returns 0.</para>
<refsect3 id="gtk-filter-list-model-get-pending.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>self</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkFilterListModel"><type>GtkFilterListModel</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-filter-list-model-get-pending.returns" role="returns">
<title>Returns</title>
<para> The number of items not yet filtered</para>
</refsect3></refsect2>

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

</refsect1>
<refsect1 id="GtkFilterListModel.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="GtkFilterListModel--filter" role="property"><title>The <literal>“filter”</literal> property</title>
<indexterm zone="GtkFilterListModel--filter"><primary>GtkFilterListModel:filter</primary></indexterm>
<programlisting>  “filter”                   <link linkend="GtkFilter"><type>GtkFilter</type></link>&#160;*</programlisting>
<para>The filter for this model</para>
<para>Owner: GtkFilterListModel</para>
<para>Flags: Read / Write</para>
</refsect2>
<refsect2 id="GtkFilterListModel--incremental" role="property"><title>The <literal>“incremental”</literal> property</title>
<indexterm zone="GtkFilterListModel--incremental"><primary>GtkFilterListModel:incremental</primary></indexterm>
<programlisting>  “incremental”              <link linkend="gboolean"><type>gboolean</type></link></programlisting>
<para>If the model should filter items incrementally</para>
<para>Owner: GtkFilterListModel</para>
<para>Flags: Read / Write</para>
<para>Default value: FALSE</para>
</refsect2>
<refsect2 id="GtkFilterListModel--model" role="property"><title>The <literal>“model”</literal> property</title>
<indexterm zone="GtkFilterListModel--model"><primary>GtkFilterListModel:model</primary></indexterm>
<programlisting>  “model”                    <link linkend="GListModel"><type>GListModel</type></link>&#160;*</programlisting>
<para>The model being filtered</para>
<para>Owner: GtkFilterListModel</para>
<para>Flags: Read / Write</para>
</refsect2>
<refsect2 id="GtkFilterListModel--pending" role="property"><title>The <literal>“pending”</literal> property</title>
<indexterm zone="GtkFilterListModel--pending"><primary>GtkFilterListModel:pending</primary></indexterm>
<programlisting>  “pending”                  <link linkend="guint"><type>guint</type></link></programlisting>
<para>Number of items not yet filtered</para>
<para>Owner: GtkFilterListModel</para>
<para>Flags: Read</para>
<para>Default value: 0</para>
</refsect2>

</refsect1>
<refsect1 id="GtkFilterListModel.see-also">
<title>See Also</title>
<para><link linkend="GListModel"><type>GListModel</type></link>, <link linkend="GtkFilter"><type>GtkFilter</type></link></para>

</refsect1>

</refentry>
