Gnome::Gtk3::ListBox

A list container

Description

A Gnome::Gtk3::ListBox is a vertical container that contains Gnome::Gtk3::ListBoxRow children. These rows can be dynamically sorted and filtered, and headers can be added dynamically depending on the row content. It also allows keyboard and mouse navigation and selection like a typical list.

Using Gnome::Gtk3::ListBox is often an alternative to Gnome::Gtk3::TreeView, especially when the list contents has a more complicated layout than what is allowed by a Gnome::Gtk3::CellRenderer, or when the contents is interactive (i.e. has a button in it).

Although a Gnome::Gtk3::ListBox must have only Gnome::Gtk3::ListBoxRow children you can add any kind of widget to it via gtk_container_add(), and a Gnome::Gtk3::ListBoxRow widget will automatically be inserted between the list and the widget.

Gnome::Gtk3::ListBoxRows can be marked as activatable or selectable. If a row is activatable, sig row-activated will be emitted for it when the user tries to activate it. If it is selectable, the row will be marked as selected when the user tries to select it.

The Gnome::Gtk3::ListBox widget was added in GTK+ 3.10.

Css Nodes

Gnome::Gtk3::ListBox uses a single CSS node with name list. Gnome::Gtk3::ListBoxRow uses a single CSS node with name row. The row nodes get the .activatable style class added when appropriate.

Synopsis

Declaration

unit class Gnome::Gtk3::ListBox;
also is Gnome::Gtk3::Container;
also does Gnome::Gtk3::Buildable;

Example

Create a ListBox with one row. This row is a grid holding a CheckBox and Label.

my Gnome::Gtk3::ListBox $lb .= new;

# The widgets
my Gnome::Gtk3::CheckButton $check .= new(:label('bold'));
my Gnome::Gtk3::Label $label .= new(:text('Turn on bold font'));

# Add the widgets to the Grid
my Gnome::Gtk3::Grid $grid .= new;
$grid.gtk-grid-attach( $check, 0, 0, 1, 1);
$grid.gtk-grid-attach( $label, 1, 0, 1, 1);

# Add the Grid to the ListBox
$lb.add($grid);

To check its values one can register signals on each important widget (e.g. $check in this case) or read the listbox entries.

my Int $index = 0;
while my $nw = $lb.get-row-at-index($index) {
  my Gnome::Gtk3::ListBoxRow $row .= new(:widget($nw));
  my Gnome::Gtk3::Grid $grid .= new(:widget($row.get-child));
  my Gnome::Gtk3::CheckButton $check .=
     new(:widget($grid.get-child-at( 0, 0)));
  if $check.get-active {
    ...
  }
}

Every check in this list looks the same, so it is useful to set a name on each of the check widgets. This name can then be retrieved within the handler or the code example above. If it is simple, like above, on can use the label text instead.

Methods

new

Create a new plain object.

multi method new ( )

Create an object using a native object from elsewhere. See also Gnome::GObject::Object.

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

Create an object using a native object from a builder. See also Gnome::GObject::Object.

multi method new ( Str :$build-id! )

[gtk_] list_box_prepend

Prepend a widget to the list. If a sort function is set, the widget will actually be inserted at the calculated position and this function has the same effect of gtk_container_add().

Since: 3.10

method gtk_list_box_prepend ( N-GObject $child )

N-GObject $child; the Gnome::Gtk3::Widget to add

[gtk_] list_box_insert

Insert the child into the box at position. If a sort function is set, the widget will actually be inserted at the calculated position and this function has the same effect of gtk_container_add().

If position is -1, or larger than the total number of items in the box, then the child will be appended to the end.

Since: 3.10

method gtk_list_box_insert ( N-GObject $child, Int $position )

N-GObject $child; the Gnome::Gtk3::Widget to add
Int $position; the position to insert child in

[[gtk_] list_box_] get_selected_row

Gets the selected row.

Note that the box may allow multiple selection, in which case you should use gtk_list_box_selected_foreach() to find all selected rows.

Returns: (transfer none): the selected row as a native ListBoxRow

Since: 3.10

method gtk_list_box_get_selected_row ( --> N-GObject  )

[[gtk_] list_box_] get_row_at_index

Gets the n-th child in the list (not counting headers). If _index is negative or larger than the number of items in the list, Any is returned.

Returns: a native ListBoxRow

Since: 3.10

method gtk_list_box_get_row_at_index ( Int $index --> N-GObject  )

Int $index; the index of the row

[[gtk_] list_box_] get_row_at_y

Gets the row at the y position.

Returns: the row or Any in case no row exists for the given y coordinate.

Since: 3.10

method gtk_list_box_get_row_at_y ( Int $y --> N-GObject  )

Int $y; position

[[gtk_] list_box_] select_row

Make row the currently selected row.

Since: 3.10

method gtk_list_box_select_row ( GtkListBoxRow $row )

GtkListBoxRow $row; (allow-none): The row to select or Any

[[gtk_] list_box_] set_placeholder

Sets the placeholder widget that is shown in the list when it doesn’t display any visible children.

Since: 3.10

method gtk_list_box_set_placeholder ( N-GObject $placeholder )

