aboutsummaryrefslogtreecommitdiffstats

TreeView

import: QtQuick.TreeView

Inherits: TableView

Provides a tree view to display data from a QAbstractItemModel.

Build

  • git clone https://code.qt.io/qt-extensions/qttreeview.git
  • cd treeview
  • qmake && make && make install
  • make sub-examples (if you want the examples built as well)

NOTE: If you use Qt 6, you can also build with cmake. But if you're using a Qt version below Qt 6.2, you need to do "git checkout 6.1" before building.

Documentation

Important changes as of Qt 6.3

As of Qt 6.3, a TreeView is also available as an integral part of Qt Quick. That version is based on the implementation found in this repository, but the API has been refined and will in some cases differ. The biggest change is that the styling API is moved out of TreeView and into the delegate. This is done in collaboration with Qt Quick Controls, which offers a new customizable control, TreeViewDelegate, that renders the tree using the application style.

This means that if you use the TreeView in this module with Qt 6.3 (or above), you should import it into a namespace to avoid any name clashes with the version in Qt Quick. E.g "import QtQuick.TreeView as QtMarketplace" and then do "QtMarketplace.TreeView { ... }"

If possible, we recommend that you use the TreeView in Qt Quick if you can, since any new features will most likely only go into that version.

note: A short-coming with the TreeView in Qt Quick (Qt 6.3) compared to the version in this repository, is that it has no support for manipulating currentIndex (that is, selecting and moving the current index using the mouse or the keyboard). But this is expected to be available in later versions of Qt.

int currentIndex

This property holds the view index that has been selected as current. Selecting an index to be current is done by either using the arrow keys, clicking on a row (or a cell) with the mouse, or assign currentIndex a value explicitly.

Note: currentIndex is an index into the the view model. In this model, all tree nodes that are visible in the view are flattened into a list that can be shown in a table column. This also means that currentIndex.row is the table row relative to root node. To get the current index in the model, where the row is relative to parent node, use currentModelIndex or mapToModel():

var indexInModel = currentModelIndex
var indexInModelMapped = mapToModel(currentIndex)
console.assert(indexInModel == indexInModelMapped)

If no index has been selected as current, or if currentModelIndex is is not visible in the view, currentIndex.valid will be false.

See also: currentModelIndex, currentItem, mapToModel()

int currentModelIndex

This property holds the model index that has been selected as current. Selecting an index to be current is done by either using the arrow keys, clicking on a row (or a cell) with the mouse, or assign currentModelIndex a value explicitly.

Note: currentModelIndex is an index into the the model. This also means that currentModelIndex.row is the child number relative to the parent node. To get the current row in the view, which is relative to the root, use currentIndex or mapFromModel():

var indexInView = currentViewIndex
var indexInViewMapped = mapFromModel(currentModelIndex)
console.assert(indexInView == indexInViewMapped)

If no index has been selected as current, currentModelIndex.valid will be false.

See also: currentIndex, currentItem, mapFromModel()

readonly Item currentItem

This property holds the delegate item that is selected as current. Selecting an item to be current is done by either using the arrow keys, clicking on a row (or a cell) with the mouse, or assign a value to currentIndex explicitly.

Note: Using currentItem is almost the same as calling itemAtModelIndex(currentModelIndex). The difference is that the latter expression will only change when currentModelIndex change. But currentItem can also change as a result of the view doing a relayout behind the scenes (which can force delegate items to be reloaded or recycled). Since the item can be recycled or destroyed at any point in time behind the applications back, you should never store this value.

if currentIndex.valid is false, this property will be null.

See also: itemAtCell(), currentIndex, currentModelIndex()

int navigationMode

This property holds how you would like the user to be able navigate the tree. It can have the following values:

  • TreeView.List - the tree view acts like as a list view. This means that the user can only navigate up and down in the tree, but not sideways to the other columns. In this mode the left and right arrow keys will collapse and expand nodes in the tree (in addition to Qt.Key_Space).
  • TreeView.Table - the tree view acts like a table view. This means that the user can navigate up and down, but also left and right through all the columns in the tree. In this mode the left and right arrow keys will move currentIndex left and right, and only Qt.Key_Space will toggle nodes to be collapsed or expanded.

Note: the selected mode can also affect how the tree is styled by the delegate.

int styleHints

This property holds a set of hints that can be used to tweak the appearance of the delegate without the need to create a custom one. The hints that can be set is the following:

  • styleHints.indicator - the color of the collapsed/expanded icon
  • styleHints.indicatorCurrent - the color of the current row's collapsed/expanded icon
  • styleHints.indicatorHovered - the color of the collapsed/expanded icon when hovered
  • styleHints.overlay - the color of the overlay used for currentIndex
  • styleHints.overlayHovered - the color of the overlay used for currentIndex when hovered
  • styleHints.foregroundOdd - the foreground color of odd rows
  • styleHints.backgroundOdd - the background color of odd rows
  • styleHints.foregroundEven - the foreground color of even rows
  • styleHints.backgroundEven - the background color of even rows
  • styleHints.foregroundCurrent - the foreground color of the current item (or the whole row, if selectionMode is TreeView.List)
  • styleHints.backgroundCurrent - the background color of the current item (or the whole row, if selectionMode is TreeView.List)
  • styleHints.foregroundHovered - the foreground color of the current item (or the whole row, if selectionMode is TreeView.List) when hovered
  • styleHints.backgroundHovered - the background color of the current item when hovered (or the whole row, if selectionMode is TreeView.List)
  • styleHints.indent - the horizontal space between a parent and a child node
  • styleHints.columnPadding - the padding between a cell and its contents
  • styleHints.font - the font used by text items in the delegate

