:right-sidebar: True

Filter
===================================================================

.. currentmodule:: gi.repository.Gtk





.. class:: Filter(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.GObject.Object`


Subclasses: :class:`~gi.repository.Gtk.BoolFilter`, :class:`~gi.repository.Gtk.CustomFilter`, :class:`~gi.repository.Gtk.FileFilter`, :class:`~gi.repository.Gtk.MultiFilter`, :class:`~gi.repository.Gtk.StringFilter`




A ``GtkFilter`` object describes the filtering to be performed by a
:obj:`~gi.repository.Gtk.FilterListModel`.

The model will use the filter to determine if it should include items
or not by calling :obj:`~gi.repository.Gtk.Filter.match` for each item and only
keeping the ones that the function returns :const:`True` for.

Filters may change what items they match through their lifetime. In that
case, they will emit the :obj:`~gi.repository.Gtk.Filter.signals.changed` signal to notify
that previous filter results are no longer valid and that items should
be checked again via :obj:`~gi.repository.Gtk.Filter.match`.

GTK provides various pre-made filter implementations for common filtering
operations. These filters often include properties that can be linked to
various widgets to easily allow searches.

However, in particular for large lists or complex search methods, it is
also possible to subclass ``GtkFilter`` and provide one's own filter.





Methods
-------

.. rst-class:: interim-class

.. class:: Filter
   :no-index:


   .. method:: changed(change: ~gi.repository.Gtk.FilterChange) -> None

      Notifies all users of the filter that it has changed.

      This emits the :obj:`~gi.repository.Gtk.Filter.signals.changed` signal. Users
      of the filter should then check items again via
      :obj:`~gi.repository.Gtk.Filter.match`.

      Depending on the ``change`` parameter, not all items need to
      be changed, but only some. Refer to the :obj:`~gi.repository.Gtk.FilterChange`
      documentation for details.

      This function is intended for implementers of ``GtkFilter``
      subclasses and should not be called from other functions.







      :param change: How the filter changed





   .. method:: get_strictness() -> ~gi.repository.Gtk.FilterMatch

      Gets the known strictness of ``filters``.

      If the strictness is not known, :const:`~gi.repository.Gtk.FilterMatch.SOME` is returned.

      This value may change after emission of the :obj:`~gi.repository.Gtk.Filter.signals.changed`
      signal.

      This function is meant purely for optimization purposes, filters can
      choose to omit implementing it, but ``GtkFilterListModel`` uses it.










   .. method:: match(item: ~gi.repository.GObject.Object) -> bool

      Checks if the given ``item`` is matched by the filter or not.







      :param item: The item to check











Signals
-------

.. rst-class:: interim-class

.. class:: Filter.signals
   :no-index:
   

   .. method:: changed(change: ~gi.repository.Gtk.FilterChange) -> None

      Emitted whenever the filter changed.

      Users of the filter should then check items again via
      :obj:`~gi.repository.Gtk.Filter.match`.

      ``GtkFilterListModel`` handles this signal automatically.

      Depending on the ``change`` parameter, not all items need
      to be checked, but only some. Refer to the :obj:`~gi.repository.Gtk.FilterChange`
      documentation for details.







      :param change: how the filter changed









Virtual Methods
---------------

.. rst-class:: interim-class

.. class:: Filter
   :no-index:
   

   .. method:: do_get_strictness() -> ~gi.repository.Gtk.FilterMatch

      Gets the known strictness of ``filters``.

      If the strictness is not known, :const:`~gi.repository.Gtk.FilterMatch.SOME` is returned.

      This value may change after emission of the :obj:`~gi.repository.Gtk.Filter.signals.changed`
      signal.

      This function is meant purely for optimization purposes, filters can
      choose to omit implementing it, but ``GtkFilterListModel`` uses it.










   .. method:: do_match(item: ~gi.repository.GObject.Object | None = None) -> bool

      Checks if the given ``item`` is matched by the filter or not.







      :param item: The item to check









Fields
------

.. rst-class:: interim-class

.. class:: Filter
   :no-index:
   

   .. attribute:: parent_instance