QAbstractItemView Class

The QAbstractItemView class provides the basic functionality for item view classes. More…

List of all members, including inherited members

Public Types

Public Functions

Public Slots

Signals

Protected Types

Protected Functions

Protected Slots

Detailed Description

An item view shows the items of a model: a QAbstractItemModel holds the data, the view shows it and lets the user work with it, a QItemSelectionModel knows which items are selected and which one is current, and a delegate draws each item and provides the widget that it is edited with. Several views can show one model, and share one selection.

auto *view = new QTreeView;
view->setModel(model);
connect(view->selectionModel(), &QItemSelectionModel::currentChanged, this, &Window::showDetails);

This class has what views share: the model, the selection model and the delegates, how items are selected (selectionMode() and selectionBehavior()), when they are edited (editTriggers()), and the signals for what the user does with an item: pressed(), clicked(), doubleClicked() and activated(). A subclass lays the items out: it implements visualRect(), indexAt(), scrollTo() and moveCursor(), and draws the items on viewport(). QTreeView is the view of Nt Widgets that does; QListWidget and QTableWidget derive from this class too, but keep their own items and use none of what has to do with a model.

Editing

edit() opens an editor on an item, if the item is Qt::ItemIsEditable. The user starts one in the ways that editTriggers() allows: by default with a double click, with F2, or by starting to type. The delegate makes the editor and writes its value to the model when the user is done; see QStyledItemDelegate.

See also QTreeView, QTreeWidget, QStyledItemDelegate and QItemSelectionModel.

Differences from Qt

Member Type Documentation

[protected] enum QAbstractItemView::CursorAction

This enum says which way moveCursor() goes from the current item.

enum QAbstractItemView::EditTrigger

This enum says what the user does to start editing an item. The EditTriggers type is a typedef for QFlags<EditTrigger>.

typedef QAbstractItemView::EditTriggers

The EditTriggers type is a typedef for QFlags<EditTrigger>. It stores an OR combination of EditTrigger values.

enum QAbstractItemView::ScrollHint

This enum says where scrollTo() puts an item.

enum QAbstractItemView::SelectionBehavior

This enum says what is selected when the user selects an item.

enum QAbstractItemView::SelectionMode

This enum says how many items the user can select, and how.

[protected] enum QAbstractItemView::State

This enum says what the view is doing.

Member Function Documentation

[explicit] QAbstractItemView::QAbstractItemView(QWidget *parent = nullptr)

Constructs an item view with the given parent. It allows one selected item.

[override] QAbstractItemView::~QAbstractItemView()

Destroys the view. The model and a selection model that was given to it are left alone.

[signal] void QAbstractItemView::activated(const QModelIndex &index)

This signal is emitted when the user activates the item index: with a double click, or with Return or Enter while it is the current item.

bool QAbstractItemView::alternatingRowColors() const

Returns whether every other row has a different background. The default is false.

See also setAlternatingRowColors().

[slot] void QAbstractItemView::clearSelection()

Deselects all items. The current item stays.

See also selectAll().

[signal] void QAbstractItemView::clicked(const QModelIndex &index)

This signal is emitted when the left mouse button is clicked on the item index.

[slot, virtual, protected] void QAbstractItemView::closeEditor(QWidget *editor, QAbstractItemDelegate::EndEditHint hint)

Closes editor, the editor of the view, and does what hint asks for: with EditNextItem or EditPreviousItem, the item after or before the one that was edited becomes the current item and gets an editor. The value of the editor is not stored here; see commitData(). Called when the delegate emits QAbstractItemDelegate::closeEditor().

[slot, virtual, protected] void QAbstractItemView::commitData(QWidget *editor)

Stores the value of editor, the editor of the view, in the model, through the delegate. Called when the delegate emits QAbstractItemDelegate::commitData().

[slot, virtual, protected] void QAbstractItemView::currentChanged(const QModelIndex &current, const QModelIndex &previous)

Called when the current item changed from previous to current. The default stores the value of an editor that is open on another item and closes it, scrolls to the new item, and starts editing it if editTriggers() has CurrentChanged.

QModelIndex QAbstractItemView::currentIndex() const

Returns the current item: the one that the keyboard works on. It is invalid if there is none.

See also setCurrentIndex() and QItemSelectionModel::currentIndex().

[slot, virtual, protected] void QAbstractItemView::dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles = QList<int>())

Called when the model changed the data of the items from topLeft to bottomRight, for the roles in roles, or for all roles if roles is empty. The default repaints the viewport, and gives an open editor of one of these items the new value.

