En esta página

QTreeWidget Class

La clase QTreeWidget ofrece una vista en árbol que utiliza un modelo de árbol predefinido. Más información...

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

Propiedades

Funciones públicas

QTreeWidget(QWidget *parent = nullptr)
virtual ~QTreeWidget()
void addTopLevelItem(QTreeWidgetItem *item)
void addTopLevelItems(const QList<QTreeWidgetItem *> &items)
void closePersistentEditor(QTreeWidgetItem *item, int column = 0)
int columnCount() const
int currentColumn() const
QTreeWidgetItem *currentItem() const
void editItem(QTreeWidgetItem *item, int column = 0)
QList<QTreeWidgetItem *> findItems(const QString &text, Qt::MatchFlags flags, int column = 0) const
QTreeWidgetItem *headerItem() const
QModelIndex indexFromItem(const QTreeWidgetItem *item, int column = 0) const
int indexOfTopLevelItem(QTreeWidgetItem *item) const
void insertTopLevelItem(int index, QTreeWidgetItem *item)
void insertTopLevelItems(int index, const QList<QTreeWidgetItem *> &items)
QTreeWidgetItem *invisibleRootItem() const
bool isPersistentEditorOpen(QTreeWidgetItem *item, int column = 0) const
QTreeWidgetItem *itemAbove(const QTreeWidgetItem *item) const
QTreeWidgetItem *itemAt(const QPoint &p) const
QTreeWidgetItem *itemAt(int x, int y) const
QTreeWidgetItem *itemBelow(const QTreeWidgetItem *item) const
QTreeWidgetItem *itemFromIndex(const QModelIndex &index) const
QWidget *itemWidget(QTreeWidgetItem *item, int column) const
void openPersistentEditor(QTreeWidgetItem *item, int column = 0)
void removeItemWidget(QTreeWidgetItem *item, int column)
QList<QTreeWidgetItem *> selectedItems() const
void setColumnCount(int columns)
void setCurrentItem(QTreeWidgetItem *item)
void setCurrentItem(QTreeWidgetItem *item, int column)
void setCurrentItem(QTreeWidgetItem *item, int column, QItemSelectionModel::SelectionFlags command)
void setHeaderItem(QTreeWidgetItem *item)
void setHeaderLabel(const QString &label)
void setHeaderLabels(const QStringList &labels)
void setItemWidget(QTreeWidgetItem *item, int column, QWidget *widget)
void setSupportedDragActions(Qt::DropActions actions)
int sortColumn() const
void sortItems(int column, Qt::SortOrder order)
Qt::DropActions supportedDragActions() const
QTreeWidgetItem *takeTopLevelItem(int index)
QTreeWidgetItem *topLevelItem(int index) const
int topLevelItemCount() const
QRect visualItemRect(const QTreeWidgetItem *item) const

Funciones públicas reimplementadas

virtual void setSelectionModel(QItemSelectionModel *selectionModel) override

Ranuras públicas

void clear()
void collapseItem(const QTreeWidgetItem *item)
void expandItem(const QTreeWidgetItem *item)
void scrollToItem(const QTreeWidgetItem *item, QAbstractItemView::ScrollHint hint = EnsureVisible)

Señales

void currentItemChanged(QTreeWidgetItem *current, QTreeWidgetItem *previous)
void itemActivated(QTreeWidgetItem *item, int column)
void itemChanged(QTreeWidgetItem *item, int column)
void itemClicked(QTreeWidgetItem *item, int column)
void itemCollapsed(QTreeWidgetItem *item)
void itemDoubleClicked(QTreeWidgetItem *item, int column)
void itemEntered(QTreeWidgetItem *item, int column)
void itemExpanded(QTreeWidgetItem *item)
void itemPressed(QTreeWidgetItem *item, int column)
void itemSelectionChanged()

Funciones protegidas

virtual bool dropMimeData(QTreeWidgetItem *parent, int index, const QMimeData *data, Qt::DropAction action)
virtual QMimeData *mimeData(const QList<QTreeWidgetItem *> &items) const
virtual QStringList mimeTypes() const
virtual Qt::DropActions supportedDropActions() const

