En esta página

QTreeWidgetItem Class

La clase `QTreeWidgetItem` proporciona un elemento para utilizarlo con la clase de ayuda ` QTreeWidget `. Más...

Encabezado: #include <QTreeWidgetItem>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets

Tipos públicos

enum ChildIndicatorPolicy { ShowIndicator, DontShowIndicator, DontShowIndicatorWhenChildless }
enum ItemType { Type, UserType }

Funciones públicas

QTreeWidgetItem(int type = Type)
QTreeWidgetItem(QTreeWidget *parent, int type = Type)
QTreeWidgetItem(QTreeWidgetItem *parent, int type = Type)
QTreeWidgetItem(const QStringList &strings, int type = Type)
QTreeWidgetItem(QTreeWidget *parent, QTreeWidgetItem *preceding, int type = Type)
QTreeWidgetItem(QTreeWidget *parent, const QStringList &strings, int type = Type)
QTreeWidgetItem(QTreeWidgetItem *parent, QTreeWidgetItem *preceding, int type = Type)
QTreeWidgetItem(QTreeWidgetItem *parent, const QStringList &strings, int type = Type)
QTreeWidgetItem(const QTreeWidgetItem &other)
virtual ~QTreeWidgetItem()
void addChild(QTreeWidgetItem *child)
void addChildren(const QList<QTreeWidgetItem *> &children)
QBrush background(int column) const
Qt::CheckState checkState(int column) const
QTreeWidgetItem *child(int index) const
int childCount() const
QTreeWidgetItem::ChildIndicatorPolicy childIndicatorPolicy() const
virtual QTreeWidgetItem *clone() const
int columnCount() const
virtual QVariant data(int column, int role) const
Qt::ItemFlags flags() const
QFont font(int column) const
QBrush foreground(int column) const
QIcon icon(int column) const
int indexOfChild(QTreeWidgetItem *child) const
void insertChild(int index, QTreeWidgetItem *child)
void insertChildren(int index, const QList<QTreeWidgetItem *> &children)
bool isDisabled() const
bool isExpanded() const
bool isFirstColumnSpanned() const
bool isHidden() const
bool isSelected() const
QTreeWidgetItem *parent() const
virtual void read(QDataStream &in)
void removeChild(QTreeWidgetItem *child)
void setBackground(int column, const QBrush &brush)
void setCheckState(int column, Qt::CheckState state)
void setChildIndicatorPolicy(QTreeWidgetItem::ChildIndicatorPolicy policy)
virtual void setData(int column, int role, const QVariant &value)
void setDisabled(bool disabled)
void setExpanded(bool expand)
void setFirstColumnSpanned(bool span)
void setFlags(Qt::ItemFlags flags)
void setFont(int column, const QFont &font)
void setForeground(int column, const QBrush &brush)
void setHidden(bool hide)
void setIcon(int column, const QIcon &icon)
void setSelected(bool select)
void setSizeHint(int column, const QSize &size)
void setStatusTip(int column, const QString &statusTip)
void setText(int column, const QString &text)
(since 6.4) void setTextAlignment(int column, Qt::Alignment alignment)
void setToolTip(int column, const QString &toolTip)
void setWhatsThis(int column, const QString &whatsThis)
QSize sizeHint(int column) const
void sortChildren(int column, Qt::SortOrder order)
QString statusTip(int column) const
QTreeWidgetItem *takeChild(int index)
QList<QTreeWidgetItem *> takeChildren()
QString text(int column) const
int textAlignment(int column) const
QString toolTip(int column) const
QTreeWidget *treeWidget() const
int type() const
QString whatsThis(int column) const
virtual void write(QDataStream &out) const
virtual bool operator<(const QTreeWidgetItem &other) const
QTreeWidgetItem &operator=(const QTreeWidgetItem &other)

Funciones protegidas

QDataStream &operator<<(QDataStream &out, const QTreeWidgetItem &item)
QDataStream &operator>>(QDataStream &in, QTreeWidgetItem &item)

Descripción detallada

