QListWidget Class
La clase QListWidget proporciona un widget de lista basado en elementos. Más información...
| Encabezado: | #include <QListWidget> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Heredado de: | QListView |
Propiedades
- count : int
- currentRow : int
- sortingEnabled : bool
(since 6.10)supportedDragActions : Qt::DropActions
Funciones públicas
| QListWidget(QWidget *parent = nullptr) | |
| virtual | ~QListWidget() |
| void | addItem(QListWidgetItem *item) |
| void | addItem(const QString &label) |
| void | addItems(const QStringList &labels) |
| void | closePersistentEditor(QListWidgetItem *item) |
| int | count() const |
| QListWidgetItem * | currentItem() const |
| int | currentRow() const |
| void | editItem(QListWidgetItem *item) |
| QList<QListWidgetItem *> | findItems(const QString &text, Qt::MatchFlags flags) const |
| QModelIndex | indexFromItem(const QListWidgetItem *item) const |
| void | insertItem(int row, QListWidgetItem *item) |
| void | insertItem(int row, const QString &label) |
| void | insertItems(int row, const QStringList &labels) |
| bool | isPersistentEditorOpen(QListWidgetItem *item) const |
| bool | isSortingEnabled() const |
| QListWidgetItem * | item(int row) const |
| QListWidgetItem * | itemAt(const QPoint &p) const |
| QListWidgetItem * | itemAt(int x, int y) const |
| QListWidgetItem * | itemFromIndex(const QModelIndex &index) const |
| QWidget * | itemWidget(QListWidgetItem *item) const |
| QList<QListWidgetItem *> | items(const QMimeData *data) const |
| void | openPersistentEditor(QListWidgetItem *item) |
| void | removeItemWidget(QListWidgetItem *item) |
| int | row(const QListWidgetItem *item) const |
| QList<QListWidgetItem *> | selectedItems() const |
| void | setCurrentItem(QListWidgetItem *item) |
| void | setCurrentItem(QListWidgetItem *item, QItemSelectionModel::SelectionFlags command) |
| void | setCurrentRow(int row) |
| void | setCurrentRow(int row, QItemSelectionModel::SelectionFlags command) |
| void | setItemWidget(QListWidgetItem *item, QWidget *widget) |
| void | setSortingEnabled(bool enable) |
| void | setSupportedDragActions(Qt::DropActions actions) |
| void | sortItems(Qt::SortOrder order = Qt::AscendingOrder) |
| Qt::DropActions | supportedDragActions() const |
| QListWidgetItem * | takeItem(int row) |
| QRect | visualItemRect(const QListWidgetItem *item) const |
Funciones públicas reimplementadas
| virtual void | setSelectionModel(QItemSelectionModel *selectionModel) override |
Ranuras públicas
| void | clear() |
| void | scrollToItem(const QListWidgetItem *item, QAbstractItemView::ScrollHint hint = EnsureVisible) |
Señales
| void | currentItemChanged(QListWidgetItem *current, QListWidgetItem *previous) |
| void | currentRowChanged(int currentRow) |
| void | currentTextChanged(const QString ¤tText) |
| void | itemActivated(QListWidgetItem *item) |
| void | itemChanged(QListWidgetItem *item) |
| void | itemClicked(QListWidgetItem *item) |
| void | itemDoubleClicked(QListWidgetItem *item) |
| void | itemEntered(QListWidgetItem *item) |
| void | itemPressed(QListWidgetItem *item) |
| void | itemSelectionChanged() |
Funciones protegidas
| virtual bool | dropMimeData(int index, const QMimeData *data, Qt::DropAction action) |
| virtual QMimeData * | mimeData(const QList<QListWidgetItem *> &items) const |
| virtual QStringList | mimeTypes() const |
| virtual Qt::DropActions | supportedDropActions() const |
Funciones protegidas reimplementadas
Descripción detallada