Funciones protegidas reimplementadas

virtual void dropEvent(QDropEvent *event) override
virtual bool event(QEvent *e) override

Descripción detallada

Directorio que muestra su contenido en forma de árbol

La clase `QTreeWidget` es una clase de conveniencia que proporciona un widget de árbol estándar con una interfaz clásica basada en elementos, similar a la utilizada por la clase ` QListView ` en Qt 3. Esta clase se basa en la arquitectura Modelo/Vista de Qt y utiliza un modelo predeterminado para almacenar elementos, cada uno de los cuales es un ` QTreeWidgetItem`.

Los desarrolladores que no necesiten la flexibilidad del marco Modelo/Vista pueden utilizar esta clase para crear listas jerárquicas sencillas con gran facilidad. Un enfoque más flexible consiste en combinar un ` QTreeView ` con un modelo de elementos estándar. Esto permite separar el almacenamiento de los datos de su representación.

En su forma más sencilla, un widget de árbol se puede construir de la siguiente manera:

auto *treeWidget = new QTreeWidget();
treeWidget->setColumnCount(1);
for (int i = 0; i < 10; ++i)
    new QTreeWidgetItem(treeWidget, { tr("item: %1").arg(i) });

Antes de poder añadir elementos al widget de árbol, hay que establecer el número de columnas con ` setColumnCount()`. Esto permite que cada elemento tenga una o más etiquetas u otros elementos decorativos. El número de columnas en uso se puede consultar con la función ` columnCount()`.

El árbol puede tener un encabezado que contenga una sección para cada columna del widget. La forma más sencilla de configurar las etiquetas de cada sección es proporcionando una lista de cadenas mediante la función ` setHeaderLabels()`, pero se puede crear un encabezado personalizado con ` QTreeWidgetItem ` e insertarlo en el árbol mediante la función ` setHeaderItem()`.

Los elementos del árbol se pueden ordenar por columna según un orden de clasificación predefinido. Si la clasificación está activada, el usuario puede ordenar los elementos haciendo clic en el encabezado de una columna. La clasificación se puede activar o desactivar llamando a ` setSortingEnabled()`. La función ` isSortingEnabled()` indica si la clasificación está activada.

Véase también QTreeWidgetItem, QTreeWidgetItemIterator, QTreeView y Programación de modelos y vistas.

Documentación de propiedades

columnCount : int

Esta propiedad indica el número de columnas que se muestran en el widget de árbol

Por defecto, esta propiedad tiene un valor de 1.

Funciones de acceso:

int columnCount() const
void setColumnCount(int columns)

[since 6.10] supportedDragActions : Qt::DropActions

Esta propiedad contiene las acciones de arrastre compatibles con esta vista

Esta enumeración se introdujo en Qt 6.10.

Funciones de acceso:

Qt::DropActions supportedDragActions() const
void setSupportedDragActions(Qt::DropActions actions)

Véase también Qt::DropActions y supportedDropActions().

[read-only] topLevelItemCount : int

Esta propiedad contiene el número de elementos de primer nivel

Por defecto, esta propiedad tiene un valor de 0.

Funciones de acceso:

int topLevelItemCount() const

Véase también columnCount() y currentItem().

Documentación de funciones de miembro

[explicit] QTreeWidget::QTreeWidget(QWidget *parent = nullptr)

Crea un widget de árbol con el objeto ` parent` proporcionado.

[virtual noexcept] QTreeWidget::~QTreeWidget()

Elimina el widget de árbol y todos sus elementos.

void QTreeWidget::addTopLevelItem(QTreeWidgetItem *item)

Añade el elemento « item » como elemento de primer nivel en el widget.

Véase también insertTopLevelItem().

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

Añade la lista de items como elementos de primer nivel en el widget.

Véase también insertTopLevelItems().

[slot] void QTreeWidget::clear()

Borra el widget de árbol eliminando todos sus elementos y selecciones.

