Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions |

# QTreeWidget Class Reference

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

    #include <QTreeWidget>

Inherits QTreeView.

- List of all members, including inherited members

### Writable Properties

- columnCount : int
- sortingEnabled : bool

- 2 writable properties inherited from QTreeView
- 7 writable properties inherited from QAbstractItemView
- 2 writable properties inherited from QViewport
- 5 writable properties inherited from QFrame
- 33 writable properties inherited from QWidget
- 1 writable property inherited from QObject

### Read-Only Properties

- 1 read-only property inherited from QViewport
- 1 read-only property inherited from QFrame
- 24 read-only properties inherited from QWidget

### Public Functions

- QTreeWidget ( QWidget * parent = 0 )
- ~QTreeWidget ()
- void appendTopLevelItem ( QTreeWidgetItem * item )
- void closePersistentEditor ( QTreeWidgetItem * item, int column = 0 )
- QTreeWidgetItem * currentItem () const
- QList<QTreeWidgetItem *> findItems ( const QString & text, QAbstractItemModel::MatchFlags flags = QAbstractItemModel::MatchDefault ) const
- QTreeWidgetItem * headerItem () const
- int indexOfTopLevelItem ( QTreeWidgetItem * item )
- void insertTopLevelItem ( int index, QTreeWidgetItem * item )
- bool isItemHidden ( const QTreeWidgetItem * item ) const
- bool isItemOpen ( const QTreeWidgetItem * item ) const
- bool isItemVisible ( const QTreeWidgetItem * item ) const
- bool isSelected ( const QTreeWidgetItem * item ) const
- void openPersistentEditor ( QTreeWidgetItem * item, int column = 0 )
- QList<QTreeWidgetItem *> selectedItems () const
- void setCurrentItem ( QTreeWidgetItem * item )
- void setHeaderItem ( QTreeWidgetItem * item )
- void setHeaderLabels ( const QStringList & labels )
- void setItemHidden ( const QTreeWidgetItem * item, bool hide )
- void setSelected ( const QTreeWidgetItem * item, bool select )
- void sortItems ( int column, Qt::SortOrder order )
- QTreeWidgetItem * takeTopLevelItem ( int index )
- QTreeWidgetItem * topLevelItem ( int index ) const
- int topLevelItemCount () const

- 16 public functions inherited from QTreeView
- 22 public functions inherited from QAbstractItemView
- 4 public functions inherited from QViewport
- 2 public functions inherited from QFrame
- 83 public functions inherited from QWidget
- 24 public functions inherited from QObject
- 2 public functions inherited from QPaintDevice

### Public Slots

- void clear ()
- void closeItem ( const QTreeWidgetItem * item )
- void ensureItemVisible ( const QTreeWidgetItem * item )
- void openItem ( const QTreeWidgetItem * item )
- void sortItems ( int column )

- 6 public slots inherited from QTreeView
- 6 public slots inherited from QAbstractItemView
- 16 public slots inherited from QWidget
- 1 public slot inherited from QObject

### Signals

- void aboutToShowContextMenu ( QMenu * menu, QTreeWidgetItem * item, int column )
- void clicked ( QTreeWidgetItem * item, int column, Qt::ButtonState button )
- void collapsed ( QTreeWidgetItem * item )
- void currentChanged ( QTreeWidgetItem * current, QTreeWidgetItem * previous )
- void doubleClicked ( QTreeWidgetItem * item, int column, Qt::ButtonState button )
- void expanded ( QTreeWidgetItem * item )
- void itemChanged ( QTreeWidgetItem * item, int column )
- void itemEntered ( QTreeWidgetItem * item, int column, Qt::ButtonState state )
- void keyPressed ( QTreeWidgetItem * item, int column, Qt::Key key, Qt::ButtonState button )
- void pressed ( QTreeWidgetItem * item, int column, Qt::ButtonState button )
- void returnPressed ( QTreeWidgetItem * item, int column )
- void selectionChanged ()

- 2 signals inherited from QTreeView
- 9 signals inherited from QAbstractItemView
- 1 signal inherited from QObject

### Static Public Members

- 4 static public members inherited from QWidget
- 4 static public members inherited from QObject

### Protected Functions

- 12 protected functions inherited from QTreeView
- 33 protected functions inherited from QAbstractItemView
- 17 protected functions inherited from QViewport
- 44 protected functions inherited from QWidget
- 9 protected functions inherited from QObject

### Protected Slots

- 3 protected slots inherited from QTreeView
- 8 protected slots inherited from QAbstractItemView

## 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;
            treeWidget = new QTreeWidget(this);

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 Model/View Programming and QTreeWidgetItem.

## Property Documentation

### columnCount : int

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

Access functions:

- int columnCount () const
- void setColumnCount ( int columns )

### sortingEnabled : bool

This property holds whether the items in the tree widget can be sorted by clicking on the header.

Access functions:

- bool isSortingEnabled () const
- void setSortingEnabled ( bool enable )

## Member Function Documentation

### QTreeWidget::QTreeWidget ( QWidget * parent = 0 )

