QTreeWidget¶

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

Synopsis¶

Functions¶

def addTopLevelItem (item)
def addTopLevelItems (items)
def closePersistentEditor (item[, column=0])
def columnCount ()
def currentColumn ()
def currentItem ()
def editItem (item[, column=0])
def findItems (text, flags[, column=0])
def headerItem ()
def indexFromItem (item[, column=0])
def indexFromItem (item[, column=0])
def indexOfTopLevelItem (item)
def insertTopLevelItem (index, item)
def insertTopLevelItems (index, items)
def invisibleRootItem ()
def isFirstItemColumnSpanned (item)
def isItemExpanded (item)
def isItemHidden (item)
def isItemSelected (item)
def isPersistentEditorOpen (item[, column=0])
def itemAbove (item)
def itemAt (p)
def itemAt (x, y)
def itemBelow (item)
def itemFromIndex (index)
def itemWidget (item, column)
def items (data)
def openPersistentEditor (item[, column=0])
def removeItemWidget (item, column)
def selectedItems ()
def setColumnCount (columns)
def setCurrentItem (item)
def setCurrentItem (item, column)
def setCurrentItem (item, column, command)
def setFirstItemColumnSpanned (item, span)
def setHeaderItem (item)
def setHeaderLabel (label)
def setHeaderLabels (labels)
def setItemExpanded (item, expand)
def setItemHidden (item, hide)
def setItemSelected (item, select)
def setItemWidget (item, column, widget)
def sortColumn ()
def sortItems (column, order)
def takeTopLevelItem (index)
def topLevelItem (index)
def topLevelItemCount ()
def visualItemRect (item)

Virtual functions¶

def dropMimeData (parent, index, data, action)
def mimeData (items)
def mimeTypes ()
def supportedDropActions ()

Slots¶

def clear ()
def collapseItem (item)
def expandItem (item)
def scrollToItem (item[, hint=EnsureVisible])

Signals¶

def currentItemChanged (current, previous)
def itemActivated (item, column)
def itemChanged (item, column)
def itemClicked (item, column)
def itemCollapsed (item)
def itemDoubleClicked (item, column)
def itemEntered (item, column)
def itemExpanded (item)
def itemPressed (item, column)
def itemSelectionChanged ()

Detailed Description¶

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:
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 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.

See also

QTreeWidgetItem QTreeWidgetItemIterator QTreeView Model/View Programming Settings Editor Example

class QTreeWidget([parent=None])¶

param parent

QWidget

Constructs a tree widget with the given parent .

PySide2.QtWidgets.QTreeWidget.addTopLevelItem(item)¶

Parameters: item – QTreeWidgetItem

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

See also

insertTopLevelItem()

PySide2.QtWidgets.QTreeWidget.addTopLevelItems(items)¶

Parameters: items –

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

See also

insertTopLevelItems()

PySide2.QtWidgets.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 treeWidget() will be invalid when called from an item’s destructor.

See also

takeTopLevelItem() topLevelItemCount() columnCount()

PySide2.QtWidgets.QTreeWidget.closePersistentEditor(item[, column=0])¶

Parameters

item – QTreeWidgetItem
column – int

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.

PySide2.QtWidgets.QTreeWidget.collapseItem(item)¶

Parameters: item – QTreeWidgetItem

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

PySide2.QtWidgets.QTreeWidget.columnCount()¶

Return type: int

See also

setColumnCount()

PySide2.QtWidgets.QTreeWidget.currentColumn()¶

Return type: int

Returns the current column in the tree widget.

See also

setCurrentItem() columnCount()

PySide2.QtWidgets.QTreeWidget.currentItem()¶

Return type: QTreeWidgetItem

Returns the current item in the tree widget.

PySide2.QtWidgets.QTreeWidget.currentItemChanged(current, previous)¶

Parameters

current – QTreeWidgetItem
previous – QTreeWidgetItem

PySide2.QtWidgets.QTreeWidget.dropMimeData(parent, index, data, action)¶

Parameters

parent – QTreeWidgetItem
index – int
data – QMimeData
action – DropAction

Return type

bool

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

PySide2.QtWidgets.QTreeWidget.editItem(item[, column=0])¶

Parameters

item – QTreeWidgetItem
column – int

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

PySide2.QtWidgets.QTreeWidget.expandItem(item)¶

Parameters: item – QTreeWidgetItem

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

PySide2.QtWidgets.QTreeWidget.findItems(text, flags[, column=0])¶

Parameters

text – unicode
flags – MatchFlags
column – int

Return type

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

PySide2.QtWidgets.QTreeWidget.headerItem()¶

