:right-sidebar: True

Sorter
===================================================================

.. currentmodule:: gi.repository.Gtk





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


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


Subclasses: :class:`~gi.repository.Gtk.ColumnViewSorter`, :class:`~gi.repository.Gtk.CustomSorter`, :class:`~gi.repository.Gtk.MultiSorter`, :class:`~gi.repository.Gtk.NumericSorter`, :class:`~gi.repository.Gtk.StringSorter`, :class:`~gi.repository.Gtk.TreeListRowSorter`




``GtkSorter`` is an object to describe sorting criteria.

Its primary user is :obj:`~gi.repository.Gtk.SortListModel`

The model will use a sorter to determine the order in which
its items should appear by calling :obj:`~gi.repository.Gtk.Sorter.compare`
for pairs of items.

Sorters may change their sorting behavior through their lifetime.
In that case, they will emit the :obj:`~gi.repository.Gtk.Sorter.signals.changed` signal
to notify that the sort order is no longer valid and should be updated
by calling :func:`~gi.repository.Gtk.Sorter.compare` again.

GTK provides various pre-made sorter implementations for common sorting
operations. :obj:`~gi.repository.Gtk.ColumnView` has built-in support for sorting lists
via the :obj:`~gi.repository.Gtk.ColumnViewColumn.props.sorter` property, where the user can
change the sorting by clicking on list headers.

Of course, in particular for large lists, it is also possible to subclass
``GtkSorter`` and provide one's own sorter.





Methods
-------

.. rst-class:: interim-class

.. class:: Sorter
   :no-index:


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

      Notifies all users of the sorter that it has changed.

      This emits the :obj:`~gi.repository.Gtk.Sorter.signals.changed` signal. Users
      of the sorter should then update the sort order via
      :obj:`~gi.repository.Gtk.Sorter.compare`.

      Depending on the ``change`` parameter, it may be possible to
      update the sort order without a full resorting. Refer to
      the :obj:`~gi.repository.Gtk.SorterChange` documentation for details.

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







      :param change: How the sorter changed





   .. method:: compare(item1: ~gi.repository.GObject.Object, item2: ~gi.repository.GObject.Object) -> ~gi.repository.Gtk.Ordering

      Compares two given items according to the sort order implemented
      by the sorter.

      Sorters implement a partial order:

      * It is reflexive, ie a = a
      * It is antisymmetric, ie if a < b and b < a, then a = b
      * It is transitive, ie given any 3 items with a ≤ b and b ≤ c,
        then a ≤ c

      The sorter may signal it conforms to additional constraints
      via the return value of :obj:`~gi.repository.Gtk.Sorter.get_order`.







      :param item1: first item to compare


      :param item2: second item to compare





   .. method:: get_order() -> ~gi.repository.Gtk.SorterOrder

      Gets the order that ``self`` conforms to.

      See :obj:`~gi.repository.Gtk.SorterOrder` for details
      of the possible return values.

      This function is intended to allow optimizations.
















Signals
-------

.. rst-class:: interim-class

.. class:: Sorter.signals
   :no-index:
   

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

      Emitted whenever the sorter changed.

      Users of the sorter should then update the sort order
      again via :func:`~gi.repository.Gtk.Sorter.compare`.

      :obj:`~gi.repository.Gtk.SortListModel` handles this signal automatically.

      Depending on the ``change`` parameter, it may be possible to update
      the sort order without a full resorting. Refer to the
      :obj:`~gi.repository.Gtk.SorterChange` documentation for details.







      :param change: how the sorter changed









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

.. rst-class:: interim-class

.. class:: Sorter
   :no-index:
   

   .. method:: do_compare(item1: ~gi.repository.GObject.Object | None = None, item2: ~gi.repository.GObject.Object | None = None) -> ~gi.repository.Gtk.Ordering

      Compares two given items according to the sort order implemented
      by the sorter.

      Sorters implement a partial order:

      * It is reflexive, ie a = a
      * It is antisymmetric, ie if a < b and b < a, then a = b
      * It is transitive, ie given any 3 items with a ≤ b and b ≤ c,
        then a ≤ c

      The sorter may signal it conforms to additional constraints
      via the return value of :obj:`~gi.repository.Gtk.Sorter.get_order`.







      :param item1: first item to compare


      :param item2: second item to compare





   .. method:: do_get_order() -> ~gi.repository.Gtk.SorterOrder

      Gets the order that ``self`` conforms to.

      See :obj:`~gi.repository.Gtk.SorterOrder` for details
      of the possible return values.

      This function is intended to allow optimizations.














Fields
------

.. rst-class:: interim-class

.. class:: Sorter
   :no-index:
   

   .. attribute:: parent_instance