En esta página

QListWidgetItem Class

La clase QListWidgetItem proporciona un elemento para su uso con la clase de vista de elementos QListWidget. Más...

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

Tipos públicos

enum ItemType { Type, UserType }

Funciones públicas

QListWidgetItem(QListWidget *parent = nullptr, int type = Type)
QListWidgetItem(const QString &text, QListWidget *parent = nullptr, int type = Type)
QListWidgetItem(const QIcon &icon, const QString &text, QListWidget *parent = nullptr, int type = Type)
QListWidgetItem(const QListWidgetItem &other)
virtual ~QListWidgetItem()
QBrush background() const
Qt::CheckState checkState() const
virtual QListWidgetItem *clone() const
virtual QVariant data(int role) const
Qt::ItemFlags flags() const
QFont font() const
QBrush foreground() const
QIcon icon() const
bool isHidden() const
bool isSelected() const
QListWidget *listWidget() const
virtual void read(QDataStream &in)
void setBackground(const QBrush &brush)
void setCheckState(Qt::CheckState state)
virtual void setData(int role, const QVariant &value)
void setFlags(Qt::ItemFlags flags)
void setFont(const QFont &font)
void setForeground(const QBrush &brush)
void setHidden(bool hide)
void setIcon(const QIcon &icon)
void setSelected(bool select)
void setSizeHint(const QSize &size)
void setStatusTip(const QString &statusTip)
void setText(const QString &text)
(since 6.4) void setTextAlignment(Qt::Alignment alignment)
void setToolTip(const QString &toolTip)
void setWhatsThis(const QString &whatsThis)
QSize sizeHint() const
QString statusTip() const
QString text() const
int textAlignment() const
QString toolTip() const
int type() const
QString whatsThis() const
virtual void write(QDataStream &out) const
virtual bool operator<(const QListWidgetItem &other) const
QListWidgetItem &operator=(const QListWidgetItem &other)
QDataStream &operator<<(QDataStream &out, const QListWidgetItem &item)
QDataStream &operator>>(QDataStream &in, QListWidgetItem &item)

Descripción detallada

Un QListWidgetItem representa un único ítem en un QListWidget. Cada ítem puede contener varias piezas de información, y las mostrará apropiadamente.

Las clases de conveniencia de vista de ítems utilizan una interfaz clásica basada en ítems en lugar de un enfoque puro de modelo/vista. Para obtener un widget de vista de lista más flexible, considere la posibilidad de utilizar la clase QListView con un modelo estándar.

Los elementos de la lista se pueden insertar automáticamente en una lista, cuando se construyen, especificando el widget de lista:

new QListWidgetItem(tr("Hazel"), listWidget);

Alternativamente, los elementos de lista también pueden crearse sin un widget padre, y posteriormente insertarse en una lista utilizando QListWidget::insertItem().

Los elementos de lista se utilizan normalmente para mostrar text() y un icon(). Estos se establecen con las funciones setText() y setIcon(). El aspecto del texto puede personalizarse con setFont(), setForeground() y setBackground(). El texto de los elementos de la lista puede alinearse con la función setTextAlignment(). Se puede añadir información sobre herramientas, consejos de estado y ayuda "¿Qué es esto?" a los elementos de la lista con setToolTip(), setStatusTip() y setWhatsThis().

Por defecto, los elementos están activados, se pueden seleccionar, comprobar y pueden ser el origen de operaciones de arrastrar y soltar.

Los indicadores de cada elemento pueden cambiarse llamando a setFlags() con el valor apropiado (véase Qt::ItemFlags). Los elementos seleccionables se pueden marcar, desmarcar y marcar parcialmente con la función setCheckState(). La función checkState() correspondiente indica el estado de comprobación actual del elemento.

La función isHidden() puede utilizarse para determinar si el elemento está oculto. Para ocultar un elemento, utilice setHidden().

Subclase

Al subclasificar QListWidgetItem para proporcionar ítems personalizados, es posible definir nuevos tipos para ellos permitiendo distinguirlos de los ítems estándar. Para subclases que requieran esta característica, asegúrate de llamar al constructor de la clase base con un valor de tipo nuevo igual o mayor que UserType, dentro de tu constructor.

Véase también QListWidget, Programación Modelo/Vista, QTreeWidgetItem, y QTableWidgetItem.

