Contents

• Properties
• Public Functions
• Reimplemented Public Functions
• Public Slots
• Signals
• Protected Functions
• Reimplemented Protected Functions
• Protected Slots
• Detailed Description
• Key Bindings
• Improving Performance

Detailed Description

TheQTreeView class provides a default model/view implementation of a tree view.

AQTreeView implements a tree representation of items from a model. This class is used to provide standard hierarchical lists that were previously provided by theQListView class, but using the more flexible approach provided by Qt's model/view architecture.

TheQTreeView class is one of theModel/View Classes and is part of Qt'smodel/view framework.

QTreeView implements the interfaces defined by theQAbstractItemView class to allow it to display data provided by models derived from theQAbstractItemModel class.

It is simple to construct a tree view displaying data from a model. In the following example, the contents of a directory are supplied by aQFileSystemModel and displayed as a tree:

QFileSystemModel*model=newQFileSystemModel;    model->setRootPath(QDir::currentPath());QTreeView*tree=newQTreeView(splitter);    tree->setModel(model);

The model/view architecture ensures that the contents of the tree view are updated as the model changes.

Items that have children can be in an expanded (children are visible) or collapsed (children are hidden) state. When this state changes acollapsed() orexpanded() signal is emitted with the model index of the relevant item.

The amount of indentation used to indicate levels of hierarchy is controlled by theindentation property.

Headers in tree views are constructed using theQHeaderView class and can be hidden usingheader()->hide(). Note that each header is configured with itsstretchLastSection property set to true, ensuring that the view does not waste any of the space assigned to it for its header. If this value is set to true, this property will override the resize mode set on the last section in the header.

Key Bindings

QTreeView supports a set of key bindings that enable the user to navigate in the view and interact with the contents of items:

AWindows XP style tree view.	AMacintosh style tree view.	APlastique style tree view.

Improving Performance

It is possible to give the view hints about the data it is handling in order to improve its performance when displaying large numbers of items. One approach that can be taken for views that are intended to display items with equal heights is to set theuniformRowHeights property to true.

Property Documentation

allColumnsShowFocus :bool

This property holds whether items should show keyboard focus using all columns.

If this property is true all columns will show focus, otherwise only one column will show focus.

The default is false.

This property was introduced in Qt 4.2.

Access functions:

animated :bool

This property holds whether animations are enabled.

If this property is true the treeview will animate expandsion and collasping of branches. If this property is false, the treeview will expand or collapse branches immediately without showing the animation.

By default, this property is false.

This property was introduced in Qt 4.2.

Access functions:

autoExpandDelay :int

This property holds the delay time before items in a tree are opened during a drag and drop operation.

This property holds the amount of time in milliseconds that the user must wait over a node before that node will automatically open or close. If the time is set to less then 0 then it will not be activated.

By default, this property has a value of -1, meaning that auto-expansion is disabled.

This property was introduced in Qt 4.3.

Access functions:

expandsOnDoubleClick :bool

This property holds whether the items can be expanded by double-clicking.

This property holds whether the user can expand and collapse items by double-clicking. The default value is true.

This property was introduced in Qt 4.4.

Access functions:

See alsoitemsExpandable.

headerHidden :bool

This property holds whether the header is shown or not.

If this property is true, the header is not shown otherwise it is. The default value is false.

This property was introduced in Qt 4.4.

Access functions:

See alsoheader().

indentation :int

This property holds indentation of the items in the tree view.

This property holds the indentation measured in pixels of the items for each level in the tree view. For top-level items, the indentation specifies the horizontal distance from the viewport edge to the items in the first column; for child items, it specifies their indentation from their parent items.

By default, this property has a value of 20.

Access functions:

itemsExpandable :bool

This property holds whether the items are expandable by the user.

This property holds whether the user can expand and collapse items interactively.

By default, this property is true.

Access functions:

rootIsDecorated :bool

This property holds whether to show controls for expanding and collapsing top-level items.

Items with children are typically shown with controls to expand and collapse them, allowing their children to be shown or hidden. If this property is false, these controls are not shown for top-level items. This can be used to make a single level tree structure appear like a simple list of items.

By default, this property is true.

Access functions:

sortingEnabled :bool

This property holds whether sorting is enabled.

If this property is true, sorting is enabled for the tree; if the property is false, sorting is not enabled. The default value is false.

Note:In order to avoid performance issues, it is recommended that sorting is enabledafter inserting the items into the tree. Alternatively, you could also insert the items into a list before inserting the items into the tree.

This property was introduced in Qt 4.2.

Access functions:

See alsosortByColumn().

uniformRowHeights :bool

