Description

Gnome::Gtk4::ColumnView presents a large dynamic list of items using multiple columns with headers.

Gnome::Gtk4::ColumnView uses the factories of its columns to generate a cell widget for each column, for each visible item and displays them together as the row for this item.

The show-row-separators and show-column-separators properties offer a simple way to display separators between the rows or columns.

Gnome::Gtk4::ColumnView allows the user to select items according to the selection characteristics of the model. For models that allow multiple selected items, it is possible to turn on *rubberband selection*, using enable-rubberband.

The column view supports sorting that can be customized by the user by clicking on column headers. To set this up, the Gnome::Gtk4::Sorter returned by .get-sorter() must be attached to a sort model for the data that the view is showing, and the columns must have sorters attached to them by calling .set-sorter() in class Gnome::Gtk4::ColumnViewColumn. The initial sort order can be set with .sort-by-column().

The column view also supports interactive resizing and reordering of columns, via Drag-and-Drop of the column headers. This can be enabled or disabled with the reorderable and resizable defined in Gnome::Gtk4::ColumnViewColumn properties.

To learn more about the list widget framework, see the [overview](section-list-widget.html).

CSS nodes

Gnome::Gtk4::ColumnView uses a single CSS node named columnview. It may carry the .column-separators style class, when show-column-separators property is set. Header widgets appear below a node with name header. The rows are contained in a Gnome::Gtk4::ListView widget, so there is a listview node with the same structure as for a standalone Gnome::Gtk4::ListView widget. If show-row-separators is set, it will be passed on to the list view, causing its CSS node to carry the .separators style class. For rubberband selection, a node with name rubberband is used.

The main columnview node may also carry style classes to select the style of [list presentation](section-list-widget.html#list-styles): .rich-list, .navigation-sidebar or .data-table.

Accessibility

Gnome::Gtk4::ColumnView uses the GTK_ACCESSIBLE_ROLE_TREE_GRID role, header title widgets are using the GTK_ACCESSIBLE_ROLE_COLUMN_HEADER role. The row widgets are using the GTK_ACCESSIBLE_ROLE_ROW role, and individual cells are using the GTK_ACCESSIBLE_ROLE_GRID_CELL role

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! )

new-columnview

Creates a new Gnome::Gtk4::ColumnView.

You most likely want to call .append-column() to add columns next.

method new-columnview ( N-Object() $model --> Gnome::Gtk4::ColumnView \)

• $model; (transfer ownership: full) the list model to use.

Methods

append-column

Appends the $column to the end of the columns in $self.

method append-column ( N-Object() $column )

• $column; a Gnome::Gtk4::ColumnViewColumn that hasn't been added to a Gnome::Gtk4::ColumnView yet.

get-columns

Gets the list of columns in this column view.

This list is constant over the lifetime of $self and can be used to monitor changes to the columns of $self by connecting to the items-changed signal.

method get-columns (--> N-List )

Return value; The list managing the columns.

get-enable-rubberband

Returns whether rows can be selected by dragging with the mouse.

method get-enable-rubberband (--> Bool )

Return value; True if rubberband selection is enabled.

get-header-factory

Gets the factory that's currently used to populate section headers.

method get-header-factory (--> N-Object )

Return value; The factory in use.

get-model

Gets the model that's currently used to read the items displayed.

method get-model (--> N-Object )

Return value; The model in use.

get-reorderable

Returns whether columns are reorderable.

method get-reorderable (--> Bool )

Return value; True if columns are reorderable.

get-row-factory

Gets the factory set via .set-row-factory().

method get-row-factory (--> N-Object )

Return value; The factory.

get-show-column-separators

Returns whether the list should show separators between columns.

method get-show-column-separators (--> Bool )

Return value; True if the list shows column separators.

get-show-row-separators

Returns whether the list should show separators between rows.

method get-show-row-separators (--> Bool )

Return value; True if the list shows separators.

get-single-click-activate

Returns whether rows will be activated on single click and selected on hover.

method get-single-click-activate (--> Bool )

Return value; True if rows are activated on single click.

get-sorter

Returns a special sorter that reflects the users sorting choices in the column view.

To allow users to customizable sorting by clicking on column headers, this sorter needs to be set on the sort model underneath the model that is displayed by the view.

