Description

Gnome::Gtk4::Sorter is an object to describe sorting criteria.

Its primary user is Gnome::Gtk4::SortListModel

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

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

GTK provides various pre-made sorter implementations for common sorting operations. Gnome::Gtk4::ColumnView has built-in support for sorting lists via the sorter defined in Gnome::Gtk4::ColumnViewColumn 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 Gnome::Gtk4::Sorter and provide one's own sorter.

Class initialization

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

Methods

changed

Notifies all users of the sorter that it has changed.

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

Depending on the $change parameter, it may be possible to update the sort order without a full resorting. Refer to the enumeration SorterChange from Gnome::Gtk4::T-sorter documentation for details.

This function is intended for implementers of Gnome::Gtk4::Sorter subclasses and should not be called from other functions.

method changed ( GtkSorterChange $change )

$change; How the sorter changed.

compare

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 .get-order().

method compare ( gpointer $item1, gpointer $item2 --> GtkOrdering )

$item1; first item to compare.
$item2; second item to compare.

Return value; GTK_ORDERING_EQUAL if $item1 == $item2, GTK_ORDERING_SMALLER if $item1 < $item2, GTK_ORDERING_LARGER if $item1 > $item2.

get-order

Gets the order that $self conforms to.

See enumeration SorterOrder from Gnome::Gtk4::T-sorter for details of the possible return values.

This function is intended to allow optimizations.

method get-order (--> GtkSorterOrder )

Return value; The order.

Signals

changed

Emitted whenever the sorter changed.

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

Gnome::Gtk4::SortListModel handles this signal automatically.

method handler (
   $change,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Sorter :$_widget,
  *C<user>-options
)

$change; how the sorter changed.
$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Sorter object.
$_widget; The object which registered the signal. User code may have left the object going out of scope.
user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.