Los elementos del widget de árbol se utilizan para contener filas de información para los widgets de árbol. Las filas suelen contener varias columnas de datos, cada una de las cuales puede contener una etiqueta de texto y un icono.

La clase `QTreeWidgetItem` es una clase de conveniencia que sustituye a la clase `QListViewItem` en Qt 3. Proporciona un elemento para su uso con la clase ` QTreeWidget `.

Los elementos suelen crearse con un padre que es o bien un QTreeWidget (para elementos de nivel superior) o bien un QTreeWidgetItem (para elementos de niveles inferiores del árbol). Por ejemplo, el siguiente código crea un elemento de nivel superior para representar ciudades del mundo y añade una entrada para Oslo como elemento hijo:

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"));

Los elementos se pueden añadir en un orden concreto especificando el elemento al que siguen cuando se crean:

QTreeWidgetItem *planets = new QTreeWidgetItem(treeWidget, cities);
planets->setText(0, tr("Planets"));

Cada columna de un elemento puede tener su propio pincel de fondo, que se establece con la función ` setBackground()`. El pincel de fondo actual se puede obtener con ` background()`. La etiqueta de texto de cada columna se puede representar con su propia fuente y pincel. Estos se especifican con las funciones ` setFont()` y ` setForeground()`, y se leen con ` font()` y ` foreground()`.

La principal diferencia entre los elementos de nivel superior y los de niveles inferiores del árbol es que un elemento de nivel superior no tiene ` parent()` (). Esta información puede utilizarse para distinguir entre elementos y resulta útil a la hora de insertar y eliminar elementos del árbol. Los elementos hijos de un elemento se pueden eliminar con takeChild() e insertar en un índice determinado de la lista de elementos hijos con la función insertChild().

Por defecto, los elementos están habilitados, son seleccionables, se pueden marcar y pueden ser objeto de una operación de arrastrar y soltar. Los indicadores de cada elemento se pueden modificar llamando a setFlags() con el valor adecuado (véase Qt::ItemFlags). Los elementos marcables se pueden marcar y desmarcar con la función setCheckState(). La función correspondiente checkState() indica si el elemento está marcado actualmente.

Subclasificación

Al crear subclases de `QTreeWidgetItem` para proporcionar elementos personalizados, es posible definir nuevos tipos para ellos, de modo que se puedan distinguir de los elementos estándar. Los constructores de las subclases que requieran esta característica deben llamar al constructor de la clase base con un valor de tipo nuevo igual o superior a ` UserType`.

Véase también QTreeWidget, QTreeWidgetItemIterator, Programación Modelo/Vista, QListWidgetItem y QTableWidgetItem.

Documentación sobre tipos de miembro

enum QTreeWidgetItem::ChildIndicatorPolicy

ConstanteValorDescripción
QTreeWidgetItem::ShowIndicator0Los controles para expandir y contraer se mostrarán para este elemento aunque no haya elementos secundarios.
QTreeWidgetItem::DontShowIndicator1Los controles para expandir y contraer nunca se mostrarán, aunque haya elementos secundarios. Si el nodo se abre de forma forzada, el usuario no podrá expandir ni contraer el elemento.
QTreeWidgetItem::DontShowIndicatorWhenChildless2Se mostrarán los controles para expandir y contraer si el elemento contiene elementos secundarios.

enum QTreeWidgetItem::ItemType

Esta enumeración describe los tipos que se utilizan para definir los elementos de los widgets de árbol.

ConstanteValorDescripción
QTreeWidgetItem::Type0El tipo por defecto para los elementos del widget de árbol.
QTreeWidgetItem::UserType1000El valor mínimo para los tipos personalizados. Los valores inferiores a UserType están reservados por Qt.

Se pueden definir nuevos tipos de usuario en subclases de ` QTreeWidgetItem ` para garantizar que los elementos personalizados reciban un tratamiento especial; por ejemplo, al ordenar los elementos.

Véase también type().

Documentación de las funciones miembro

[explicit] QTreeWidgetItem::QTreeWidgetItem(int type = Type)

Crea un elemento de widget de árbol del tipo especificado type. El elemento debe insertarse en un widget de árbol.

