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
- columnCount : int
(since 6.10)supportedDragActions : Qt::DropActions- topLevelItemCount : int
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
Descripción detallada

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.