Table Of Contents

Previous topic

QTreeView

Next topic

QListView

QTreeWidget

Inheritance diagram of QTreeWidget

Synopsis

Functions

Virtual functions

Slots

Signals

Detailed Description

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

The PySide.QtGui.QTreeWidget class is a convenience class that provides a standard tree widget with a classic item-based interface similar to that used by the PySide.QtGui.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 PySide.QtGui.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 PySide.QtGui.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:

treeWidget = QTreeWidget()
treeWidget.setColumnCount(1)
items = []
for i in range(10):
    items.append(QTreeWidgetItem(None, QStringList(QString("item: %1").arg(i))))
treeWidget.insertTopLevelItems(None, items)

Before items can be added to the tree widget, the number of columns must be set with PySide.QtGui.QTreeWidget.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 PySide.QtGui.QTreeWidget.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 PySide.QtGui.QTreeWidget.setHeaderLabels() , but a custom header can be constructed with a PySide.QtGui.QTreeWidgetItem and inserted into the tree with the PySide.QtGui.QTreeWidget.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 PySide.QtGui.QTreeView.setSortingEnabled() . The PySide.QtGui.QTreeView.isSortingEnabled() function indicates whether sorting is enabled.

../../_images/windowsxp-treeview.png ../../_images/macintosh-treeview.png ../../_images/plastique-treeview.png
A Windows XP style tree widget. A Macintosh style tree widget. A Plastique style tree widget.

See also

PySide.QtGui.QTreeWidgetItem PySide.QtGui.QTreeWidgetItemIterator PySide.QtGui.QTreeView Model/View Programming Settings Editor Example

class PySide.QtGui.QTreeWidget([parent=None])
Parameters:parentPySide.QtGui.QWidget

Constructs a tree widget with the given parent .

PySide.QtGui.QTreeWidget.addTopLevelItem(item)
Parameters:itemPySide.QtGui.QTreeWidgetItem

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

PySide.QtGui.QTreeWidget.addTopLevelItems(items)
Parameters:items
PySide.QtGui.QTreeWidget.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.

PySide.QtGui.QTreeWidget.closePersistentEditor(item[, column=0])
Parameters:

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.

PySide.QtGui.QTreeWidget.collapseItem(item)
Parameters:itemPySide.QtGui.QTreeWidgetItem

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

PySide.QtGui.QTreeWidget.columnCount()
Return type:PySide.QtCore.int

This property holds the number of columns displayed in the tree widget.

By default, this property has a value of 1.

PySide.QtGui.QTreeWidget.currentColumn()
Return type:PySide.QtCore.int

Returns the current column in the tree widget.

PySide.QtGui.QTreeWidget.currentItem()
Return type:PySide.QtGui.QTreeWidgetItem

Returns the current item in the tree widget.

PySide.QtGui.QTreeWidget.currentItemChanged(current, previous)
Parameters:
PySide.QtGui.QTreeWidget.dropMimeData(parent, index, data, action)
Parameters:
Return type:

PySide.QtCore.bool

PySide.QtGui.QTreeWidget.editItem(item[, column=0])
Parameters:

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

PySide.QtGui.QTreeWidget.expandItem(item)
Parameters:itemPySide.QtGui.QTreeWidgetItem

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

PySide.QtGui.QTreeWidget.findItems(text, flags[, column=0])
Parameters:
  • text – unicode
  • flagsPySide.QtCore.Qt.MatchFlags
  • columnPySide.QtCore.int
Return type:

PySide.QtGui.QTreeWidget.headerItem()
Return type:PySide.QtGui.QTreeWidgetItem

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

PySide.QtGui.QTreeWidget.indexFromItem(item[, column=0])
Parameters:
Return type:

PySide.QtCore.QModelIndex

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

PySide.QtGui.QTreeWidget.indexOfTopLevelItem(item)
Parameters:itemPySide.QtGui.QTreeWidgetItem
Return type:PySide.QtCore.int

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

