QStyledItemDelegate Class
La clase QStyledItemDelegate ofrece funciones de visualización y edición para los elementos de datos de un modelo. Más información...
| Encabezado: | #include <QStyledItemDelegate> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Heredado de: | QAbstractItemDelegate |
| Heredado por: |
Funciones públicas
| QStyledItemDelegate(QObject *parent = nullptr) | |
| virtual | ~QStyledItemDelegate() |
| virtual QString | displayText(const QVariant &value, const QLocale &locale) const |
| QItemEditorFactory * | itemEditorFactory() const |
| 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
| virtual void | initStyleOption(QStyleOptionViewItem *option, const QModelIndex &index) 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
Al mostrar datos de modelos en vistas de elementos de Qt, por ejemplo, una ` QTableView`, los elementos individuales son dibujados por un delegado. Además, cuando se edita un elemento, este proporciona un widget de edición, que se coloca sobre la vista del elemento mientras se lleva a cabo la edición. QStyledItemDelegate es el delegado predeterminado para todas las vistas de elementos de Qt y se les asigna al crearlas.
La clase QStyledItemDelegate es una de las clases de modelo/vista y forma parte del marco de trabajo de modelo/vista de Qt. El delegado permite que la visualización y la edición de elementos se desarrollen de forma independiente del modelo y la vista.
A los datos de los elementos en los modelos se les asigna un ` ItemDataRole`; cada elemento puede almacenar un ` QVariant ` para cada rol. `QStyledItemDelegate` implementa la visualización y la edición de los tipos de datos más comunes que esperan los usuarios, incluidos los booleanos, los enteros y las cadenas.
Los datos se representarán de forma diferente en función del rol que tengan en el modelo. La siguiente tabla describe los roles y los tipos de datos que el delegado puede gestionar para cada uno de ellos. A menudo basta con asegurarse de que el modelo devuelva los datos adecuados para cada uno de los roles para determinar la apariencia de los elementos en las vistas.
| Función | Tipos aceptados |
|---|---|
| Qt::BackgroundRole | QBrush |
| Qt::CheckStateRole | Qt::CheckState |
| Qt::DecorationRole | QIcon, QPixmap, QImage 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 |
Los editores se crean mediante un ` QItemEditorFactory`; en todos los delegados de elementos se instala una instancia estática predeterminada proporcionada por ` QItemEditorFactory `. Puedes establecer una fábrica personalizada mediante ` setItemEditorFactory()` o establecer una nueva fábrica predeterminada con ` QItemEditorFactory::setDefaultFactory()`.
QItemEditorFactory *editorFactory = new QItemEditorFactory;
QItemEditorCreatorBase *creator = new QStandardItemEditorCreator<MyFancyDateTimeEdit>();
editorFactory->registerEditor(QMetaType::QDateTime, creator);
QItemEditorFactory::setDefaultFactory(editorFactory);Una vez configurada la nueva fábrica, todos los delegados de elementos estándar la utilizarán (es decir, también los delegados que se crearon antes de que se configurara la nueva fábrica por defecto).
Lo que se edita son los datos almacenados en el modelo del elemento mediante la clase ` EditRole `. Consulte la clase ` QItemEditorFactory ` para obtener una introducción más general a las fábricas de editores de elementos.
Subclasificación de QStyledItemDelegate
Si el delegado no admite el dibujo de los tipos de datos que necesitas o si deseas personalizar el dibujo de los elementos, debes crear una subclase de `QStyledItemDelegate` y reimplementar ` paint()` y, posiblemente, ` sizeHint()`. La función ` paint()` se invoca individualmente para cada elemento, y con ` sizeHint()` puedes especificar la sugerencia para cada uno de ellos.
Al reimplementar ` paint()`, lo habitual es gestionar los tipos de datos que se desean dibujar y utilizar la implementación de la superclase para los demás tipos.
El dibujo de los indicadores de las casillas de selección lo realiza el estilo actual. El estilo también especifica el tamaño y los rectángulos delimitadores en los que se deben dibujar los datos para las diferentes funciones de datos. El rectángulo delimitador del propio elemento también lo calcula el estilo. Por lo tanto, al dibujar tipos de datos ya compatibles, es recomendable solicitar al estilo dichos rectángulos delimitadores. La descripción de la clase ` QStyle ` explica esto con más detalle.
Si desea modificar cualquiera de los rectángulos delimitadores calculados por el estilo o el dibujo de los indicadores de casillas de selección, puede crear una subclase de ` QStyle`. Tenga en cuenta, sin embargo, que el tamaño de los elementos también puede verse afectado al reimplementar ` sizeHint()`.
Es posible que un delegado personalizado proporcione editores sin utilizar una fábrica de elementos de editor. En este caso, deben reimplementarse las siguientes funciones virtuales:
- 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.
El ejemplo «Star Delegate » crea editores reimplementando estos métodos.
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 para los elementos de las vistas. La diferencia entre ellas 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.
Si deseas personalizar el dibujo de las vistas de elementos, debes implementar un estilo personalizado. Consulta la documentación de la clase ` QStyle ` para obtener más detalles.
Véase también Clases de delegado, QItemDelegate, QAbstractItemDelegate, QStyle y Ejemplo de delegado Star.
Documentación de las funciones de miembro
[explicit] QStyledItemDelegate::QStyledItemDelegate(QObject *parent = nullptr)
Crea un delegado de elemento con el ` parent` indicado.
[virtual noexcept] QStyledItemDelegate::~QStyledItemDelegate()
Elimina el delegado del elemento.
[override virtual] QWidget *QStyledItemDelegate::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().
[virtual] QString QStyledItemDelegate::displayText(const QVariant &value, const QLocale &locale) const
Esta función devuelve la cadena que el delegado utilizará para mostrar el « Qt::DisplayRole » del modelo en « locale ». « value » es el valor de « Qt::DisplayRole » proporcionado por el modelo.
La implementación por defecto utiliza el « QLocale::toString » para convertir « value » en un « QString ».
Esta función no se invoca para índices de modelo vacíos, es decir, índices para los que el modelo devuelve un ` QVariant` no válido.
Véase también QAbstractItemModel::data().
[override virtual protected] bool QStyledItemDelegate::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 QStyledItemDelegate::eventFilter(QObject *object, QEvent *event)
Reimplementa: QObject::eventFilter(QObject *watched, QEvent *event).
Consulta los detalles en QAbstractItemDelegate::handleEditorEvent().
[virtual protected] void QStyledItemDelegate::initStyleOption(QStyleOptionViewItem *option, const QModelIndex &index) const
Inicializa ` option ` con los valores utilizando el índice ` index`. Este método resulta útil para las subclases cuando necesitan un ` QStyleOptionViewItem`, pero no quieren rellenar toda la información por sí mismas.
Véase también QStyleOption::initFrom().
QItemEditorFactory *QStyledItemDelegate::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 QStyledItemDelegate::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`.
Esta función dibuja el elemento utilizando el ` QStyle` de la vista.
Al reimplementar `paint` en una subclase, utiliza ` initStyleOption()` para configurar ` option ` de la misma forma que ` QStyledItemDelegate`.
Siempre que sea posible, utiliza ` option ` durante el dibujo. En especial, su variable ` rect ` para decidir dónde dibujar y su ` state ` para determinar si está habilitado o seleccionado.
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éanse también QItemDelegate::paint(), QStyle::drawControl() y QStyle::CE_ItemViewItem.
[override virtual] void QStyledItemDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const
Reimplementa: QAbstractItemDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const.
Establece los datos que el widget « editor » debe 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 QStyledItemDelegate::setItemEditorFactory(QItemEditorFactory *factory)
Establece la fábrica de editores que debe 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 QStyledItemDelegate::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 predeterminada 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 QStyledItemDelegate::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`.
Esta función utiliza el QStyle de la vista para determinar el tamaño del elemento.
Véanse también QStyle::sizeFromContents() y QStyle::CT_ItemViewItem.
[override virtual] void QStyledItemDelegate::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 ` según 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.