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 used by the model.

For simple use, use .set-events(). For more elaborate widgets for each list entry use one or more methods .set-setup(), .set-bind(), .set-unbind(), and .set-teardown(). Do not call .set-events() in that case.

Most events are defined by Gnome::Gtk4::SignalListItemFactory. The info can be looked up here or here.

The selection-changed event is defined in Gnome::Gtk4::R-SelectionModel. Note that while GnomeTools::Gtk::DropDown also uses GnomeTools::Gtk::R-ListModel role, the selection mechanism is a bit different. Please look for .set-selection-changed() in nomeTools::Gtk::DropDown to get the proper info.

Methods

append

method append ( *@items )

• @items; item strings. The bind and unbind callback routines will receive these strings to properly fill in the data or remove it.

find

Find the position of the list item in the list.

method find ( Str $item --> UInt )

• $item; the string to look for.

Returns the position of the string if found.

get-n-items

Get the number of items in the list.

method get-n-items ( --> UInt )

Returns the number of items in the list.

get-selection

Get the list of currently selected items.

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

• $rows; When set, return the positions in the list, otherwise return a list of item strings.

Returns the list of currently selected items.

get-string

Get the list item string given the position in the list.

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

• $pos; the position in the list

Returns the item string given the position in the list.

remove

Remove the item given its position in the list.

method remove ( *@pos )

• @pos; a list of positions to be removed

set-bind

After the return of a widget, created by the callback when the setup event fired, another event arrives, the bind event. Here the widget is bound to the data and any other non permanent widgets created and registering signal handlers for data to be displayed is created.

After this, the list item 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 set-bind ( Any:D $object, Str:D $method, *%options )

• $object; the object where the callback method is defined.

• $method; the method called when the bind event arrives.

• %options; any named arguments are passed to the callback method.

The callback method must have the following API;

method $object."$method" ( Gnome::Gtk4::Widget $widget, Str $item, *%options )

• $widget; the widget created before.

• $item; the list item provided when new items are added.

• %options. Any named arguments provided to .set-bind().

set-events

Register a series of events defined in the Gnome::Gtk4::SignalListItemFactory class. The purpose of this method is to register a series of events at once without the need of user methods to capture the events. The entries in the list are populated with Gnome::Gtk4::Labels. The text in the labels are set with user text from .append().

method set-events ( )

set-selection

Make selection changes.

method set-selection ( *@pos )

• @pos; one or more positions in the list to select. If the model uses single selection, only one item is selected.

set-selection-changed

The selection-changed event is emitted when the selection state of some of the items in the model changes.

method set-selection-changed ( Any:D $object, Str:D $method, *%options )

• $object; the object where the callback method is defined.

• $method; the method called when the setup event arrives.

• %options; any named arguments are passed to the callback method.

The user method must have the following API;

method $object."$method" ( $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.

set-setup

When new items are appended using .append() or .splice() the setup event is emitted to set up permanent widgets in a Gnome::Gtk4::ListItem. The meaning of permanent is that it does not change whatever is given as list data. In this role, however, the list item is kept hidden and controlled. The only thing the user must do, when called, is; create and return a widget without any content that is depending on the data you give. That part comes when the bind event arrives.

method set-setup ( Any:D $object, Str:D $method, *%options )

• $object; the object where the callback method is defined.

• $method; the method called when the setup event arrives.

• %options; any named arguments are passed to the callback method.

The callback method must have the following API;

method $object."$method" ( *%options --> Gnome::Gtk4::Widget )

• %options. Any named arguments provided to .set-setup().

The callback routine must return the top leve widget.

set-teardown

The teardown 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 set-teardown ( Any:D $object, Str:D $method, *%options )

• $object; the object where the callback method is defined.

• $method; the method called when the bind event arrives.

• %options; any named arguments are passed to the callback method.

The callback method must have the following API;

method $object."$method" ( Gnome::Gtk4::Widget $widget, *%options )

• $widget; the widget created before.

• %options. Any named arguments provided to .set-bind().

set-unbind

This .set-unbind() method must be called if in the bind phase any extra non-permanent widgets are added. The unbind 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 set-unbind ( Any:D $object, Str:D $method, *%options )

• $object; the object where the callback method is defined.

• $method; the method called when the bind event arrives.

• %options; any named arguments are passed to the callback method.

The callback method must have the following API;

method $object."$method" ( Gnome::Gtk4::Widget $widget, Str $item, *%options )

• $widget; the widget created before.

• $item; the list item provided when new items are added.

• %options. Any named arguments provided to .set-bind().

splice

Remove list items at given position in the list. Then insert new items at that position.

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

• $pos; position in the list

• $nremove; number of list items to remove

• @str-array; list items to insert at the position