Constructs a tree widget with the given parent.

### QTreeWidget::~QTreeWidget ()

Destroys the tree widget and all its items.

### void QTreeWidget::aboutToShowContextMenu ( QMenu * menu, QTreeWidgetItem * item, int column ) `[signal]`

This signal is emitted when the tree widget is about to show a context menu specified by menu. The menu is actived for the specified item and column.

### void QTreeWidget::appendTopLevelItem ( QTreeWidgetItem * item )

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

See also insertToplevelItem().

### void QTreeWidget::clear () `[slot]`

Clears the tree widget by removing all of its items.

### void QTreeWidget::clicked ( QTreeWidgetItem * item, int column, Qt::ButtonState button ) `[signal]`

This signal is emitted when the user 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, or -1 if no item was clicked. The button clicked is specified by button (see Qt::ButtonState).

### void QTreeWidget::closeItem ( const QTreeWidgetItem * item ) `[slot]`

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

### void QTreeWidget::closePersistentEditor ( 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.

### void QTreeWidget::collapsed ( QTreeWidgetItem * item ) `[signal]`

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

See also isItemOpen().

### void QTreeWidget::currentChanged ( 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.

### QTreeWidgetItem * QTreeWidget::currentItem () const

Returns the current item in the tree widget.

See also setCurrentItem().

### void QTreeWidget::doubleClicked ( QTreeWidgetItem * item, int column, Qt::ButtonState button ) `[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, or -1 if no item was clicked. The button clicked is specified by button (see Qt::ButtonState).

### void QTreeWidget::ensureItemVisible ( const QTreeWidgetItem * item ) `[slot]`

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

### void QTreeWidget::expanded ( QTreeWidgetItem * item ) `[signal]`

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

See also isItemOpen().

### QList<QTreeWidgetItem *> QTreeWidget::findItems ( const QString & text, QAbstractItemModel::MatchFlags flags = QAbstractItemModel::MatchDefault ) const

Returns a list of items that match the given text, using the criteria given by the flags (see QAbstractItemModel::MatchFlags).

### QTreeWidgetItem * QTreeWidget::headerItem () const

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

See also setHeaderItem().

### int QTreeWidget::indexOfTopLevelItem ( QTreeWidgetItem * item )

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

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

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

See also appendToplevelItem().

### bool QTreeWidget::isItemHidden ( const QTreeWidgetItem * item ) const

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

### bool QTreeWidget::isItemOpen ( const QTreeWidgetItem * item ) const

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

### bool QTreeWidget::isItemVisible ( const QTreeWidgetItem * item ) const

Returns true if the item is in the viewport; otherwise returns false.

### bool QTreeWidget::isSelected ( const QTreeWidgetItem * item ) const

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

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

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

### void QTreeWidget::itemEntered ( QTreeWidgetItem * item, int column, Qt::ButtonState state ) `[signal]`

This signal is emitted when the mouse cursor enters an item over the specified column. The state of the mouse buttons is specified by state.

See also Qt::ButtonState.

### void QTreeWidget::keyPressed ( QTreeWidgetItem * item, int column, Qt::Key key, Qt::ButtonState button ) `[signal]`

This signal is emitted when the user presses a key inside the widget. The specified item and column had the focus when the key was pressed. If no item had the focus, item is 0 and column is -1.

If a mouse button was pressed at the time of the key press, its state is specified by button (see Qt::ButtonState).

See also returnPressed().

### void QTreeWidget::openItem ( const QTreeWidgetItem * item ) `[slot]`

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

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

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

### void QTreeWidget::pressed ( QTreeWidgetItem * item, int column, Qt::ButtonState button ) `[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. The button clicked is specified by button (see Qt::ButtonState).

### void QTreeWidget::returnPressed ( QTreeWidgetItem * item, int column ) `[signal]`

This signal is emitted when the return key is pressed inside the widget.

The specified item and column had the focus when the return key was pressed. If no item had the focus, item is 0 and column is -1.

See also keyPressed().

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

Returns a list of all selected items.

### void QTreeWidget::selectionChanged () `[signal]`

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

### void QTreeWidget::setCurrentItem ( QTreeWidgetItem * item )

Sets the current item in the tree widget.

See also currentItem().

### void QTreeWidget::setHeaderItem ( 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.

See also headerItem().

### void QTreeWidget::setHeaderLabels ( const QStringList & labels )

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

### void QTreeWidget::setItemHidden ( const QTreeWidgetItem * item, bool hide )

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

### void QTreeWidget::setSelected ( const QTreeWidgetItem * item, bool select )

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

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

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

### void QTreeWidget::sortItems ( int column ) `[slot]`

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Sorts all items in the widget by the values in the given column. The items are sorted in the order given by the sort indicator in the header.

### QTreeWidgetItem * QTreeWidget::takeTopLevelItem ( int index )

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

### QTreeWidgetItem * QTreeWidget::topLevelItem ( int index ) const

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

### int QTreeWidget::topLevelItemCount () const

Returns the number of top-level items.