Documentación de tipos miembros

enum QListWidgetItem::ItemType

Este enum describe los tipos que se utilizan para describir los elementos del widget de lista.

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

Puede definir nuevos tipos de usuario en las subclases de QListWidgetItem para asegurarse de que los elementos personalizados reciben un tratamiento especial.

Véase también type().

Documentación de las funciones miembro

[explicit] QListWidgetItem::QListWidgetItem(QListWidget *parent = nullptr, int type = Type)

Construye un elemento de widget de lista vacío del type especificado con el parent dado. Si no se especifica parent, el elemento deberá insertarse en un widget de lista con QListWidget::insertItem().

Este constructor inserta el elemento en el modelo del padre que se pasa al constructor. Si el modelo está ordenado, entonces el comportamiento de la inserción es indeterminado ya que el modelo llamará al método operador '<' en el elemento que, en este punto, aún no está construido. Para evitar el comportamiento indeterminado, recomendamos no especificar el padre y utilizar QListWidget::insertItem() en su lugar.

Véase también type().

[explicit] QListWidgetItem::QListWidgetItem(const QString &text, QListWidget *parent = nullptr, int type = Type)

Construye un elemento de widget de lista vacío del type especificado con los text y parent dados. Si no se especifica el padre, el elemento deberá insertarse en un widget de lista con QListWidget::insertItem().

Este constructor inserta el elemento en el modelo del padre que se pasa al constructor. Si el modelo está ordenado, entonces el comportamiento de la inserción es indeterminado, ya que el modelo llamará al método operador '<' en el elemento que, en este punto, aún no está construido. Para evitar el comportamiento indeterminado, recomendamos no especificar el padre y utilizar QListWidget::insertItem() en su lugar.

Véase también type().

[explicit] QListWidgetItem::QListWidgetItem(const QIcon &icon, const QString &text, QListWidget *parent = nullptr, int type = Type)

Construye un elemento de widget de lista vacío del type especificado con los icon, text y parent dados. Si no se especifica el padre, el elemento deberá insertarse en un widget de lista con QListWidget::insertItem().

Este constructor inserta el elemento en el modelo del padre que se pasa al constructor. Si el modelo está ordenado, entonces el comportamiento de la inserción es indeterminado ya que el modelo llamará al método operador '<' en el elemento que, en este punto, aún no está construido. Para evitar el comportamiento indeterminado, recomendamos no especificar el padre y utilizar QListWidget::insertItem() en su lugar.

Véase también type().

QListWidgetItem::QListWidgetItem(const QListWidgetItem &other)

Construye una copia de other. Tenga en cuenta que type() y listWidget() no se copian.

Esta función es útil cuando se reimplementa clone().

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

[virtual noexcept] QListWidgetItem::~QListWidgetItem()

Destruye el elemento de la lista.

QBrush QListWidgetItem::background() const

Devuelve el pincel utilizado para mostrar el fondo del elemento de la lista.

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

Qt::CheckState QListWidgetItem::checkState() const

Devuelve el estado comprobado del elemento de la lista (véase Qt::CheckState).

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

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

Crea una copia exacta del artículo.

[virtual] QVariant QListWidgetItem::data(int role) const

Devuelve los datos del elemento para un determinado role. Reimplemente esta función si necesita roles adicionales o un comportamiento especial para ciertos roles.

Véase también Qt::ItemDataRole y setData().

Qt::ItemFlags QListWidgetItem::flags() const

Devuelve las banderas de artículo de este artículo (véase Qt::ItemFlags).

Véase también setFlags().

QFont QListWidgetItem::font() const

Devuelve la fuente utilizada para mostrar el texto de este elemento de la lista.

Véase también setFont().

QBrush QListWidgetItem::foreground() const

Devuelve el pincel utilizado para mostrar el primer plano del elemento de la lista (por ejemplo, texto).

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

QIcon QListWidgetItem::icon() const

Devuelve el icono del elemento de la lista.

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

bool QListWidgetItem::isHidden() const

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

Véase también setHidden().

bool QListWidgetItem::isSelected() const

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

Véase también setSelected().

QListWidget *QListWidgetItem::listWidget() const

Devuelve el widget de lista que contiene el elemento.

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

Lee el elemento del flujo in.