Véase también type().

[explicit] QTreeWidgetItem::QTreeWidgetItem(QTreeWidget *parent, int type = Type)

Crea un elemento de widget de árbol del tipo especificado en ` type ` y lo añade a los elementos de la lista dada en ` parent`.

Véase también type().

[explicit] QTreeWidgetItem::QTreeWidgetItem(QTreeWidgetItem *parent, int type = Type)

Crea un elemento de widget de árbol y lo añade a la lista « parent » indicada.

Véase también type().

[explicit] QTreeWidgetItem::QTreeWidgetItem(const QStringList &strings, int type = Type)

Crea un elemento de widget de árbol a partir de la lista especificada type. El elemento debe insertarse en un widget de árbol. La lista proporcionada strings se establecerá como texto del elemento para cada columna del mismo.

Véase también type().

QTreeWidgetItem::QTreeWidgetItem(QTreeWidget *parent, QTreeWidgetItem *preceding, int type = Type)

Crea un elemento de widget de árbol del tipo « type » especificado y lo inserta en el « parent » indicado, después del elemento « preceding ».

Véase también type().

QTreeWidgetItem::QTreeWidgetItem(QTreeWidget *parent, const QStringList &strings, int type = Type)

Crea un elemento de widget de árbol del tipo « type » especificado y lo añade a los elementos de la lista « parent » indicada. La lista « strings » proporcionada se establecerá como texto del elemento para cada columna del mismo.

Véase también type().

QTreeWidgetItem::QTreeWidgetItem(QTreeWidgetItem *parent, QTreeWidgetItem *preceding, int type = Type)

Crea un elemento de widget de árbol del tipo « type » especificado, que se inserta en « parent » después del elemento secundario « preceding ».

Véase también type().

QTreeWidgetItem::QTreeWidgetItem(QTreeWidgetItem *parent, const QStringList &strings, int type = Type)

Crea un elemento de widget de árbol y lo añade a la lista « parent » indicada. La lista de « strings » proporcionada se establecerá como texto del elemento para cada columna del mismo.

Véase también type().

QTreeWidgetItem::QTreeWidgetItem(const QTreeWidgetItem &other)

Crea una copia de ` other`. Ten en cuenta que ` type()` y ` treeWidget()` no se copian.

Esta función resulta útil a la hora de reimplementar ` clone()`.

Véanse también data() y flags().

[virtual noexcept] QTreeWidgetItem::~QTreeWidgetItem()

Elimina este elemento del widget de árbol.

El elemento se eliminará de l QTreeWidgets a los que se haya añadido. Esto permite eliminar un elemento de forma segura en cualquier momento.

void QTreeWidgetItem::addChild(QTreeWidgetItem *child)

Añade el elemento « child » a la lista de elementos secundarios.

Véase también insertChild() y takeChild().

void QTreeWidgetItem::addChildren(const QList<QTreeWidgetItem *> &children)

Añade la lista indicada de children al elemento.

Véase también insertChildren() y takeChildren().

QBrush QTreeWidgetItem::background(int column) const

Devuelve el pincel utilizado para renderizar el fondo del elemento ` column` especificado.

Véase también setBackground() y foreground().

Qt::CheckState QTreeWidgetItem::checkState(int column) const

Devuelve el estado de selección de la etiqueta en el elemento ` column` indicado.

Véase también setCheckState() y Qt::CheckState.

QTreeWidgetItem *QTreeWidgetItem::child(int index) const

Devuelve el elemento situado en la posición index de la lista de elementos hijos de dicho elemento.

Véase también parent().

int QTreeWidgetItem::childCount() const

Devuelve el número de elementos secundarios.

QTreeWidgetItem::ChildIndicatorPolicy QTreeWidgetItem::childIndicatorPolicy() const

Devuelve la política del indicador de elementos. Esta política determina cuándo se muestra el indicador de expansión/contracción de las ramas del árbol.

Véase también setChildIndicatorPolicy().

[virtual] QTreeWidgetItem *QTreeWidgetItem::clone() const

Crea una copia profunda del elemento y de sus elementos secundarios.

