Contents

• Properties
• Public Functions
• Reimplemented Public Functions
• Public Slots
• Signals
• Protected Functions
• Reimplemented Protected Functions
• Detailed Description

Detailed Description

TheQTreeWidget class provides a tree view that uses a predefined tree model.

TheQTreeWidget class is a convenience class that provides a standard tree widget with a classic item-based interface similar to that used by theQListView 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 aQTreeWidgetItem.

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 aQTreeView 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=newQTreeWidget();treeWidget->setColumnCount(1);QList<QTreeWidgetItem*> items;for (int i=0; i<10;++i)    items.append(newQTreeWidgetItem((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 withsetColumnCount(). This allows each item to have one or more labels or other decorations. The number of columns in use can be found with thecolumnCount() 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 withsetHeaderLabels(), but a custom header can be constructed with aQTreeWidgetItem and inserted into the tree with thesetHeaderItem() 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 callingsetSortingEnabled(). TheisSortingEnabled() function indicates whether sorting is enabled.

AWindows XP style tree widget.	AMacintosh style tree widget.	APlastique style tree widget.

Property Documentation

columnCount :int

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

By default, this property has a value of 1.

Access functions:

topLevelItemCount : constint

This property holds the number of top-level items.

By default, this property has a value of 0.

Access functions:

See alsocolumnCount() andcurrentItem().

Member Function Documentation

QTreeWidget::QTreeWidget(QWidget * parent = 0)

Constructs a tree widget with the givenparent.

QTreeWidget::~QTreeWidget()

Destroys the tree widget and all its items.

void QTreeWidget::addTopLevelItem(QTreeWidgetItem * item)

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

This function was introduced in Qt 4.1.

See alsoinsertTopLevelItem().

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

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

See alsoinsertTopLevelItems().

[slot]void 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 ofQTreeWidgetItem::treeWidget() will be invalid when called from an item's destructor.

See alsotakeTopLevelItem(),topLevelItemCount(), andcolumnCount().

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

Closes the persistent editor for theitem in the givencolumn.

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

See alsoopenPersistentEditor().

[slot]void QTreeWidget::collapseItem(constQTreeWidgetItem * item)

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

See alsoexpandItem(),currentItem(),itemAt(), andtopLevelItem().

int QTreeWidget::currentColumn() const

Returns the current column in the tree widget.

This function was introduced in Qt 4.1.

See alsosetCurrentItem() andcolumnCount().

QTreeWidgetItem * QTreeWidget::currentItem() const

Returns the current item in the tree widget.

See alsosetCurrentItem() andcurrentItemChanged().

[signal]void QTreeWidget::currentItemChanged(QTreeWidgetItem * current,QTreeWidgetItem * previous)

This signal is emitted when the current item changes. The current item is specified bycurrent, and this replaces theprevious current item.

See alsosetCurrentItem().

[virtual protected]void QTreeWidget::dropEvent(QDropEvent * event)

Reimplemented fromQWidget::dropEvent().

[virtual protected]bool QTreeWidget::dropMimeData(QTreeWidgetItem * parent,int index, constQMimeData * data,Qt::DropAction action)

Handles thedata supplied by a drag and drop operation that ended with the givenaction in theindex in the givenparent 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 alsosupportedDropActions().

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

Starts editing theitem in the givencolumn if it is editable.

[virtual protected]bool QTreeWidget::event(QEvent * e)

Reimplemented fromQObject::event().

[slot]void QTreeWidget::expandItem(constQTreeWidgetItem * item)

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

See alsocollapseItem(),currentItem(),itemAt(),topLevelItem(), anditemExpanded().

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

Returns a list of items that match the giventext, using the givenflags, in the givencolumn.

QTreeWidgetItem * QTreeWidget::headerItem() const

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

See alsosetHeaderItem().

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

Returns theQModelIndex assocated with the givenitem in the givencolumn.

See alsoitemFromIndex() andtopLevelItem().

int QTreeWidget::indexOfTopLevelItem(QTreeWidgetItem * item) const

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

See alsosortItems() andtopLevelItemCount().

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

Inserts theitem atindex in the top level in the view.

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

See alsoaddTopLevelItem() andcolumnCount().

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

Inserts the list ofitems atindex 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 alsoaddTopLevelItems().

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 theQTreeWidgetItem 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(constQTreeWidgetItem * item) const

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

This function was introduced in Qt 4.3.

See alsosetFirstItemColumnSpanned().

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

Returns the item above the givenitem.

This function was introduced in Qt 4.3.

[signal]void QTreeWidget::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. on theQStyle::SH_ItemView_ActivateItemOnSingleClick style hint) or pressing a special key (e.g.,Enter).

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

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

Returns a pointer to the item at the coordinatesp. The coordinates are relative to the tree widget'sviewport().

See alsovisualItemRect().

QTreeWidgetItem * QTreeWidget::itemAt(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'sviewport().

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

Returns the item visually below the givenitem.

This function was introduced in Qt 4.3.

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

This signal is emitted when the contents of thecolumn in the specifieditem changes.

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

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

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

[signal]void QTreeWidget::itemCollapsed(QTreeWidgetItem * item)

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

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

See alsoQTreeWidgetItem::isExpanded(),itemExpanded(), andcollapseItem().

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

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

The specifieditem is the item that was clicked, or 0 if no item was clicked. Thecolumn is the item's column that was clicked. If no item was double clicked, no signal will be emitted.

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

This signal is emitted when the mouse cursor enters anitem over the specifiedcolumn.QTreeWidget mouse tracking needs to be enabled for this feature to work.

[signal]void QTreeWidget::itemExpanded(QTreeWidgetItem * item)

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

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

See alsosetItemExpanded(),QTreeWidgetItem::isExpanded(),itemCollapsed(), andexpandItem().

[protected]QTreeWidgetItem * QTreeWidget::itemFromIndex(constQModelIndex & index) const

Returns a pointer to theQTreeWidgetItem assocated with the givenindex.

See alsoindexFromItem().

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

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

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

[signal]void QTreeWidget::itemSelectionChanged()

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

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

Returns the widget displayed in the cell specified byitem and the givencolumn.

Note:The tree takes ownership of the widget.

This function was introduced in Qt 4.1.

See alsosetItemWidget().

[virtual protected]QMimeData * QTreeWidget::mimeData(constQList<QTreeWidgetItem *> items) const

Returns an object that contains a serialized description of the specifieditems. The format used to describe the items is obtained from themimeTypes() function.

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

[virtual protected]QStringList QTreeWidget::mimeTypes() const

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

See alsomimeData().

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

Opens a persistent editor for theitem in the givencolumn.

See alsoclosePersistentEditor().

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

Removes the widget set in the givenitem in the givencolumn.

This function was introduced in Qt 4.3.

[slot]void QTreeWidget::scrollToItem(constQTreeWidgetItem * item,QAbstractItemView::ScrollHint hint = EnsureVisible)

Ensures that theitem is visible, scrolling the view if necessary using the specifiedhint.

See alsocurrentItem(),itemAt(), andtopLevelItem().

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

Returns a list of all selected non-hidden items.

See alsoitemSelectionChanged().

void QTreeWidget::setCurrentItem(QTreeWidgetItem * item)

Sets the currentitem in the tree widget.

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

See alsocurrentItem() andcurrentItemChanged().

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

Sets the currentitem in the tree widget and the current column tocolumn.

This function was introduced in Qt 4.1.

See alsocurrentItem().

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

Sets the currentitem in the tree widget and the current column tocolumn, using the givencommand.

This function was introduced in Qt 4.4.

See alsocurrentItem().

void QTreeWidget::setFirstItemColumnSpanned(constQTreeWidgetItem * item,bool span)

Sets the givenitem to only show one section for all columns ifspan is true; otherwise the item will show one section per column.

This function was introduced in Qt 4.3.

See alsoisFirstItemColumnSpanned().

void QTreeWidget::setHeaderItem(QTreeWidgetItem * item)

Sets the headeritem 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 alsoheaderItem() andsetHeaderLabels().

void QTreeWidget::setHeaderLabel(constQString & label)

Same assetHeaderLabels(QStringList(label)).

This function was introduced in Qt 4.2.

void QTreeWidget::setHeaderLabels(constQStringList & labels)

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

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

See alsosetHeaderItem() andsetHeaderLabel().

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

Sets the givenwidget to be displayed in the cell specified by the givenitem andcolumn.

The givenwidget'sautoFillBackground 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, useQTreeView and subclassQItemDelegate instead.

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

Note:The tree takes ownership of the widget.

This function was introduced in Qt 4.1.

See alsoitemWidget() andDelegate Classes.

[virtual]void QTreeWidget::setSelectionModel(QItemSelectionModel * selectionModel)

Reimplemented fromQAbstractItemView::setSelectionModel().

int QTreeWidget::sortColumn() const

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

This function was introduced in Qt 4.1.

See alsosortItems().

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

Sorts the items in the widget in the specifiedorder by the values in the givencolumn.

See alsosortColumn().

[virtual protected]Qt::DropActions QTreeWidget::supportedDropActions() const

Returns the drop actions supported by this view.

See alsoQt::DropActions.

QTreeWidgetItem * QTreeWidget::takeTopLevelItem(int index)

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

See alsoinsertTopLevelItem(),topLevelItem(), andtopLevelItemCount().

QTreeWidgetItem * QTreeWidget::topLevelItem(int index) const

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

See alsotopLevelItemCount() andinsertTopLevelItem().

QRect QTreeWidget::visualItemRect(constQTreeWidgetItem * item) const

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

See alsoitemAt().