ZListView

• 

  list view

• 

  in focused state

• 

  in disabled state

• 

  with decorated item

A list view allows the user to select an item from a list. It supports scrolling if the amount of items does not fit into its geometry.

The items in the list view can come either from a internally managed model or from a externally managed QAbstractItemModel derived Qt item model.

Currently ZListView does not support selecting multiple items.

When used with a model the list view displays the DisplayRole. Additionally it supports a (possibly colored) decoration on the left side of the item text. This allows adding additional information to the displayed options. To keep alignment of the items it is recommended to keep the width of the decoration plus the amount of space after the decoration(Tui::LeftDecorationSpaceRole) consistent over all items. The decoration is configured using the Qt item roles Tui::LeftDecorationRole for the text, Tui::LeftDecorationFgRole and Tui::LeftDecorationBgRole (both of type Tui::ZColor) for overriding the color of the decoration, and Tui::LeftDecorationSpaceRole (a number) for additional uncolored cells after the decoration.

Example

Using internal item storage:

Tui::ZListView *listview = new Tui::ZListView(dialog);
listview->setItems({"item1", "item2", "item3"});
listview->setCurrentIndex(listview->model()->index(1, 0));

listview->setMinimumSize(10, 5); // currently required
layout->addWidget(listview);

Using items from a external QAbstractItemModel:

std::unique_ptr<QAbstractItemModel> model;
model = std::make_unique<QStringListModel>(QStringList{"item1", "item2", "item3"});
Tui::ZListView *listview = new Tui::ZListView(dialog);
listview->setModel(model.get());
listview->setCurrentIndex(model->index(1, 0));

listview->setMinimumSize(10, 5); // currently required
layout->addWidget(listview);

Keyboard Usage

Key	Result
↑	Move selection to previous item (does not cycle to bottom)
↓	Move selection to next item (does not cycle to top)
Home	Select first item
End	Select last item
Page Up	Select item one page up
Page Down	Select item one page down
Enter	emit enterPressed(int selected) signal
(any letter)	Search next item beginning with the typed letter

Behavior

List views by default accept focus and have a expanding vertical and horizontal layout policy. The size request of a list view is currently empty(i.e. to use in layouts use of setMinimumSize(int w, int h) is required).

Palette

Palette Color	Usage
dataview.fg, dataview.bg	Body of the list view (active, unfocused)
dataview.selected.fg, dataview.selected.bg	selected items in list (active, unfocused)
dataview.selected.focused.fg, dataview.selected.focused.bg	selected items in list (active, focused)
dataview.disabled.fg, dataview.disabled.bg	Body of the list view (disabled)
dataview.disabled.selected.fg, dataview.disabled.selected.bg	selected items in list (disabled)

ZListView

class Tui::ZListView : public Tui::ZWidget

A list view widget.

Enums

enum ScrollHint

enumerator EnsureVisible

Assure that the reference item is visible.

enumerator PositionAtTop

Assure that the reference item is at the top of the visible area.

enumerator PositionAtBottom

Assure that the reference item is at the bottom of the visible area.

enumerator PositionAtCenter

Assure that the reference item is at the center of the visible area.

Functions

void setItems(const QStringList &newItems)

Set the items to display and use the internal model.

If an external model was in use detaches from it and switches to the internal model.

QStringList items() const

Returns a list of the contents (Qt::DisplayRole) for all items in the list view’s current model.

QString currentItem() const

Returns the contents (Qt::DisplayRole) of the current item or an empty string if there is no current item.

void setModel(QAbstractItemModel *model)

Set a new model for the list view.

If the model is changed, this detaches current model and attaches to the new model.

QAbstractItemModel *model() const

Returns the currently used model.

This can be either the internal model or a application-set model.

void setCurrentIndex(QModelIndex index)

QModelIndex currentIndex() const

The current selection as QModelIndex.

QItemSelectionModel *selectionModel() const

Returns the current selection model.

void scrollTo(const QModelIndex &index, Tui::ZListView::ScrollHint hint = EnsureVisible)

Scrolls the list view so that the item at index is visible.

The list view will try to scroll according to scrollHint.

Signals

void enterPressed(int selected)

This signal is emitted when the user presses the Enter key with the index of the currently selected item as selected.