GnomeTools::Gtk::R-ListModel

Description

Role to be used for classes such as GnomeTools::Gtk::ListView. Its purpose is to register and process events. The role is also used to add, find and remove items from the list in the model.

When an event fires, user methods are called when they are defined. The user must provide an object where these methods are defined. The call to be used is .set-events() defined in the classes using this role.

Selection type events.

The selection-changed event is emitted when the selection state of some of the items in the model changes. Note that this signal does not specify the new selection state of the items, they need to be queried manually. It is also not necessary for a model to change the selection state of any of the items in the selection model, though it would be rather useless to emit such a signal.

The user method must be named selection-changed and its API must be

method selection-changed ( UInt $position, @selections, *%options )

$position is the position of the last clicked selection
@selections is the selection of items used to add items to the list.
%options. Any named arguments .new() are given to the method.

Signal factory type events.

Method setup-list-item; Handles the setup event. The event is emitted to set up permanent things on the Gnome::Gtk4::ListItem. However, the list item is kept under the hood of this class. So, this means the called routine only needs to create and return the widget used in the row. Any named arguments *%options given to .new() are given to the method.

method setup-list-item ( *%options --> Gnome::Gtk4::Widget )

Method bind-list-item; Handles the bind event. The event is emitted to bind the widgets created by .setup-list-item() to their values and, optionally, add entry specific widgets to the given widget. Signals are connected to listen to changes - both to changes in the item to update the widgets or to changes in the widgets to update the item. After this signal has been called, the listitem may be shown in a list widget. The $item is the string inserted in the list using e.g. .append(). Any named arguments in *%options given to .new() are given to the method.

method bind-list-item ( Gnome::Gtk4::Widget $widget, Str $item, *%options )

Method unbind-list-item; Handles the unbind event. The event is emitted to undo everything done when binding. Usually this means disconnecting signal handlers or removing non-permanent widgets. Once this signal has been called, the listitem will no longer be used in a list widget. The bind and unbind events may be emitted multiple times again to bind the listitem for use with new items. By reusing listitems, potentially costly setup can be avoided. However, it means code needs to make sure to properly clean up the listitem when unbinding so that no information from the previous use leaks into the next one. Any named arguments in *%options given to .new() are given to the method.

method unbind-list-item ( Gnome::Gtk4::Widget $widget, Str $item, *%options )

Method teardown-list-item; Handles the teardown event. The event is emitted to undo the effects of the setup event. After this signal was emitted on a listitem, the listitem will be destroyed and not be used again. No $item is provided because the item is already destroyed. Any named arguments in *%options given to .new() are given to the method.

method teardown-list-item ( Gnome::Gtk4::Widget $widget, *%options )

get-selection

Get the current selection.

method get-selection ( Bool :$rows = False --> List )

$rows: By default a list of items are returned. When row numbers are needed set the variable to True.

append

Add an item at the end of the list

method append ( *@list-item )

@list-item: Items to append. Items must be of Str type

find

Gets the position of the item in the list. The return value can be undefined.

method find ( Str $list-item --> UInt )

$list-item: The item to find.

get-string

Gets the item at $pos of the item in the list. The return value can be undefined.

method get-string ( UInt $pos --> Str )

$pos: The item at the position.

remove

Remove the item at $pos of the item in the list.

method remove ( UInt $pos )

$pos: The item at the position.

An example to remove selected items

# Reverse rows because after each removal the row count decreases
# This causes to remove wrong rows or throwing errors like:
# (process:8769): Gtk-CRITICAL **: 18:25:48.324: gtk_string_list_splice:
# assertion 'position + n_removals <= objects_get_size (&self->items)'
# failed.
# The error shows that under the hood, splice() is used

my @selections = $listview.get-selection(:rows).reverse;
for @selections -> $selection {
  $listview.remove($selection);
}

splice

Remove and/or insert items at position given by $pos.

method splice ( UInt $pos, UInt $nremove, @str-array )

$pos: The item at the position.
$nremove: Number of rows to remove at $pos.
@str-array: The array of items to insert at $pos after removal.