This property holds whether all items in the treeview have the same height.

This property should only be set to true if it is guaranteed that all items in the view has the same height. This enables the view to do some optimizations.

The height is obtained from the first item in the view. It is updated when the data changes on that item.

By default, this property is false.

Access functions:

wordWrap :bool

This property holds the item text word-wrapping policy.

If this property is true then the item text is wrapped where necessary at word-breaks; otherwise it is not wrapped at all. This property is false by default.

Note that even if wrapping is enabled, the cell will not be expanded to fit all text. Ellipsis will be inserted according to the currenttextElideMode.

This property was introduced in Qt 4.3.

Access functions:

Member Function Documentation

QTreeView::QTreeView(QWidget * parent = 0)

Constructs a tree view with aparent to represent a model's data. UsesetModel() to set the model.

See alsoQAbstractItemModel.

QTreeView::~QTreeView()

Destroys the tree view.

[slot]void QTreeView::collapse(constQModelIndex & index)

Collapses the model item specified by theindex.

See alsocollapsed().

[slot]void QTreeView::collapseAll()

Collapses all expanded items.

This function was introduced in Qt 4.2.

See alsoexpandAll(),expand(),collapse(), andsetExpanded().

[signal]void QTreeView::collapsed(constQModelIndex & index)

This signal is emitted when the item specified byindex is collapsed.

int QTreeView::columnAt(int x) const

Returns the column in the tree view whose header covers thex coordinate given.

[protected slot]void QTreeView::columnCountChanged(int oldCount,int newCount)

Informs the tree view that the number of columns in the tree view has changed fromoldCount tonewCount.

[protected slot]void QTreeView::columnMoved()

This slot is called whenever a column has been moved.

[protected slot]void QTreeView::columnResized(int column,int oldSize,int newSize)

This function is called whenevercolumn's size is changed in the header.oldSize andnewSize give the previous size and the new size in pixels.

See alsosetColumnWidth().

int QTreeView::columnViewportPosition(int column) const

Returns the horizontal position of thecolumn in the viewport.

int QTreeView::columnWidth(int column) const

Returns the width of thecolumn.

See alsoresizeColumnToContents() andsetColumnWidth().

[virtual protected]void QTreeView::currentChanged(constQModelIndex & current, constQModelIndex & previous)

Reimplemented fromQAbstractItemView::currentChanged().

[virtual]void QTreeView::dataChanged(constQModelIndex & topLeft, constQModelIndex & bottomRight)

Reimplemented fromQAbstractItemView::dataChanged().

[virtual protected]void QTreeView::dragMoveEvent(QDragMoveEvent * event)

Reimplemented fromQWidget::dragMoveEvent().

[virtual protected]void QTreeView::drawBranches(QPainter * painter, constQRect & rect, constQModelIndex & index) const

Draws the branches in the tree view on the same row as the model itemindex, using thepainter given. The branches are drawn in the rectangle specified byrect.

[virtual protected]void QTreeView::drawRow(QPainter * painter, constQStyleOptionViewItem & option, constQModelIndex & index) const

Draws the row in the tree view that contains the model itemindex, using thepainter given. Theoption control how the item is displayed.

See alsosetAlternatingRowColors().

[protected]void QTreeView::drawTree(QPainter * painter, constQRegion & region) const

Draws the part of the tree intersecting the givenregion using the specifiedpainter.

This function was introduced in Qt 4.2.

See alsopaintEvent().

[slot]void QTreeView::expand(constQModelIndex & index)

Expands the model item specified by theindex.

See alsoexpanded().

[slot]void QTreeView::expandAll()

Expands all expandable items.

Warning: if the model contains a large number of items, this function will take some time to execute.

This function was introduced in Qt 4.2.

See alsocollapseAll(),expand(),collapse(), andsetExpanded().

[slot]void QTreeView::expandToDepth(int depth)

Expands all expandable items to the givendepth.

This function was introduced in Qt 4.3.

See alsoexpandAll(),collapseAll(),expand(),collapse(), andsetExpanded().

[signal]void QTreeView::expanded(constQModelIndex & index)

This signal is emitted when the item specified byindex is expanded.

See alsosetExpanded().

QHeaderView * QTreeView::header() const

Returns the header for the tree view.

See alsosetHeader() andQAbstractItemModel::headerData().

[slot]void QTreeView::hideColumn(int column)

Hides thecolumn given.

Note:This function should only be called after the model has been initialized, as the view needs to know the number of columns in order to hidecolumn.

See alsoshowColumn() andsetColumnHidden().

[virtual protected]int QTreeView::horizontalOffset() const