PySide.QtGui.QTreeWidget.insertTopLevelItem(index, item)
Parameters:

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.

PySide.QtGui.QTreeWidget.insertTopLevelItems(index, items)
Parameters:
  • indexPySide.QtCore.int
  • items
PySide.QtGui.QTreeWidget.invisibleRootItem()
Return type:PySide.QtGui.QTreeWidgetItem

Returns the tree widget’s invisible root item.

The invisible root item provides access to the tree widget’s top-level items through the PySide.QtGui.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.

PySide.QtGui.QTreeWidget.isFirstItemColumnSpanned(item)
Parameters:itemPySide.QtGui.QTreeWidgetItem
Return type:PySide.QtCore.bool

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

PySide.QtGui.QTreeWidget.isItemExpanded(item)
Parameters:itemPySide.QtGui.QTreeWidgetItem
Return type:PySide.QtCore.bool

Returns true if the given item is open; otherwise returns false.

This function is deprecated. Use QTreeWidgetItem.isExpanded() instead.

PySide.QtGui.QTreeWidget.isItemHidden(item)
Parameters:itemPySide.QtGui.QTreeWidgetItem
Return type:PySide.QtCore.bool

Returns true if the item is explicitly hidden, otherwise returns false.

This function is deprecated. Use QTreeWidgetItem.isHidden() instead.

PySide.QtGui.QTreeWidget.isItemSelected(item)
Parameters:itemPySide.QtGui.QTreeWidgetItem
Return type:PySide.QtCore.bool

Returns true if the item is selected; otherwise returns false.

This function is deprecated. Use QTreeWidgetItem.isSelected() instead.

PySide.QtGui.QTreeWidget.itemAbove(item)
Parameters:itemPySide.QtGui.QTreeWidgetItem
Return type:PySide.QtGui.QTreeWidgetItem

Returns the item above the given item .

PySide.QtGui.QTreeWidget.itemActivated(item, column)
Parameters:
PySide.QtGui.QTreeWidget.itemAt(x, y)
Parameters:
  • xPySide.QtCore.int
  • yPySide.QtCore.int
Return type:

PySide.QtGui.QTreeWidgetItem

This is an overloaded function.

Returns a pointer to the item at the coordinates (x , y ).

PySide.QtGui.QTreeWidget.itemAt(p)
Parameters:pPySide.QtCore.QPoint
Return type:PySide.QtGui.QTreeWidgetItem

Returns a pointer to the item at the coordinates p .

PySide.QtGui.QTreeWidget.itemBelow(item)
Parameters:itemPySide.QtGui.QTreeWidgetItem
Return type:PySide.QtGui.QTreeWidgetItem

Returns the item visually below the given item .

PySide.QtGui.QTreeWidget.itemChanged(item, column)
Parameters:
PySide.QtGui.QTreeWidget.itemClicked(item, column)
Parameters:
PySide.QtGui.QTreeWidget.itemCollapsed(item)
Parameters:itemPySide.QtGui.QTreeWidgetItem
PySide.QtGui.QTreeWidget.itemDoubleClicked(item, column)
Parameters:
PySide.QtGui.QTreeWidget.itemEntered(item, column)
Parameters:
PySide.QtGui.QTreeWidget.itemExpanded(item)
Parameters:itemPySide.QtGui.QTreeWidgetItem
PySide.QtGui.QTreeWidget.itemFromIndex(index)
Parameters:indexPySide.QtCore.QModelIndex
Return type:PySide.QtGui.QTreeWidgetItem

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

PySide.QtGui.QTreeWidget.itemPressed(item, column)
Parameters:
PySide.QtGui.QTreeWidget.itemSelectionChanged()
PySide.QtGui.QTreeWidget.itemWidget(item, column)
Parameters:
Return type:

PySide.QtGui.QWidget

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

Note

The tree takes ownership of the widget.

PySide.QtGui.QTreeWidget.mimeData(items)
Parameters:items
Return type:PySide.QtCore.QMimeData
PySide.QtGui.QTreeWidget.mimeTypes()
Return type:list of strings

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

