En esta página

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

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 &currentText)
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

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

Descripción detallada

Lista de iconos meteorológicos

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 &currentText)

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.