Reimplemented fromQAbstractItemView::horizontalOffset().

Returns the horizontal offset of the items in the treeview.

Note that the tree view uses the horizontal header section positions to determine the positions of columns in the view.

See alsoverticalOffset().

QModelIndex QTreeView::indexAbove(constQModelIndex & index) const

Returns the model index of the item aboveindex.

[virtual]QModelIndex QTreeView::indexAt(constQPoint & point) const

Reimplemented fromQAbstractItemView::indexAt().

QModelIndex QTreeView::indexBelow(constQModelIndex & index) const

Returns the model index of the item belowindex.

[protected]int QTreeView::indexRowSizeHint(constQModelIndex & index) const

Returns the size hint for the row indicated byindex.

See alsosizeHintForColumn() anduniformRowHeights().

bool QTreeView::isColumnHidden(int column) const

Returns true if thecolumn is hidden; otherwise returns false.

See alsohideColumn() andisRowHidden().

bool QTreeView::isExpanded(constQModelIndex & index) const

Returns true if the model itemindex is expanded; otherwise returns false.

See alsoexpand(),expanded(), andsetExpanded().

bool QTreeView::isFirstColumnSpanned(int row, constQModelIndex & parent) const

Returns true if the item in first column in the givenrow of theparent is spanning all the columns; otherwise returns false.

This function was introduced in Qt 4.3.

See alsosetFirstColumnSpanned().

[virtual protected]bool QTreeView::isIndexHidden(constQModelIndex & index) const

Reimplemented fromQAbstractItemView::isIndexHidden().

bool QTreeView::isRowHidden(int row, constQModelIndex & parent) const

Returns true if the item in the givenrow of theparent is hidden; otherwise returns false.

See alsosetRowHidden() andisColumnHidden().

[virtual protected]void QTreeView::keyPressEvent(QKeyEvent * event)

Reimplemented fromQWidget::keyPressEvent().

[virtual]void QTreeView::keyboardSearch(constQString & search)

Reimplemented fromQAbstractItemView::keyboardSearch().

[virtual protected]void QTreeView::mouseDoubleClickEvent(QMouseEvent * event)

Reimplemented fromQWidget::mouseDoubleClickEvent().

[virtual protected]void QTreeView::mouseMoveEvent(QMouseEvent * event)

Reimplemented fromQWidget::mouseMoveEvent().

[virtual protected]void QTreeView::mousePressEvent(QMouseEvent * event)

Reimplemented fromQWidget::mousePressEvent().

[virtual protected]void QTreeView::mouseReleaseEvent(QMouseEvent * event)

Reimplemented fromQWidget::mouseReleaseEvent().

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

Reimplemented fromQAbstractItemView::moveCursor().

Move the cursor in the way described bycursorAction, using the information provided by the buttonmodifiers.

[virtual protected]void QTreeView::paintEvent(QPaintEvent * event)

Reimplemented fromQWidget::paintEvent().

[virtual]void QTreeView::reset()

Reimplemented fromQAbstractItemView::reset().

[slot]void QTreeView::resizeColumnToContents(int column)

Resizes thecolumn given to the size of its contents.

See alsocolumnWidth() andsetColumnWidth().

[protected]int QTreeView::rowHeight(constQModelIndex & index) const

Returns the height of the row indicated by the givenindex.

This function was introduced in Qt 4.3.

See alsoindexRowSizeHint().

[virtual protected]void QTreeView::rowsAboutToBeRemoved(constQModelIndex & parent,int start,int end)

Reimplemented fromQAbstractItemView::rowsAboutToBeRemoved().

Informs the view that the rows from thestart row to theend row inclusive are about to removed from the givenparent model item.

[virtual protected]void QTreeView::rowsInserted(constQModelIndex & parent,int start,int end)

Reimplemented fromQAbstractItemView::rowsInserted().

Informs the view that the rows from thestart row to theend row inclusive have been inserted into theparent model item.

[protected slot]void QTreeView::rowsRemoved(constQModelIndex & parent,int start,int end)

Informs the view that the rows from thestart row to theend row inclusive have been removed from the givenparent model item.

This function was introduced in Qt 4.1.

[virtual protected]void QTreeView::scrollContentsBy(int dx,int dy)

Reimplemented fromQAbstractScrollArea::scrollContentsBy().

Scrolls the contents of the tree view by (dx,dy).

[virtual]void QTreeView::scrollTo(constQModelIndex & index,ScrollHint hint = EnsureVisible)

Reimplemented fromQAbstractItemView::scrollTo().

Scroll the contents of the tree view until the given model itemindex is visible. Thehint parameter specifies more precisely where the item should be located after the operation. If any of the parents of the model item are collapsed, they will be expanded to ensure that the model item is visible.