PySide.QtGui.QTreeWidget.openPersistentEditor(item[, column=0])
Parameters:

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

PySide.QtGui.QTreeWidget.removeItemWidget(item, column)
Parameters:

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

PySide.QtGui.QTreeWidget.scrollToItem(item[, hint=EnsureVisible])
Parameters:
PySide.QtGui.QTreeWidget.selectedItems()
Return type:

Returns a list of all selected non-hidden items.

PySide.QtGui.QTreeWidget.setColumnCount(columns)
Parameters:columnsPySide.QtCore.int

This property holds the number of columns displayed in the tree widget.

By default, this property has a value of 1.

PySide.QtGui.QTreeWidget.setCurrentItem(item, column)
Parameters:

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

PySide.QtGui.QTreeWidget.setCurrentItem(item, column, command)
Parameters:
PySide.QtGui.QTreeWidget.setCurrentItem(item)
Parameters:itemPySide.QtGui.QTreeWidgetItem

Sets the current item in the tree widget.

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

PySide.QtGui.QTreeWidget.setFirstItemColumnSpanned(item, span)
Parameters:

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.

PySide.QtGui.QTreeWidget.setHeaderItem(item)
Parameters:itemPySide.QtGui.QTreeWidgetItem

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.

PySide.QtGui.QTreeWidget.setHeaderLabel(label)
Parameters:label – unicode

Same as setHeaderLabels( PySide.QtCore.QStringList (label )).

PySide.QtGui.QTreeWidget.setHeaderLabels(labels)
Parameters:labels – list of strings

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

Note that PySide.QtGui.QTreeWidget.setHeaderLabels() won’t remove existing columns.

PySide.QtGui.QTreeWidget.setItemExpanded(item, expand)
Parameters:

Sets the item referred to by item to either closed or opened, depending on the value of expand .

This function is deprecated. Use QTreeWidgetItem.setExpanded() instead.

PySide.QtGui.QTreeWidget.setItemHidden(item, hide)
Parameters:

Hides the given item if hide is true; otherwise shows the item.

This function is deprecated. Use QTreeWidgetItem.setHidden() instead.

PySide.QtGui.QTreeWidget.setItemSelected(item, select)
Parameters:

If select is true, the given item is selected; otherwise it is deselected.

This function is deprecated. Use QTreeWidgetItem.setSelected() instead.

PySide.QtGui.QTreeWidget.setItemWidget(item, column, widget)
Parameters:

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

The given widget ‘s PySide.QtGui.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 PySide.QtGui.QTreeView and subclass PySide.QtGui.QItemDelegate instead.

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

Note

The tree takes ownership of the widget.

See also

PySide.QtGui.QTreeWidget.itemWidget() Delegate Classes

PySide.QtGui.QTreeWidget.sortColumn()
Return type:PySide.QtCore.int

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

PySide.QtGui.QTreeWidget.sortItems(column, order)
Parameters:
  • columnPySide.QtCore.int
  • orderPySide.QtCore.Qt.SortOrder
PySide.QtGui.QTreeWidget.supportedDropActions()
Return type:PySide.QtCore.Qt.DropActions

Returns the drop actions supported by this view.

See also

Qt.DropActions

PySide.QtGui.QTreeWidget.takeTopLevelItem(index)
Parameters:indexPySide.QtCore.int
Return type:PySide.QtGui.QTreeWidgetItem

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

PySide.QtGui.QTreeWidget.topLevelItem(index)
Parameters:indexPySide.QtCore.int
Return type:PySide.QtGui.QTreeWidgetItem

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

PySide.QtGui.QTreeWidget.topLevelItemCount()
Return type:PySide.QtCore.int

This property holds the number of top-level items.

By default, this property has a value of 0.

PySide.QtGui.QTreeWidget.visualItemRect(item)
Parameters:itemPySide.QtGui.QTreeWidgetItem
Return type:PySide.QtCore.QRect

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