int QTreeWidgetItem::columnCount() const

Devuelve el número de columnas del elemento.

[virtual] QVariant QTreeWidgetItem::data(int column, int role) const

Devuelve el valor de los campos « column » y « role » del elemento.

Véase también setData().

[protected] void QTreeWidgetItem::emitDataChanged()

Hace que el modelo asociado a este elemento emita una señal « dataChanged()» para este elemento.

Normalmente, solo es necesario llamar a esta función si se ha creado una subclase de ` QTreeWidgetItem ` y se han reimplementado ` data()` y/o ` setData()`.

Véase también setData().

Qt::ItemFlags QTreeWidgetItem::flags() const

Devuelve los indicadores utilizados para describir el elemento. Estos determinan si el elemento se puede marcar, editar y seleccionar.

El valor por defecto de los indicadores es Qt::ItemIsSelectable | Qt::ItemIsUserCheckable | Qt::ItemIsEnabled | Qt::ItemIsDragEnabled | Qt::ItemIsDropEnabled.

Véase también setFlags().

QFont QTreeWidgetItem::font(int column) const

Devuelve la fuente utilizada para visualizar el texto en el archivo column especificado.

Véase también setFont().

QBrush QTreeWidgetItem::foreground(int column) const

Devuelve el pincel utilizado para renderizar el primer plano (por ejemplo, el texto) del ` column` especificado. Si se establece un pincel creado de forma predeterminada, la vista utilizará el color predeterminado del estilo.

Véase también setForeground() y background().

QIcon QTreeWidgetItem::icon(int column) const

Devuelve el icono que se muestra en el column especificado.

Véase también setIcon() y iconSize.

int QTreeWidgetItem::indexOfChild(QTreeWidgetItem *child) const

Devuelve el índice del « child » indicado en la lista de elementos secundarios del elemento.

void QTreeWidgetItem::insertChild(int index, QTreeWidgetItem *child)

Inserta el elemento « child » en « index » en la lista de elementos secundarios.

Si el elemento secundario ya se ha insertado en otro lugar, no se volverá a insertar.

void QTreeWidgetItem::insertChildren(int index, const QList<QTreeWidgetItem *> &children)

Inserta la lista de « children » indicada en la lista de elementos secundarios de index.

Los elementos secundarios que ya se hayan insertado en otro lugar no se volverán a insertar.

bool QTreeWidgetItem::isDisabled() const

Devuelve « true » si el elemento está desactivado; en caso contrario, devuelve « false ».

Véase también setFlags().

bool QTreeWidgetItem::isExpanded() const

Devuelve « true » si el elemento está expandido; en caso contrario, devuelve « false ».

Véase también setExpanded().

bool QTreeWidgetItem::isFirstColumnSpanned() const

Devuelve « true » si el elemento ocupa todas las columnas de una fila; en caso contrario, devuelve « false ».

Véase también setFirstColumnSpanned().

bool QTreeWidgetItem::isHidden() const

Devuelve « true » si el elemento está oculto; en caso contrario, devuelve « false ».

Véase también setHidden().

bool QTreeWidgetItem::isSelected() const

Devuelve « true » si el elemento está seleccionado; en caso contrario, devuelve « false ».

Véase también setSelected().

QTreeWidgetItem *QTreeWidgetItem::parent() const

Devuelve el elemento padre del elemento.

Véase también child().

[virtual] void QTreeWidgetItem::read(QDataStream &in)

Lee el elemento del flujo in. Esta operación solo lee datos en un único elemento.

Véase también write().

void QTreeWidgetItem::removeChild(QTreeWidgetItem *child)

Elimina el elemento especificado en « child ». El elemento eliminado no se borrará.

void QTreeWidgetItem::setBackground(int column, const QBrush &brush)

Establece el pincel de fondo de la etiqueta del « column » indicado en el « brush » especificado. Al establecer un pincel creado de forma predeterminada, la vista utilizará el color predeterminado del estilo.

Nota: Si se utilizan hojas de estilo de Qt en el mismo widget que setBackground(), las hojas de estilo tendrán prioridad en caso de conflicto entre las configuraciones.