Return type: QTreeWidgetItem

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

See also

setHeaderItem()

PySide2.QtWidgets.QTreeWidget.indexFromItem(item[, column=0])¶

Parameters

item – QTreeWidgetItem
column – int

Return type

QModelIndex

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

PySide2.QtWidgets.QTreeWidget.indexFromItem(item[, column=0])¶

Parameters

item – QTreeWidgetItem
column – int

Return type

QModelIndex

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

PySide2.QtWidgets.QTreeWidget.indexOfTopLevelItem(item)¶

Parameters: item – QTreeWidgetItem
Return type: int

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

See also

sortItems() topLevelItemCount()

PySide2.QtWidgets.QTreeWidget.insertTopLevelItem(index, item)¶

Parameters

index – int
item – QTreeWidgetItem

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

PySide2.QtWidgets.QTreeWidget.insertTopLevelItems(index, items)¶

Parameters

index – int
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()

PySide2.QtWidgets.QTreeWidget.invisibleRootItem()¶

Return type: 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 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.

PySide2.QtWidgets.QTreeWidget.isFirstItemColumnSpanned(item)¶

Parameters: item – QTreeWidgetItem
Return type: bool

Note

This function is deprecated.

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

This function is deprecated. Use isFirstColumnSpanned() instead.

See also

setFirstItemColumnSpanned()

PySide2.QtWidgets.QTreeWidget.isItemExpanded(item)¶

Parameters: item – QTreeWidgetItem
Return type: bool

Note

This function is deprecated.

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

This function is deprecated. Use isExpanded() instead.

See also

itemExpanded()

PySide2.QtWidgets.QTreeWidget.isItemHidden(item)¶

Parameters: item – QTreeWidgetItem
Return type: bool

Note

This function is deprecated.

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

This function is deprecated. Use isHidden() instead.

PySide2.QtWidgets.QTreeWidget.isItemSelected(item)¶

Parameters: item – QTreeWidgetItem
Return type: bool

Note

This function is deprecated.

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

This function is deprecated. Use isSelected() instead.

See also

itemSelectionChanged()

PySide2.QtWidgets.QTreeWidget.isPersistentEditorOpen(item[, column=0])¶

Parameters

item – QTreeWidgetItem
column – int

Return type

bool

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

PySide2.QtWidgets.QTreeWidget.itemAbove(item)¶

Parameters: item – QTreeWidgetItem
Return type: QTreeWidgetItem

Returns the item above the given item .

PySide2.QtWidgets.QTreeWidget.itemActivated(item, column)¶

Parameters

item – QTreeWidgetItem
column – int

PySide2.QtWidgets.QTreeWidget.itemAt(p)¶

Parameters: p – QPoint
Return type: QTreeWidgetItem

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

See also

visualItemRect()

PySide2.QtWidgets.QTreeWidget.itemAt(x, y)¶

Parameters

x – int
y – int

Return type

QTreeWidgetItem

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

PySide2.QtWidgets.QTreeWidget.itemBelow(item)¶

Parameters: item – QTreeWidgetItem
Return type: QTreeWidgetItem

Returns the item visually below the given item .

PySide2.QtWidgets.QTreeWidget.itemChanged(item, column)¶

Parameters

item – QTreeWidgetItem
column – int

PySide2.QtWidgets.QTreeWidget.itemClicked(item, column)¶

Parameters

item – QTreeWidgetItem
column – int

PySide2.QtWidgets.QTreeWidget.itemCollapsed(item)¶

Parameters: item – QTreeWidgetItem

PySide2.QtWidgets.QTreeWidget.itemDoubleClicked(item, column)¶

Parameters

item – QTreeWidgetItem
column – int

PySide2.QtWidgets.QTreeWidget.itemEntered(item, column)¶

Parameters

item – QTreeWidgetItem
column – int

PySide2.QtWidgets.QTreeWidget.itemExpanded(item)¶

Parameters: item – QTreeWidgetItem

PySide2.QtWidgets.QTreeWidget.itemFromIndex(index)¶

Parameters: index – QModelIndex
Return type: QTreeWidgetItem

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

See also

indexFromItem()

PySide2.QtWidgets.QTreeWidget.itemPressed(item, column)¶

Parameters

item – QTreeWidgetItem
column – int

PySide2.QtWidgets.QTreeWidget.itemSelectionChanged()¶

PySide2.QtWidgets.QTreeWidget.itemWidget(item, column)¶

Parameters

item – QTreeWidgetItem
column – int

Return type

QWidget

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

See also

setItemWidget()

PySide2.QtWidgets.QTreeWidget.items(data)¶