QListWidget es una clase de conveniencia que proporciona una vista de lista similar a la que ofrece QListView, pero con una interfaz clásica basada en elementos para añadir y eliminar elementos. QListWidget utiliza un modelo interno para gestionar cada QListWidgetItem de la lista.
Para obtener un widget de vista de lista más flexible, utiliza la clase QListView con un modelo estándar.
Los widgets de lista se construyen de la misma manera que otros widgets:
QListWidget *listWidget = new QListWidget(this);El método ` selectionMode()` de un widget de lista determina cuántos elementos de la lista se pueden seleccionar al mismo tiempo y si se pueden crear selecciones complejas de elementos. Esto se puede configurar con la función ` setSelectionMode()`.
Hay dos formas de añadir elementos a la lista: pueden crearse con el widget de lista como widget padre, o bien pueden crearse sin widget padre y añadirse a la lista posteriormente. Si ya existe un widget de lista cuando se crean los elementos, el primer método es más sencillo de utilizar:
new QListWidgetItem(tr("Oak"), listWidget);
new QListWidgetItem(tr("Fir"), listWidget);
new QListWidgetItem(tr("Pine"), listWidget);Si necesitas insertar un nuevo elemento en la lista en una posición concreta, este debe crearse sin un widget padre. A continuación, debe utilizarse la función insertItem() para colocarlo dentro de la lista. El widget de lista se hará cargo del elemento.
QListWidgetItem *newItem = new QListWidgetItem;
newItem->setText(itemText);
listWidget->insertItem(row, newItem);Para varios elementos, se puede utilizar en su lugar insertItems(). El número de elementos de la lista se obtiene con la función count(). Para eliminar elementos de la lista, utiliza takeItem().
El elemento actual de la lista se puede obtener con ` currentItem()` y modificarse con ` setCurrentItem()`. El usuario también puede cambiar el elemento actual navegando con el teclado o haciendo clic en otro elemento. Cuando cambia el elemento actual, se emite la señal ` currentItemChanged()` con el nuevo elemento actual y el elemento que era actual anteriormente.
Véase también QListWidgetItem, QListView, QTreeView, Programación Modelo/Vista y Ejemplo de cuadro de diálogo con pestañas.
Documentación de propiedades
[read-only] count : int
Esta propiedad contiene el número de elementos de la lista, incluidos los elementos ocultos.
Funciones de acceso:
| int | count() const |
currentRow : int
Esta propiedad contiene el número de fila del elemento actual.
Dependiendo del modo de selección actual, la fila también puede estar seleccionada.
Funciones de acceso:
| int | currentRow() const |
| void | setCurrentRow(int row) |
| void | setCurrentRow(int row, QItemSelectionModel::SelectionFlags command) |
Señal de notificación:
| void | currentRowChanged(int currentRow) |
sortingEnabled : bool
Esta propiedad indica si la ordenación está activada
Si esta propiedad es « true », la ordenación está habilitada para la lista; si la propiedad es «false», la ordenación no está habilitada.
El valor por defecto es «false».
Funciones de acceso:
| bool | isSortingEnabled() const |
| void | setSortingEnabled(bool enable) |
[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().
Documentación de las funciones miembro
[explicit] QListWidget::QListWidget(QWidget *parent = nullptr)
Crea un QListWidget vacío con el « parent » indicado.
[virtual noexcept] QListWidget::~QListWidget()
Elimina el widget de lista y todos sus elementos.
void QListWidget::addItem(QListWidgetItem *item)
Inserta el archivo « item » al final del widget de lista.
Advertencia: Solo se puede añadir una vezun « QListWidgetItem » a un « QListWidget ». Añadir varias veces el mismo « QListWidgetItem » a un « QListWidget » provocará un comportamiento indefinido.
Véase también insertItem().
void QListWidget::addItem(const QString &label)
Inserta un elemento con el texto « label » al final del widget de lista.
void QListWidget::addItems(const QStringList &labels)
Inserta elementos con el texto « labels » al final del widget de lista.
Véase también insertItems().
[slot] void QListWidget::clear()
Elimina todos los elementos y selecciones de la vista.
Advertencia: Todos los elementos se eliminarán de forma permanente.
void QListWidget::closePersistentEditor(QListWidgetItem *item)
Cierra el editor persistente correspondiente a la entrada « item » indicada.
Véase también openPersistentEditor() y isPersistentEditorOpen().
QListWidgetItem *QListWidget::currentItem() const
Devuelve el elemento actual.
Véase también setCurrentItem().
[signal] void QListWidget::currentItemChanged(QListWidgetItem *current, QListWidgetItem *previous)
Esta señal se emite cada vez que cambia el elemento actual.
previous es el elemento que tenía el foco anteriormente; current es el nuevo elemento actual.
[signal] void QListWidget::currentRowChanged(int currentRow)
Esta señal se emite cada vez que cambia el elemento actual.
currentRow es la fila del elemento actual. Si no hay ningún elemento actual, la propiedad « currentRow » es -1.
Nota: Señalde notificación para la propiedad « currentRow ».
[signal] void QListWidget::currentTextChanged(const QString ¤tText)
Esta señal se emite cada vez que cambia el elemento actual.
currentText es el texto del elemento actual. Si no hay ningún elemento actual, la función « currentText » no es válida.
[override virtual protected] void QListWidget::dropEvent(QDropEvent *event)
Reimplementa: QListView::dropEvent(QDropEvent *event).
[virtual protected] bool QListWidget::dropMimeData(int index, const QMimeData *data, Qt::DropAction action)
Gestiona los objetos ` data ` proporcionados por una operación externa de arrastrar y soltar que haya finalizado con el objeto ` action ` dado en el objeto ` index` dado. Devuelve ` true ` si el modelo puede gestionar ` data ` y ` action `; en caso contrario, devuelve ` false`.
Véase también supportedDropActions() y supportedDragActions.
void QListWidget::editItem(QListWidgetItem *item)
Comienza a editar el archivo « item » si es editable.
[override virtual protected] bool QListWidget::event(QEvent *e)
Reimplementa: QListView::event(QEvent *e).
QList<QListWidgetItem *> QListWidget::findItems(const QString &text, Qt::MatchFlags flags) const
Busca elementos cuyo texto coincida con la cadena « text » utilizando el « flags » indicado.
QModelIndex QListWidget::indexFromItem(const QListWidgetItem *item) const
Devuelve el objeto ` QModelIndex ` asociado al ` item` indicado.
Nota: En las versiones de Qt anteriores a la 5.10, esta función aceptaba un ` item` que no fuera de tipo `const `.
void QListWidget::insertItem(int row, QListWidgetItem *item)
Inserta el elemento item en la posición de la lista indicada por row.
Véase también addItem().
void QListWidget::insertItem(int row, const QString &label)
Inserta un elemento con el texto « label » en el widget de lista, en la posición indicada por « row ».
Véase también addItem().
void QListWidget::insertItems(int row, const QStringList &labels)
Inserta los elementos de la lista de labels en la lista, empezando por el row indicado.
Véase también insertItem() y addItem().
bool QListWidget::isPersistentEditorOpen(QListWidgetItem *item) const
Devuelve si hay un editor persistente abierto para el elemento item.
Véase también openPersistentEditor() y closePersistentEditor().
QListWidgetItem *QListWidget::item(int row) const
Devuelve el elemento que ocupa el ` row ` indicado en la lista, si se ha establecido alguno; en caso contrario, devuelve ` nullptr`.
Véase también row().
[signal] void QListWidget::itemActivated(QListWidgetItem *item)
Esta señal se emite cuando se activa el « item ». El « item » se activa cuando el usuario hace clic o doble clic sobre él, dependiendo de la configuración del sistema. También se activa cuando el usuario pulsa la tecla de activación (en Windows y X11 es la tecla « Return », en Mac OS X es « Command+O »).
QListWidgetItem *QListWidget::itemAt(const QPoint &p) const
Devuelve un puntero al elemento situado en las coordenadas p. Las coordenadas son relativas al método viewport() del widget de lista.
QListWidgetItem *QListWidget::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 lista.
Esta es una función sobrecargada.
[signal] void QListWidget::itemChanged(QListWidgetItem *item)
Esta señal se emite cada vez que cambian los datos de item.
[signal] void QListWidget::itemClicked(QListWidgetItem *item)
Esta señal se emite con el item especificado cuando se pulsa un botón del ratón sobre un elemento del widget.
Véase también itemPressed() y itemDoubleClicked().
[signal] void QListWidget::itemDoubleClicked(QListWidgetItem *item)
Esta señal se emite con el item especificado cuando se hace doble clic con el ratón sobre un elemento del widget.
Véase también itemClicked() y itemPressed().
[signal] void QListWidget::itemEntered(QListWidgetItem *item)
Esta señal se emite cuando el cursor del ratón entra en un elemento. El objeto ` item ` es el elemento en el que se ha entrado. Esta señal solo se emite cuando `mouseTracking` está activado, o cuando se pulsa un botón del ratón mientras se desplaza el cursor hacia un elemento.
Véase también QWidget::setMouseTracking().
QListWidgetItem *QListWidget::itemFromIndex(const QModelIndex &index) const
Devuelve un puntero al objeto ` QListWidgetItem ` asociado al objeto ` index` indicado.
[signal] void QListWidget::itemPressed(QListWidgetItem *item)
Esta señal se emite con el item especificado cuando se pulsa un botón del ratón sobre un elemento del widget.
Véase también itemClicked() y itemDoubleClicked().
[signal] void QListWidget::itemSelectionChanged()
Esta señal se emite cada vez que cambia la selección.
Véase también selectedItems(), QListWidgetItem::isSelected() y currentItemChanged().
QWidget *QListWidget::itemWidget(QListWidgetItem *item) const
Devuelve el widget que se muestra en el item indicado.
Véase también setItemWidget() y removeItemWidget().
QList<QListWidgetItem *> QListWidget::items(const QMimeData *data) const
Devuelve una lista de punteros a los elementos contenidos en el objeto ` data `. Si el objeto no ha sido creado mediante una llamada a ` QListWidget ` en el mismo proceso, la lista estará vacía.
[virtual protected] QMimeData *QListWidget::mimeData(const QList<QListWidgetItem *> &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 QListWidget::mimeTypes() const
Devuelve una lista de tipos MIME que se pueden utilizar para describir una lista de elementos de un «listwidget».
Véase también mimeData().
void QListWidget::openPersistentEditor(QListWidgetItem *item)
Abre un editor para el archivo item especificado. El editor permanece abierto tras la edición.
Véase también closePersistentEditor() y isPersistentEditorOpen().
void QListWidget::removeItemWidget(QListWidgetItem *item)
Elimina el conjunto de widgets establecido en el item indicado.
Para eliminar por completo un elemento (fila) de la lista, borra el elemento o utiliza takeItem().
Véase también itemWidget() y setItemWidget().
int QListWidget::row(const QListWidgetItem *item) const
Devuelve la fila que contiene el valor « item » indicado.
Véase también item().
[slot] void QListWidget::scrollToItem(const QListWidgetItem *item, QAbstractItemView::ScrollHint hint = EnsureVisible)
Desplaza la vista si es necesario para garantizar que el « item » esté visible.
hint Especifica dónde debe situarse el « item » tras la operación.
QList<QListWidgetItem *> QListWidget::selectedItems() const
Devuelve una lista con todos los elementos seleccionados en el widget de lista.
void QListWidget::setCurrentItem(QListWidgetItem *item)
Establece el elemento actual como « item ».
A menos que el modo de selección sea « NoSelection », el elemento también queda seleccionado.
Véase también currentItem().
void QListWidget::setCurrentItem(QListWidgetItem *item, QItemSelectionModel::SelectionFlags command)
Establece el elemento actual en « item », utilizando el « command » proporcionado.
void QListWidget::setCurrentRow(int row, QItemSelectionModel::SelectionFlags command)
Establece la fila actual como la especificada en « row », utilizando el valor proporcionado en « command »,
Nota: Funciónde asignación para la propiedad ` currentRow`.
Véase también currentRow().
void QListWidget::setItemWidget(QListWidgetItem *item, QWidget *widget)
Establece el elemento « widget » que se mostrará en el « item » indicado.
Esta función solo debe utilizarse para mostrar contenido estático en lugar de un elemento del widget de lista. Si deseas mostrar contenido dinámico personalizado o implementar un widget de editor personalizado, utiliza « QListView » y crea una subclase de « QStyledItemDelegate » en su lugar.
Nota: La lista asume la propiedad de widget.
Véase también itemWidget(), removeItemWidget() y Clases delegadas.
[override virtual] void QListWidget::setSelectionModel(QItemSelectionModel *selectionModel)
Reimplementa: QAbstractItemView::setSelectionModel(QItemSelectionModel *selectionModel).
void QListWidget::sortItems(Qt::SortOrder order = Qt::AscendingOrder)
Ordena todos los elementos del widget de lista según el criterio especificado en « order ».
[virtual protected] Qt::DropActions QListWidget::supportedDropActions() const
Devuelve las acciones de arrastrar y soltar compatibles con esta vista.
Véase también Qt::DropActions, supportedDragActions y dropMimeData().
QListWidgetItem *QListWidget::takeItem(int row)
Elimina y devuelve el elemento de la posición indicada ( row ) en el widget de lista; en caso contrario, devuelve nullptr.
Los elementos eliminados de un widget de lista no serán gestionados por Qt, por lo que deberán eliminarse manualmente.
Véase también insertItem() y addItem().
QRect QListWidget::visualItemRect(const QListWidgetItem *item) const
Devuelve el rectángulo de la ventana gráfica que ocupa el elemento en item.
© 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.