QItemDelegate Class
La clase QItemDelegate proporciona facilidades de visualización y edición para los elementos de datos de un modelo. Más...
| Cabecera: | #include <QItemDelegate> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets)target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Hereda: | 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 puede utilizarse para proporcionar funciones de visualización personalizadas y widgets de edición para vistas de elementos basadas en subclases de QAbstractItemView. El uso de un delegado para este propósito permite que los mecanismos de visualización y edición sean personalizados y desarrollados independientemente del modelo y la vista.
La clase QItemDelegate es una de las Clases Modelo/Vista y forma parte del framework modelo/vista de Qt. Observe que QStyledItemDelegate se ha encargado de dibujar las vistas de elementos de Qt. Recomendamos el uso de QStyledItemDelegate al crear nuevos delegados.
Cuando se muestran elementos de un modelo personalizado en una vista estándar, a menudo es suficiente con asegurarse de que el modelo devuelve los datos apropiados para cada uno de los roles que determinan la apariencia de los elementos en las vistas. El delegado por defecto utilizado por las vistas estándar de Qt utiliza esta información de rol para mostrar los elementos en la mayoría de las formas comunes esperadas por los usuarios. Sin embargo, a veces es necesario tener un mayor control sobre la apariencia de los elementos que el que puede proporcionar el delegado por defecto.
Esta clase proporciona implementaciones por defecto de las funciones para pintar datos de elementos en una vista y editar datos de modelos de elementos. Las implementaciones predeterminadas de las funciones virtuales paint() y sizeHint(), definidas en QAbstractItemDelegate, se proporcionan 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.
Cuando se editan datos en una vista de elemento, QItemDelegate proporciona un widget editor, que es un widget que se coloca encima de la vista mientras se realiza la edición. Los editores se crean con un QItemEditorFactory; una instancia estática por defecto proporcionada por QItemEditorFactory se instala en todos los delegados de ítem. Puedes establecer una fábrica personalizada utilizando setItemEditorFactory() o establecer una nueva fábrica por defecto con QItemEditorFactory::setDefaultFactory(). Son los datos almacenados en el modelo de ítem con Qt::EditRole los que se editan.
Aquí sólo se reimplementan las funciones de edición estándar para los delegados basados en widgets:
- createEditor() devuelve el widget utilizado para cambiar los datos del modelo y puede reimplementarse para personalizar el comportamiento de edición.
- setEditorData() proporciona al widget datos para manipular.
- updateEditorGeometry() garantiza que el editor se muestre correctamente con respecto a la vista del elemento.
- setModelData() devuelve los datos actualizados al modelo.
La señal closeEditor() indica que el usuario ha terminado de editar los datos, y que el widget editor puede ser destruido.
Roles y tipos de datos estándar
El delegado por defecto utilizado por las vistas estándar suministradas con Qt asocia cada rol estándar (definido por Qt::ItemDataRole) con ciertos tipos de datos. Los modelos que devuelven datos en estos tipos pueden influir en la apariencia del delegado como se describe en la siguiente tabla.
| Rol | Tipos aceptados |
|---|---|
| Qt::BackgroundRole | QBrush |
| Qt::CheckStateRole | Qt::CheckState |
| Qt::DecorationRole | QIcon, QPixmap y QColor |
| Qt::DisplayRole | QString y tipos con representación de cadena |
| Qt::EditRole | Véase QItemEditorFactory para más detalles |
| Qt::FontRole | QFont |
| Qt::SizeHintRole | QSize |
| Qt::TextAlignmentRole | Qt::Alignment |
| Qt::ForegroundRole | QBrush |
Si el delegado por defecto no permite el nivel de personalización que necesitas, ya sea para la visualización o para la edición de datos, es posible subclasificar QItemDelegate para implementar el comportamiento deseado.
Subclase
Al subclasificar QItemDelegate para crear un delegado que muestre los ítems utilizando un renderizador personalizado, es importante asegurarse de que el delegado puede renderizar los ítems adecuadamente para todos los estados requeridos; como seleccionado, deshabilitado, marcado. La documentación de la función paint() contiene algunas pistas que muestran cómo conseguirlo.
Puedes proporcionar editores personalizados utilizando QItemEditorFactory. El siguiente código muestra cómo se puede poner un editor personalizado a disposición de los delegados con la fábrica de editores de elementos por defecto.
QItemEditorFactory *editorFactory = new QItemEditorFactory; QItemEditorCreatorBase *creator = new QStandardItemEditorCreator<MyFancyDateTimeEdit>(); editorFactory->registerEditor(QMetaType::QDateTime, creator); QItemEditorFactory::setDefaultFactory(editorFactory);
Una vez establecida la fábrica por defecto, todos los delegados de ítems estándar la utilizarán (también los delegados que fueron creados antes de establecer la fábrica por defecto).
De esta forma, puedes evitar subclasificar QItemDelegate, y todos los valores del tipo especificado (por ejemplo QMetaType::QDateTime) serán editados usando 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 de Programación Modelo/Vista.
QStyledItemDelegate vs. QItemDelegate
Desde Qt 4.4, hay dos clases delegadas: QItemDelegate y QStyledItemDelegate. Sin embargo, el delegado por defecto es QStyledItemDelegate. Estas dos clases son alternativas independientes para pintar y proporcionar editores para elementos en vistas. La diferencia entre ellas es que QStyledItemDelegate utiliza el estilo actual para pintar sus elementos. Por lo tanto, recomendamos utilizar QStyledItemDelegate como clase base cuando se implementen delegados personalizados o cuando se trabaje con hojas de estilo Qt. El código requerido para cualquiera de las dos clases debería ser igual a menos que el delegado personalizado necesite utilizar el estilo para dibujar.
Véase también Clases delegadas, QStyledItemDelegate, y QAbstractItemDelegate.
Documentación de Propiedades
clipping : bool
si el delegado debe recortar los eventos de pintura
Esta propiedad ajustará el recorte de pintura al tamaño del elemento. El valor por defecto es on. Es útil para casos como cuando las imágenes son más grandes que el tamaño del elemento.
Funciones de acceso:
| bool | hasClipping() const |
| void | setClipping(bool clip) |
Documentación de funciones miembro
[explicit] QItemDelegate::QItemDelegate(QObject *parent = nullptr)
Construye un elemento delegado con la dirección parent.
[virtual noexcept] QItemDelegate::~QItemDelegate()
Destruye el elemento delegado.
[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 usado para editar el item especificado por index para editar. El widget parent y el estilo option se utilizan para controlar cómo aparece el widget editor.
Ver también QAbstractItemDelegate::createEditor().
[protected] void QItemDelegate::drawBackground(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const
Renderiza el fondo del ítem para el index dado , usando el painter y el estilo option dados.
[virtual protected] void QItemDelegate::drawCheck(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, Qt::CheckState state) const
Renderiza un indicador de comprobación dentro del rectángulo especificado por rect, utilizando el painter y el estilo option dados, utilizando el state dado.
[virtual protected] void QItemDelegate::drawDecoration(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QPixmap &pixmap) const
Renderiza la decoración pixmap dentro del rectángulo especificado por rect utilizando el painter y el estilo option dados.
[virtual protected] void QItemDelegate::drawDisplay(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QString &text) const
Renderiza la vista del elemento text dentro del rectángulo especificado por rect utilizando el painter y el estilo option dados.
[virtual protected] void QItemDelegate::drawFocus(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect) const
Renderiza la región dentro del rectángulo especificado por rect, indicando que tiene el foco, utilizando el painter y el estilo option dados.
[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).
Ver detalles en QAbstractItemDelegate::handleEditorEvent().
QItemEditorFactory *QItemDelegate::itemEditorFactory() const
Devuelve la fábrica del editor utilizada por el delegado del elemento. Si no se establece 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.
Renderiza el delegado usando el painter y el estilo option dados para el item especificado por index.
Cuando reimplemente esta función en una subclase, deberá actualizar el área contenida en la variable rect de la opción, utilizando la variable state de la opción para determinar el estado del elemento a mostrar, y ajustar la forma en que se pinta en consecuencia.
Por ejemplo, un elemento seleccionado puede necesitar ser mostrado de forma diferente a los elementos no seleccionados, como se muestra en el siguiente código:
if (option.state & QStyle::State_Selected) painter->fillRect(option.rect, option.palette.highlight());
Después de pintar, debe asegurarse de que el pintor vuelve al estado en el que se encontraba cuando se llamó a esta función. Por ejemplo, puede ser útil llamar a QPainter::save() antes de pintar 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 a mostrar y editar por el editor desde el 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 en la dirección factory especificada. Si no se establece ninguna fábrica de editores, el delegado de elementos 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 los datos del widget editor y los almacena en el model especificado en el ítem index.
La implementación por defecto obtiene el valor a almacenar en el modelo de datos 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, tenga en cuenta que en el caso de 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 item especificado por index de acuerdo al estilo option dado.
© 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.
