QStyledItemDelegate Class
La clase QStyledItemDelegate proporciona funciones de visualización y edición de elementos de datos de un modelo. Más...
| Cabecera: | #include <QStyledItemDelegate> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets)target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Hereda: | 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
Cuando se muestran datos de modelos en vistas de elementos de Qt, por ejemplo, un QTableView, los elementos individuales son dibujados por un delegado. Además, cuando se edita un elemento, proporciona un widget de editor, que se coloca encima de la vista de elemento mientras se realiza la edición. QStyledItemDelegate es el delegado por defecto para todas las vistas de elementos de Qt, y se instala en ellas cuando se crean.
La clase QStyledItemDelegate es una de las Clases Modelo/Vista y forma parte del framework modelo/vista de Qt. El delegado permite que la visualización y edición de elementos se desarrolle independientemente del modelo y la vista.
A los datos de los ítems en los modelos se les asigna un ItemDataRole; cada ítem puede almacenar un QVariant para cada rol. QStyledItemDelegate implementa la visualización y edición para los tipos de datos más comunes esperados por los usuarios, incluyendo booleanos, enteros y cadenas.
Los datos se dibujarán de forma diferente dependiendo del rol que tengan en el modelo. La siguiente tabla describe los roles y los tipos de datos que el delegado puede manejar para cada uno de ellos. A menudo es suficiente asegurarse de que el modelo devuelve los datos apropiados para cada uno de los roles para determinar la apariencia de los elementos en las vistas.
| Rol | Tipos aceptados |
|---|---|
| Qt::BackgroundRole | QBrush |
| Qt::CheckStateRole | Qt::CheckState |
| Qt::DecorationRole | QIcon QPixmap, y QImage 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 |
Los editores se crean con una QItemEditorFactory; una instancia estática por defecto proporcionada por QItemEditorFactory se instala en todos los delegados de elementos. Puede establecer una fábrica personalizada utilizando setItemEditorFactory() o establecer una nueva fábrica por defecto con QItemEditorFactory::setDefaultFactory().
QItemEditorFactory *editorFactory = new QItemEditorFactory; QItemEditorCreatorBase *creator = new QStandardItemEditorCreator<MyFancyDateTimeEdit>(); editorFactory->registerEditor(QMetaType::QDateTime, creator); QItemEditorFactory::setDefaultFactory(editorFactory);
Una vez establecida la nueva fábrica, todos los delegados de ítems estándar la utilizarán (es decir, también los delegados que se crearon antes de establecer la nueva fábrica por defecto).
Son los datos almacenados en el modelo de ítem con EditRole los que se editan. Ver la clase QItemEditorFactory para una introducción de más alto nivel a las fábricas editoras de ítems.
Subclase de QStyledItemDelegate
Si el delegado no soporta el pintado de los tipos de datos que necesitas o quieres personalizar el dibujado de los ítems, necesitas subclasificar QStyledItemDelegate, y reimplementar paint() y posiblemente sizeHint(). La función paint() es llamada individualmente para cada ítem, y con sizeHint(), puedes especificar la sugerencia para cada uno de ellos.
Al reimplementar paint(), uno normalmente manejaría los tipos de datos que le gustaría dibujar y utilizaría la implementación de la superclase para otros tipos.
El pintado de los indicadores de casilla de verificación se realiza mediante el estilo actual. El estilo también especifica el tamaño y los rectángulos delimitadores en los que dibujar los datos para los diferentes roles de datos. El rectángulo delimitador del propio elemento también se calcula mediante el estilo. Cuando se dibujan tipos de datos ya soportados, es una buena idea preguntar al estilo por estos rectángulos delimitadores. La descripción de la clase QStyle describe esto con más detalle.
Si desea modificar alguno de los rectángulos delimitadores calculados por el estilo o el pintado de los indicadores de casilla de verificación, puede subclasificar QStyle. Tenga en cuenta, sin embargo, que el tamaño de los elementos también puede verse afectado reimplementando sizeHint().
Es posible que un delegado personalizado proporcione editores sin utilizar una fábrica de elementos de editor. En este caso, las siguientes funciones virtuales deben ser reimplementadas:
- createEditor() devuelve el widget utilizado para cambiar 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.
El ejemplo Star Delegate crea editores reimplementando estos métodos.
QStyledItemDelegate vs. 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 pintar y proporcionar editores para elementos en vistas. La diferencia entre ellas es que QStyledItemDelegate utiliza el estilo actual para pintar sus elementos. Por 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 el pintado.
Si desea personalizar el pintado de las vistas de elementos, deberá implementar un estilo personalizado. Consulte la documentación de la clase QStyle para obtener más detalles.
Véase también Clases de delegados, QItemDelegate, QAbstractItemDelegate, QStyle, y Ejemplo de delegado estrella.
Documentación de las funciones miembro
[explicit] QStyledItemDelegate::QStyledItemDelegate(QObject *parent = nullptr)
Construye un elemento delegado con la dirección parent.
[virtual noexcept] QStyledItemDelegate::~QStyledItemDelegate()
Destruye el elemento delegado.
[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 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().
[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 del 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 llama 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).
Ver 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 es útil para subclases cuando necesitan un QStyleOptionViewItem, pero no quieren rellenar toda la información ellos mismos.
Véase también QStyleOption::initFrom().
QItemEditorFactory *QStyledItemDelegate::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 QStyledItemDelegate::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.
Esta función pinta el elemento utilizando la vista QStyle.
Al reimplementar paint en una subclase. Utilice initStyleOption() para configurar option del mismo modo que QStyledItemDelegate.
Siempre que sea posible, utilice el option mientras pinta. Especialmente su variable rect para decidir dónde dibujar y su state para determinar si está activado o seleccionado.
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 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 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 QStyledItemDelegate::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 QStyledItemDelegate::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 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 QStyle de la vista para determinar el tamaño del elemento.
Véase 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 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.