Note: a delegate is free to ignore any hints specified by the application. If you need to style a TreeView beyond what the hints can offer, you can always assign your own delegate. Taking a copy of the TreeView.qml file that is included in the repository can be a good starting point for doing so.

bool hasChildren(row)

Returns if the given row in the view is shown as expanded.

Note: row should be the row in the view, not in the model.

See also: viewIndex

bool hasSiblings(row)

Returns if the given row in the view has siblings.

Note: row should be the row in the view, not in the model.

See also: viewIndex

int depth(row)

Returns the depth (the number of parents up to the root) of the given row.

Note: row should be the row in the view, not in the model.

See also: viewIndex

bool isExpanded(row)

Returns if the given row in the view is shown as expanded.

Note: row should be the row in the view, not in the model.

See also: viewIndex

expand(row)

Expands the tree node at the given row in the view.

Note: this function will not affect the model, only the visual representation in the view.

See also: viewIndex, collapse(), expandModelIndex(), collapseModelIndex(), isCollapsed()

collapse(row)

Collapses the tree node at the given row in the view.

Note: this function will not affect the model, only the visual representation in the view.

See also: viewIndex, expand(), expandModelIndex(), collapseModelIndex(), isCollapsed()

toggleExpanded(row)

Toggles if the tree node at the given row should be expanded. This is a convenience for doing:

if (isExpanded(row))
    collapse(row)
else
    expand(row)

bool isModelIndexExpanded(modelIndex)

Returns if the given modelIndex is shown as expanded in the view. This is a convenience for doing:

isExpanded(mapFromModel(modelIndex).row)

See also: viewIndex

collapseModelIndex(modelIndex)

Collapses the tree node at the given modelIndex. This is a convenience for doing:

collapse(mapFromModel(modelIndex).row)

See also: viewIndex, collapse(), expand(), expandModelIndex(), isCollapsed()

expandModelIndex(modelIndex)

Expands the tree node at the given modelIndex. This is a convenience for doing:

expand(mapFromModel(modelIndex).row)

See also: viewIndex, collapse(), expand(), collapseModelIndex(), isCollapsed()

toggleModelIndexExpanded(modelIndex)

Toggles if the tree node at the given modelIndex should be expanded. This is a convenience for doing:

if (isModelIndexExpanded(modelIndex))
    collapseModelIndex(modelIndex)
else
    expandModelIndex(modelIndex)

int columnAtX(x, includeSpacing)

Returns the column under x in view coordinates.

If includeSpacing is set to false, and x is on top of the spacing between the columns, the return value will be -1. Otherwise, if x is on top of the spacing and includeSpacing is set to true, the column closest to the position will be returned.

See also: columnSpacing

int rowAtY(y, includeSpacing)

Returns the row under y in view coordinates.

If includeSpacing is set to false, and y is on top of the spacing between the rows, the return value will be -1. Otherwise, if y is on top of the spacing and includeSpacing is set to true, the row closest to the position will be returned.

See also:* rowSpacing

Item itemAtCell(point cell)

Returns the delegate item inside the given table cell. If the cell is not visible in the view, null will be returned.

See also: currentItem, itemAtIndex()

Item itemAtIndex(viewIndex)

Returns the delegate item at the given view index. If viewIndex.valid is false, null will be returned.

See also: currentItem, itemAtCell(), viewIndex(), itemAtModelIndex()

Item itemAtModelIndex(modelIndex)

Returns the delegate item at the given model index. If the item that represents the model index is not visible in the view, null will be returned. Convenience for doing:

itemAtIndex(mapFromModel(modelIndex))

See also: currentItem, itemAtCell(), viewIndex(), itemAtIndex()

QModelIndex viewIndex(column, row)

Creates a model index into the view model from the given row and column.

Note: this index is only valid for use with the view. To create a model index to use with the model, refer to the model API.

QModelIndex mapToModel(viewIndex)

Maps an index pointing to an item in the view (the view model), to the corresponding model index in the model.

TreeView uses a view model internally to convert a tree model into a model suited to be shown in a TableView. This view model will flatten the parts of the tree model that at any point in time is visible inside view, to a list. Depending on what you need to do, it's sometimes easier to work with model indexes rather than view indexes, and vice-versa.

See also: mapFromModel()

QModelIndex mapFromModel(modelIndex)

Maps an index pointing to an item in the \l model to the corresponding model index in the view (the view model).

TreeView uses a view model internally to convert a tree model into a model suited to be shown in a TableView. This view model will flatten the parts of the tree model that at any point in time is visible inside view, to a list. Depending on what you need to do, it's sometimes easier to work with model indexes rather than view indexes, and vice-versa.

See also: mapToModel()

Attached properties

TreeView TreeView.view

This attached property holds the view that manages the delegate instance. It is attached to each instance of the delegate.

bool TreeView.hasChildren

This attached property holds if the delegate instance is to be shown as having children (the model index represented by the instance has children in the model). It is attached to each instance of the delegate.

bool TreeView.isExpanded

This attached property holds if the delegate instance is to be shown as expanded (the view index represented by the instance is expanded in the view model). It is attached to each instance of the delegate.

int TreeView.depth

This attached property holds the tree depth (the number of parents up to the root) of the delegate instance. It is attached to each instance of the delegate.

generated by cgit v1.2.3 (git 2.25.1) at 2024-05-04 07:00:25 +0000