Nota: Dado que cada elemento se retira del widget de árbol antes de ser eliminado, el valor devuelto por ` QTreeWidgetItem::treeWidget()` no será válido cuando se llame desde el destructor de un elemento.

Véase también ` takeTopLevelItem()`, ` topLevelItemCount()` y ` columnCount()`.

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

Cierra el editor persistente de la tabla « item » en la tabla « column » indicada.

Esta función no tiene ningún efecto si no hay ningún editor persistente abierto para esta combinación de elemento y columna.

Véase también openPersistentEditor() y isPersistentEditorOpen().

[slot] void QTreeWidget::collapseItem(const QTreeWidgetItem *item)

Cierra el elemento « item ». Esto hace que se contraiga el árbol que contiene los elementos secundarios del elemento.

Véase también expandItem(), currentItem(), itemAt() y topLevelItem().

int QTreeWidget::currentColumn() const

Devuelve la columna actual en el widget de árbol.

Véase también setCurrentItem() y columnCount().

QTreeWidgetItem *QTreeWidget::currentItem() const

Devuelve el elemento actual del widget de árbol.

Véase también setCurrentItem() y currentItemChanged().

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

Esta señal se emite cuando cambia el elemento actual. El elemento actual se especifica mediante current, y esto sustituye al elemento actual de previous.

Véase también setCurrentItem().

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

Reimplementa: QAbstractItemView::dropEvent(QDropEvent *event).

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

Gestiona el objeto ` data ` proporcionado por una operación de arrastrar y soltar que ha finalizado con el ` action ` especificado en el ` index ` del elemento ` parent ` indicado.

La implementación por defecto devuelve ` true ` si la operación de soltar se ha gestionado correctamente mediante la decodificación de los datos MIME y su inserción en el modelo; en caso contrario, devuelve ` false`.

Véase también supportedDropActions() y supportedDragActions.

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

Comienza a editar el archivo « item » en la ruta indicada column, siempre que sea editable.

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

Reimplementa: ` QAbstractItemView::event(QEvent *event)`.

[slot] void QTreeWidget::expandItem(const QTreeWidgetItem *item)

Despliega el elemento « item ». Esto hace que se despliegue el árbol que contiene los elementos secundarios del elemento.

Véase también collapseItem(), currentItem(), itemAt(), topLevelItem() y itemExpanded().

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

Devuelve una lista de elementos que coinciden con el ` text` especificado, utilizando el ` flags` especificado, en el ` column` especificado.

QTreeWidgetItem *QTreeWidget::headerItem() const

Devuelve el elemento utilizado para el encabezado del widget de árbol.

Véase también setHeaderItem().

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

Devuelve el objeto ` QModelIndex ` asociado al ` item ` indicado en el ` column` especificado.

Nota: En las versiones de Qt anteriores a la 5.7, esta función aceptaba un item que no era unconst.

Véase también itemFromIndex() y topLevelItem().

int QTreeWidget::indexOfTopLevelItem(QTreeWidgetItem *item) const

Devuelve el índice del elemento de primer nivel item especificado, o -1 si no se encuentra el elemento.

Véase también sortItems() y topLevelItemCount().

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

Inserta el elemento « item » en « index » en el nivel superior de la vista.

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

Véase también addTopLevelItem() y columnCount().

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

Inserta la lista de items disponible en index en el nivel superior de la vista.

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

Véase también addTopLevelItems().

QTreeWidgetItem *QTreeWidget::invisibleRootItem() const

Devuelve el elemento raíz invisible del widget de árbol.

El elemento raíz invisible permite acceder a los elementos de nivel superior del widget de árbol a través de la API « QTreeWidgetItem », lo que permite escribir funciones capaces de tratar los elementos de nivel superior y sus hijos de forma uniforme; por ejemplo, funciones recursivas.

bool QTreeWidget::isPersistentEditorOpen(QTreeWidgetItem *item, int column = 0) const

Devuelve si hay un editor persistente abierto para el elemento item en la columna column.