Véase también background() y setForeground().

void QTreeWidgetItem::setCheckState(int column, Qt::CheckState state)

Establece el estado de verificación del elemento en la column indicada como « state ».

Véase también checkState().

void QTreeWidgetItem::setChildIndicatorPolicy(QTreeWidgetItem::ChildIndicatorPolicy policy)

Establece el indicador de elemento « policy ». Esta política determina cuándo se muestra el indicador de expansión/contracción de las ramas del árbol. El valor por defecto es « DontShowIndicatorWhenChildless ».

Véase también childIndicatorPolicy().

[virtual] void QTreeWidgetItem::setData(int column, int role, const QVariant &value)

Establece el valor de los atributos « column » y « role » del elemento en el valor especificado « value ».

role describe el tipo de datos especificado por value y viene definido por la enumeración Qt::ItemDataRole.

Nota: La implementación por defecto trata Qt::EditRole y Qt::DisplayRole como si se refirieran a los mismos datos.

Véase también data().

void QTreeWidgetItem::setDisabled(bool disabled)

Desactiva el elemento si « disabled » es «true»; en caso contrario, lo activa.

Véase también isDisabled() y setFlags().

void QTreeWidgetItem::setExpanded(bool expand)

Expande el elemento si expand es verdadero; en caso contrario, lo contrae.

Advertencia: El parámetro ` QTreeWidgetItem ` debe añadirse a ` QTreeWidget ` antes de llamar a esta función.

Véase también isExpanded().

void QTreeWidgetItem::setFirstColumnSpanned(bool span)

Establece que la primera sección ocupe todas las columnas si span es verdadero; en caso contrario, se muestran todas las secciones de elementos.

Véase también isFirstColumnSpanned().

void QTreeWidgetItem::setFlags(Qt::ItemFlags flags)

Establece los indicadores del elemento según el valor especificado en flags. Estos determinan si el elemento se puede seleccionar o modificar. Esto se suele utilizar para desactivar un elemento.

Véase también flags().

void QTreeWidgetItem::setFont(int column, const QFont &font)

Establece la fuente utilizada para mostrar el texto en el archivo « column » en la fuente indicada en « font ».

Véanse también font(), setText() y setForeground().

void QTreeWidgetItem::setForeground(int column, const QBrush &brush)

Establece el pincel de primer plano de la etiqueta en el column indicado como el brush especificado.

Véase también foreground() y setBackground().

void QTreeWidgetItem::setHidden(bool hide)

Oculta el elemento si hide es verdadero; en caso contrario, lo muestra.

Nota: La llamada a esta función no tiene ningún efecto si el elemento no se encuentra actualmente en una vista. En concreto, si se llama a setHidden(true) sobre un elemento y solo después se añade a una vista, el elemento quedará visible.

Véase también ` isHidden()`.

void QTreeWidgetItem::setIcon(int column, const QIcon &icon)

Establece el icono que se mostrará en el archivo « column » especificado en « icon ».

Véanse también icon(), setText() y iconSize.

void QTreeWidgetItem::setSelected(bool select)

Establece el estado seleccionado del elemento en « select ».

Véase también isSelected().

void QTreeWidgetItem::setSizeHint(int column, const QSize &size)

Establece la indicación de tamaño del elemento del árbol en el ` column ` especificado como ` size`. Si no se establece ninguna indicación de tamaño o si ` size ` no es válido, el delegado del elemento calculará la indicación de tamaño basándose en los datos del elemento.

Véase también sizeHint().

void QTreeWidgetItem::setStatusTip(int column, const QString &statusTip)

Establece el mensaje de estado de la dirección column indicada en el texto statusTip. Para que esta función funcione, es necesario tener activado el seguimiento del ratón QTreeWidget.

Véase también statusTip(), setToolTip() y setWhatsThis().

void QTreeWidgetItem::setText(int column, const QString &text)

Establece el texto que se mostrará en el elemento « column » especificado como el valor de « text » indicado.

Véanse también text(), setFont() y setForeground().