Véase también write().

void QListWidgetItem::setBackground(const QBrush &brush)

Establece el pincel de fondo del elemento de la lista en la dirección brush. Establecer un pincel construido por defecto permitirá a la vista usar el color por defecto del estilo.

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

void QListWidgetItem::setCheckState(Qt::CheckState state)

Establece el estado de comprobación del elemento de la lista en state.

Véase también checkState().

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

Establece los datos para un role dado al value dado. Reimplemente esta función si necesita roles adicionales o un comportamiento especial para ciertos roles.

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

Véase también Qt::ItemDataRole y data().

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

Establece los indicadores del elemento de la lista en flags.

Véase también flags() y Qt::ItemFlags.

void QListWidgetItem::setFont(const QFont &font)

Establece la fuente utilizada al pintar el elemento en la dirección font.

Véase también font().

void QListWidgetItem::setForeground(const QBrush &brush)

Establece el pincel de primer plano del elemento de la lista en la dirección brush. Establecer un pincel construido por defecto permitirá a la vista utilizar el color por defecto del estilo.

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

void QListWidgetItem::setHidden(bool hide)

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

Véase también isHidden().

void QListWidgetItem::setIcon(const QIcon &icon)

Establece el icono del elemento de la lista en la dirección icon.

Véase también icon(), text() y iconSize.

void QListWidgetItem::setSelected(bool select)

Establece el estado seleccionado del elemento en select.

Véase también isSelected().

void QListWidgetItem::setSizeHint(const QSize &size)

Establece el tamaño del elemento de la lista en size. Si no se establece ninguna indicación de tamaño o size no es válida, el delegado del elemento calculará la indicación de tamaño basándose en los datos del elemento.

Véase también sizeHint().

void QListWidgetItem::setStatusTip(const QString &statusTip)

Establece la información de estado para el elemento de la lista en el texto especificado por statusTip. QListWidget mouseTracking debe estar activado para que esta función funcione.

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

void QListWidgetItem::setText(const QString &text)

Establece el texto de los elementos del widget de lista en la dirección text.

Véase también text().

[since 6.4] void QListWidgetItem::setTextAlignment(Qt::Alignment alignment)

Establece la alineación del texto del elemento de la lista en alignment.

Esta función se introdujo en Qt 6.4.

Véase también textAlignment().

void QListWidgetItem::setToolTip(const QString &toolTip)

Establece la información sobre herramientas para el elemento de la lista en el texto especificado por toolTip.

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

void QListWidgetItem::setWhatsThis(const QString &whatsThis)

Establece la ayuda "¿Qué es esto?" para el elemento de la lista en el texto especificado por whatsThis.

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

QSize QListWidgetItem::sizeHint() const

Devuelve la sugerencia de tamaño establecida para el elemento de la lista.

Véase también setSizeHint().

QString QListWidgetItem::statusTip() const

Devuelve la información de estado del elemento de la lista.

Véase también setStatusTip().

QString QListWidgetItem::text() const

Devuelve el texto del elemento de la lista.

Véase también setText().

int QListWidgetItem::textAlignment() const

Devuelve la alineación del texto del elemento de la lista.

Nota: Esta función devuelve un int por razones históricas. Será corregida para devolver Qt::Alignment en Qt 7.

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

QString QListWidgetItem::toolTip() const

Devuelve la información sobre herramientas del elemento de la lista.

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

int QListWidgetItem::type() const

Devuelve el tipo pasado al constructor QListWidgetItem.

QString QListWidgetItem::whatsThis() const

Devuelve el texto de ayuda "¿Qué es esto?" del elemento de la lista.

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

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

Escribe el elemento en el flujo out.

Véase también read().

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

Devuelve true si el texto de este elemento es menor que el texto del elemento other; en caso contrario devuelve false.

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

Asigna los datos y banderas de other a este elemento. Tenga en cuenta que type() y listWidget() no se copian.

Esta función es útil cuando se reimplementa clone().

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

No miembros relacionados

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

Escribe el elemento del widget de lista item en el flujo out.

Este operador utiliza QListWidgetItem::write().

Véase también Serializar tipos de datos Qt.

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

Lee un elemento de widget de lista del flujo in a item.

Este operador utiliza QListWidgetItem::read().

Véase también Serializar tipos de datos 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.