N-GObject $placeholder; (allow-none): a Gnome::Gtk3::Widget or Any

[[gtk_] list_box_] set_adjustment

Sets the adjustment (if any) that the widget uses to for vertical scrolling. For instance, this is used to get the page size for PageUp/Down key handling.

In the normal case when the box is packed inside a Gnome::Gtk3::ScrolledWindow the adjustment from that will be picked up automatically, so there is no need to manually do that.

Since: 3.10

method gtk_list_box_set_adjustment ( N-GObject $adjustment )

N-GObject $adjustment; (allow-none): the adjustment, or Any

[[gtk_] list_box_] get_adjustment

Gets the adjustment (if any) that the widget uses to for vertical scrolling.

Returns: (transfer none): the adjustment

Since: 3.10

method gtk_list_box_get_adjustment ( --> N-GObject  )

[[gtk_] list_box_] selected_foreach

Calls a function for each selected child. Note that the selection cannot be modified from within this function.

Since: 3.14

method gtk_list_box_selected_foreach (
  $callback-object, Str $callback_name, *%user-options
)

$callback-object; Object wherein the callback method is declared
Str $callback-name; Name of the callback method
%user-options; named arguments which will be provided to the callback

The callback method signature is

method f (
  Gnome::Gtk3::ListBox $listbox, Gnome::Gtk3::GtkListRow $row,
  *%user-options
)

[[gtk_] list_box_] get_selected_rows

Creates a list of all selected children.

Returns: (element-type Gnome::Gtk3::ListBoxRow) (transfer container): A GList containing the Gnome::Gtk3::Widget for each selected child. Free with g_list_free() when done.

Since: 3.14

method gtk_list_box_get_selected_rows ( --> N-GList  )

[[gtk_] list_box_] unselect_row

Unselects a single row of box, if the selection mode allows it.

Since: 3.14

method gtk_list_box_unselect_row ( GtkListBoxRow $row )

GtkListBoxRow $row; the row to unselected

[[gtk_] list_box_] select_all

Select all children of box, if the selection mode allows it.

Since: 3.14

method gtk_list_box_select_all ( )

[[gtk_] list_box_] unselect_all

Unselect all children of box, if the selection mode allows it.

Since: 3.14

method gtk_list_box_unselect_all ( )

[[gtk_] list_box_] set_selection_mode

Sets how selection works in the listbox. See Gnome::Gtk3::SelectionMode for details.

Since: 3.10

method gtk_list_box_set_selection_mode ( GtkSelectionMode $mode )

GtkSelectionMode $mode; The Gnome::Gtk3::SelectionMode

[[gtk_] list_box_] get_selection_mode

Gets the selection mode of the listbox.

Returns: a Gnome::Gtk3::SelectionMode

Since: 3.10

method gtk_list_box_get_selection_mode ( --> GtkSelectionMode  )

[[gtk_] list_box_] invalidate_filter

Update the filtering for all rows. Call this when result of the filter function on the box is changed due to an external factor. For instance, this would be used if the filter function just looked for a specific search string and the entry with the search string has changed.

Since: 3.10

method gtk_list_box_invalidate_filter ( )

[[gtk_] list_box_] invalidate_sort

Update the sorting for all rows. Call this when result of the sort function on the box is changed due to an external factor.

Since: 3.10

method gtk_list_box_invalidate_sort ( )

[[gtk_] list_box_] invalidate_headers

Update the separators for all rows. Call this when result of the header function on the box is changed due to an external factor.

Since: 3.10

method gtk_list_box_invalidate_headers ( )

[[gtk_] list_box_] set_activate_on_single_click

If single is 1, rows will be activated when you click on them, otherwise you need to double-click.

Since: 3.10

method gtk_list_box_set_activate_on_single_click ( Int $single )

Int $single; a boolean

[[gtk_] list_box_] get_activate_on_single_click

Returns whether rows activate on single clicks.

Returns: 1 if rows are activated on single click, 0 otherwise

Since: 3.10

method gtk_list_box_get_activate_on_single_click ( --> Int  )

[[gtk_] list_box_] drag_unhighlight_row

If a row has previously been highlighted via gtk_list_box_drag_highlight_row() it will have the highlight removed.

Since: 3.10

method gtk_list_box_drag_unhighlight_row ( )

[[gtk_] list_box_] drag_highlight_row

This is a helper function for implementing DnD onto a Gnome::Gtk3::ListBox. The passed in row will be highlighted via gtk_drag_highlight(), and any previously highlighted row will be unhighlighted.

The row will also be unhighlighted when the widget gets a drag leave event.

Since: 3.10

method gtk_list_box_drag_highlight_row ( GtkListBoxRow $row )

GtkListBoxRow $row; a Gnome::Gtk3::ListBoxRow

[gtk_] list_box_new

Creates a new Gnome::Gtk3::ListBox container.

Returns: a new Gnome::Gtk3::ListBox

Since: 3.10

method gtk_list_box_new ( --> N-GObject  )

Signals

There are two ways to connect to a signal. The first option you have is to use register-signal() from Gnome::GObject::Object. The second option is to use g_signal_connect_object() directly from Gnome::GObject::Signal.