[since 6.4] void QTreeWidgetItem::setTextAlignment(int column, Qt::Alignment alignment)

Establece la alineación del texto de la etiqueta del elemento « column » indicado según el valor especificado en « alignment ».

Esta función se introdujo en Qt 6.4.

Véase también textAlignment().

void QTreeWidgetItem::setToolTip(int column, const QString &toolTip)

Establece la descripción emergente del elemento column especificado en toolTip.

Véase también toolTip(), setStatusTip() y setWhatsThis().

void QTreeWidgetItem::setWhatsThis(int column, const QString &whatsThis)

Establece la ayuda «¿Qué es esto?» para el column especificado en whatsThis.

Véase también whatsThis(), setStatusTip() y setToolTip().

QSize QTreeWidgetItem::sizeHint(int column) const

Devuelve la sugerencia de tamaño establecida para el elemento del árbol en el column indicado (véase QSize).

Véase también setSizeHint().

void QTreeWidgetItem::sortChildren(int column, Qt::SortOrder order)

Ordena los elementos secundarios del elemento utilizando el ` order` proporcionado, según los valores del ` column` proporcionado.

Nota: Esta función no realiza ninguna acción si el elemento no está asociado a un « QTreeWidget ».

QString QTreeWidgetItem::statusTip(int column) const

Devuelve la descripción del estado del contenido del archivo column especificado.

Véase también setStatusTip().

QTreeWidgetItem *QTreeWidgetItem::takeChild(int index)

Elimina el elemento de index y lo devuelve; en caso contrario, devuelve 0.

QList<QTreeWidgetItem *> QTreeWidgetItem::takeChildren()

Elimina la lista de elementos secundarios y la devuelve; de lo contrario, devuelve una lista vacía.

QString QTreeWidgetItem::text(int column) const

Devuelve el texto que figura en el archivo « column » especificado.

Véase también setText().

int QTreeWidgetItem::textAlignment(int column) const

Devuelve la alineación del texto de la etiqueta en el objeto ` column` especificado.

Nota: Esta función devuelve un entero por motivos históricos. Se corregirá para que devuelva ` Qt::Alignment ` en Qt 7.

Véase también ` setTextAlignment()` y ` Qt::Alignment`.

QString QTreeWidgetItem::toolTip(int column) const

Devuelve la descripción emergente de la entrada de control de texto « column » especificada.

Véase también setToolTip().

QTreeWidget *QTreeWidgetItem::treeWidget() const

Devuelve el widget de árbol que contiene el elemento.

int QTreeWidgetItem::type() const

Devuelve el tipo pasado al constructor ` QTreeWidgetItem `.

QString QTreeWidgetItem::whatsThis(int column) const

Devuelve la ayuda «¿Qué es esto?» correspondiente al contenido de la dirección column indicada.

Véase también setWhatsThis().

[virtual] void QTreeWidgetItem::write(QDataStream &out) const

Escribe el elemento en el flujo out. Esto solo escribe los datos de un único elemento.

Véase también read().

[virtual] bool QTreeWidgetItem::operator<(const QTreeWidgetItem &other) const

Devuelve « true » si el texto del elemento es menor que el del elemento « other »; en caso contrario, devuelve « false ».

QTreeWidgetItem &QTreeWidgetItem::operator=(const QTreeWidgetItem &other)

Asigna los datos y los indicadores de ` other` a este elemento. Ten en cuenta que ` type()` y ` treeWidget()` no se copian.

Esta función resulta útil a la hora de reimplementar clone().

Véase también data() y flags().

Elementos no miembros relacionados

QDataStream &operator<<(QDataStream &out, const QTreeWidgetItem &item)

Escribe el elemento del widget de árbol item en el flujo out.

Este operador utiliza QTreeWidgetItem::write().

Véase también «Serialización detipos de datos de Qt».

QDataStream &operator>>(QDataStream &in, QTreeWidgetItem &item)

Lee un elemento del widget de árbol desde el flujo « in » y lo almacena en « item ».

Este operador utiliza QTreeWidgetItem::read().

Véase también «Serialización detipos de datos de Qt».

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.