QItemDelegate Class
La clase QItemDelegate ofrece funciones de visualización y edición para los elementos de datos de un modelo. Más información...
| Encabezado: | #include <QItemDelegate> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Heredado de: | QAbstractItemDelegate |
Propiedades
- clipping : bool
Funciones públicas
| QItemDelegate(QObject *parent = nullptr) | |
| virtual | ~QItemDelegate() |
| bool | hasClipping() const |
| QItemEditorFactory * | itemEditorFactory() const |
| void | setClipping(bool clip) |
| void | setItemEditorFactory(QItemEditorFactory *factory) |
Funciones públicas reimplementadas
| virtual QWidget * | createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const override |
| virtual void | paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const override |
| virtual void | setEditorData(QWidget *editor, const QModelIndex &index) const override |
| virtual void | setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const override |
| virtual QSize | sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const override |
| virtual void | updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const override |
Funciones protegidas
| void | drawBackground(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const |
| virtual void | drawCheck(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, Qt::CheckState state) const |
| virtual void | drawDecoration(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QPixmap &pixmap) const |
| virtual void | drawDisplay(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QString &text) const |
| virtual void | drawFocus(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect) const |
Funciones protegidas reimplementadas
| virtual bool | editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index) override |
| virtual bool | eventFilter(QObject *object, QEvent *event) override |
Descripción detallada
QItemDelegate se puede utilizar para proporcionar características de visualización personalizadas y controles de edición para vistas de elementos basadas en subclases de QAbstractItemView. El uso de un delegado con este fin permite personalizar y desarrollar los mecanismos de visualización y edición de forma independiente del modelo y la vista.
La clase QItemDelegate es una de las clases de modelo/vista y forma parte del marco de trabajo de modelo/vista de Qt. Ten en cuenta que ` QStyledItemDelegate ` ha asumido la tarea de dibujar las vistas de elementos de Qt. Recomendamos el uso de ` QStyledItemDelegate ` al crear nuevos delegados.
Al mostrar elementos de un modelo personalizado en una vista estándar, suele bastar con asegurarse de que el modelo devuelva los datos adecuados para cada uno de los roles que determinan la apariencia de los elementos en las vistas. El delegado predeterminado que utilizan las vistas estándar de Qt emplea esta información de roles para mostrar los elementos en la mayoría de los formatos habituales que esperan los usuarios. Sin embargo, a veces es necesario tener un control aún mayor sobre la apariencia de los elementos del que puede ofrecer el delegado predeterminado.
Esta clase proporciona implementaciones predeterminadas de las funciones para dibujar los datos de los elementos en una vista y editar datos de los modelos de los elementos. Se proporcionan implementaciones predeterminadas de las funciones virtuales « paint()» y « sizeHint()», definidas en « QAbstractItemDelegate », para garantizar que el delegado implemente el comportamiento básico correcto que esperan las vistas. Puedes reimplementar estas funciones en subclases para personalizar la apariencia de los elementos.
Al editar datos en la vista de un elemento, QItemDelegate proporciona un widget de editor, que es un widget que se coloca sobre la vista mientras se realiza la edición. Los editores se crean mediante « QItemEditorFactory »; en todos los delegados de elementos se instala una instancia estática por defecto proporcionada por « QItemEditorFactory ». Se puede establecer una fábrica personalizada mediante « setItemEditorFactory()» o definir una nueva fábrica por defecto con « QItemEditorFactory::setDefaultFactory()». Lo que se edita son los datos almacenados en el modelo del elemento con « Qt::EditRole ».
Aquí solo se reimplementan las funciones de edición estándar para los delegados basados en widgets:
- createEditor() devuelve el widget utilizado para modificar los datos del modelo y puede reimplementarse para personalizar el comportamiento de edición.
- setEditorData() proporciona al widget los datos que debe manipular.
- updateEditorGeometry() garantiza que el editor se muestre correctamente en relación con la vista del elemento.
- setModelData() devuelve los datos actualizados al modelo.
La señal « closeEditor » () indica que el usuario ha finalizado la edición de los datos y que el widget del editor puede eliminarse.
Roles y tipos de datos estándar
El delegado predeterminado utilizado por las vistas estándar suministradas con Qt asocia cada rol estándar (definido por Qt::ItemDataRole) con determinados tipos de datos. Los modelos que devuelven datos en estos tipos pueden influir en la apariencia del delegado, tal y como se describe en la siguiente tabla.
| Papel | Tipos aceptados |
|---|---|
| Qt::BackgroundRole | QBrush |
| Qt::CheckStateRole | Qt::CheckState |
| Qt::DecorationRole | QIcon, QPixmap y QColor |
| Qt::DisplayRole | QString y tipos con representación como cadena |
| Qt::EditRole | Consulte QItemEditorFactory para obtener más detalles |
| Qt::FontRole | QFont |
| Qt::SizeHintRole | QSize |
| Qt::TextAlignmentRole | Qt::Alignment |
| Qt::ForegroundRole | QBrush |
Si el delegado predeterminado no permite el nivel de personalización que necesitas, ya sea para fines de visualización o para editar datos, es posible crear una subclase de QItemDelegate para implementar el comportamiento deseado.
Creación de subclases
Al crear una subclase de QItemDelegate para crear un delegado que muestre elementos mediante un renderizador personalizado, es importante asegurarse de que el delegado pueda renderizar los elementos adecuadamente en todos los estados requeridos, tales como «seleccionado», «desactivado» o «marcado». La documentación de la función paint() contiene algunas sugerencias que muestran cómo lograrlo.
Se pueden proporcionar editores personalizados utilizando un ` QItemEditorFactory`. El siguiente código muestra cómo se puede poner un editor personalizado a disposición de los delegados mediante la fábrica de editores de elementos predeterminada.
QItemEditorFactory *editorFactory = new QItemEditorFactory;
QItemEditorCreatorBase *creator = new QStandardItemEditorCreator<MyFancyDateTimeEdit>();
editorFactory->registerEditor(QMetaType::QDateTime, creator);
QItemEditorFactory::setDefaultFactory(editorFactory);Una vez configurada la fábrica predeterminada, todos los delegados de elementos estándar la utilizarán (incluidos los delegados creados antes de configurar la fábrica predeterminada).
De esta forma, se evita crear subclases de `QItemDelegate`, y todos los valores del tipo especificado (por ejemplo, ` QMetaType::QDateTime`) se editarán utilizando el editor proporcionado (como ` MyFancyDateTimeEdit ` en el ejemplo anterior).
Una alternativa es reimplementar createEditor(), setEditorData(), setModelData() y updateEditorGeometry(). Este proceso se describe en la documentación general sobre programación Modelo/Vista.
QStyledItemDelegate frente a QItemDelegate
Desde Qt 4.4, existen dos clases de delegado: QItemDelegate y QStyledItemDelegate. Sin embargo, el delegado por defecto es QStyledItemDelegate. Estas dos clases son alternativas independientes para dibujar y proporcionar editores a los elementos de las vistas. La diferencia entre ambas es que QStyledItemDelegate utiliza el estilo actual para dibujar sus elementos. Por lo tanto, recomendamos utilizar QStyledItemDelegate como clase base al implementar delegados personalizados o al trabajar con hojas de estilo de Qt. El código necesario para cualquiera de las dos clases debería ser el mismo, a menos que el delegado personalizado necesite utilizar el estilo para el dibujo.
Véase también Clases de delegado, QStyledItemDelegate y QAbstractItemDelegate.
Documentación sobre propiedades
clipping : bool
si el delegado debe recortar los eventos de pintura
Esta propiedad establece el recorte de pintura al tamaño del elemento. El valor por defecto es «activado». Resulta útil en casos como cuando las imágenes son más grandes que el tamaño del elemento.
Funciones de Access:
| bool | hasClipping() const |
| void | setClipping(bool clip) |
Documentación de las funciones de miembro
[explicit] QItemDelegate::QItemDelegate(QObject *parent = nullptr)
Crea un delegado de elemento con el parent proporcionado.
[virtual noexcept] QItemDelegate::~QItemDelegate()
Elimina el delegado del elemento.
[override virtual] QWidget *QItemDelegate::createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const
Reimplementa: ` QAbstractItemDelegate::createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const`.
Devuelve el widget utilizado para editar el elemento especificado por ` index `. El widget ` parent ` y el estilo ` option ` se utilizan para controlar el aspecto del widget del editor.
Véase también QAbstractItemDelegate::createEditor().
[protected] void QItemDelegate::drawBackground(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const
Representa el fondo del elemento para el « index » especificado, utilizando el « painter » y el estilo « option » indicados.
[virtual protected] void QItemDelegate::drawCheck(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, Qt::CheckState state) const
Muestra un indicador de marca de verificación dentro del rectángulo especificado por ` rect`, utilizando el ` painter ` y el estilo ` option` indicados, y el ` state` especificado.
[virtual protected] void QItemDelegate::drawDecoration(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QPixmap &pixmap) const
Muestra la decoración pixmap dentro del rectángulo especificado por rect utilizando el painter y el estilo option indicados.
[virtual protected] void QItemDelegate::drawDisplay(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QString &text) const
Muestra la vista del elemento text dentro del rectángulo especificado por rect utilizando el painter y el estilo option indicados.
[virtual protected] void QItemDelegate::drawFocus(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect) const
Muestra la región situada dentro del rectángulo especificado por rect, indicando que tiene el foco, utilizando el painter y el estilo option indicados.
[override virtual protected] bool QItemDelegate::editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index)
Reimplementa: QAbstractItemDelegate::editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index).
[override virtual protected] bool QItemDelegate::eventFilter(QObject *object, QEvent *event)
Reimplementa: QObject::eventFilter(QObject *watched, QEvent *event).
Consulta los detalles en QAbstractItemDelegate::handleEditorEvent().
QItemEditorFactory *QItemDelegate::itemEditorFactory() const
Devuelve la fábrica de editores utilizada por el delegado del elemento. Si no se ha establecido ninguna fábrica de editores, la función devolverá null.
Véase también setItemEditorFactory().
[override virtual] void QItemDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const
Reimplementa: QAbstractItemDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const.
Representa el delegado utilizando el ` painter ` y el estilo ` option ` proporcionados para el elemento especificado por ` index`.
Al reimplementar esta función en una subclase, debe actualizar el área que contiene la variable « rect » de la opción, utilizando la variable « state » de la opción para determinar el estado del elemento que se va a mostrar, y ajustar la forma en que se dibuja en consecuencia.
Por ejemplo, puede que sea necesario mostrar un elemento seleccionado de forma diferente a los elementos no seleccionados, tal y como se muestra en el siguiente código:
if (option.state & QStyle::State_Selected)
painter->fillRect(option.rect, option.palette.highlight());Tras el dibujo, debes asegurarte de que el «painter» vuelva al estado en el que se encontraba cuando se llamó a esta función. Por ejemplo, puede resultar útil llamar a ` QPainter::save()` antes de dibujar y a ` QPainter::restore()` después.
Véase también ` QStyle::State`.
[override virtual] void QItemDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const
Reimplementa: QAbstractItemDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const.
Establece los datos que el editor mostrará y editará a partir del elemento del modelo de datos especificado por el modelo index.
La implementación por defecto almacena los datos en la propiedad de usuario del widget editor.
Véase también ` QMetaProperty::isUser()`.
void QItemDelegate::setItemEditorFactory(QItemEditorFactory *factory)
Establece la fábrica de editores que utilizará el delegado del elemento como la especificada en factory. Si no se establece ninguna fábrica de editores, el delegado del elemento utilizará la fábrica de editores predeterminada.
Véase también itemEditorFactory().
[override virtual] void QItemDelegate::setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const
Reimplementa: QAbstractItemDelegate::setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const.
Obtiene datos del widget ` editor ` y los almacena en el ` model ` especificado, en el elemento ` index`.
La implementación por defecto obtiene el valor que se va a almacenar en el modelo de datos a partir de la propiedad de usuario del widget « editor ».
Véase también ` QMetaProperty::isUser()`.
[override virtual] QSize QItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const
Reimplementa: ` QAbstractItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const`.
Devuelve el tamaño que necesita el delegado para mostrar el elemento especificado por ` index`, teniendo en cuenta la información de estilo proporcionada por ` option`.
Al reimplementar esta función, ten en cuenta que, en el caso de los elementos de texto, ` QItemDelegate ` añade un margen (es decir, 2 * ` QStyle::PM_FocusFrameHMargin`) a la longitud del texto.
[override virtual] void QItemDelegate::updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const
Reimplementa: QAbstractItemDelegate::updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const.
Actualiza el ` editor ` para el elemento especificado por ` index ` de acuerdo con el estilo ` option ` proporcionado.
© 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.