[virtual]void QTreeView::selectAll()

Reimplemented fromQAbstractItemView::selectAll().

[virtual protected]QModelIndexList QTreeView::selectedIndexes() const

Reimplemented fromQAbstractItemView::selectedIndexes().

[virtual protected]void QTreeView::selectionChanged(constQItemSelection & selected, constQItemSelection & deselected)

Reimplemented fromQAbstractItemView::selectionChanged().

void QTreeView::setColumnHidden(int column,bool hide)

Ifhide is true thecolumn is hidden, otherwise thecolumn is shown.

See alsoisColumnHidden(),hideColumn(), andsetRowHidden().

void QTreeView::setColumnWidth(int column,int width)

Sets the width of the givencolumn to thewidth specified.

This function was introduced in Qt 4.2.

See alsocolumnWidth() andresizeColumnToContents().

void QTreeView::setExpanded(constQModelIndex & index,bool expanded)

Sets the item referred to byindex to either collapse or expanded, depending on the value ofexpanded.

See alsoexpanded(),expand(), andisExpanded().

void QTreeView::setFirstColumnSpanned(int row, constQModelIndex & parent,bool span)

Ifspan is true the item in the first column in therow with the givenparent is set to span all columns, otherwise all items on therow are shown.

This function was introduced in Qt 4.3.

See alsoisFirstColumnSpanned().

void QTreeView::setHeader(QHeaderView * header)

Sets the header for the tree view, to the givenheader.

The view takes ownership over the givenheader and deletes it when a new header is set.

See alsoQAbstractItemModel::headerData().

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

Reimplemented fromQAbstractItemView::setModel().

[virtual]void QTreeView::setRootIndex(constQModelIndex & index)

Reimplemented fromQAbstractItemView::setRootIndex().

void QTreeView::setRowHidden(int row, constQModelIndex & parent,bool hide)

Ifhide is true therow with the givenparent is hidden, otherwise therow is shown.

See alsoisRowHidden() andsetColumnHidden().

[virtual protected]void QTreeView::setSelection(constQRect & rect,QItemSelectionModel::SelectionFlags command)

Reimplemented fromQAbstractItemView::setSelection().

Applies the selectioncommand to the items in or touched by the rectangle,rect.

See alsoselectionCommand().

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

Reimplemented fromQAbstractItemView::setSelectionModel().

[slot]void QTreeView::showColumn(int column)

Shows the givencolumn in the tree view.

See alsohideColumn() andsetColumnHidden().

[virtual protected]int QTreeView::sizeHintForColumn(int column) const

Reimplemented fromQAbstractItemView::sizeHintForColumn().

Returns the size hint for thecolumn's width or -1 if there is no model.

If you need to set the width of a given column to a fixed value, callQHeaderView::resizeSection() on the view's header.

If you reimplement this function in a subclass, note that the value you return is only used whenresizeColumnToContents() is called. In that case, if a larger column width is required by either the view's header or the item delegate, that width will be used instead.

See alsoQWidget::sizeHint andheader().

void QTreeView::sortByColumn(int column,Qt::SortOrder order)

Sets the model up for sorting by the values in the givencolumn andorder.

column may be -1, in which case no sort indicator will be shown and the model will return to its natural, unsorted order. Note that not all models support this and may even crash in this case.

This function was introduced in Qt 4.2.

See alsosortingEnabled.

[virtual protected]void QTreeView::timerEvent(QTimerEvent * event)

Reimplemented fromQObject::timerEvent().

[virtual protected]void QTreeView::updateGeometries()

Reimplemented fromQAbstractItemView::updateGeometries().

[virtual protected]int QTreeView::verticalOffset() const

Reimplemented fromQAbstractItemView::verticalOffset().

Returns the vertical offset of the items in the tree view.

See alsohorizontalOffset().

[virtual protected]bool QTreeView::viewportEvent(QEvent * event)

Reimplemented fromQAbstractScrollArea::viewportEvent().

[virtual]QRect QTreeView::visualRect(constQModelIndex & index) const

Reimplemented fromQAbstractItemView::visualRect().

Returns the rectangle on the viewport occupied by the item atindex. If the index is not visible or explicitly hidden, the returned rectangle is invalid.

[virtual protected]QRegion QTreeView::visualRegionForSelection(constQItemSelection & selection) const

Reimplemented fromQAbstractItemView::visualRegionForSelection().

Returns the rectangle from the viewport of the items in the givenselection.

Since 4.7, the returned region only contains rectangles intersecting (or included in) the viewport.