The QTreeWidget class provides a tree view that uses a predefined tree model. More...

#include <qtreewidget.h>

Inheritance diagram for QTreeWidget:

Collaboration diagram for QTreeWidget:

Public Slots
void	scrollToItem (const QTreeWidgetItem *item, QAbstractItemView::ScrollHint hint=EnsureVisible)
	Ensures that the item is visible, scrolling the view if necessary using the specified hint.
void	expandItem (const QTreeWidgetItem *item)
	Expands the item.
void	collapseItem (const QTreeWidgetItem *item)
	Closes the item.
void	clear ()
	Clears the tree widget by removing all of its items and selections.
Public Slots inherited from QTreeView
void	hideColumn (int column)
	Hides the column given.
void	showColumn (int column)
	Shows the given column in the tree view.
void	expand (const QModelIndex &index)
	Expands the model item specified by the index.
void	collapse (const QModelIndex &index)
	Collapses the model item specified by the index.
void	resizeColumnToContents (int column)
	Resizes the column given to the size of its contents.
void	sortByColumn (int column, Qt::SortOrder order)
	Sorts the model by the values in the given column and order.
void	expandAll ()
	Expands all expandable items.
void	expandRecursively (const QModelIndex &index, int depth=-1)
void	collapseAll ()
	Collapses all expanded items.
void	expandToDepth (int depth)
	Expands all expandable items to the given depth.
Public Slots inherited from QAbstractItemView
void	edit (const QModelIndex &index)
	Starts editing the item corresponding to the given index if it is editable.
void	clearSelection ()
	Deselects all selected items.
void	setCurrentIndex (const QModelIndex &index)
	Sets the current item to be the item at index.
void	scrollToTop ()
	Scrolls the view to the top.
void	scrollToBottom ()
	Scrolls the view to the bottom.
void	update (const QModelIndex &index)
	Updates the area occupied by the given index.

Signals
void	itemPressed (QTreeWidgetItem *item, int column)
	This signal is emitted when the user presses a mouse button inside the widget.
void	itemClicked (QTreeWidgetItem *item, int column)
	This signal is emitted when the user clicks inside the widget.
void	itemDoubleClicked (QTreeWidgetItem *item, int column)
	This signal is emitted when the user double clicks inside the widget.
