QTreeWidget Class Reference

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

  1. #include <QTreeWidget>

Inherits: QTreeView.

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:

  1. QTreeWidget *treeWidget = new QTreeWidget();
  2. treeWidget->setColumnCount(1);
  3. for (int i = 0; i < 10; ++i)
  4.     items.append(new QTreeWidgetItem((QTreeWidget*)0, QStringList(QString("item: %1").arg(i))));
  5. 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.

Screenshot of a Windows XP style tree widget

Screenshot of a Windows XP style tree widget

Screenshot of a Macintosh style tree widget

Screenshot of a Macintosh style tree widget

Screenshot of a Plastique style tree widget

Screenshot of a Plastique style tree widget

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

See also QTreeWidgetItem, QTreeWidgetItemIterator, QTreeView, Model/View Programming, and Settings Editor Example.

Properties

Toggle detailscolumnCountcolumnCount : int

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

By default, this property has a value of 1.

Access functions:

Look up this member in the source code.

Toggle detailstopLevelItemCounttopLevelItemCount : const int

This property holds the number of top-level items

By default, this property has a value of 0.

See also columnCount() and currentItem().

Access functions:

    Look up this member in the source code.

      Public Functions

      Toggle details QTreeWidget

      QTreeWidgetQTreeWidget ( QWidget *parent=0 ) ( QWidget *parent=0 )

      Constructs a tree widget with the given parent.

      Look up this member in the source code.

      Toggle details QTreeWidget

      ~QTreeWidget~QTreeWidget () ()

      Destroys the tree widget and all its items.

      Look up this member in the source code.

      Toggle details void QTreeWidget

      addTopLevelItemaddTopLevelItem ( QTreeWidgetItem *item ) ( QTreeWidgetItem *item )

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

      See also insertTopLevelItem().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      addTopLevelItemsaddTopLevelItems ( const QList <QTreeWidgetItem *> &items ...) ( const QList <QTreeWidgetItem *> &items )

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

      See also insertTopLevelItems().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      closePersistentEditorclosePersistentEditor ( QTreeWidgetItem *item , int column=0 ...) ( 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().

      Look up this member in the source code.

      Toggle details int QTreeWidget

      currentColumncurrentColumn () ()const

      Returns the current column in the tree widget.

      See also setCurrentItem() and columnCount().

      Look up this member in the source code.

      Toggle details QTreeWidgetItem * QTreeWidget

      currentItemcurrentItem () ()const

      Returns the current item in the tree widget.

      See also setCurrentItem() and currentItemChanged().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      dropEventdropEvent ( QDropEvent *event ) ( QDropEvent *event ) [virtual protected]

      Reimplemented from QWidget::dropEvent().

      Look up this member in the source code.

      Toggle details bool QTreeWidget

      dropMimeDatadropMimeData ( QTreeWidgetItem *parent , int index , const QMimeData *data , Qt::DropAction action ...) ( QTreeWidgetItem *parent , int index , const QMimeData *data , Qt::DropAction action ) [virtual protected]

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

      Look up this member in the source code.

      Toggle details void QTreeWidget

      editItemeditItem ( QTreeWidgetItem *item , int column=0 ...) ( QTreeWidgetItem *item , int column=0 )

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

      Look up this member in the source code.

      Toggle details bool QTreeWidget

      eventevent ( QEvent *e ) ( QEvent *e ) [virtual protected]

      Reimplemented from QObject::event().

      Look up this member in the source code.

      Toggle details QList <QTreeWidgetItem *> QTreeWidget

      findItemsfindItems ( const QString &text , Qt::MatchFlags flags , int column=0 ...) ( 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.

      Look up this member in the source code.

      Toggle details QTreeWidgetItem * QTreeWidget

      headerItemheaderItem () ()const

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

      See also setHeaderItem().

      Look up this member in the source code.

      Toggle details QModelIndex QTreeWidget

      indexFromItemindexFromItem ( QTreeWidgetItem *item , int column=0 ...) ( QTreeWidgetItem *item , int column=0 )const[protected]

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

      See also itemFromIndex() and topLevelItem().

      Look up this member in the source code.

      Toggle details int QTreeWidget

      indexOfTopLevelItemindexOfTopLevelItem ( QTreeWidgetItem *item ) ( QTreeWidgetItem *item )const

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

      See also sortItems() and topLevelItemCount().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      insertTopLevelIteminsertTopLevelItem ( int index , QTreeWidgetItem *item ...) ( 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 wont be inserted.

      See also addTopLevelItem() and columnCount().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      insertTopLevelItemsinsertTopLevelItems ( int index , const QList <QTreeWidgetItem *> &items ...) ( 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 wont be inserted.

      See also addTopLevelItems().

      Look up this member in the source code.

      Toggle details QTreeWidgetItem * QTreeWidget

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

      Look up this member in the source code.

      Toggle details bool QTreeWidget

      isFirstItemColumnSpannedisFirstItemColumnSpanned ( const QTreeWidgetItem *item ...) ( const QTreeWidgetItem *item )const

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

      See also setFirstItemColumnSpanned().

      Look up this member in the source code.

      Toggle details QTreeWidgetItem * QTreeWidget

      itemAboveitemAbove ( const QTreeWidgetItem *item ...) ( const QTreeWidgetItem *item )const

      Returns the item above the given item.

      Look up this member in the source code.

      Toggle details QTreeWidgetItem * QTreeWidget

      itemAtitemAt ( const QPoint &p ) ( const QPoint &p )const

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

      See also visualItemRect().

      Look up this member in the source code.

      Toggle details QTreeWidgetItem * QTreeWidget

      itemAtitemAt ( int x , int y ) ( int x , int y )const

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

      Look up this member in the source code.

      Toggle details QTreeWidgetItem * QTreeWidget

      itemBelowitemBelow ( const QTreeWidgetItem *item ...) ( const QTreeWidgetItem *item )const

      Returns the item visually below the given item.

      Look up this member in the source code.

      Toggle details QTreeWidgetItem * QTreeWidget

      itemFromIndexitemFromIndex ( const QModelIndex &index ...) ( const QModelIndex &index )const[protected]

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

      See also indexFromItem().

      Look up this member in the source code.

      Toggle details QWidget * QTreeWidget

      itemWidgetitemWidget ( QTreeWidgetItem *item , int column ...) ( QTreeWidgetItem *item , int column )const

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

      Note: The tree takes ownership of the widget.

      See also setItemWidget().

      Look up this member in the source code.

      Toggle details QMimeData * QTreeWidget

      mimeDatamimeData ( const QList <QTreeWidgetItem *>items ...) ( const QList <QTreeWidgetItem *>items )const [virtual protected]

      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.

      Look up this member in the source code.

      Toggle details QStringList QTreeWidget

      mimeTypesmimeTypes () ()const [virtual protected]

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

      See also mimeData().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      openPersistentEditoropenPersistentEditor ( QTreeWidgetItem *item , int column=0 ...) ( QTreeWidgetItem *item , int column=0 )

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

      See also closePersistentEditor().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      removeItemWidgetremoveItemWidget ( QTreeWidgetItem *item , int column ...) ( QTreeWidgetItem *item , int column )

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

      Look up this member in the source code.

      Toggle details QList <QTreeWidgetItem *> QTreeWidget

      selectedItemsselectedItems () ()const

      Returns a list of all selected non-hidden items.

      See also itemSelectionChanged().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      setCurrentItemsetCurrentItem ( QTreeWidgetItem *item ) ( 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().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      setCurrentItemsetCurrentItem ( QTreeWidgetItem *item , int column ...) ( QTreeWidgetItem *item , int column )

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

      See also currentItem().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      setCurrentItemsetCurrentItem ( QTreeWidgetItem *item , int column , QItemSelectionModel::SelectionFlags command ...) ( 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().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      setFirstItemColumnSpannedsetFirstItemColumnSpanned ( const QTreeWidgetItem *item , bool span ...) ( const 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.

      See also isFirstItemColumnSpanned().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      setHeaderItemsetHeaderItem ( QTreeWidgetItem *item ) ( 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() and setHeaderLabels().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      setHeaderLabelsetHeaderLabel ( const QString &label ) ( const QString &label )

      Same as setHeaderLabels(QStringList(label)).

      Look up this member in the source code.

      Toggle details void QTreeWidget

      setHeaderLabelssetHeaderLabels ( const QStringList &labels ) ( 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() and setHeaderLabel().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      setItemWidgetsetItemWidget ( QTreeWidgetItem *item , int column , QWidget *widget ...) ( 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 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.

      See also itemWidget() and Delegate Classes.

      Look up this member in the source code.

      Toggle details void QTreeWidget

      setSelectionModelsetSelectionModel ( QItemSelectionModel *selectionModel ...) ( QItemSelectionModel *selectionModel ) [virtual]

      Reimplemented from QAbstractItemView::setSelectionModel().

      Look up this member in the source code.

      Toggle details int QTreeWidget

      sortColumnsortColumn () ()const

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

      See also sortItems().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      sortItemssortItems ( int column , Qt::SortOrder order ) ( 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().

      Look up this member in the source code.

      Toggle details Qt::DropActions QTreeWidget

      supportedDropActionssupportedDropActions () ()const [virtual protected]

      Returns the drop actions supported by this view.

      See also Qt::DropActions.

      Look up this member in the source code.

      Toggle details QTreeWidgetItem * QTreeWidget

      takeTopLevelItemtakeTopLevelItem ( int index ) ( int index )

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

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

      Look up this member in the source code.

      Toggle details QTreeWidgetItem * QTreeWidget

      topLevelItemtopLevelItem ( int index ) ( int index )const

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

      See also topLevelItemCount() and insertTopLevelItem().

      Look up this member in the source code.

      Toggle details QRect QTreeWidget

      visualItemRectvisualItemRect ( const QTreeWidgetItem *item ) ( const QTreeWidgetItem *item )const

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

      See also itemAt().

      Look up this member in the source code.

      Toggle details bool QTreeWidget

      isItemExpandedisItemExpanded ( const QTreeWidgetItem *item ) ( const QTreeWidgetItem *item )const Obsolete function

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

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

      See also itemExpanded().

      Look up this member in the source code.

      Toggle details bool QTreeWidget

      isItemHiddenisItemHidden ( const QTreeWidgetItem *item ) ( const QTreeWidgetItem *item )const Obsolete function

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

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

      Look up this member in the source code.

      Toggle details bool QTreeWidget

      isItemSelectedisItemSelected ( const QTreeWidgetItem *item ) ( const QTreeWidgetItem *item )const Obsolete function

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

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

      See also itemSelectionChanged().

      Look up this member in the source code.

      Toggle details QList <QTreeWidgetItem *> QTreeWidget

      itemsitems ( const QMimeData *data ...) ( const QMimeData *data )const[protected] Obsolete function

      Returns an empty list

      See also mimeData().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      setItemExpandedsetItemExpanded ( const QTreeWidgetItem *item , bool expand ...) ( const QTreeWidgetItem *item , bool expand ) Obsolete function

      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.

      See also expandItem(), collapseItem(), and itemExpanded().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      setItemHiddensetItemHidden ( const QTreeWidgetItem *item , bool hide ...) ( const QTreeWidgetItem *item , bool hide ) Obsolete function

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

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

      See also isItemHidden() and itemChanged().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      setItemSelectedsetItemSelected ( const QTreeWidgetItem *item , bool select ...) ( const QTreeWidgetItem *item , bool select ) Obsolete function

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

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

      See also isItemSelected() and itemSelectionChanged().

      Look up this member in the source code.

      Signals

      Toggle details void QTreeWidget

      currentItemChangedcurrentItemChanged ( QTreeWidgetItem *current , QTreeWidgetItem *previous ...) ( 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().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      itemActivateditemActivated ( QTreeWidgetItem *item , int column ...) ( 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., 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.

      Look up this member in the source code.

      Toggle details void QTreeWidget

      itemChangeditemChanged ( QTreeWidgetItem *item , int column ...) ( QTreeWidgetItem *item , int column ) [signal]

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

      Look up this member in the source code.

      Toggle details void QTreeWidget

      itemClickeditemClicked ( QTreeWidgetItem *item , int column ...) ( 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.

      Look up this member in the source code.

      Toggle details void QTreeWidget

      itemCollapseditemCollapsed ( QTreeWidgetItem *item ) ( 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(), and collapseItem().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      itemDoubleClickeditemDoubleClicked ( QTreeWidgetItem *item , int column ...) ( 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 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.

      Look up this member in the source code.

      Toggle details void QTreeWidget

      itemEntereditemEntered ( QTreeWidgetItem *item , int column ...) ( 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.

      Look up this member in the source code.

      Toggle details void QTreeWidget

      itemExpandeditemExpanded ( QTreeWidgetItem *item ) ( QTreeWidgetItem *item ) [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().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      itemPresseditemPressed ( QTreeWidgetItem *item , int column ...) ( 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 0 if no item was clicked. The column is the item's column that was clicked, or -1 if no item was clicked.

      Look up this member in the source code.

      Toggle details void QTreeWidget

      itemSelectionChangeditemSelectionChanged () () [signal]

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

      Look up this member in the source code.

      Public Slots

      Toggle details void QTreeWidget

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

      Look up this member in the source code.

      Toggle details void QTreeWidget

      collapseItemcollapseItem ( const QTreeWidgetItem *item ) ( const QTreeWidgetItem *item ) [slot]

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

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

      Look up this member in the source code.

      Toggle details void QTreeWidget

      expandItemexpandItem ( const QTreeWidgetItem *item ) ( 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(), and itemExpanded().

      Look up this member in the source code.

      Toggle details void QTreeWidget

      scrollToItemscrollToItem ( const QTreeWidgetItem *item , QAbstractItemView::ScrollHint hint=EnsureVisible ...) ( 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(), and topLevelItem().

      Look up this member in the source code.

      Notes provided by the Qt Community

      No notes