QAbstractItemDelegate Class
La clase `QAbstractItemDelegate` se utiliza para mostrar y editar elementos de datos de un modelo. Más información...
| Encabezado: | #include <QAbstractItemDelegate> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Heredado de: | QObject |
| Heredado por: |
Tipos públicos
| enum | EndEditHint { NoHint, EditNextItem, EditPreviousItem, SubmitModelCache, RevertModelCache } |
Funciones públicas
| QAbstractItemDelegate(QObject *parent = nullptr) | |
| virtual | ~QAbstractItemDelegate() |
| virtual QWidget * | createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const |
| virtual void | destroyEditor(QWidget *editor, const QModelIndex &index) const |
| virtual bool | editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index) |
(since 6.10) bool | handleEditorEvent(QObject *editor, QEvent *event) |
| virtual bool | helpEvent(QHelpEvent *event, QAbstractItemView *view, const QStyleOptionViewItem &option, const QModelIndex &index) |
| virtual void | paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const = 0 |
| virtual void | setEditorData(QWidget *editor, const QModelIndex &index) const |
| virtual void | setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const |
| virtual QSize | sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const = 0 |
| virtual void | updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const |
Señales
| void | closeEditor(QWidget *editor, QAbstractItemDelegate::EndEditHint hint = NoHint) |
| void | commitData(QWidget *editor) |
| void | sizeHintChanged(const QModelIndex &index) |
Descripción detallada
Una clase `QAbstractItemDelegate` proporciona la interfaz y la funcionalidad común para los delegados en la arquitectura modelo/vista. Los delegados muestran elementos individuales en las vistas y gestionan la edición de los datos del modelo.
La clase `QAbstractItemDelegate` es una de las clases de modelo/vista y forma parte del marco de trabajo de modelo/vista de Qt.
Para representar un elemento de forma personalizada, debes implementar ` paint()` y ` sizeHint()`. La clase ` QStyledItemDelegate ` proporciona implementaciones predeterminadas para estas funciones; si no necesitas una representación personalizada, crea una subclase de esa clase.
A continuación, ofrecemos un ejemplo de cómo dibujar una barra de progreso en «items»; en nuestro caso, para un programa de gestión de paquetes.