Véase también openPersistentEditor() y closePersistentEditor().

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

Devuelve el elemento situado encima del elemento dado item.

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

Esta señal se emite cuando el usuario activa un elemento haciendo clic una o dos veces (dependiendo de la plataforma, es decir, según la indicación de estilo « QStyle::SH_ItemView_ActivateItemOnSingleClick ») o pulsando una tecla especial (por ejemplo, « Enter »).

El item especificado es el elemento en el que se ha hecho clic, o nullptr si no se ha hecho clic en ningún elemento. El column es la columna del elemento en la que se ha hecho clic, o -1 si no se ha hecho clic en ningún elemento.

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

Devuelve un puntero al elemento situado en las coordenadas p. Las coordenadas son relativas al sistema de coordenadas del widget de árbol viewport().

Véase también visualItemRect().

QTreeWidgetItem *QTreeWidget::itemAt(int x, int y) const

Devuelve un puntero al elemento situado en las coordenadas (x, y). Las coordenadas son relativas al método ` viewport()` del widget de árbol.

Esta es una función sobrecargada.

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

Devuelve el elemento situado visualmente debajo del ` item` indicado.

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

Esta señal se emite cuando cambia el contenido de la variable « column » en la variable « item » especificada.

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

Esta señal se emite cuando el usuario hace clic dentro del widget.

El « item » especificado es el elemento sobre el que se ha hecho clic. El « column » es la columna del elemento sobre la que se ha hecho clic. Si no se ha hecho clic en ningún elemento, no se emitirá ninguna señal.

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

Esta señal se emite cuando el elemento « item » especificado se contrae de tal forma que no se muestra ninguno de sus elementos secundarios.

Nota: Esta señal no se emitirá si un elemento cambia de estado al invocarse collapseAll().

Véase también ` QTreeWidgetItem::isExpanded()`, ` itemExpanded()` y ` collapseItem()`.

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

Esta señal se emite cuando el usuario hace doble clic dentro del widget.

El « item » especificado es el elemento sobre el que se ha hecho clic, o « nullptr » si no se ha hecho clic en ningún elemento. El « column » es la columna del elemento sobre la que se ha hecho clic. Si no se ha hecho doble clic en ningún elemento, no se emitirá ninguna señal.

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

Esta señal se emite cuando el cursor del ratón entra en un « item » situado sobre el « column » especificado. QTreeWidget Es necesario habilitar el seguimiento del ratón para que esta función funcione.

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

Esta señal se emite cuando se despliega el elemento « item » especificado, de modo que se muestren todos sus elementos secundarios.

Véase también QTreeWidgetItem::isExpanded(), itemCollapsed() y expandItem().

QTreeWidgetItem *QTreeWidget::itemFromIndex(const QModelIndex &index) const

Devuelve un puntero al objeto ` QTreeWidgetItem ` asociado al objeto ` index` indicado.

Véase también indexFromItem().

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

Esta señal se emite cuando el usuario pulsa un botón del ratón dentro del widget.

El « item » especificado es el elemento sobre el que se ha hecho clic, o « nullptr » si no se ha hecho clic en ningún elemento. El « column » es la columna del elemento sobre la que se ha hecho clic, o -1 si no se ha hecho clic en ningún elemento.

[signal] void QTreeWidget::itemSelectionChanged()

Esta señal se emite cuando cambia la selección en el widget de árbol. La selección actual se puede obtener mediante la función ` selectedItems()`.

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

Devuelve el widget que se muestra en la celda especificada por item y el column indicado.

Véase también setItemWidget() y removeItemWidget().

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

Devuelve un objeto que contiene una descripción serializada de la lista especificada ` items`. El formato utilizado para describir los elementos se obtiene mediante la función ` mimeTypes()`.

Si la lista de elementos está vacía, se devuelve nullptr en lugar de una lista vacía serializada.

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

Devuelve una lista de tipos MIME que se pueden utilizar para describir una lista de elementos del widget de árbol.

Véase también mimeData().

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