[signal] void QAbstractItemView::doubleClicked(const QModelIndex &index)

This signal is emitted when the item index is double-clicked.

[slot] void QAbstractItemView::edit(const QModelIndex &index)

Opens an editor on the item index, if the item is enabled and Qt::ItemIsEditable. This works whatever editTriggers() is. The editor that is open on another item is closed first, and its value stored.

See also setEditTriggers() and QAbstractItemDelegate::createEditor().

[virtual, protected] bool QAbstractItemView::edit(const QModelIndex &index, EditTrigger trigger, QEvent *event)

This is an overloaded function.

Starts editing the item index because of trigger, and returns true if the view is now editing it or the delegate handled event. The delegate sees event first, which is how a click toggles a check box. Then, if trigger is one of editTriggers(), or is AllEditTriggers as from edit(), and the item is enabled and editable, the delegate makes an editor for it. A subclass calls this from its event handlers.

EditTriggers QAbstractItemView::editTriggers() const

Returns what the user does to start editing an item: by default, a double click, F2, or typing.

See also setEditTriggers().

[virtual] QModelIndex QAbstractItemView::indexAt(const QPoint &point) const

Returns the item at the position point of the viewport, or an invalid index if there is none. The default returns an invalid index.

See also visualRect().

[virtual, protected] void QAbstractItemView::initViewItemOption(QStyleOptionViewItem *option) const

Fills option with what is the same for all items of the view: its palette, font, state and the widget. A view passes it to the delegate for each item, with the rectangle and the state of that item added.

QAbstractItemDelegate * QAbstractItemView::itemDelegate() const

Returns the delegate of the view: the one that setItemDelegate() set, or a QStyledItemDelegate of the view.

See also setItemDelegate() and itemDelegateForIndex().

QAbstractItemDelegate * QAbstractItemView::itemDelegateForColumn(int column) const

Returns the delegate that was set for the column column, or nullptr.

See also setItemDelegateForColumn().

[virtual] QAbstractItemDelegate * QAbstractItemView::itemDelegateForIndex(const QModelIndex &index) const

Returns the delegate that draws and edits the item index: the one of its row, else the one of its column, else itemDelegate().

See also setItemDelegate().

QAbstractItemDelegate * QAbstractItemView::itemDelegateForRow(int row) const

Returns the delegate that was set for the row row, or nullptr.

See also setItemDelegateForRow().

QAbstractItemModel * QAbstractItemView::model() const

Returns the model that the view shows, or nullptr.

See also setModel().

[virtual, protected] QModelIndex QAbstractItemView::moveCursor(CursorAction cursorAction, Qt::KeyboardModifiers modifiers)

Returns the item that cursorAction leads to from the current item, with the keys of modifiers held; the view makes it the current item. A subclass knows how its items are laid out and implements this. The default returns an invalid index, for no move.

[signal] void QAbstractItemView::pressed(const QModelIndex &index)

This signal is emitted when a mouse button is pressed on the item index.

[slot, virtual] void QAbstractItemView::reset()

Brings the view back to its state for a model that is new or was reset: closes the editor and lays the items out again. A subclass that keeps something about the items, such as which are expanded, forgets it here and calls this implementation.

QModelIndex QAbstractItemView::rootIndex() const

Returns the item whose children the view shows: an invalid index, for the top of the model, unless setRootIndex() set another one.

See also setRootIndex().

[slot, virtual, protected] void QAbstractItemView::rowsAboutToBeRemoved(const QModelIndex &parent, int start, int end)

Called before the rows start to end are removed from under parent. The default closes the editor if it is on one of them or on one of their descendants, without storing its value.

[slot, virtual, protected] void QAbstractItemView::rowsInserted(const QModelIndex &parent, int start, int end)

Called when the rows start to end were inserted under parent. The default repaints the viewport.

[virtual] void QAbstractItemView::scrollTo(const QModelIndex &index, ScrollHint hint = EnsureVisible)

Scrolls the view so that the item index shows, at the place that hint says. The default does nothing.

See also visualRect().

[slot] void QAbstractItemView::scrollToBottom()

Scrolls the view to its bottom.

See also scrollToTop() and scrollTo().

[slot] void QAbstractItemView::scrollToTop()

Scrolls the view to its top.

See also scrollToBottom() and scrollTo().

[slot, virtual] void QAbstractItemView::selectAll()

Selects all the items that the view shows, if the selection mode allows more than one. The default does nothing: it is the subclass that knows its items.

SelectionBehavior QAbstractItemView::selectionBehavior() const

