|  | Home · All Classes · Modules

# QTreeWidget Class Reference
[QtGui module]

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

Inherits QTreeView.

### Methods

- __init__ (self, QWidget parent = None)
- addTopLevelItem (self, QTreeWidgetItem item)
- addTopLevelItems (self, list-of-QTreeWidgetItem items)
- clear (self)
- closePersistentEditor (self, QTreeWidgetItem item, int column = 0)
- collapseItem (self, QTreeWidgetItem item)
- int columnCount (self)
- int currentColumn (self)
- QTreeWidgetItem currentItem (self)
- dropEvent (self, QDropEvent event)
- bool dropMimeData (self, QTreeWidgetItem parent, int index, QMimeData data, Qt.DropAction action)
- editItem (self, QTreeWidgetItem item, int column = 0)
- bool event (self, QEvent e)
- expandItem (self, QTreeWidgetItem item)
- list-of-QTreeWidgetItem findItems (self, QString text, Qt.MatchFlags flags, int column = 0)
- QTreeWidgetItem headerItem (self)
- QModelIndex indexFromItem (self, QTreeWidgetItem item, int column = 0)
- int indexOfTopLevelItem (self, QTreeWidgetItem item)
- insertTopLevelItem (self, int index, QTreeWidgetItem item)
- insertTopLevelItems (self, int index, list-of-QTreeWidgetItem items)
- QTreeWidgetItem invisibleRootItem (self)
- bool isFirstItemColumnSpanned (self, QTreeWidgetItem item)
- bool isItemExpanded (self, QTreeWidgetItem item)
- bool isItemHidden (self, QTreeWidgetItem item)
- bool isItemSelected (self, QTreeWidgetItem item)
- bool isSortingEnabled (self)
- QTreeWidgetItem itemAbove (self, QTreeWidgetItem item)
- QTreeWidgetItem itemAt (self, QPoint p)
- QTreeWidgetItem itemAt (self, int ax, int ay)
- QTreeWidgetItem itemBelow (self, QTreeWidgetItem item)
- QTreeWidgetItem itemFromIndex (self, QModelIndex index)
- list-of-QTreeWidgetItem items (self, QMimeData data)
- QWidget itemWidget (self, QTreeWidgetItem item, int column)
- QMimeData mimeData (self, list-of-QTreeWidgetItem items)
- QStringList mimeTypes (self)
- openPersistentEditor (self, QTreeWidgetItem item, int column = 0)
- removeItemWidget (self, QTreeWidgetItem item, int column)
- scrollToItem (self, QTreeWidgetItem item, QAbstractItemView.ScrollHint hint = QAbstractItemView.EnsureVisible)
- list-of-QTreeWidgetItem selectedItems (self)
- setColumnCount (self, int columns)
- setCurrentItem (self, QTreeWidgetItem item)
- setCurrentItem (self, QTreeWidgetItem item, int column)
- setCurrentItem (self, QTreeWidgetItem item, int column, QItemSelectionModel.SelectionFlags command)
- setFirstItemColumnSpanned (self, QTreeWidgetItem item, bool span)
- setHeaderItem (self, QTreeWidgetItem item)
- setHeaderLabel (self, QString alabel)
- setHeaderLabels (self, QStringList labels)
- setItemExpanded (self, QTreeWidgetItem item, bool expand)
- setItemHidden (self, QTreeWidgetItem item, bool hide)
- setItemSelected (self, QTreeWidgetItem item, bool select)
- setItemWidget (self, QTreeWidgetItem item, int column, QWidget widget)
- setSelectionModel (self, QItemSelectionModel selectionModel)
- setSortingEnabled (self, bool enable)
- int sortColumn (self)
- sortItems (self, int column, Qt.SortOrder order)
- Qt.DropActions supportedDropActions (self)
- QTreeWidgetItem takeTopLevelItem (self, int index)
- QTreeWidgetItem topLevelItem (self, int index)
- int topLevelItemCount (self)
- QRect visualItemRect (self, QTreeWidgetItem item)

### Qt Signals

- void currentItemChanged (QTreeWidgetItem *,QTreeWidgetItem *)
- void itemActivated (QTreeWidgetItem *,int)
- void itemChanged (QTreeWidgetItem *,int)
- void itemClicked (QTreeWidgetItem *,int)
- void itemCollapsed (QTreeWidgetItem *)
- void itemDoubleClicked (QTreeWidgetItem *,int)
- void itemEntered (QTreeWidgetItem *,int)
- void itemExpanded (QTreeWidgetItem *)
- void itemPressed (QTreeWidgetItem *,int)
- void itemSelectionChanged ()