Abre un editor persistente para el archivo « item » en la ruta indicada column.

Véase también closePersistentEditor() y isPersistentEditorOpen().

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

Elimina el conjunto de widgets definido en la URL item dentro de la URL column.

Véase también itemWidget() y setItemWidget().

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

Garantiza que el elemento « item » esté visible, desplazando la vista si es necesario mediante el « hint » especificado.

Véase también currentItem(), itemAt() y topLevelItem().

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

Devuelve una lista de todos los elementos seleccionados que no estén ocultos.

Véase también itemSelectionChanged().

void QTreeWidget::setCurrentItem(QTreeWidgetItem *item)

Establece el « item » actual en el widget de árbol.

A menos que el modo de selección sea « NoSelection », el elemento también queda seleccionado.

Véase también « currentItem()» y « currentItemChanged()».

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

Establece el « item » actual en el widget de árbol y la columna actual en « column ».

Véase también currentItem().

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

Establece el « item » actual en el widget de árbol y la columna actual en « column », utilizando el « command » indicado.

Véase también currentItem().

void QTreeWidget::setHeaderItem(QTreeWidgetItem *item)

Establece el encabezado « item » para el widget de árbol. La etiqueta de cada columna del encabezado se obtiene de la etiqueta correspondiente del elemento.

El widget de árbol asume la propiedad del elemento.

Véase también headerItem() y setHeaderLabels().

void QTreeWidget::setHeaderLabel(const QString &label)

Igual que setHeaderLabels(QStringList(label)).

void QTreeWidget::setHeaderLabels(const QStringList &labels)

Añade una columna en el encabezado para cada elemento de la lista « labels » y establece la etiqueta de cada columna.

Ten en cuenta que setHeaderLabels() no elimina las columnas existentes.

Véanse también setHeaderItem() y setHeaderLabel().

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

Establece que el elemento widget indicado se muestre en la celda especificada por los elementos item y column indicados.

La propiedad autoFillBackground del widget indicado debe estar establecida en true; de lo contrario, el fondo del widget será transparente, mostrando tanto los datos del modelo como el elemento del widget de árbol.

Esta función solo debe utilizarse para mostrar contenido estático en lugar de un elemento del widget de árbol. Si deseas mostrar contenido dinámico personalizado o implementar un widget de editor personalizado, utiliza en su lugar QTreeView y subclasifica QStyledItemDelegate.

Esta función no se puede invocar antes de que se haya configurado la jerarquía de elementos; es decir, el ` QTreeWidgetItem ` que contendrá ` widget ` debe haberse añadido a la vista antes de establecer ` widget `.

Nota: El árbol asume la propiedad de widget.

Véase también itemWidget(), removeItemWidget() y Clases delegadas.

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

Reimplementa: ` QTreeView::setSelectionModel` (`QItemSelectionModel *selectionModel`).

int QTreeWidget::sortColumn() const

Devuelve la columna que se utiliza para ordenar el contenido del widget.

Véase también sortItems().

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

Ordena los elementos del widget en el « order » especificado según los valores del « column » indicado.

Véase también sortColumn().

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

Devuelve las acciones de arrastre y suelta compatibles con esta vista.

Véase también Qt::DropActions, supportedDragActions y dropMimeData().

QTreeWidgetItem *QTreeWidget::takeTopLevelItem(int index)

Elimina el elemento de nivel superior situado en la dirección index especificada en el árbol y lo devuelve; en caso contrario, devuelve nullptr;

Véase también insertTopLevelItem(), topLevelItem() y topLevelItemCount().

QTreeWidgetItem *QTreeWidget::topLevelItem(int index) const

Devuelve el elemento de nivel superior en la dirección indicada index, o nullptr si el elemento no existe.

Véase también topLevelItemCount() y insertTopLevelItem().

QRect QTreeWidget::visualItemRect(const QTreeWidgetItem *item) const

Devuelve el rectángulo que ocupa el elemento en la ventana gráfica en item.

Véase también itemAt().

© 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.