See .set-sorter() in class Gnome::Gtk4::ColumnViewColumn for setting up per-column sorting.

Here is an example:

method get-sorter (--> N-Object )

Return value; the Gnome::Gtk4::Sorter of $self.

get-tab-behavior

Gets the behavior set for the <kbd>Tab</kbd> key.

method get-tab-behavior (--> GtkListTabBehavior )

Return value; The behavior of the <kbd>Tab</kbd> key.

insert-column

Inserts a column at the given position in the columns of $self.

If $column is already a column of $self, it will be repositioned.

method insert-column ( UInt() $position, N-Object() $column )

• $position; the position to insert $column at.

• $column; the Gnome::Gtk4::ColumnViewColumn to insert.

remove-column

Removes the $column from the list of columns of $self.

method remove-column ( N-Object() $column )

• $column; a Gnome::Gtk4::ColumnViewColumn that's part of $self.

scroll-to

Scroll to the row at the given position - or cell if a column is given - and performs the actions specified in $flags.

This function works no matter if the listview is shown or focused. If it isn't, then the changes will take effect once that happens.

method scroll-to ( UInt() $pos, N-Object() $column, UInt $flags, N-Object $scroll )

• $pos; position of the item.

• $column; The column to scroll to or undefined to not scroll columns..

• $flags; actions to perform.

• $scroll; (transfer ownership: full) details of how to perform the scroll operation or undefined to scroll into view

set-enable-rubberband

Sets whether selections can be changed by dragging with the mouse.

method set-enable-rubberband ( Bool() $enable-rubberband )

• $enable-rubberband; True to enable rubberband selection.

set-header-factory

Sets the Gnome::Gtk4::ListItemFactory to use for populating the Gnome::Gtk4::ListHeader objects used in section headers.

If this factory is set to undefined, the list will not show section headers.

method set-header-factory ( N-Object() $factory )

• $factory; the factory to use.

set-model

Sets the model to use.

This must be a Gnome::Gtk4::R-SelectionModel.

method set-model ( N-Object() $model )

• $model; the model to use.

set-reorderable

Sets whether columns should be reorderable by dragging.

method set-reorderable ( Bool() $reorderable )

• $reorderable; whether columns should be reorderable.

set-row-factory

Sets the factory used for configuring rows. The factory must be for configuring Gnome::Gtk4::ColumnViewRow objects.

If this factory is not set - which is the default - then the defaults will be used.

This factory is not used to set the widgets displayed in the individual cells. For that see [method $GtkColumnViewColumn.set_factory] and GtkColumnViewCell.

method set-row-factory ( N-Object() $factory )

• $factory; The row factory.

set-show-column-separators

Sets whether the list should show separators between columns.

method set-show-column-separators ( Bool() $show-column-separators )

• $show-column-separators; True to show column separators.

set-show-row-separators

Sets whether the list should show separators between rows.

method set-show-row-separators ( Bool() $show-row-separators )

• $show-row-separators; True to show row separators.

set-single-click-activate

Sets whether rows should be activated on single click and selected on hover.

method set-single-click-activate ( Bool() $single-click-activate )

• $single-click-activate; True to activate items on single click.

set-tab-behavior

Sets the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys.

method set-tab-behavior ( GtkListTabBehavior $tab-behavior )

• $tab-behavior; The desired tab behavior.

sort-by-column

Sets the sorting of the view.

This function should be used to set up the initial sorting. At runtime, users can change the sorting of a column view by clicking on the list headers.

This call only has an effect if the sorter returned by .get-sorter() is set on a sort model, and .set-sorter() in class Gnome::Gtk4::ColumnViewColumn has been called on $column to associate a sorter with the column.

If $column is undefined, the view will be unsorted.

method sort-by-column ( N-Object() $column, GtkSortType $direction )

• $column; the Gnome::Gtk4::ColumnViewColumn to sort by.

• $direction; the direction to sort in.

Signals

activate

Emitted when a row has been activated by the user, usually via activating the GtkListBase|list.activate-item action.

This allows for a convenient way to handle activation in a columnview. See .set-activatable() in class Gnome::Gtk4::ListItem for details on how to use this signal.

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

• $position; position of item to activate.

• $_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::ColumnView 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.