## Detailed Description

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

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((QTreeWidget*)0, 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 setSortingEnabled(). The isSortingEnabled() function indicates whether sorting is enabled.

A Windows XP style tree widget. | A Macintosh style tree widget. | A Plastique style tree widget.

## Method Documentation

### QTreeWidget.__init__ (self, QWidget parent = None)

The parent argument, if not None, causes self to be owned by Qt instead of PyQt.

Constructs a tree widget with the given parent.

### QTreeWidget.addTopLevelItem (self, QTreeWidgetItem item)

The item argument has it's ownership transferred to Qt.

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

This function was introduced in Qt 4.1.

See also insertTopLevelItem().

### QTreeWidget.addTopLevelItems (self, list-of-QTreeWidgetItem items)

The items argument has it's ownership transferred to Qt.

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

See also insertTopLevelItems().

### QTreeWidget.clear (self)

This method is also a Qt slot with the C++ signature `void clear()`.

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(), and columnCount().

### QTreeWidget.closePersistentEditor (self, 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().

### QTreeWidget.collapseItem (self, QTreeWidgetItem item)

This method is also a Qt slot with the C++ signature `void collapseItem(const QTreeWidgetItem *)`.

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

See also expandItem(), currentItem(), itemAt(), and topLevelItem().

### int QTreeWidget.columnCount (self)

### int QTreeWidget.currentColumn (self)

Returns the current column in the tree widget.

This function was introduced in Qt 4.1.

See also setCurrentItem() and columnCount().

### QTreeWidgetItem QTreeWidget.currentItem (self)

Returns the current item in the tree widget.

See also setCurrentItem() and currentItemChanged().

### QTreeWidget.dropEvent (self, QDropEvent event)

Reimplemented from QWidget.dropEvent().

### bool QTreeWidget.dropMimeData (self, QTreeWidgetItem parent, int index, 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.

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().

### QTreeWidget.editItem (self, QTreeWidgetItem item, int column = 0)

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

### bool QTreeWidget.event (self, QEvent e)

Reimplemented from QObject.event().

### QTreeWidget.expandItem (self, QTreeWidgetItem item)

This method is also a Qt slot with the C++ signature `void expandItem(const QTreeWidgetItem *)`.

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

See also collapseItem(), currentItem(), itemAt(), topLevelItem(), and itemExpanded().

### list-of-QTreeWidgetItem QTreeWidget.findItems (self, QString text, Qt.MatchFlags flags, int column = 0)

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

### QTreeWidgetItem QTreeWidget.headerItem (self)

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

See also setHeaderItem().

### QModelIndex QTreeWidget.indexFromItem (self, QTreeWidgetItem item, int column = 0)

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

See also itemFromIndex() and topLevelItem().

### int QTreeWidget.indexOfTopLevelItem (self, QTreeWidgetItem item)

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

See also sortItems() and topLevelItemCount().

### QTreeWidget.insertTopLevelItem (self, int index, QTreeWidgetItem item)

The item argument has it's ownership transferred to Qt.

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

If the item has already been inserted somewhere else it wont be inserted.

See also addTopLevelItem() and columnCount().

### QTreeWidget.insertTopLevelItems (self, int index, list-of-QTreeWidgetItem items)

The items argument has it's ownership transferred to Qt.

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

Items that have already been inserted somewhere else wont be inserted.

This function was introduced in Qt 4.1.

See also addTopLevelItems().

### QTreeWidgetItem QTreeWidget.invisibleRootItem (self)

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.

This function was introduced in Qt 4.2.

### bool QTreeWidget.isFirstItemColumnSpanned (self, QTreeWidgetItem item)

Returns true if the given item is set to show only one section over all columns; otherwise returns false.

This function was introduced in Qt 4.3.

See also setFirstItemColumnSpanned().

### bool QTreeWidget.isItemExpanded (self, QTreeWidgetItem item)

### bool QTreeWidget.isItemHidden (self, QTreeWidgetItem item)

### bool QTreeWidget.isItemSelected (self, QTreeWidgetItem item)

### bool QTreeWidget.isSortingEnabled (self)

### QTreeWidgetItem QTreeWidget.itemAbove (self, QTreeWidgetItem item)

Returns the item above the given item.

This function was introduced in Qt 4.3.

### QTreeWidgetItem QTreeWidget.itemAt (self, QPoint p)

Returns a pointer to the item at the coordinates p. The coordinates are relative to the tree widget's viewport().

See also visualItemRect().

### QTreeWidgetItem QTreeWidget.itemAt (self, int ax, int ay)

This is an overloaded function.

Returns a pointer to the item at the coordinates (x, y). The coordinates are relative to the tree widget's viewport().

### QTreeWidgetItem QTreeWidget.itemBelow (self, QTreeWidgetItem item)

Returns the item visually below the given item.

This function was introduced in Qt 4.3.

### QTreeWidgetItem QTreeWidget.itemFromIndex (self, QModelIndex index)

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

See also indexFromItem().

### list-of-QTreeWidgetItem QTreeWidget.items (self, QMimeData data)

### QWidget QTreeWidget.itemWidget (self, QTreeWidgetItem item, int column)

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

Note: The tree takes ownership of the widget.

This function was introduced in Qt 4.1.

See also setItemWidget().

### QMimeData QTreeWidget.mimeData (self, list-of-QTreeWidgetItem items)

The QMimeData result

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, 0 is returned rather than a serialized empty list.

### QStringList QTreeWidget.mimeTypes (self)

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

See also mimeData().

### QTreeWidget.openPersistentEditor (self, QTreeWidgetItem item, int column = 0)

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

See also closePersistentEditor().

### QTreeWidget.removeItemWidget (self, QTreeWidgetItem item, int column)

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

This function was introduced in Qt 4.3.

### QTreeWidget.scrollToItem (self, QTreeWidgetItem item, QAbstractItemView.ScrollHint hint = QAbstractItemView.EnsureVisible)

This method is also a Qt slot with the C++ signature `void scrollToItem(const QTreeWidgetItem *,QAbstractItemView::ScrollHint = QAbstractItemView.EnsureVisible)`.

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

See also currentItem(), itemAt(), and topLevelItem().

### list-of-QTreeWidgetItem QTreeWidget.selectedItems (self)

Returns a list of all selected non-hidden items.

See also itemSelectionChanged().

### QTreeWidget.setColumnCount (self, int columns)

### QTreeWidget.setCurrentItem (self, QTreeWidgetItem item)

Sets the current item in the tree widget.

Unless the selection mode is NoSelection, the item is also be selected.

See also currentItem() and currentItemChanged().

### QTreeWidget.setCurrentItem (self, QTreeWidgetItem item, int column)

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

This function was introduced in Qt 4.1.

See also currentItem().

### QTreeWidget.setCurrentItem (self, 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.

This function was introduced in Qt 4.4.

See also currentItem().

### QTreeWidget.setFirstItemColumnSpanned (self, QTreeWidgetItem item, bool span)

Sets the given item to only show one section for all columns if span is true; otherwise the item will show one section per column.

This function was introduced in Qt 4.3.

See also isFirstItemColumnSpanned().

### QTreeWidget.setHeaderItem (self, QTreeWidgetItem item)

The item argument has it's ownership transferred to Qt.

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() and setHeaderLabels().

### QTreeWidget.setHeaderLabel (self, QString alabel)

Same as setHeaderLabels(QStringList(label)).

This function was introduced in Qt 4.2.

### QTreeWidget.setHeaderLabels (self, 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() and setHeaderLabel().

### QTreeWidget.setItemExpanded (self, QTreeWidgetItem item, bool expand)

### QTreeWidget.setItemHidden (self, QTreeWidgetItem item, bool hide)

### QTreeWidget.setItemSelected (self, QTreeWidgetItem item, bool select)

### QTreeWidget.setItemWidget (self, QTreeWidgetItem item, int column, QWidget widget)

The widget argument has it's ownership transferred to Qt.

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

The given widget's 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 QItemDelegate 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 the widget.

This function was introduced in Qt 4.1.

See also itemWidget() and Delegate Classes.

### QTreeWidget.setSelectionModel (self, QItemSelectionModel selectionModel)

Reimplemented from QAbstractItemView.setSelectionModel().

### QTreeWidget.setSortingEnabled (self, bool enable)

### int QTreeWidget.sortColumn (self)

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

This function was introduced in Qt 4.1.

See also sortItems().

### QTreeWidget.sortItems (self, 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().

### Qt.DropActions QTreeWidget.supportedDropActions (self)

Returns the drop actions supported by this view.

See also Qt.DropActions.

### QTreeWidgetItem QTreeWidget.takeTopLevelItem (self, int index)

The QTreeWidgetItem result

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

See also insertTopLevelItem(), topLevelItem(), and topLevelItemCount().

### QTreeWidgetItem QTreeWidget.topLevelItem (self, int index)

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

See also topLevelItemCount() and insertTopLevelItem().

### int QTreeWidget.topLevelItemCount (self)

### QRect QTreeWidget.visualItemRect (self, QTreeWidgetItem item)

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

See also itemAt().

## Qt Signal Documentation

### void currentItemChanged (QTreeWidgetItem *,QTreeWidgetItem *)

This is the default overload of this 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().

### void itemActivated (QTreeWidgetItem *,int)

This is the default overload of this 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., Enter).

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

### void itemChanged (QTreeWidgetItem *,int)

This is the default overload of this signal.

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

### void itemClicked (QTreeWidgetItem *,int)

This is the default overload of this 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.

### void itemCollapsed (QTreeWidgetItem *)

This is the default overload of this 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(), and collapseItem().

### void itemDoubleClicked (QTreeWidgetItem *,int)

This is the default overload of this signal.

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

The specified item is the item that was clicked, or 0 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.

### void itemEntered (QTreeWidgetItem *,int)

This is the default overload of this 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.

### void itemExpanded (QTreeWidgetItem *)

This is the default overload of this signal.

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

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

See also setItemExpanded(), QTreeWidgetItem.isExpanded(), itemCollapsed(), and expandItem().

### void itemPressed (QTreeWidgetItem *,int)

This is the default overload of this 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 0 if no item was clicked. The column is the item's column that was clicked, or -1 if no item was clicked.

### void itemSelectionChanged ()

This is the default overload of this signal.

This signal is emitted when the selection changes in the tree widget. The current selection can be found with selectedItems().