Skip to content

Gtk.Sorter

class — extends GObject.Object

Describes sorting criteria for a SortListModel.

Its primary user is SortListModel

The model will use a sorter to determine the order in which its items should appear by calling Sorter.compare for pairs of items.

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

GTK provides various pre-made sorter implementations for common sorting operations. ColumnView has built-in support for sorting lists via the ColumnViewColumn.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

changed

def changed(self, change: SorterChange | int) -> None

Notifies all users of the sorter that it has changed.

This emits the Sorter.changed signal. Users of the sorter should then update the sort order via Sorter.compare.

Depending on the change parameter, it may be possible to update the sort order without a full resorting. Refer to the SorterChange documentation for details.

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

Parameters:

  • change — How the sorter changed

compare

def compare(self, item1: GObject.Object, item2: GObject.Object) -> 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 Sorter.get_order.

Parameters:

  • item1 — first item to compare
  • item2 — second item to compare

get_order

def get_order(self) -> SorterOrder

Gets the order that self conforms to.

See SorterOrder for details of the possible return values.

This function is intended to allow optimizations.

Virtual methods

do_compare

def do_compare(self, item1: GObject.Object | None = ..., item2: GObject.Object | None = ...) -> 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 Sorter.get_order.

Parameters:

  • item1 — first item to compare
  • item2 — second item to compare

do_get_order

def do_get_order(self) -> SorterOrder

Gets the order that self conforms to.

See SorterOrder for details of the possible return values.

This function is intended to allow optimizations.

Signals

changed

def on_changed(self, change: SorterChange) -> None: ...

Emitted whenever the sorter changed.

Users of the sorter should then update the sort order again via Sorter.compare.

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 SorterChange documentation for details.