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) |
Elementos no miembros relacionados
| 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.
| Constante | Valor | Descripción |
|---|---|---|
QListWidgetItem::Type | 0 | El tipo predeterminado para los elementos del widget de lista. |
QListWidgetItem::UserType | 1000 | El 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().
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.