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 información...

Encabezado: #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 elemento en un QListWidget. Cada elemento puede contener varios datos y los mostrará de forma adecuada.

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

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

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

Como alternativa, los elementos de la lista también se pueden crear sin un widget padre e insertarse posteriormente en una lista mediante ` QListWidget::insertItem()`.

Los elementos de lista se utilizan normalmente para mostrar text() y un icon(). Estos se configuran con las funciones setText() y setIcon(). La apariencia del texto se puede personalizar con setFont(), setForeground() y setBackground(). El texto de los elementos de lista se puede alinear utilizando la función setTextAlignment(). Se pueden añadir información sobre herramientas, consejos de estado y la ayuda «¿Qué es esto?» a los elementos de la lista mediante las funciones setToolTip(), setStatusTip() y setWhatsThis().

Por defecto, los elementos están habilitados, son seleccionables, se pueden marcar y pueden ser objeto de operaciones de arrastrar y soltar.

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

La función isHidden() permite determinar si el elemento está oculto. Para ocultar un elemento, utiliza setHidden().

Subclasificación

Al crear subclases de `QListWidgetItem` para proporcionar elementos personalizados, es posible definir nuevos tipos para ellos, lo que permite distinguirlos de los elementos estándar. Para las 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 sobre tipos de miembros

enum QListWidgetItem::ItemType

Esta enumeración describe los tipos que se utilizan para definir los elementos de los widgets de lista.

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

Puedes definir nuevos tipos de usuario en subclases de ` QListWidgetItem ` para garantizar que los elementos personalizados reciban un tratamiento especial.

Véase también type().

Documentación de las funciones miembro

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

Crea un elemento de widget de lista vacío del tipo « type » especificado con el « parent » proporcionado. Si no se especifica « parent », el elemento deberá insertarse en un widget de lista mediante « QListWidget::insertItem()».

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

Véase también type().

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

Crea un elemento de widget de lista vacío del tipo « type » especificado con los valores « text » y « parent » proporcionados. Si no se especifica el padre, el elemento deberá insertarse en un widget de lista mediante « QListWidget::insertItem()».

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

Véase también type().

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

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

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

Véase también ` type()`.

QListWidgetItem::QListWidgetItem(const QListWidgetItem &other)

Crea una copia de ` other`. Ten en cuenta que ` type()` y ` listWidget()` no se copian.

Esta función resulta útil a la hora de reimplementar clone().

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

[virtual noexcept] QListWidgetItem::~QListWidgetItem()

Elimina 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 de selección del elemento de la lista (véase Qt::CheckState).

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

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

Crea una copia exacta del elemento.

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

Devuelve los datos del elemento para un « role » determinado. Reimplementa esta función si necesitas roles adicionales o un comportamiento especial para determinados roles.

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

Qt::ItemFlags QListWidgetItem::flags() const

Devuelve los indicadores de este elemento (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, el 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 el objeto ` brush` indicado. Si se establece un pincel creado de forma predeterminada, la vista utilizará el color predeterminado del estilo.

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

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

Establece el estado de selecció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 de un « role » determinado en el « value » indicado. Reimplementa esta función si necesitas roles adicionales o un comportamiento especial para determinados roles.

Nota: La implementación por defecto considera que Qt::EditRole y Qt::DisplayRole hacen referencia 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 que se utiliza al dibujar el elemento en la fuente especificada font.

Véase también font().

void QListWidgetItem::setForeground(const QBrush &brush)

Establece el pincel de primer plano del elemento de la lista en el ` brush` indicado. Si se establece un pincel creado de forma predeterminada, la vista utilizará el color predeterminado 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 el icon especificado.

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 la indicación de tamaño para el elemento de la lista como « size ». Si no se establece ninguna indicación de tamaño o si « size » no es válido, 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 descripción emergente del estado del elemento de la lista con el texto especificado en statusTip. QListWidget Es necesario que la función «mouseTracking» esté activada para que esta característica 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 según el valor proporcionado en 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 descripción emergente del elemento de la lista con el texto especificado en toolTip.

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

void QListWidgetItem::setWhatsThis(const QString &whatsThis)

Establece la ayuda «¿Qué es esto?» del elemento de la lista con el texto especificado en whatsThis.

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

QSize QListWidgetItem::sizeHint() const

Devuelve el valor de «hint» de tamaño establecido 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 motivos históricos. Se corregirá para que devuelva Qt::Alignment en Qt 7.

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

QString QListWidgetItem::toolTip() const

Devuelve la información de ayuda 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 de un elemento de « other »; en caso contrario, devuelve « false ».

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

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

Esta función resulta útil a la hora de reimplementar clone().

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

Elementos 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 «Serialización detipos de datos de Qt».

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

Lee un elemento del widget de lista desde el flujo in y lo guarda en item.

Este operador utiliza QListWidgetItem::read().

Véase también «Serialización detipos de datos de 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.