Creamos la clase ` WidgetDelegate `, que hereda de ` QStyledItemDelegate`. Realizamos el dibujo en la función ` paint()`:
void WidgetDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option,
const QModelIndex &index) const
{
if (index.column() == 1) {
int progress = index.data().toInt();
QStyleOptionProgressBar progressBarOption;
progressBarOption.rect = option.rect;
progressBarOption.minimum = 0;
progressBarOption.maximum = 100;
progressBarOption.progress = progress;
progressBarOption.text = QString::number(progress) + "%";
progressBarOption.textVisible = true;
QApplication::style()->drawControl(QStyle::CE_ProgressBar,
&progressBarOption, painter);
} else
QStyledItemDelegate::paint(painter, option, index);Fíjate en que utilizamos un ` QStyleOptionProgressBar ` e inicializamos sus miembros. A continuación, podemos utilizar el ` QStyle ` actual para dibujarlo.
Para ofrecer una edición personalizada, se pueden utilizar dos enfoques. El primer enfoque consiste en crear un control de edición y mostrarlo directamente sobre el elemento. Para ello, hay que reimplementar createEditor() para proporcionar un control de edición, setEditorData() para rellenar el editor con los datos del modelo y setModelData() para que el delegado pueda actualizar el modelo con los datos del editor.
El segundo enfoque consiste en gestionar los eventos del usuario directamente reimplementando editorEvent().
Véase también Programación Modelo/Vista, QStyledItemDelegate y QStyle.
Documentación sobre tipos de miembros
enum QAbstractItemDelegate::EndEditHint
Esta enumeración describe las diferentes indicaciones que el delegado puede proporcionar a los componentes del modelo y de la vista para que la edición de datos en un modelo resulte una experiencia cómoda para el usuario.
| Constante | Valor | Descripción |
|---|---|---|
QAbstractItemDelegate::NoHint | 0 | No hay ninguna acción recomendada que se deba realizar. |
Estas indicaciones permiten al delegado influir en el comportamiento de la vista:
| Constante | Valor | Descripción |
|---|---|---|
QAbstractItemDelegate::EditNextItem | 1 | La vista debe utilizar el delegado para abrir un editor en el siguiente elemento de la vista. |
QAbstractItemDelegate::EditPreviousItem | 2 | La vista debe utilizar el delegado para abrir un editor en el elemento anterior de la vista. |
Ten en cuenta que las vistas personalizadas pueden interpretar los conceptos de «siguiente» y «anterior» de forma diferente.
Las siguientes sugerencias resultan especialmente útiles cuando se utilizan modelos que almacenan datos en caché, como aquellos que manipulan datos localmente para aumentar el rendimiento o ahorrar ancho de banda de red.
| Constante | Valor | Descripción |
|---|---|---|
QAbstractItemDelegate::SubmitModelCache | 3 | Si el modelo almacena datos en caché, debe escribir los datos almacenados en el almacén de datos subyacente. |
QAbstractItemDelegate::RevertModelCache | 4 | Si el modelo almacena datos en caché, debe descartar los datos almacenados y sustituirlos por los datos del almacén subyacente. |
Aunque los modelos y las vistas deben responder a estas sugerencias de forma adecuada, los componentes personalizados pueden ignorar alguna o todas ellas si no son relevantes.
Documentación de funciones de miembro
[explicit] QAbstractItemDelegate::QAbstractItemDelegate(QObject *parent = nullptr)
Crea un nuevo delegado de elemento abstracto con el ` parent` indicado.
[virtual noexcept] QAbstractItemDelegate::~QAbstractItemDelegate()
Elimina el delegado del elemento abstracto.
[signal] void QAbstractItemDelegate::closeEditor(QWidget *editor, QAbstractItemDelegate::EndEditHint hint = NoHint)
Esta señal se emite cuando el usuario ha terminado de editar un elemento utilizando el ` editor` especificado.
El hint permite al delegado influir en el comportamiento del modelo y la vista una vez finalizada la edición. Indica a estos componentes qué acción deben realizar a continuación para ofrecer al usuario una experiencia de edición cómoda. Por ejemplo, si se especifica EditNextItem, la vista debe utilizar un delegado para abrir un editor en el siguiente elemento del modelo.
Véase también EndEditHint.
[signal] void QAbstractItemDelegate::commitData(QWidget *editor)
Esta señal debe emitirse cuando el widget « editor » haya finalizado la edición de los datos y desee volver a escribirlos en el modelo.
[virtual] QWidget *QAbstractItemDelegate::createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const
Devuelve el editor que se utilizará para editar el elemento de datos con el index dado. Ten en cuenta que el índice contiene información sobre el modelo que se está utilizando. El widget padre del editor se especifica mediante parent, y las opciones del elemento mediante option.
La implementación básica devuelve ` nullptr`. Si deseas una edición personalizada, deberás reimplementar esta función.
El widget editor devuelto debe tener Qt::StrongFocus; de lo contrario, los QMouseEventrecibidos por el widget se propagarán a la vista. El fondo de la vista se verá a través a menos que el editor dibuje su propio fondo (por ejemplo, con setAutoFillBackground()).
Véase también destroyEditor(), setModelData() y setEditorData().
[virtual] void QAbstractItemDelegate::destroyEditor(QWidget *editor, const QModelIndex &index) const
Se invoca cuando ya no se necesita el objeto « editor » para editar el elemento de datos con el « index » indicado y debe eliminarse. El comportamiento por defecto consiste en llamar a la función «deleteLater» del editor. Es posible, por ejemplo, evitar esta eliminación reimplementando esta función.
Véase también createEditor().
[virtual] bool QAbstractItemDelegate::editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index)
Cuando se inicia la edición de un elemento, se invoca esta función con el ` event ` que ha activado la edición, el ` model`, el ` index ` del elemento y el ` option ` utilizado para mostrar el elemento.
Los eventos del ratón se envían a editorEvent() aunque no inicien la edición del elemento. Esto puede resultar útil, por ejemplo, si se desea abrir un menú contextual al pulsar el botón derecho del ratón sobre un elemento.
La implementación base devuelve ` false ` (lo que indica que no ha gestionado el evento).
[since 6.10] bool QAbstractItemDelegate::handleEditorEvent(QObject *editor, QEvent *event)
Implementa el manejo estándar de eventos en nombre del editor actualmente activo. Llama a esta función desde una sobrescritura de eventFilter() en una subclase de QAbstractItemModel y devuelve su resultado. Para evitar el procesamiento duplicado de eventos, no llames a la implementación de la clase padre de eventFilter() después de llamar a esta función.
Devuelve ` true ` si el ` editor ` proporcionado es un ` QWidget ` válido y el ` event ` proporcionado se gestiona; en caso contrario, devuelve ` false`. Los siguientes eventos de pulsación de teclas se gestionan de forma predeterminada:
- Tab
- Backtab
- Enter
- Return
- Esc
Si el tipo de editor es QTextEdit o QPlainTextEdit, entonces no se gestionan las teclas Tab, Backtab, Enter y Return.
En el caso de los eventos de pulsación de teclas Tab, Backtab, Enter y Return, los datos de editor se guardan en el modelo y se cierra el editor. Si event corresponde a una pulsación de la tecla Tab, la vista abrirá un editor en el siguiente elemento de la vista. Del mismo modo, si event corresponde a una pulsación de la tecla Backtab, la vista abrirá un editor en el elemento anterior de la vista.
Si el evento es un evento de pulsación de tecla Esc, el editor se cierra sin guardar sus datos.
Esta función se introdujo en Qt 6.10.
Véase también commitData() y closeEditor().
[virtual] bool QAbstractItemDelegate::helpEvent(QHelpEvent *event, QAbstractItemView *view, const QStyleOptionViewItem &option, const QModelIndex &index)
Cada vez que se produce un evento de ayuda, se invoca esta función con los parámetros event, view, option y el index correspondiente al elemento en el que se produce el evento.
Devuelve true si el delegado puede gestionar el evento; en caso contrario, devuelve false. Un valor de retorno true indica que los datos obtenidos mediante el índice tenían el rol requerido.
Para los eventos « QEvent::ToolTip » y « QEvent::WhatsThis » que se hayan gestionado correctamente, puede mostrarse la ventana emergente correspondiente en función de la configuración del sistema del usuario.
Véase también QHelpEvent.
[pure virtual] void QAbstractItemDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const
Esta función abstracta pura debe reimplementarse si deseas proporcionar una representación personalizada. Utiliza ` painter ` y `style` ` option ` para representar el elemento especificado por `item` ` index`.
Si reimplementas esto, también debes reimplementar sizeHint().
[virtual] void QAbstractItemDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const
Establece el contenido del ` editor ` indicado con los datos del elemento situado en el ` index` indicado. Ten en cuenta que el índice contiene información sobre el modelo que se está utilizando.
La implementación básica no realiza ninguna acción. Si deseas personalizar la edición, deberás reimplementar esta función.
Véase también setModelData().
[virtual] void QAbstractItemDelegate::setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const
Establece los datos del elemento situado en la posición index de la tabla model con el contenido de la posición editor.
La implementación básica no realiza ninguna acción. Si deseas personalizar la edición, deberás reimplementar esta función.
Véase también setEditorData().
[pure virtual] QSize QAbstractItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const
Esta función puramente abstracta debe reimplementarse si deseas proporcionar una representación personalizada. Las opciones se especifican mediante ` option ` y el elemento del modelo mediante ` index`.
Si la reimplementas, también debes reimplementar paint().
[signal] void QAbstractItemDelegate::sizeHintChanged(const QModelIndex &index)
Esta señal debe emitirse cuando cambie el método « sizeHint()» de « index ».
Las vistas se conectan automáticamente a esta señal y reajustan la disposición de los elementos según sea necesario.
[virtual] void QAbstractItemDelegate::updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const
Actualiza la geometría de la « editor » del elemento con el « index » indicado, según el rectángulo especificado en el « option ». Si el elemento tiene una disposición interna, el editor se distribuirá en consecuencia. Ten en cuenta que el índice contiene información sobre el modelo que se está utilizando.
La implementación básica no realiza ninguna acción. Si deseas una edición personalizada, debes reimplementar esta función.
© 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.