QTreeWidgetItem Class▲
-
Header: QTreeWidgetItem
-
CMake:
find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
-
qmake: QT += widgets
-
Group: QTreeWidgetItem is part of model-view
Detailed Description▲
Tree widget items are used to hold rows of information for tree widgets. Rows usually contain several columns of data, each of which can contain a text label and an icon.
The QTreeWidgetItem class is a convenience class that replaces the QListViewItem class in Qt 3. It provides an item for use with the QTreeWidget class.
Items are usually constructed with a parent that is either a QTreeWidget (for top-level items) or a QTreeWidgetItem (for items on lower levels of the tree). For example, the following code constructs a top-level item to represent cities of the world, and adds a entry for Oslo as a child item:
QTreeWidgetItem *cities = new QTreeWidgetItem(treeWidget);
cities->setText(0, tr("Cities"));
QTreeWidgetItem *osloItem = new QTreeWidgetItem(cities);
osloItem->setText(0, tr("Oslo"));
osloItem->setText(1, tr("Yes"));Items can be added in a particular order by specifying the item they follow when they are constructed:
QTreeWidgetItem *planets = new QTreeWidgetItem(treeWidget, cities);
planets->setText(0, tr("Planets"));Each column in an item can have its own background brush which is set with the setBackground() function. The current background brush can be found with background(). The text label for each column can be rendered with its own font and brush. These are specified with the setFont() and setForeground() functions, and read with font() and foreground().
The main difference between top-level items and those in lower levels of the tree is that a top-level item has no parent(). This information can be used to tell the difference between items, and is useful to know when inserting and removing items from the tree. Children of an item can be removed with takeChild() and inserted at a given index in the list of children with the insertChild() function.
By default, items are enabled, selectable, checkable, and can be the source of a drag and drop operation. Each item's flags can be changed by calling setFlags() with the appropriate value (see Qt::ItemFlags). Checkable items can be checked and unchecked with the setCheckState() function. The corresponding checkState() function indicates whether the item is currently checked.
Subclassing▲
When subclassing QTreeWidgetItem to provide custom items, it is possible to define new types for them so that they can be distinguished from standard items. The constructors for subclasses that require this feature need to call the base class constructor with a new type value equal to or greater than UserType.
See Also▲
Member Type Documentation▲
enum QTreeWidgetItem::ChildIndicatorPolicy▲
|
Constant |
Value |
Description |
|---|---|---|
|
QTreeWidgetItem::ShowIndicator |
0 |
The controls for expanding and collapsing will be shown for this item even if there are no children. |
|
QTreeWidgetItem::DontShowIndicator |
1 |
The controls for expanding and collapsing will never be shown even if there are children. If the node is forced open the user will not be able to expand or collapse the item. |
|
QTreeWidgetItem::DontShowIndicatorWhenChildless |
2 |
The controls for expanding and collapsing will be shown if the item contains children. |
enum QTreeWidgetItem::ItemType▲
This enum describes the types that are used to describe tree widget items.
|
Constant |
Value |
Description |
|---|---|---|
|
QTreeWidgetItem::Type |
0 |
The default type for tree widget items. |
|
QTreeWidgetItem::UserType |
1000 |
The minimum value for custom types. Values below UserType are reserved by Qt. |
You can define new user types in QTreeWidgetItem subclasses to ensure that custom items are treated specially; for example, when items are sorted.
See Also▲
See also type()
Member Function Documentation▲
[explicit] QTreeWidgetItem::QTreeWidgetItem(int type = Type)▲
Constructs a tree widget item of the specified type. The item must be inserted into a tree widget.
See Also▲
See also type()
[explicit] QTreeWidgetItem::QTreeWidgetItem(const QStringList &strings, int type = Type)▲
Constructs a tree widget item of the specified type. The item must be inserted into a tree widget. The given list of strings will be set as the item text for each column in the item.
See Also▲
See also type()
[explicit] QTreeWidgetItem::QTreeWidgetItem(QTreeWidget *parent, int type = Type)▲
Constructs a tree widget item of the specified type and appends it to the items in the given parent.
See Also▲
See also type()
QTreeWidgetItem::QTreeWidgetItem(QTreeWidget *parent, const QStringList &strings, int type = Type)▲
Constructs a tree widget item of the specified type and appends it to the items in the given parent. The given list of strings will be set as the item text for each column in the item.
See Also▲
See also type()
QTreeWidgetItem::QTreeWidgetItem(QTreeWidget *parent, QTreeWidgetItem *preceding, int type = Type)▲
Constructs a tree widget item of the specified type and inserts it into the given parent after the preceding item.
See Also▲
See also type()
[explicit] QTreeWidgetItem::QTreeWidgetItem(QTreeWidgetItem *parent, int type = Type)▲
QTreeWidgetItem::QTreeWidgetItem(QTreeWidgetItem *parent, const QStringList &strings, int type = Type)▲
Constructs a tree widget item and append it to the given parent. The given list of strings will be set as the item text for each column in the item.
See Also▲
See also type()
QTreeWidgetItem::QTreeWidgetItem(QTreeWidgetItem *parent, QTreeWidgetItem *preceding, int type = Type)▲
Constructs a tree widget item of the specified type that is inserted into the parent after the preceding child item.
See Also▲
See also type()
QTreeWidgetItem::QTreeWidgetItem(const QTreeWidgetItem &other)▲
Constructs a copy of other. Note that type() and treeWidget() are not copied.
This function is useful when reimplementing clone().
See Also▲
[virtual] QTreeWidgetItem::~QTreeWidgetItem()▲
Destroys this tree widget item.
The item will be removed from QTreeWidgets to which it has been added. This makes it safe to delete an item at any time.
void QTreeWidgetItem::addChild(QTreeWidgetItem *child)▲
void QTreeWidgetItem::addChildren(const QList<QTreeWidgetItem *> &children)▲
QBrush QTreeWidgetItem::background(int column) const▲
Returns the brush used to render the background of the specified column.
See Also▲
See also setBackground(), foreground()
Qt::CheckState QTreeWidgetItem::checkState(int column) const▲
Returns the check state of the label in the given column.
See Also▲
See also setCheckState(), Qt::CheckState
QTreeWidgetItem *QTreeWidgetItem::child(int index) const▲
int QTreeWidgetItem::childCount() const▲
Returns the number of child items.
QTreeWidgetItem::ChildIndicatorPolicy QTreeWidgetItem::childIndicatorPolicy() const▲
Returns the item indicator policy. This policy decides when the tree branch expand/collapse indicator is shown.
See Also▲
See also setChildIndicatorPolicy()
[virtual] QTreeWidgetItem *QTreeWidgetItem::clone() const▲
Creates a deep copy of the item and of its children.
int QTreeWidgetItem::columnCount() const▲
Returns the number of columns in the item.
[virtual] QVariant QTreeWidgetItem::data(int column, int role) const▲
[protected] void QTreeWidgetItem::emitDataChanged()▲
Causes the model associated with this item to emit a dataChanged() signal for this item.
You normally only need to call this function if you have subclassed QTreeWidgetItem and reimplemented data() and/or setData().
See Also▲
See also setData()
Qt::ItemFlags QTreeWidgetItem::flags() const▲
Returns the flags used to describe the item. These determine whether the item can be checked, edited, and selected.
The default value for flags is Qt::ItemIsSelectable | Qt::ItemIsUserCheckable | Qt::ItemIsEnabled | Qt::ItemIsDragEnabled | Qt::ItemIsDropEnabled.
See Also▲
See also setFlags()
QFont QTreeWidgetItem::font(int column) const▲
QBrush QTreeWidgetItem::foreground(int column) const▲
Returns the brush used to render the foreground (e.g. text) of the specified column. Setting a default-constructed brush will let the view use the default color from the style.
See Also▲
See also setForeground(), background()
QIcon QTreeWidgetItem::icon(int column) const▲
int QTreeWidgetItem::indexOfChild(QTreeWidgetItem *child) const▲
Returns the index of the given child in the item's list of children.
void QTreeWidgetItem::insertChild(int index, QTreeWidgetItem *child)▲
Inserts the child item at index in the list of children.
If the child has already been inserted somewhere else it won't be inserted again.
void QTreeWidgetItem::insertChildren(int index, const QList<QTreeWidgetItem *> &children)▲
Inserts the given list of children into the list of the item children at index .
Children that have already been inserted somewhere else won't be inserted.
bool QTreeWidgetItem::isDisabled() const▲
bool QTreeWidgetItem::isExpanded() const▲
bool QTreeWidgetItem::isFirstColumnSpanned() const▲
Returns true if the item is spanning all the columns in a row; otherwise returns false.
See Also▲
See also setFirstColumnSpanned()
bool QTreeWidgetItem::isHidden() const▲
bool QTreeWidgetItem::isSelected() const▲
QTreeWidgetItem *QTreeWidgetItem::parent() const▲
[virtual] void QTreeWidgetItem::read(QDataStream &in)▲
void QTreeWidgetItem::removeChild(QTreeWidgetItem *child)▲
Removes the given item indicated by child. The removed item will not be deleted.
void QTreeWidgetItem::setBackground(int column, const QBrush &brush)▲
Sets the background brush of the label in the given column to the specified brush. Setting a default-constructed brush will let the view use the default color from the style.
If Qt Style Sheets are used on the same widget as setBackground(), style sheets will take precedence if the settings conflict.
See Also▲
See also background(), setForeground()
void QTreeWidgetItem::setCheckState(int column, Qt::CheckState state)▲
void QTreeWidgetItem::setChildIndicatorPolicy(QTreeWidgetItem::ChildIndicatorPolicy policy)▲
Sets the item indicator policy. This policy decides when the tree branch expand/collapse indicator is shown. The default value is DontShowIndicatorWhenChildless.
See Also▲
See also childIndicatorPolicy()
[virtual] void QTreeWidgetItem::setData(int column, int role, const QVariant &value)▲
Sets the value for the item's column and role to the given value.
The role describes the type of data specified by value, and is defined by the Qt::ItemDataRole enum.
The default implementation treats Qt::EditRole and Qt::DisplayRole as referring to the same data.
See Also▲
See also data()
void QTreeWidgetItem::setDisabled(bool disabled)▲
Disables the item if disabled is true; otherwise enables the item.
See Also▲
See also isDisabled(), setFlags()
void QTreeWidgetItem::setExpanded(bool expand)▲
Expands the item if expand is true, otherwise collapses the item.
The QTreeWidgetItem must be added to the QTreeWidget before calling this function.
See Also▲
See also isExpanded()
void QTreeWidgetItem::setFirstColumnSpanned(bool span)▲
Sets the first section to span all columns if span is true; otherwise all item sections are shown.
See Also▲
See also isFirstColumnSpanned()
void QTreeWidgetItem::setFlags(Qt::ItemFlags flags)▲
Sets the flags for the item to the given flags. These determine whether the item can be selected or modified. This is often used to disable an item.
See Also▲
See also flags()
void QTreeWidgetItem::setFont(int column, const QFont &font)▲
Sets the font used to display the text in the given column to the given font.
See Also▲
See also font(), setText(), setForeground()
void QTreeWidgetItem::setForeground(int column, const QBrush &brush)▲
Sets the foreground brush of the label in the given column to the specified brush.
See Also▲
See also foreground(), setBackground()
void QTreeWidgetItem::setHidden(bool hide)▲
Hides the item if hide is true, otherwise shows the item.
A call to this function has no effect if the item is not currently in a view. In particular, calling setHidden(true) on an item and only then adding it to a view will result in a visible item.
See Also▲
See also isHidden()
void QTreeWidgetItem::setIcon(int column, const QIcon &icon)▲
Sets the icon to be displayed in the given column to icon.
See Also▲
void QTreeWidgetItem::setSelected(bool select)▲
void QTreeWidgetItem::setSizeHint(int column, const QSize &size)▲
Sets the size hint for the tree item in the given column to be size. If no size hint is set or size is invalid, the item delegate will compute the size hint based on the item data.
See Also▲
See also sizeHint()
void QTreeWidgetItem::setStatusTip(int column, const QString &statusTip)▲
Sets the status tip for the given column to the given statusTip. QTreeWidget mouse tracking needs to be enabled for this feature to work.
See Also▲
See also statusTip(), setToolTip(), setWhatsThis()
void QTreeWidgetItem::setText(int column, const QString &text)▲
Sets the text to be displayed in the given column to the given text.
See Also▲
See also text(), setFont(), setForeground()
[since 6.4] void QTreeWidgetItem::setTextAlignment(int column, Qt::Alignment alignment)▲
Sets the text alignment for the label in the given column to the alignment specified.
This function was introduced in Qt 6.4.
void QTreeWidgetItem::setToolTip(int column, const QString &toolTip)▲
Sets the tooltip for the given column to toolTip.
See Also▲
See also toolTip(), setStatusTip(), setWhatsThis()
void QTreeWidgetItem::setWhatsThis(int column, const QString &whatsThis)▲
Sets the "What's This?" help for the given column to whatsThis.
See Also▲
See also whatsThis(), setStatusTip(), setToolTip()
QSize QTreeWidgetItem::sizeHint(int column) const▲
Returns the size hint set for the tree item in the given column (see QSize).
See Also▲
See also setSizeHint()
void QTreeWidgetItem::sortChildren(int column, Qt::SortOrder order)▲
Sorts the children of the item using the given order, by the values in the given column.
This function does nothing if the item is not associated with a QTreeWidget.
QString QTreeWidgetItem::statusTip(int column) const▲
QTreeWidgetItem *QTreeWidgetItem::takeChild(int index)▲
Removes the item at index and returns it, otherwise return 0.
QList<QTreeWidgetItem *> QTreeWidgetItem::takeChildren()▲
Removes the list of children and returns it, otherwise returns an empty list.
QString QTreeWidgetItem::text(int column) const▲
int QTreeWidgetItem::textAlignment(int column) const▲
Returns the text alignment for the label in the given column.
This function returns an int for historical reasons. It will be corrected to return Qt::Alignment in Qt 7.
See Also▲
See also setTextAlignment(), Qt::Alignment
QString QTreeWidgetItem::toolTip(int column) const▲
QTreeWidget *QTreeWidgetItem::treeWidget() const▲
Returns the tree widget that contains the item.
int QTreeWidgetItem::type() const▲
Returns the type passed to the QTreeWidgetItem constructor.
QString QTreeWidgetItem::whatsThis(int column) const▲
Returns the "What's This?" help for the contents of the given column.
See Also▲
See also setWhatsThis()
[virtual] void QTreeWidgetItem::write(QDataStream &out) const▲
Writes the item to stream out. This only writes data from one single item.
See Also▲
See also read()
[virtual] bool QTreeWidgetItem::operator<(const QTreeWidgetItem &other) const▲
Returns true if the text in the item is less than the text in the other item, otherwise returns false.
QTreeWidgetItem &QTreeWidgetItem::operator=(const QTreeWidgetItem &other)▲
Related Non-Members▲
QDataStream &operator<<(QDataStream &out, const QTreeWidgetItem &item)▲
Writes the tree widget item item to stream out.
This operator uses QTreeWidgetItem::write().
See Also▲
See also Serializing Qt Data Types
QDataStream &operator>>(QDataStream &in, QTreeWidgetItem &item)▲
Reads a tree widget item from stream in into item.
This operator uses QTreeWidgetItem::read().
See Also▲
See also Serializing Qt Data Types
Obsolete Members for QTreeWidgetItem▲
The following members of class QTreeWidgetItem are deprecated. We strongly advise against using them in new code.
Obsolete Member Function Documentation▲
void QTreeWidgetItem::setTextAlignment(int column, int alignment)▲
This function is deprecated. We strongly advise against using it in new code.
Use the overload that takes a Qt::Alignment argument.
Sets the text alignment for the label in the given column to the alignment specified.
See Also▲
See also textAlignment(), Qt::Alignment