First method

The positional arguments of the signal handler are all obligatory as well as their types. The named attributes :$widget and user data are optional.

# handler method
method mouse-event ( N-GdkEvent $event, :$widget ) { ... }

# connect a signal on window object
my Gnome::Gtk3::Window $w .= new( ... );
$w.register-signal( self, 'mouse-event', 'button-press-event');

Second method

my Gnome::Gtk3::Window $w .= new( ... );
my Callable $handler = sub (
  N-GObject $native, N-GdkEvent $event, OpaquePointer $data
) {
  ...
}

$w.connect-object( 'button-press-event', $handler);

Also here, the types of positional arguments in the signal handler are important. This is because both methods register-signal() and g_signal_connect_object() are using the signatures of the handler routines to setup the native call interface.

Supported signals

row-selected

The row-selected signal is emitted when a new row is selected, or (with a Any row) when the selection is cleared.

When the box is using GTK_SELECTION_MULTIPLE, this signal will not give you the full picture of selection changes, and you should use the selected-rows-changed signal instead.

Since: 3.10

method handler (
  N-GObject $row,
  Int :$_handler_id,
  Gnome::GObject::Object :_widget($box),
  *%user-options
);

$box; the Gnome::Gtk3::ListBox on which the signal is emitted
$row; the selected row, a native ListBoxRow

selected-rows-changed

The selected-rows-changed signal is emitted when the set of selected rows changes.

Since: 3.14

method handler (
  Int :$_handler_id,
  Gnome::GObject::Object :_widget($box),
  *%user-options
);

$box; the Gnome::Gtk3::ListBox on wich the signal is emitted

select-all

The select-all signal is a [keybinding signal][Gnome::Gtk3::BindingSignal] which gets emitted to select all children of the box, if the selection mode permits it.

The default bindings for this signal is Ctrl-a.

Since: 3.14

method handler (
  Int :$_handler_id,
  Gnome::GObject::Object :_widget($box),
  *%user-options
);

$box; the Gnome::Gtk3::ListBox on which the signal is emitted

unselect-all

The unselect-all signal is a keybinding signal which gets emitted to unselect all children of the box, if the selection mode permits it.

The default bindings for this signal is Ctrl-Shift-a.

Since: 3.14

method handler (
  Int :$_handler_id,
  Gnome::GObject::Object :_widget($box),
  *%user-options
);

$box; the Gnome::Gtk3::ListBox on which the signal is emitted

row-activated

The row-activated signal is emitted when a row has been activated by the user.

Since: 3.10

method handler (
  N-GObject $row,
  Int :$_handler_id,
  Gnome::GObject::Object :_widget($box),
  *%user-options
);

$box; the Gnome::Gtk3::ListBox on which the signal is emitted
$row; the activated row, a native ListBoxRow

activate-cursor-row

method handler (
  Int :$_handler_id,
  Gnome::GObject::Object :_widget($listbox),
  *%user-options
);

$listbox; the Gnome::Gtk3::ListBox on which the signal is emitted

toggle-cursor-row

method handler (
  Int :$_handler_id,
  Gnome::GObject::Object :_widget($listbox),
  *%user-options
);

$listbox; object receiving the signal

move-cursor

method handler (
  GtkMovementStep $arg1,
  Int $arg2,
  Int :$_handler_id,
  Gnome::GObject::Object :_widget($listbox),
  *%user-options
);

$listbox; the Gnome::Gtk3::ListBox on which the signal is emitted
$arg1; a GtkMovementStep
$arg2; ?

activate

method handler (
  Int :$_handler_id,
  Gnome::GObject::Object :_widget($listbox),
  *%user-options
);

$listbox;

Gnome::Gtk3::ListBox

Description

Css Nodes

See Also

Synopsis

Declaration

Example

Methods

new

[gtk_] list_box_prepend

[gtk_] list_box_insert

[[gtk_] list_box_] get_selected_row

[[gtk_] list_box_] get_row_at_index

[[gtk_] list_box_] get_row_at_y

[[gtk_] list_box_] select_row

[[gtk_] list_box_] set_placeholder

[[gtk_] list_box_] set_adjustment

[[gtk_] list_box_] get_adjustment

[[gtk_] list_box_] selected_foreach

[[gtk_] list_box_] get_selected_rows

[[gtk_] list_box_] unselect_row

[[gtk_] list_box_] select_all

[[gtk_] list_box_] unselect_all

[[gtk_] list_box_] set_selection_mode

[[gtk_] list_box_] get_selection_mode

[[gtk_] list_box_] invalidate_filter

[[gtk_] list_box_] invalidate_sort

[[gtk_] list_box_] invalidate_headers

[[gtk_] list_box_] set_activate_on_single_click

[[gtk_] list_box_] get_activate_on_single_click

[[gtk_] list_box_] drag_unhighlight_row

[[gtk_] list_box_] drag_highlight_row

[gtk_] list_box_new

Signals

First method

Second method

Supported signals

row-selected

selected-rows-changed

select-all

unselect-all

row-activated

activate-cursor-row

toggle-cursor-row

move-cursor

activate