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;
QTreeWidget *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 )
topLevelItemCount : const int
This property holds the number of top-level items.
Access functions:
- int topLevelItemCount () const
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::addTopLevelItem ( 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 and selections.
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::collapseItem ( const QTreeWidgetItem * item ) [slot]
Closes the item. This causes the tree containing the item's children to be collapsed.
QTreeWidgetItem * QTreeWidget::currentItem () const
Returns the current item in the tree widget.
See also setCurrentItem().
void QTreeWidget::currentItemChanged ( 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.
bool QTreeWidget::dropMimeData ( 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.
See also supportedDropActions().
void QTreeWidget::editItem ( QTreeWidgetItem * item, int column = 0 )
Starts editing the item in the given column if it is editable.
void QTreeWidget::expandItem ( const QTreeWidgetItem * item ) [slot]
Expands the item. This causes the tree containing the item's children to be expanded.
Returns a list of items that match the given text, using the given flags, in the given column.
Returns the item used for the tree widget's header.
See also setHeaderItem().
QModelIndex QTreeWidget::indexFromItem ( QTreeWidgetItem * item, int column = 0 ) const [protected]
Returns the QModelIndex assocated with the given item in the given column.
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 addTopLevelItem().
bool QTreeWidget::isItemExpanded ( const QTreeWidgetItem * item ) const
Returns true if the given item is open; otherwise returns false.
bool QTreeWidget::isItemHidden ( const QTreeWidgetItem * item ) const
Returns true if the item is explicitly hidden, otherwise returns false.
bool QTreeWidget::isItemSelected ( const QTreeWidgetItem * item ) const
Returns true if the item is selected and not-hidden and does not have hidden parents; otherwise returns false.
void QTreeWidget::itemActivated ( QTreeWidgetItem * item, int column ) [signal]
This signal is emitted when the user activates an item by single- or double-clicking (depending on the platform) 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.
QTreeWidgetItem * QTreeWidget::itemAt ( const QPoint & p ) const
Returns a pointer to the item at the coordinates p.
QTreeWidgetItem * QTreeWidget::itemAt ( int x, int y ) const
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Returns a pointer to the item at the coordinates (x, y).
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::itemClicked ( 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, or 0 if no item was clicked. The column is the item's column that was clicked, or -1 if no item was clicked.
void QTreeWidget::itemCollapsed ( QTreeWidgetItem * item ) [signal]
This signal is emitted when the specified item is collapsed so that none of its children are displayed.
See also isItemExpanded().
void QTreeWidget::itemDoubleClicked ( 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, or -1 if no item was clicked.
void QTreeWidget::itemEntered ( QTreeWidgetItem * item, int column ) [signal]
This signal is emitted when the mouse cursor enters an item over the specified column.
void QTreeWidget::itemExpanded ( QTreeWidgetItem * item ) [signal]
This signal is emitted when the specified item is expanded so that all of its children are displayed.
See also setItemExpanded() and isItemExpanded().
QTreeWidgetItem * QTreeWidget::itemFromIndex ( const QModelIndex & index ) const [protected]
Returns a pointer to the QTreeWidgetItem assocated with the given index.
void QTreeWidget::itemPressed ( 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.
void QTreeWidget::itemSelectionChanged () [signal]
This signal is emitted when the selection changes in the tree widget. The current selection can be found with selectedItems().
QList<QTreeWidgetItem *> QTreeWidget::items ( const QMimeData * data ) const [protected]
Returns a list of pointers to the items contained in the data object. If the object was not created by a QTreeWidget in the same process, the list is empty.
QMimeData * QTreeWidget::mimeData ( 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.
QStringList QTreeWidget::mimeTypes () const [virtual protected]
Returns a list of MIME types that can be used to describe a list of treewidget items.
See also mimeData().
void QTreeWidget::openPersistentEditor ( QTreeWidgetItem * item, int column = 0 )
Opens a persistent editor for the item in the given column.
Returns a list of all selected non-hidden items.
void QTreeWidget::setCurrentItem ( QTreeWidgetItem * item )
Sets the current item in the tree widget.
See also currentItem().
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().
Adds a column in the header for each item in the labels list, and sets the label for each column.
void QTreeWidget::setItemExpanded ( const QTreeWidgetItem * item, bool expand )
Sets the item referred to by item to either closed or opened, depending on the value of expand.
See also itemExpanded(), expandItem(), and collapseItem().
void QTreeWidget::setItemHidden ( const QTreeWidgetItem * item, bool hide )
Hides the given item if hide is true; otherwise shows the item.
See also isItemHidden().
void QTreeWidget::setItemSelected ( const QTreeWidgetItem * item, bool select )
If select is true, the given item is selected; otherwise it is deselected.
See also isItemSelected().
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.
Qt::DropActions QTreeWidget::supportedDropActions () const [virtual protected]
Returns the drop actions supported by this view.
See also Qt::DropActions.
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.
QRect QTreeWidget::visualItemRect ( const QTreeWidgetItem * item ) const
Returns the rectangle on the viewport occupied by the item at item.