Parameters: data – QMimeData
Return type

Returns an empty list

See also

mimeData()

PySide2.QtWidgets.QTreeWidget.mimeData(items)¶

Parameters: items –
Return type: QMimeData

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

PySide2.QtWidgets.QTreeWidget.mimeTypes()¶

Return type: list of strings

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

See also

mimeData()

PySide2.QtWidgets.QTreeWidget.openPersistentEditor(item[, column=0])¶

Parameters

item – QTreeWidgetItem
column – int

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

PySide2.QtWidgets.QTreeWidget.removeItemWidget(item, column)¶

Parameters

item – QTreeWidgetItem
column – int

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

PySide2.QtWidgets.QTreeWidget.scrollToItem(item[, hint=EnsureVisible])¶

Parameters

item – QTreeWidgetItem
hint – ScrollHint

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

PySide2.QtWidgets.QTreeWidget.selectedItems()¶

Return type

Returns a list of all selected non-hidden items.

See also

itemSelectionChanged()

PySide2.QtWidgets.QTreeWidget.setColumnCount(columns)¶

Parameters: columns – int

See also

columnCount()

PySide2.QtWidgets.QTreeWidget.setCurrentItem(item)¶

Parameters: item – QTreeWidgetItem

Sets the current item in the tree widget.

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

See also

currentItem() currentItemChanged()

PySide2.QtWidgets.QTreeWidget.setCurrentItem(item, column)¶

Parameters

item – QTreeWidgetItem
column – int

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

See also

currentItem()

PySide2.QtWidgets.QTreeWidget.setCurrentItem(item, column, command)¶

Parameters

item – QTreeWidgetItem
column – int
command – SelectionFlags

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

See also

currentItem()

PySide2.QtWidgets.QTreeWidget.setFirstItemColumnSpanned(item, span)¶

Parameters

item – QTreeWidgetItem
span – bool

Note

This function is deprecated.

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 is deprecated. Use setFirstColumnSpanned() instead.

See also

isFirstItemColumnSpanned()

PySide2.QtWidgets.QTreeWidget.setHeaderItem(item)¶

Parameters: item – 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.

See also

headerItem() setHeaderLabels()

PySide2.QtWidgets.QTreeWidget.setHeaderLabel(label)¶

Parameters: label – unicode

Same as setHeaderLabels ( QStringList (label )).

PySide2.QtWidgets.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 won’t remove existing columns.

See also

setHeaderItem() setHeaderLabel()

PySide2.QtWidgets.QTreeWidget.setItemExpanded(item, expand)¶

Parameters

item – QTreeWidgetItem
expand – bool

Note

This function is deprecated.

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

This function is deprecated. Use setExpanded() instead.

PySide2.QtWidgets.QTreeWidget.setItemHidden(item, hide)¶

Parameters

item – QTreeWidgetItem
hide – bool

Note

This function is deprecated.

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

This function is deprecated. Use setHidden() instead.

See also

isItemHidden() itemChanged()

PySide2.QtWidgets.QTreeWidget.setItemSelected(item, select)¶

Parameters

item – QTreeWidgetItem
select – bool

Note

This function is deprecated.

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

This function is deprecated. Use setSelected() instead.

PySide2.QtWidgets.QTreeWidget.setItemWidget(item, column, widget)¶

Parameters

item – QTreeWidgetItem
column – int
widget – QWidget

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 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 the widget.

See also

itemWidget() Delegate Classes

PySide2.QtWidgets.QTreeWidget.sortColumn()¶

Return type: int

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

See also

sortItems()

PySide2.QtWidgets.QTreeWidget.sortItems(column, order)¶

Parameters

column – int
order – SortOrder

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

See also

sortColumn()

PySide2.QtWidgets.QTreeWidget.supportedDropActions()¶

Return type: DropActions

Returns the drop actions supported by this view.

See also

DropActions

PySide2.QtWidgets.QTreeWidget.takeTopLevelItem(index)¶

Parameters: index – int
Return type: QTreeWidgetItem

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

PySide2.QtWidgets.QTreeWidget.topLevelItem(index)¶

Parameters: index – int
Return type: QTreeWidgetItem

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

PySide2.QtWidgets.QTreeWidget.topLevelItemCount()¶

Return type: int

PySide2.QtWidgets.QTreeWidget.visualItemRect(item)¶

Parameters: item – QTreeWidgetItem
Return type: QRect

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

See also

itemAt()

Qt Documentation

Table of Contents

Previous topic

Next topic

QTreeWidget¶

Synopsis¶

Functions¶

Virtual functions¶

Slots¶

Signals¶

Detailed Description¶