void	itemActivated (QTreeWidgetItem *item, int column)
	This signal is emitted when the user activates an item by single- or double-clicking (depending on the platform, i.e.
void	itemEntered (QTreeWidgetItem *item, int column)
	This signal is emitted when the mouse cursor enters an item over the specified column.
void	itemChanged (QTreeWidgetItem *item, int column)
	This signal is emitted when the contents of the column in the specified item changes.
void	itemExpanded (QTreeWidgetItem *item)
	This signal is emitted when the specified item is expanded so that all of its children are displayed.
void	itemCollapsed (QTreeWidgetItem *item)
	This signal is emitted when the specified item is collapsed so that none of its children are displayed.
void	currentItemChanged (QTreeWidgetItem current, QTreeWidgetItem previous)
	This signal is emitted when the current item changes.
void	itemSelectionChanged ()
	This signal is emitted when the selection changes in the tree widget.
Signals inherited from QTreeView
void	expanded (const QModelIndex &index)
	This signal is emitted when the item specified by index is expanded.
void	collapsed (const QModelIndex &index)
	This signal is emitted when the item specified by index is collapsed.
Signals inherited from QAbstractItemView
void	pressed (const QModelIndex &index)
	This signal is emitted when a mouse button is pressed.
void	clicked (const QModelIndex &index)
	This signal is emitted when a mouse button is left-clicked.
void	doubleClicked (const QModelIndex &index)
	This signal is emitted when a mouse button is double-clicked.
void	activated (const QModelIndex &index)
	This signal is emitted when the item specified by index is activated by the user.
void	entered (const QModelIndex &index)
	This signal is emitted when the mouse cursor enters the item specified by index.
void	viewportEntered ()
	This signal is emitted when the mouse cursor enters the viewport.
void	iconSizeChanged (const QSize &size)

Public Member Functions
	QTreeWidget (QWidget *parent=nullptr)
	Constructs a tree widget with the given parent.
	~QTreeWidget ()
	Destroys the tree widget and all its items.
int	columnCount () const
void	setColumnCount (int columns)
QTreeWidgetItem *	invisibleRootItem () const
	Returns the tree widget's invisible root item.
QTreeWidgetItem *	topLevelItem (int index) const
	Returns the top level item at the given index, or \nullptr if the item does not exist.
int	topLevelItemCount () const
void	insertTopLevelItem (int index, QTreeWidgetItem *item)
	Inserts the item at index in the top level in the view.
void	addTopLevelItem (QTreeWidgetItem *item)
	Appends the item as a top-level item in the widget.
QTreeWidgetItem *	takeTopLevelItem (int index)
	Removes the top-level item at the given index in the tree and returns it, otherwise returns \nullptr;.
int	indexOfTopLevelItem (QTreeWidgetItem *item) const
	Returns the index of the given top-level item, or -1 if the item cannot be found.
void	insertTopLevelItems (int index, const QList< QTreeWidgetItem * > &items)
	Inserts the list of items at index in the top level in the view.
void	addTopLevelItems (const QList< QTreeWidgetItem * > &items)
	Appends the list of items as a top-level items in the widget.
QTreeWidgetItem *	headerItem () const
	Returns the item used for the tree widget's header.
void	setHeaderItem (QTreeWidgetItem *item)
	Sets the header item for the tree widget.
void	setHeaderLabels (const QStringList &labels)
	Adds a column in the header for each item in the labels list, and sets the label for each column.
void	setHeaderLabel (const QString &label)
	Same as setHeaderLabels(QStringList(label)).
QTreeWidgetItem *	currentItem () const
	Returns the current item in the tree widget.
int	currentColumn () const
	Returns the current column in the tree widget.
void	setCurrentItem (QTreeWidgetItem *item)
	Sets the current item in the tree widget.
void	setCurrentItem (QTreeWidgetItem *item, int column)
	Sets the current item in the tree widget and the current column to column.
void	setCurrentItem (QTreeWidgetItem *item, int column, QItemSelectionModel::SelectionFlags command)
	Sets the current item in the tree widget and the current column to column, using the given command.
QTreeWidgetItem *	itemAt (const QPoint &p) const
	Returns a pointer to the item at the coordinates p.
QTreeWidgetItem *	itemAt (int x, int y) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Returns a pointer to the item at the coordinates (x, y).
QRect	visualItemRect (const QTreeWidgetItem *item) const
	Returns the rectangle on the viewport occupied by the item at item.
int	sortColumn () const
	Returns the column used to sort the contents of the widget.
void	sortItems (int column, Qt::SortOrder order)
	Sorts the items in the widget in the specified order by the values in the given column.
void	editItem (QTreeWidgetItem *item, int column=0)
	Starts editing the item in the given column if it is editable.
void	openPersistentEditor (QTreeWidgetItem *item, int column=0)
	Opens a persistent editor for the item in the given column.
void	closePersistentEditor (QTreeWidgetItem *item, int column=0)
	Closes the persistent editor for the item in the given column.
bool	isPersistentEditorOpen (QTreeWidgetItem *item, int column=0) const
QWidget *	itemWidget (QTreeWidgetItem *item, int column) const
	Returns the widget displayed in the cell specified by item and the given column.
void	setItemWidget (QTreeWidgetItem item, int column, QWidget widget)
	Sets the given widget to be displayed in the cell specified by the given item and column.
void	removeItemWidget (QTreeWidgetItem *item, int column)
	Removes the widget set in the given item in the given column.
QList< QTreeWidgetItem * >	selectedItems () const
	Returns a list of all selected non-hidden items.
QList< QTreeWidgetItem * >	findItems (const QString &text, Qt::MatchFlags flags, int column=0) const
	Returns a list of items that match the given text, using the given flags, in the given column.
QTreeWidgetItem *	itemAbove (const QTreeWidgetItem *item) const
	Returns the item above the given item.
QTreeWidgetItem *	itemBelow (const QTreeWidgetItem *item) const
	Returns the item visually below the given item.
QModelIndex	indexFromItem (const QTreeWidgetItem *item, int column=0) const
	Returns the QModelIndex associated with the given item in the given column.
QTreeWidgetItem *	itemFromIndex (const QModelIndex &index) const
	Returns a pointer to the QTreeWidgetItem associated with the given index.
void	setSelectionModel (QItemSelectionModel *selectionModel) override
	\reimp
bool	isPersistentEditorOpen (const QModelIndex &index) const
Public Member Functions inherited from QTreeView
	QTreeView (QWidget *parent=nullptr)
	Constructs a tree view with a parent to represent a model's data.
	~QTreeView ()
	Destroys the tree view.
void	setRootIndex (const QModelIndex &index) override
	\reimp
QHeaderView *	header () const
	Returns the header for the tree view.
void	setHeader (QHeaderView *header)
	Sets the header for the tree view, to the given header.
int	autoExpandDelay () const
void	setAutoExpandDelay (int delay)
int	indentation () const
void	setIndentation (int i)
void	resetIndentation ()
bool	rootIsDecorated () const
void	setRootIsDecorated (bool show)
bool	uniformRowHeights () const
void	setUniformRowHeights (bool uniform)
bool	itemsExpandable () const
void	setItemsExpandable (bool enable)
bool	expandsOnDoubleClick () const
void	setExpandsOnDoubleClick (bool enable)
int	columnViewportPosition (int column) const
	Returns the horizontal position of the column in the viewport.
int	columnWidth (int column) const
	Returns the width of the column.
void	setColumnWidth (int column, int width)
	Sets the width of the given column to the width specified.
int	columnAt (int x) const
	Returns the column in the tree view whose header covers the x coordinate given.
bool	isColumnHidden (int column) const
	Returns `true` if the column is hidden; otherwise returns `false`.
void	setColumnHidden (int column, bool hide)
	If hide is true the column is hidden, otherwise the column is shown.
bool	isHeaderHidden () const
void	setHeaderHidden (bool hide)
bool	isRowHidden (int row, const QModelIndex &parent) const
	Returns `true` if the item in the given row of the parent is hidden; otherwise returns `false`.
void	setRowHidden (int row, const QModelIndex &parent, bool hide)
	If hide is true the row with the given parent is hidden, otherwise the row is shown.
bool	isFirstColumnSpanned (int row, const QModelIndex &parent) const
	Returns `true` if the item in first column in the given row of the parent is spanning all the columns; otherwise returns `false`.
void	setFirstColumnSpanned (int row, const QModelIndex &parent, bool span)
	If span is true the item in the first column in the row with the given parent is set to span all columns, otherwise all items on the row are shown.
bool	isExpanded (const QModelIndex &index) const
	Returns `true` if the model item index is expanded; otherwise returns false.
void	setExpanded (const QModelIndex &index, bool expand)
	Sets the item referred to by index to either collapse or expanded, depending on the value of expanded.
void	setSortingEnabled (bool enable)
bool	isSortingEnabled () const
void	setAnimated (bool enable)
bool	isAnimated () const
void	setAllColumnsShowFocus (bool enable)
bool	allColumnsShowFocus () const
void	setWordWrap (bool on)
bool	wordWrap () const
void	setTreePosition (int logicalIndex)
int	treePosition () const
void	keyboardSearch (const QString &search) override
	\reimp
QRect	visualRect (const QModelIndex &index) const override
	Returns the rectangle on the viewport occupied by the item at index.
void	scrollTo (const QModelIndex &index, ScrollHint hint=EnsureVisible) override
	Scroll the contents of the tree view until the given model item index is visible.
QModelIndex	indexAt (const QPoint &p) const override
	\reimp
QModelIndex	indexAbove (const QModelIndex &index) const
	Returns the model index of the item above index.
QModelIndex	indexBelow (const QModelIndex &index) const
	Returns the model index of the item below index.
void	doItemsLayout () override
void	reset () override
	\reimp
void	dataChanged (const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList< int > &roles=QList< int >()) override
	\reimp
void	selectAll () override
	\reimp
Public Member Functions inherited from QAbstractItemView
	QAbstractItemView (QWidget *parent=nullptr)
	Constructs an abstract item view with the given parent.
	~QAbstractItemView ()
	Destroys the view.
QAbstractItemModel *	model () const
	Returns the model that this view is presenting.
QItemSelectionModel *	selectionModel () const
	Returns the current selection model.
void	setItemDelegate (QAbstractItemDelegate *delegate)
	Sets the item delegate for this view and its model to delegate.
QAbstractItemDelegate *	itemDelegate () const
	Returns the item delegate used by this view and model.
void	setSelectionMode (QAbstractItemView::SelectionMode mode)
QAbstractItemView::SelectionMode	selectionMode () const
void	setSelectionBehavior (QAbstractItemView::SelectionBehavior behavior)
QAbstractItemView::SelectionBehavior	selectionBehavior () const
QModelIndex	currentIndex () const
	Returns the model index of the current item.
QModelIndex	rootIndex () const
	Returns the model index of the model's root item.
void	setEditTriggers (EditTriggers triggers)
EditTriggers	editTriggers () const
void	setVerticalScrollMode (ScrollMode mode)
ScrollMode	verticalScrollMode () const
void	resetVerticalScrollMode ()
void	setHorizontalScrollMode (ScrollMode mode)
ScrollMode	horizontalScrollMode () const
void	resetHorizontalScrollMode ()
void	setAutoScroll (bool enable)
bool	hasAutoScroll () const
void	setAutoScrollMargin (int margin)
int	autoScrollMargin () const
void	setTabKeyNavigation (bool enable)
bool	tabKeyNavigation () const
void	setAlternatingRowColors (bool enable)
bool	alternatingRowColors () const
void	setIconSize (const QSize &size)
QSize	iconSize () const
void	setTextElideMode (Qt::TextElideMode mode)
Qt::TextElideMode	textElideMode () const
QSize	sizeHintForIndex (const QModelIndex &index) const
	Returns the size hint for the item with the specified index or an invalid size for invalid indexes.
virtual int	sizeHintForRow (int row) const
	Returns the height size hint for the specified row or -1 if there is no model.
int	updateThreshold () const
void	setUpdateThreshold (int threshold)
void	openPersistentEditor (const QModelIndex &index)
	Opens a persistent editor on the item at the given index.
void	closePersistentEditor (const QModelIndex &index)
	Closes the persistent editor for the item at the given index.
bool	isPersistentEditorOpen (const QModelIndex &index) const
void	setIndexWidget (const QModelIndex &index, QWidget *widget)
	Sets the given widget on the item at the given index, passing the ownership of the widget to the viewport.
QWidget *	indexWidget (const QModelIndex &index) const
	Returns the widget for the item at the given index.
void	setItemDelegateForRow (int row, QAbstractItemDelegate *delegate)
	Sets the given item delegate used by this view and model for the given row.
QAbstractItemDelegate *	itemDelegateForRow (int row) const
	Returns the item delegate used by this view and model for the given row, or \nullptr if no delegate has been assigned.
void	setItemDelegateForColumn (int column, QAbstractItemDelegate *delegate)
	Sets the given item delegate used by this view and model for the given column.
QAbstractItemDelegate *	itemDelegateForColumn (int column) const
	Returns the item delegate used by this view and model for the given column.
virtual QAbstractItemDelegate *	itemDelegateForIndex (const QModelIndex &index) const
virtual QVariant	inputMethodQuery (Qt::InputMethodQuery query) const override
	\reimp

Protected Member Functions
bool	event (QEvent *e) override
	\reimp
virtual QStringList	mimeTypes () const
	Returns a list of MIME types that can be used to describe a list of treewidget items.
virtual QMimeData *	mimeData (const QList< QTreeWidgetItem * > &items) const
	Returns an object that contains a serialized description of the specified items.
virtual bool	dropMimeData (QTreeWidgetItem parent, int index, const QMimeData data, Qt::DropAction action)
	Handles the data supplied by a drag and drop operation that ended with the given action in the index in the given parent item.
virtual Qt::DropActions	supportedDropActions () const
	Returns the drop actions supported by this view.
Protected Member Functions inherited from QTreeView
	QTreeView (QTreeViewPrivate &dd, QWidget *parent=nullptr)
void	scrollContentsBy (int dx, int dy) override
	Scrolls the contents of the tree view by (dx, dy).
void	rowsInserted (const QModelIndex &parent, int start, int end) override
	Informs the view that the rows from the start row to the end row inclusive have been inserted into the parent model item.
void	rowsAboutToBeRemoved (const QModelIndex &parent, int start, int end) override
	Informs the view that the rows from the start row to the end row inclusive are about to removed from the given parent model item.
QModelIndex	moveCursor (CursorAction cursorAction, Qt::KeyboardModifiers modifiers) override
	Move the cursor in the way described by cursorAction, using the information provided by the button modifiers.
int	horizontalOffset () const override
	Returns the horizontal offset of the items in the treeview.
int	verticalOffset () const override
	Returns the vertical offset of the items in the tree view.
void	setSelection (const QRect &rect, QItemSelectionModel::SelectionFlags command) override
	Applies the selection command to the items in or touched by the rectangle, rect.
QRegion	visualRegionForSelection (const QItemSelection &selection) const override
	Returns the rectangle from the viewport of the items in the given selection.
QModelIndexList	selectedIndexes () const override
	\reimp
void	changeEvent (QEvent *event) override
	\reimp
void	timerEvent (QTimerEvent *event) override
	\reimp
void	paintEvent (QPaintEvent *event) override
	\reimp
void	drawTree (QPainter *painter, const QRegion &region) const
	Draws the part of the tree intersecting the given region using the specified painter.
virtual void	drawRow (QPainter *painter, const QStyleOptionViewItem &options, const QModelIndex &index) const
	Draws the row in the tree view that contains the model item index, using the painter given.
virtual void	drawBranches (QPainter *painter, const QRect &rect, const QModelIndex &index) const
	Draws the branches in the tree view on the same row as the model item index, using the painter given.
void	mousePressEvent (QMouseEvent *event) override
	\reimp
void	mouseReleaseEvent (QMouseEvent *event) override
	\reimp
void	mouseDoubleClickEvent (QMouseEvent *event) override
	\reimp
void	mouseMoveEvent (QMouseEvent *event) override
	\reimp
void	keyPressEvent (QKeyEvent *event) override
	\reimp
bool	viewportEvent (QEvent *event) override
	\reimp
void	updateGeometries () override
	\reimp
QSize	viewportSizeHint () const override
	\reimp
int	sizeHintForColumn (int column) const override
	Returns the size hint for the column's width or -1 if there is no model.
int	indexRowSizeHint (const QModelIndex &index) const
	Returns the size hint for the row indicated by index.
int	rowHeight (const QModelIndex &index) const
	Returns the height of the row indicated by the given index.
void	horizontalScrollbarAction (int action) override
bool	isIndexHidden (const QModelIndex &index) const override
	\reimp
void	selectionChanged (const QItemSelection &selected, const QItemSelection &deselected) override
	\reimp
void	currentChanged (const QModelIndex &current, const QModelIndex &previous) override
	\reimp
Protected Member Functions inherited from QAbstractItemView
	QAbstractItemView (QAbstractItemViewPrivate &, QWidget *parent=nullptr)
virtual bool	edit (const QModelIndex &index, EditTrigger trigger, QEvent *event)
	Starts editing the item at index, creating an editor if necessary, and returns `true` if the view's \l{State} is now EditingState; otherwise returns `false`.
virtual QItemSelectionModel::SelectionFlags	selectionCommand (const QModelIndex &index, const QEvent *event=nullptr) const
	Returns the SelectionFlags to be used when updating a selection model for the specified index.
virtual void	initViewItemOption (QStyleOptionViewItem *option) const
State	state () const
	Returns the item view's state.
void	setState (State state)
	Sets the item view's state to the given state.
void	scheduleDelayedItemsLayout ()
	Schedules a layout of the items in the view to be executed when the event processing starts.
void	executeDelayedItemsLayout ()
	Executes the scheduled layouts without waiting for the event processing to begin.
void	setDirtyRegion (const QRegion &region)
	Marks the given region as dirty and schedules it to be updated.
void	scrollDirtyRegion (int dx, int dy)
	Prepares the view for scrolling by ({dx},{dy}) pixels by moving the dirty regions in the opposite direction.
QPoint	dirtyRegionOffset () const
	Returns the offset of the dirty regions in the view.
void	startAutoScroll ()
void	stopAutoScroll ()
void	doAutoScroll ()
bool	focusNextPrevChild (bool next) override
	\reimp
bool	event (QEvent *event) override
	\reimp
bool	viewportEvent (QEvent *event) override
	This function is used to handle tool tips, and What's This?
void	mousePressEvent (QMouseEvent *event) override
	This function is called with the given event when a mouse button is pressed while the cursor is inside the widget.
void	mouseMoveEvent (QMouseEvent *event) override
	This function is called with the given event when a mouse move event is sent to the widget.
void	mouseReleaseEvent (QMouseEvent *event) override
	This function is called with the given event when a mouse button is released, after a mouse press event on the widget.
void	mouseDoubleClickEvent (QMouseEvent *event) override
	This function is called with the given event when a mouse button is double clicked inside the widget.
void	focusInEvent (QFocusEvent *event) override
	This function is called with the given event when the widget obtains the focus.
void	focusOutEvent (QFocusEvent *event) override
	This function is called with the given event when the widget loses the focus.
void	keyPressEvent (QKeyEvent *event) override
	This function is called with the given event when a key event is sent to the widget.
void	resizeEvent (QResizeEvent *event) override
	This function is called with the given event when a resize event is sent to the widget.
void	timerEvent (QTimerEvent *event) override
	This function is called with the given event when a timer event is sent to the widget.
void	inputMethodEvent (QInputMethodEvent *event) override
	\reimp
bool	eventFilter (QObject object, QEvent event) override
	\reimp
QSize	viewportSizeHint () const override

Properties
int	columnCount
	the number of columns displayed in the tree widget
int	topLevelItemCount
	the number of top-level items
Properties inherited from QTreeView
int	autoExpandDelay
	The delay time before items in a tree are opened during a drag and drop operation.
int	indentation
	indentation of the items in the tree view.
bool	rootIsDecorated
	whether to show controls for expanding and collapsing top-level items
bool	uniformRowHeights
	whether all items in the treeview have the same height
bool	itemsExpandable
	whether the items are expandable by the user.
bool	sortingEnabled
	whether sorting is enabled
bool	animated
	whether animations are enabled
bool	allColumnsShowFocus
	whether items should show keyboard focus using all columns
bool	wordWrap
	the item text word-wrapping policy
bool	headerHidden
	whether the header is shown or not.
bool	expandsOnDoubleClick
	whether the items can be expanded by double-clicking.
Properties inherited from QAbstractItemView
bool	autoScroll
	whether autoscrolling in drag move events is enabled
int	autoScrollMargin
	the size of the area when auto scrolling is triggered
EditTriggers	editTriggers
	which actions will initiate item editing
bool	tabKeyNavigation
	whether item navigation with tab and backtab is enabled.
bool	alternatingRowColors
	whether to draw the background using alternating colors
SelectionMode	selectionMode
	which selection mode the view operates in
SelectionBehavior	selectionBehavior
	which selection behavior the view uses
QSize	iconSize
	the size of items' icons
Qt::TextElideMode	textElideMode
	the position of the "..." in elided text.
ScrollMode	verticalScrollMode
	how the view scrolls its contents in the vertical direction
ScrollMode	horizontalScrollMode
	how the view scrolls its contents in the horizontal direction
int	updateThreshold

Private Member Functions
void	setModel (QAbstractItemModel *model) override
	\reimp

Friends
class	QTreeModel
class	QTreeWidgetItem

Additional Inherited Members
Public Types inherited from QAbstractItemView
enum	SelectionMode { NoSelection , SingleSelection , MultiSelection , ExtendedSelection , ContiguousSelection }
	This enum indicates how the view responds to user selections: More...
enum	SelectionBehavior { SelectItems , SelectRows , SelectColumns }
	\value SelectItems Selecting single items. More...
enum	ScrollHint { EnsureVisible , PositionAtTop , PositionAtBottom , PositionAtCenter }
	\value EnsureVisible Scroll to ensure that the item is visible. More...
enum	EditTrigger { NoEditTriggers = 0 , CurrentChanged = 1 , DoubleClicked = 2 , SelectedClicked = 4 , EditKeyPressed = 8 , AnyKeyPressed = 16 , AllEditTriggers = 31 }
	This enum describes actions which will initiate item editing. More...
enum	ScrollMode { ScrollPerItem , ScrollPerPixel }
	Describes how the scrollbar should behave. More...
Protected Types inherited from QAbstractItemView
enum	CursorAction { MoveUp , MoveDown , MoveLeft , MoveRight , MoveHome , MoveEnd , MovePageUp , MovePageDown , MoveNext , MovePrevious }
	This enum describes the different ways to navigate between items,. More...
enum	State { NoState , DraggingState , DragSelectingState , EditingState , ExpandingState , CollapsingState , AnimatingState }
	Describes the different states the view can be in. More...
Protected Slots inherited from QTreeView
void	columnResized (int column, int oldSize, int newSize)
	This function is called whenever {column}'s size is changed in the header.
void	columnCountChanged (int oldCount, int newCount)
	Informs the tree view that the number of columns in the tree view has changed from oldCount to newCount.
void	columnMoved ()
	This slot is called whenever a column has been moved.
void	reexpand ()
void	rowsRemoved (const QModelIndex &parent, int first, int last)
	Informs the view that the rows from the start row to the end row inclusive have been removed from the given parent model item.
void	verticalScrollbarValueChanged (int value) override
Protected Slots inherited from QAbstractItemView
virtual void	updateEditorData ()
virtual void	updateEditorGeometries ()
virtual void	verticalScrollbarAction (int action)
virtual void	verticalScrollbarValueChanged (int value)
virtual void	horizontalScrollbarValueChanged (int value)
virtual void	closeEditor (QWidget *editor, QAbstractItemDelegate::EndEditHint hint)
	Closes the given editor, and releases it.
virtual void	commitData (QWidget *editor)
	Commit the data in the editor to the model.
virtual void	editorDestroyed (QObject *editor)
	This function is called when the given editor has been destroyed.

Detailed Description

The QTreeWidget class provides a tree view that uses a predefined tree model.

\inmodule QtWidgets

{Directory displaying its contents as a tree}

The QTreeWidget class is a convenience class that provides a standard tree widget with a classic item-based interface similar to that used by the QListView class in Qt 3. This class is based on Qt's Model/View architecture and uses a default model to hold items, each of which is a QTreeWidgetItem.

Developers who do not need the flexibility of the Model/View framework can use this class to create simple hierarchical lists very easily. A more flexible approach involves combining a QTreeView with a standard item model. This allows the storage of data to be separated from its representation.

In its simplest form, a tree widget can be constructed in the following way:

QTreeWidget *treeWidget = new QTreeWidget();
treeWidget->setColumnCount(1);
QList<QTreeWidgetItem *> items;
for (int i = 0; i < 10; ++i)
    items.append(new QTreeWidgetItem(static_cast<QTreeWidget *>(nullptr), QStringList(QString("item: %1").arg(i))));
treeWidget->insertTopLevelItems(0, items);

Before items can be added to the tree widget, the number of columns must be set with setColumnCount(). This allows each item to have one or more labels or other decorations. The number of columns in use can be found with the columnCount() function.

The tree can have a header that contains a section for each column in the widget. It is easiest to set up the labels for each section by supplying a list of strings with setHeaderLabels(), but a custom header can be constructed with a QTreeWidgetItem and inserted into the tree with the setHeaderItem() function.

The items in the tree can be sorted by column according to a predefined sort order. If sorting is enabled, the user can sort the items by clicking on a column header. Sorting can be enabled or disabled by calling \l{QTreeView::setSortingEnabled()}{setSortingEnabled()}. The \l{QTreeView::isSortingEnabled()}{isSortingEnabled()} function indicates whether sorting is enabled.

See also: QTreeWidgetItem, QTreeWidgetItemIterator, QTreeView, {Model/View Programming}

Definition at line 226 of file qtreewidget.h.

Constructor & Destructor Documentation

◆ QTreeWidget()

QTreeWidget::QTreeWidget ( QWidget * parent = nullptr )

explicit

Constructs a tree widget with the given parent.

Definition at line 2559 of file qtreewidget.cpp.

◆ ~QTreeWidget()

QTreeWidget::~QTreeWidget ( )

Destroys the tree widget and all its items.

Definition at line 2597 of file qtreewidget.cpp.

Member Function Documentation

◆ addTopLevelItem()

void QTreeWidget::addTopLevelItem ( QTreeWidgetItem * item )

Appends the item as a top-level item in the widget.

See also: insertTopLevelItem()

Definition at line 2689 of file qtreewidget.cpp.

◆ addTopLevelItems()

void QTreeWidget::addTopLevelItems ( const QList< QTreeWidgetItem * > & items )

Appends the list of items as a top-level items in the widget.

See also: insertTopLevelItems()

Definition at line 2738 of file qtreewidget.cpp.

◆ clear

void QTreeWidget::clear ( )

slot

Clears the tree widget by removing all of its items and selections.

{Note:} Since each item is removed from the tree widget before being deleted, the return value of QTreeWidgetItem::treeWidget() will be invalid when called from an item's destructor.

See also: takeTopLevelItem(), topLevelItemCount(), columnCount()

Definition at line 3147 of file qtreewidget.cpp.

◆ closePersistentEditor()

void QTreeWidget::closePersistentEditor	(	QTreeWidgetItem *	item,
		int	column = 0 )

Closes the persistent editor for the item in the given column.

This function has no effect if no persistent editor is open for this combination of item and column.

See also: openPersistentEditor(), isPersistentEditorOpen()

Definition at line 2965 of file qtreewidget.cpp.

◆ collapseItem

void QTreeWidget::collapseItem ( const QTreeWidgetItem * item )

slot

Closes the item.

This causes the tree containing the item's children to be collapsed.

See also: expandItem(), currentItem(), itemAt(), topLevelItem()

Definition at line 3131 of file qtreewidget.cpp.

◆ columnCount()

int QTreeWidget::columnCount ( ) const

Definition at line 2609 of file qtreewidget.cpp.

◆ currentColumn()

int QTreeWidget::currentColumn ( ) const

Returns the current column in the tree widget.

See also: setCurrentItem(), columnCount()

Definition at line 2826 of file qtreewidget.cpp.

◆ currentItem()

QTreeWidgetItem * QTreeWidget::currentItem ( ) const

Returns the current item in the tree widget.

See also: setCurrentItem(), currentItemChanged()

Definition at line 2815 of file qtreewidget.cpp.

◆ currentItemChanged

void QTreeWidget::currentItemChanged	(	QTreeWidgetItem *	current,
		QTreeWidgetItem *	previous )

signal

This signal is emitted when the current item changes.

The current item is specified by current, and this replaces the previous current item.

See also: setCurrentItem()

◆ dropMimeData()

bool QTreeWidget::dropMimeData	(	QTreeWidgetItem *	parent,
		int	index,
		const QMimeData *	data,
		Qt::DropAction	action )

protectedvirtual

Handles the data supplied by a drag and drop operation that ended with the given action in the index in the given parent item.

The default implementation returns true if the drop was successfully handled by decoding the mime data and inserting it into the model; otherwise it returns false.

See also: supportedDropActions(), supportedDragActions

Definition at line 3208 of file qtreewidget.cpp.

◆ editItem()

void QTreeWidget::editItem	(	QTreeWidgetItem *	item,
		int	column = 0 )

Starts editing the item in the given column if it is editable.

Definition at line 2938 of file qtreewidget.cpp.

◆ event()

bool QTreeWidget::event ( QEvent * e )

overrideprotected

\reimp

Definition at line 3351 of file qtreewidget.cpp.

◆ expandItem

void QTreeWidget::expandItem ( const QTreeWidgetItem * item )

slot

Expands the item.

This causes the tree containing the item's children to be expanded.

See also: collapseItem(), currentItem(), itemAt(), topLevelItem(), itemExpanded()

Definition at line 3118 of file qtreewidget.cpp.

◆ findItems()

QList< QTreeWidgetItem * > QTreeWidget::findItems	(	const QString &	text,
		Qt::MatchFlags	flags,
		int	column = 0 ) const

Returns a list of items that match the given text, using the given flags, in the given column.

Definition at line 3048 of file qtreewidget.cpp.

◆ headerItem()

QTreeWidgetItem * QTreeWidget::headerItem ( ) const

Returns the item used for the tree widget's header.

See also: setHeaderItem()

Definition at line 2749 of file qtreewidget.cpp.

◆ indexFromItem()

QModelIndex QTreeWidget::indexFromItem	(	const QTreeWidgetItem *	item,
		int	column = 0 ) const

Returns the QModelIndex associated with the given item in the given column.

Note: In Qt versions prior to 5.7, this function took a non-{const} item.

See also: itemFromIndex(), topLevelItem()

Definition at line 3254 of file qtreewidget.cpp.

◆ indexOfTopLevelItem()

int QTreeWidget::indexOfTopLevelItem ( QTreeWidgetItem * item ) const

Returns the index of the given top-level item, or -1 if the item cannot be found.

See also: sortItems(), topLevelItemCount()

Definition at line 2713 of file qtreewidget.cpp.

◆ insertTopLevelItem()

void QTreeWidget::insertTopLevelItem	(	int	index,
		QTreeWidgetItem *	item )

Inserts the item at index in the top level in the view.

If the item has already been inserted somewhere else it won't be inserted.

See also: addTopLevelItem(), columnCount()

Definition at line 2678 of file qtreewidget.cpp.

◆ insertTopLevelItems()

void QTreeWidget::insertTopLevelItems	(	int	index,
		const QList< QTreeWidgetItem * > &	items )

Inserts the list of items at index in the top level in the view.

Items that have already been inserted somewhere else won't be inserted.

See also: addTopLevelItems()

Definition at line 2727 of file qtreewidget.cpp.

◆ invisibleRootItem()

QTreeWidgetItem * QTreeWidget::invisibleRootItem ( ) const

Returns the tree widget's invisible root item.

The invisible root item provides access to the tree widget's top-level items through the QTreeWidgetItem API, making it possible to write functions that can treat top-level items and their children in a uniform way; for example, recursive functions.

Definition at line 2636 of file qtreewidget.cpp.

◆ isPersistentEditorOpen() [1/2]

bool QAbstractItemView::isPersistentEditorOpen ( const QModelIndex & index ) const

Since: 5.10

Returns whether a persistent editor is open for the item at index index.

See also: openPersistentEditor(), closePersistentEditor()

Definition at line 187 of file qabstractitemview.cpp.

◆ isPersistentEditorOpen() [2/2]

bool QTreeWidget::isPersistentEditorOpen	(	QTreeWidgetItem *	item,
		int	column = 0 ) const

Since: 5.10

Returns whether a persistent editor is open for item item in column column.

See also: openPersistentEditor(), closePersistentEditor()

Definition at line 2980 of file qtreewidget.cpp.

◆ itemAbove()

QTreeWidgetItem * QTreeWidget::itemAbove ( const QTreeWidgetItem * item ) const

Returns the item above the given item.

Definition at line 3065 of file qtreewidget.cpp.

◆ itemActivated

void QTreeWidget::itemActivated	(	QTreeWidgetItem *	item,
		int	column )

signal

This signal is emitted when the user activates an item by single- or double-clicking (depending on the platform, i.e.

on the QStyle::SH_ItemView_ActivateItemOnSingleClick style hint) or pressing a special key (e.g., \uicontrol Enter).

The specified item is the item that was clicked, or \nullptr if no item was clicked. The column is the item's column that was clicked, or -1 if no item was clicked.

◆ itemAt() [1/2]

QTreeWidgetItem * QTreeWidget::itemAt ( const QPoint & p ) const

Returns a pointer to the item at the coordinates p.

The coordinates are relative to the tree widget's \l{QAbstractScrollArea::}{viewport()}.

See also: visualItemRect()

Definition at line 2875 of file qtreewidget.cpp.

◆ itemAt() [2/2]

QTreeWidgetItem * QTreeWidget::itemAt	(	int	x,
		int	y ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Returns a pointer to the item at the coordinates (x, y).

The coordinates are relative to the tree widget's \l{QAbstractScrollArea::}{viewport()}.

Definition at line 340 of file qtreewidget.h.

◆ itemBelow()

QTreeWidgetItem * QTreeWidget::itemBelow ( const QTreeWidgetItem * item ) const

Returns the item visually below the given item.

Definition at line 3078 of file qtreewidget.cpp.

◆ itemChanged

void QTreeWidget::itemChanged	(	QTreeWidgetItem *	item,
		int	column )

signal

This signal is emitted when the contents of the column in the specified item changes.

◆ itemClicked

void QTreeWidget::itemClicked	(	QTreeWidgetItem *	item,
		int	column )

signal

This signal is emitted when the user clicks inside the widget.

The specified item is the item that was clicked. The column is the item's column that was clicked. If no item was clicked, no signal will be emitted.

◆ itemCollapsed

void QTreeWidget::itemCollapsed ( QTreeWidgetItem * item )

signal

This signal is emitted when the specified item is collapsed so that none of its children are displayed.

Note: This signal will not be emitted if an item changes its state when collapseAll() is invoked.

See also: QTreeWidgetItem::isExpanded(), itemExpanded(), collapseItem()

◆ itemDoubleClicked

void QTreeWidget::itemDoubleClicked	(	QTreeWidgetItem *	item,
		int	column )

signal

This signal is emitted when the user double clicks inside the widget.

The specified item is the item that was clicked, or \nullptr if no item was clicked. The column is the item's column that was clicked. If no item was double clicked, no signal will be emitted.

◆ itemEntered

void QTreeWidget::itemEntered	(	QTreeWidgetItem *	item,
		int	column )

signal

This signal is emitted when the mouse cursor enters an item over the specified column.

QTreeWidget mouse tracking needs to be enabled for this feature to work.

◆ itemExpanded

void QTreeWidget::itemExpanded ( QTreeWidgetItem * item )

signal

This signal is emitted when the specified item is expanded so that all of its children are displayed.

See also: QTreeWidgetItem::isExpanded(), itemCollapsed(), expandItem()

◆ itemFromIndex()

QTreeWidgetItem * QTreeWidget::itemFromIndex ( const QModelIndex & index ) const

Returns a pointer to the QTreeWidgetItem associated with the given index.

See also: indexFromItem()

Definition at line 3265 of file qtreewidget.cpp.

◆ itemPressed

void QTreeWidget::itemPressed	(	QTreeWidgetItem *	item,
		int	column )

signal

This signal is emitted when the user presses a mouse button inside the widget.

The specified item is the item that was clicked, or \nullptr if no item was clicked. The column is the item's column that was clicked, or -1 if no item was clicked.

◆ itemSelectionChanged

void QTreeWidget::itemSelectionChanged ( )

signal

This signal is emitted when the selection changes in the tree widget.

The current selection can be found with selectedItems().

◆ itemWidget()

QWidget * QTreeWidget::itemWidget	(	QTreeWidgetItem *	item,
		int	column ) const

Returns the widget displayed in the cell specified by item and the given column.

See also: setItemWidget(), removeItemWidget()

Definition at line 2991 of file qtreewidget.cpp.

◆ mimeData()

QMimeData * QTreeWidget::mimeData ( const QList< QTreeWidgetItem * > & items ) const

protectedvirtual

Returns an object that contains a serialized description of the specified items.

The format used to describe the items is obtained from the mimeTypes() function.

If the list of items is empty, \nullptr is returned rather than a serialized empty list.

Definition at line 3173 of file qtreewidget.cpp.

◆ mimeTypes()

QStringList QTreeWidget::mimeTypes ( ) const

protectedvirtual

Returns a list of MIME types that can be used to describe a list of treewidget items.

See also: mimeData()

Definition at line 3160 of file qtreewidget.cpp.

◆ openPersistentEditor()

void QTreeWidget::openPersistentEditor	(	QTreeWidgetItem *	item,
		int	column = 0 )

Opens a persistent editor for the item in the given column.

See also: closePersistentEditor(), isPersistentEditorOpen()

Definition at line 2950 of file qtreewidget.cpp.

◆ removeItemWidget()

void QTreeWidget::removeItemWidget	(	QTreeWidgetItem *	item,
		int	column )

inline

Removes the widget set in the given item in the given column.

See also: itemWidget(), setItemWidget()

Definition at line 337 of file qtreewidget.h.

◆ scrollToItem

void QTreeWidget::scrollToItem	(	const QTreeWidgetItem *	item,
		QAbstractItemView::ScrollHint	hint = EnsureVisible )

slot

Ensures that the item is visible, scrolling the view if necessary using the specified hint.

See also: currentItem(), itemAt(), topLevelItem()

Definition at line 3106 of file qtreewidget.cpp.

◆ selectedItems()

QList< QTreeWidgetItem * > QTreeWidget::selectedItems ( ) const

Returns a list of all selected non-hidden items.

See also: itemSelectionChanged()

Definition at line 3029 of file qtreewidget.cpp.

◆ setColumnCount()

void QTreeWidget::setColumnCount ( int columns )

Definition at line 2619 of file qtreewidget.cpp.

◆ setCurrentItem() [1/3]

void QTreeWidget::setCurrentItem ( QTreeWidgetItem * item )

Sets the current item in the tree widget.

Unless the selection mode is \l{QAbstractItemView::}{NoSelection}, the item is also selected.

See also: currentItem(), currentItemChanged()

Definition at line 2839 of file qtreewidget.cpp.

◆ setCurrentItem() [2/3]

void QTreeWidget::setCurrentItem	(	QTreeWidgetItem *	item,
		int	column )

Sets the current item in the tree widget and the current column to column.

See also: currentItem()

Definition at line 2849 of file qtreewidget.cpp.

◆ setCurrentItem() [3/3]

void QTreeWidget::setCurrentItem	(	QTreeWidgetItem *	item,
		int	column,
		QItemSelectionModel::SelectionFlags	command )

Sets the current item in the tree widget and the current column to column, using the given command.

See also: currentItem()

Definition at line 2861 of file qtreewidget.cpp.

◆ setHeaderItem()

void QTreeWidget::setHeaderItem ( QTreeWidgetItem * item )

Sets the header item for the tree widget.

The label for each column in the header is supplied by the corresponding label in the item.

The tree widget takes ownership of the item.

See also: headerItem(), setHeaderLabels()

Definition at line 2764 of file qtreewidget.cpp.

◆ setHeaderLabel()

void QTreeWidget::setHeaderLabel ( const QString & label )

inline

Same as setHeaderLabels(QStringList(label)).

Definition at line 343 of file qtreewidget.h.

◆ setHeaderLabels()

void QTreeWidget::setHeaderLabels ( const QStringList & labels )

Adds a column in the header for each item in the labels list, and sets the label for each column.

Note that setHeaderLabels() won't remove existing columns.

See also: setHeaderItem(), setHeaderLabel()

Definition at line 2794 of file qtreewidget.cpp.

◆ setItemWidget()

void QTreeWidget::setItemWidget	(	QTreeWidgetItem *	item,
		int	column,
		QWidget *	widget )

Sets the given widget to be displayed in the cell specified by the given item and column.

The given widget's \l {QWidget::}{autoFillBackground} property must be set to true, otherwise the widget's background will be transparent, showing both the model data and the tree widget item.

This function should only be used to display static content in the place of a tree widget item. If you want to display custom dynamic content or implement a custom editor widget, use QTreeView and subclass QStyledItemDelegate instead.

This function cannot be called before the item hierarchy has been set up, i.e., the QTreeWidgetItem that will hold widget must have been added to the view before widget is set.

Note: The tree takes ownership of widget.

See also: itemWidget(), removeItemWidget(), {Delegate Classes}

Definition at line 3018 of file qtreewidget.cpp.

◆ setModel()

void QTreeWidget::setModel ( QAbstractItemModel * model )

overrideprivatevirtual

\reimp

Reimplemented from QTreeView.

Definition at line 3343 of file qtreewidget.cpp.

◆ setSelectionModel()

void QTreeWidget::setSelectionModel ( QItemSelectionModel * selectionModel )

overridevirtual

\reimp

Reimplemented from QTreeView.

Definition at line 3091 of file qtreewidget.cpp.

◆ sortColumn()

int QTreeWidget::sortColumn ( ) const

Returns the column used to sort the contents of the widget.

See also: sortItems()

Definition at line 2912 of file qtreewidget.cpp.

◆ sortItems()

void QTreeWidget::sortItems	(	int	column,
		Qt::SortOrder	order )

Sorts the items in the widget in the specified order by the values in the given column.

See also: sortColumn()

Definition at line 2927 of file qtreewidget.cpp.

◆ supportedDropActions()

Qt::DropActions QTreeWidget::supportedDropActions ( ) const

protectedvirtual

Returns the drop actions supported by this view.

See also: Qt::DropActions, supportedDragActions, dropMimeData()

Definition at line 3221 of file qtreewidget.cpp.

◆ takeTopLevelItem()

QTreeWidgetItem * QTreeWidget::takeTopLevelItem ( int index )

Removes the top-level item at the given index in the tree and returns it, otherwise returns \nullptr;.

See also: insertTopLevelItem(), topLevelItem(), topLevelItemCount()

Definition at line 2701 of file qtreewidget.cpp.

◆ topLevelItem()

QTreeWidgetItem * QTreeWidget::topLevelItem ( int index ) const

Returns the top level item at the given index, or \nullptr if the item does not exist.

See also: topLevelItemCount(), insertTopLevelItem()

Definition at line 2649 of file qtreewidget.cpp.

◆ topLevelItemCount()

int QTreeWidget::topLevelItemCount ( ) const

Definition at line 2664 of file qtreewidget.cpp.

◆ visualItemRect()

QRect QTreeWidget::visualItemRect ( const QTreeWidgetItem * item ) const

Returns the rectangle on the viewport occupied by the item at item.

See also: itemAt()

Definition at line 2894 of file qtreewidget.cpp.

◆ QTreeModel

friend class QTreeModel

friend

Definition at line 235 of file qtreewidget.h.

◆ QTreeWidgetItem

friend class QTreeWidgetItem

friend

Definition at line 236 of file qtreewidget.h.

Property Documentation

◆ columnCount

int QTreeWidget::columnCount

readwrite

the number of columns displayed in the tree widget

By default, this property has a value of 1.

Definition at line 229 of file qtreewidget.h.

◆ topLevelItemCount

int QTreeWidget::topLevelItemCount

read

the number of top-level items

By default, this property has a value of 0.

See also: columnCount(), currentItem()

Definition at line 230 of file qtreewidget.h.

The documentation for this class was generated from the following files:

qtbase/src/widgets/itemviews/qtreewidget.h (824c333aac9265fe457658d77c36b6f600fcf8e5)
qtbase/src/widgets/itemviews/qtreewidget.cpp (87806f5cad6e4ce75a899598c15c126995682562)

Public Slots

Signals

Public Member Functions

Protected Member Functions

Properties

Private Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ QTreeWidget()

◆ ~QTreeWidget()

Member Function Documentation

◆ addTopLevelItem()

◆ addTopLevelItems()

◆ clear

◆ closePersistentEditor()

◆ collapseItem

◆ columnCount()

◆ currentColumn()

◆ currentItem()

◆ currentItemChanged

◆ dropMimeData()

◆ editItem()

◆ event()

◆ expandItem

◆ findItems()

◆ headerItem()

◆ indexFromItem()

◆ indexOfTopLevelItem()

◆ insertTopLevelItem()

◆ insertTopLevelItems()

◆ invisibleRootItem()

◆ isPersistentEditorOpen() [1/2]

◆ isPersistentEditorOpen() [2/2]

◆ itemAbove()

◆ itemActivated

◆ itemAt() [1/2]

◆ itemAt() [2/2]

◆ itemBelow()

◆ itemChanged

◆ itemClicked

◆ itemCollapsed

◆ itemDoubleClicked

◆ itemEntered

◆ itemExpanded

◆ itemFromIndex()

◆ itemPressed

◆ itemSelectionChanged

◆ itemWidget()

◆ mimeData()

◆ mimeTypes()

◆ openPersistentEditor()

◆ removeItemWidget()

◆ scrollToItem

◆ selectedItems()

◆ setColumnCount()

◆ setCurrentItem() [1/3]

◆ setCurrentItem() [2/3]

◆ setCurrentItem() [3/3]

◆ setHeaderItem()

◆ setHeaderLabel()

◆ setHeaderLabels()

◆ setItemWidget()

◆ setModel()

◆ setSelectionModel()

◆ sortColumn()

◆ sortItems()

◆ supportedDropActions()

◆ takeTopLevelItem()

◆ topLevelItem()

◆ topLevelItemCount()

◆ visualItemRect()

Friends And Related Symbol Documentation

◆ QTreeModel

◆ QTreeWidgetItem

Property Documentation

◆ columnCount

◆ topLevelItemCount