Returns what is selected when the user selects an item: the item, its row or its column.

See also setSelectionBehavior().

[slot, virtual, protected] void QAbstractItemView::selectionChanged(const QItemSelection &selected, const QItemSelection &deselected)

Called when the selection changed: selected has the items that are selected now and were not before, and deselected those that are no longer selected. The default repaints the viewport.

SelectionMode QAbstractItemView::selectionMode() const

Returns how items are selected.

See also setSelectionMode().

[virtual, protected] void QAbstractItemView::selectionModeChanged()

Called when the selection mode changes: a subclass brings its selection in line with it. The default does nothing.

QItemSelectionModel * QAbstractItemView::selectionModel() const

Returns the selection model of the view: the one that setModel() made, or the one that setSelectionModel() was given. It is nullptr while the view has no model.

See also setSelectionModel().

void QAbstractItemView::setAlternatingRowColors(bool enable)

Sets whether every other row has the alternate base color of the palette as its background to enable.

See also alternatingRowColors().

[slot] void QAbstractItemView::setCurrentIndex(const QModelIndex &index)

Makes the item index the current item and, unless the selection mode is NoSelection, the selected one. The view scrolls to it.

See also currentIndex() and QItemSelectionModel::setCurrentIndex().

void QAbstractItemView::setEditTriggers(EditTriggers triggers)

Sets what the user does to start editing an item to triggers. With NoEditTriggers the user cannot edit; edit() still can.

See also editTriggers() and edit().

void QAbstractItemView::setItemDelegate(QAbstractItemDelegate *delegate)

Sets the delegate that draws and edits the items of the view to delegate. The view does not own it, so several views can share one. A nullptr gives the view its own QStyledItemDelegate again.

See also itemDelegate() and setItemDelegateForColumn().

void QAbstractItemView::setItemDelegateForColumn(int column, QAbstractItemDelegate *delegate)

Sets the delegate for the items of the column column to delegate, or takes it away if delegate is nullptr: a column of dates or of ratings is drawn and edited in its own way.

See also itemDelegateForColumn() and setItemDelegateForRow().

void QAbstractItemView::setItemDelegateForRow(int row, QAbstractItemDelegate *delegate)

Sets the delegate for the items of the row row to delegate, or takes it away if delegate is nullptr. A delegate for a row goes before one for a column.

See also itemDelegateForRow() and setItemDelegateForColumn().

[virtual] void QAbstractItemView::setModel(QAbstractItemModel *model)

Sets the model that the view shows to model, and gives the view a new selection model for it. The view does not own the model: several views can show one. A nullptr leaves the view without items.

See also model() and setSelectionModel().

[slot, virtual] void QAbstractItemView::setRootIndex(const QModelIndex &index)

Makes the item index the root of the view: the view shows its children as its top items. An invalid index shows the whole model.

See also rootIndex().

void QAbstractItemView::setSelectionBehavior(SelectionBehavior behavior)

Sets what is selected when the user selects an item to behavior.

See also selectionBehavior().

void QAbstractItemView::setSelectionMode(SelectionMode mode)

Sets how items are selected to mode. A selection that the new mode does not allow is cleared.

See also selectionMode().

[virtual] void QAbstractItemView::setSelectionModel(QItemSelectionModel *selectionModel)

Sets the selection model of the view to selectionModel, which has to be one for the model of the view. Giving two views the same selection model makes them show the same selection and the same current item.

See also selectionModel() and setModel().

void QAbstractItemView::setTextElideMode(Qt::TextElideMode mode)

Sets where the text of an item gets its ellipsis when it does not fit to mode.

See also textElideMode().

QSize QAbstractItemView::sizeHintForIndex(const QModelIndex &index) const

Returns the size that the delegate of the item index wants for it, or an invalid size if index is not valid.

[protected] State QAbstractItemView::state() const

Returns EditingState while an editor is open.

Qt::TextElideMode QAbstractItemView::textElideMode() const

Returns where the text of an item gets its ellipsis when it does not fit. The default is at the end.

See also setTextElideMode().

[slot] void QAbstractItemView::update(const QModelIndex &index)

Repaints the item index.

[protected] void QAbstractItemView::updateEditorGeometries()

Places the editor of the view over its item again. A subclass calls this when it has scrolled or laid its items out anew.

[virtual] QRect QAbstractItemView::visualRect(const QModelIndex &index) const

Returns the rectangle that the item index takes on the viewport, which is empty if the item is not laid out, because a parent of it is collapsed for example. The default returns an empty rectangle.

See also indexAt() and scrollTo().