En esta página

QDataWidgetMapper Class

La clase QDataWidgetMapper permite establecer una correspondencia entre una sección de un modelo de datos y los widgets. Más información...

Encabezado: #include <QDataWidgetMapper>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Heredado de: QObject

Tipos públicos

enum SubmitPolicy { AutoSubmit, ManualSubmit }

Propiedades

Funciones públicas

QDataWidgetMapper(QObject *parent = nullptr)
virtual ~QDataWidgetMapper()
void addMapping(QWidget *widget, int section)
void addMapping(QWidget *widget, int section, const QByteArray &propertyName)
void clearMapping()
int currentIndex() const
QAbstractItemDelegate *itemDelegate() const
QByteArray mappedPropertyName(QWidget *widget) const
int mappedSection(QWidget *widget) const
QWidget *mappedWidgetAt(int section) const
QAbstractItemModel *model() const
Qt::Orientation orientation() const
void removeMapping(QWidget *widget)
QModelIndex rootIndex() const
void setItemDelegate(QAbstractItemDelegate *delegate)
void setModel(QAbstractItemModel *model)
void setOrientation(Qt::Orientation aOrientation)
void setRootIndex(const QModelIndex &index)
void setSubmitPolicy(QDataWidgetMapper::SubmitPolicy policy)
QDataWidgetMapper::SubmitPolicy submitPolicy() const

Ranuras públicas

void revert()
virtual void setCurrentIndex(int index)
void setCurrentModelIndex(const QModelIndex &index)
bool submit()
void toFirst()
void toLast()
void toNext()
void toPrevious()

Señales

void currentIndexChanged(int index)

Descripción detallada

QDataWidgetMapper se puede utilizar para crear widgets sensibles a los datos asignándolos a secciones de un modelo de elementos. Una sección es una columna del modelo si la orientación es horizontal (por defecto); en caso contrario, es una fila.

Cada vez que cambia el índice actual, cada widget se actualiza con datos del modelo a través de la propiedad especificada al realizar su asignación. Si el usuario edita el contenido de un widget, los cambios se leen mediante la misma propiedad y se vuelven a escribir en el modelo. Por defecto, se utiliza la propiedad de usuario ( user property ) de cada widget para transferir datos entre el modelo y el widget. Desde Qt 4.3, una función adicional ` addMapping()` permite utilizar una propiedad con nombre en lugar de la propiedad de usuario por defecto.

Es posible configurar un delegado de elemento para admitir widgets personalizados. Por defecto, se utiliza una propiedad « QStyledItemDelegate » para sincronizar el modelo con los widgets.

Supongamos que tenemos un modelo de elemento llamado model con el siguiente contenido:

1Qt NoruegaOslo
2Qt AustraliaBrisbane
3Qt EE. UU.Palo Alto
4Qt ChinaPekín
5Qt AlemaniaBerlín

El siguiente código asignará las columnas del modelo a los widgets denominados mySpinBox, myLineEdit y myCountryChooser:

QDataWidgetMapper *mapper = new QDataWidgetMapper;
mapper->setModel(model);
mapper->addMapping(mySpinBox, 0);
mapper->addMapping(myLineEdit, 1);
mapper->addMapping(myCountryChooser, 2);
mapper->toFirst();

Tras la llamada a toFirst(), mySpinBox muestra el valor 1, myLineEdit muestra Qt Norway y myCountryChooser muestra Oslo. Las funciones de navegación toFirst(), toNext(), toPrevious(), toLast() y setCurrentIndex() pueden utilizarse para navegar por el modelo y actualizar los widgets con el contenido del modelo.

La función setRootIndex() permite especificar un elemento concreto de un modelo como índice raíz; los elementos secundarios de este se asignarán a los widgets correspondientes de la interfaz de usuario.

QDataWidgetMapper admite dos políticas de envío: « AutoSubmit » y « ManualSubmit ». « AutoSubmit » actualizará el modelo tan pronto como el widget actual pierda el foco, mientras que « ManualSubmit » no actualizará el modelo a menos que se llame a « submit()». « ManualSubmit » resulta útil cuando se muestra un cuadro de diálogo que permite al usuario cancelar todas las modificaciones. Además, las demás vistas que muestran el modelo no se actualizarán hasta que el usuario haya finalizado todas sus modificaciones y las haya enviado.

Ten en cuenta que QDataWidgetMapper realiza un seguimiento de las modificaciones externas. Si el contenido del modelo se actualiza en otro módulo de la aplicación, los widgets también se actualizan.

Véase también QAbstractItemModel y QAbstractItemDelegate.

Documentación sobre los tipos de miembros

enum QDataWidgetMapper::SubmitPolicy

Esta enumeración describe las posibles políticas de envío que admite un QDataWidgetMapper.

ConstanteValorDescripción
QDataWidgetMapper::AutoSubmit0Cada vez que un widget pierde el foco, el valor actual del widget se asigna al modelo del elemento.
QDataWidgetMapper::ManualSubmit1El modelo no se actualiza hasta que se llama a ` submit()`.

Documentación de la propiedad

currentIndex : int

Esta propiedad contiene la fila o columna actual

Los widgets se rellenan con los datos de la fila en index si la orientación es horizontal (por defecto); en caso contrario, con los datos de la columna en index.

Funciones de acceso:

int currentIndex() const
virtual void setCurrentIndex(int index)

Señal de notificación:

void currentIndexChanged(int index)

Véase también setCurrentModelIndex(), toFirst(), toNext(), toPrevious() y toLast().

orientation : Qt::Orientation

Esta propiedad almacena la orientación del modelo

Si la orientación es « Qt::Horizontal » (por defecto), un widget se asigna a una columna de un modelo de datos. El widget se rellenará con los datos del modelo procedentes de la columna asignada y de la fila a la que apunta « currentIndex()».

Utiliza « Qt::Horizontal » para datos tabulares con un aspecto similar a este:

1Qt NoruegaOslo
2Qt AustraliaBrisbane
3Qt EE. UU.Silicon Valley
4Qt ChinaPekín
5Qt AlemaniaBerlín

Si la orientación se establece en « Qt::Vertical », un widget se asigna a una fila. Al llamar a « setCurrentIndex()» se cambiará la columna actual. El widget se rellenará con los datos del modelo procedentes de la fila asignada y de la columna a la que apunta « currentIndex()».

Utiliza ` Qt::Vertical ` para datos tabulares con un aspecto similar a este:

12345
Qt NoruegaQt AustraliaQt EE. UU.Qt ChinaQt Alemania
OsloBrisbaneSilicon ValleyPekínBerlín

Al cambiar la orientación se borran todas las asignaciones existentes.

Funciones de acceso:

Qt::Orientation orientation() const
void setOrientation(Qt::Orientation aOrientation)

submitPolicy : SubmitPolicy

Esta propiedad contiene la política de envío actual

Si se modifica la política de envío actual, todos los widgets volverán a mostrar los datos actuales del modelo.

Funciones de acceso:

QDataWidgetMapper::SubmitPolicy submitPolicy() const
void setSubmitPolicy(QDataWidgetMapper::SubmitPolicy policy)

Documentación de las funciones de miembro

[explicit] QDataWidgetMapper::QDataWidgetMapper(QObject *parent = nullptr)

Crea un nuevo QDataWidgetMapper con el objeto padre parent. Por defecto, la orientación es horizontal y la política de envío es AutoSubmit.

Véase también setOrientation() y setSubmitPolicy().

[virtual noexcept] QDataWidgetMapper::~QDataWidgetMapper()

Destruye el objeto.

void QDataWidgetMapper::addMapping(QWidget *widget, int section)

Añade una correspondencia entre un « widget » y un « section » del modelo. El « section » es una columna del modelo si la orientación es horizontal (valor por defecto); en caso contrario, es una fila.

Para el siguiente ejemplo, supongamos un modelo myModel que tiene dos columnas: la primera contiene los nombres de las personas de un grupo y la segunda, sus edades. La primera columna se asigna a la QLineEdit nameLineEdit , y la segunda, a la QSpinBox ageSpinBox :

QDataWidgetMapper *mapper = new QDataWidgetMapper;
mapper->setModel(myModel);
mapper->addMapping(nameLineEdit, 0);
mapper->addMapping(ageSpinBox, 1);

Notas:

  • Si el widget ya está asignado a una sección, la asignación anterior se sustituirá por la nueva.
  • Solo se permiten asignaciones uno a uno entre secciones y widgets. No es posible asignar una sola sección a varios widgets, ni asignar un solo widget a varias secciones.

Véase también removeMapping(), mappedSection() y clearMapping().

void QDataWidgetMapper::addMapping(QWidget *widget, int section, const QByteArray &propertyName)

Es básicamente lo mismo que addMapping(), pero añade la posibilidad de especificar la propiedad que se va a utilizar indicando propertyName.

Véase también addMapping().

void QDataWidgetMapper::clearMapping()

Borra todas las asignaciones.

Véase también addMapping() y removeMapping().

[signal] void QDataWidgetMapper::currentIndexChanged(int index)

Esta señal se emite después de que el índice actual haya cambiado y todos los widgets se hayan rellenado con los nuevos datos. index es el nuevo índice actual.

Nota: Señalde notificación para la propiedad currentIndex.

Véase también currentIndex() y setCurrentIndex().

QAbstractItemDelegate *QDataWidgetMapper::itemDelegate() const

Devuelve el delegado del elemento actual.

Véase también setItemDelegate().

QByteArray QDataWidgetMapper::mappedPropertyName(QWidget *widget) const

Devuelve el nombre de la propiedad que se utiliza al asignar datos a la « widget » indicada.

Véase también mappedSection(), addMapping() y removeMapping().

int QDataWidgetMapper::mappedSection(QWidget *widget) const

Devuelve la sección a la que está asignado el « widget » o -1 si el widget no está asignado.

Véase también addMapping() y removeMapping().

QWidget *QDataWidgetMapper::mappedWidgetAt(int section) const

Devuelve el widget asignado a section, o 0 si no hay ningún widget asignado a esa sección.

Véase también addMapping() y removeMapping().

QAbstractItemModel *QDataWidgetMapper::model() const

Devuelve el modelo actual.

Véase también setModel().

void QDataWidgetMapper::removeMapping(QWidget *widget)

Elimina la asignación correspondiente a widget.

Véase también addMapping() y clearMapping().

[slot] void QDataWidgetMapper::revert()

Actualiza todos los widgets con los datos actuales del modelo. Se perderán todos los cambios que no se hayan enviado.

Véase también submit() y setSubmitPolicy().

QModelIndex QDataWidgetMapper::rootIndex() const

Devuelve el índice raíz actual.

Véase también setRootIndex().

[slot] void QDataWidgetMapper::setCurrentModelIndex(const QModelIndex &index)

Establece el índice actual en la fila de ` index ` si la orientación es horizontal (por defecto); en caso contrario, en la columna de ` index`.

Llama internamente a ` setCurrentIndex()`. Esta ranura de conveniencia se puede conectar a la señal ` currentRowChanged()` o ` currentColumnChanged()` de la propiedad ` selection model` de otra vista.

El siguiente ejemplo ilustra cómo actualizar todos los widgets con nuevos datos cada vez que cambia la selección de una « QTableView » denominada « myTableView »:

QDataWidgetMapper *mapper = new QDataWidgetMapper;
connect(myTableView->selectionModel(), &QItemSelectionModel::currentRowChanged,
        mapper, &QDataWidgetMapper::setCurrentModelIndex);

Véase también currentIndex().

void QDataWidgetMapper::setItemDelegate(QAbstractItemDelegate *delegate)

Establece el delegado del elemento en delegate. El delegado se utilizará para escribir datos desde el modelo al widget y desde el widget al modelo, mediante QAbstractItemDelegate::setEditorData() y QAbstractItemDelegate::setModelData().

Cualquier delegado existente se eliminará, pero no se borrará. QDataWidgetMapper no asume la propiedad de delegate.

El delegado también decide cuándo aplicar los datos y cuándo cambiar el editor, utilizando QAbstractItemDelegate::commitData() y QAbstractItemDelegate::closeEditor().

Advertencia: Nose debe compartir la misma instancia de un delegado entre mapeadores de widgets o vistas. Hacerlo puede provocar un comportamiento de edición incorrecto o poco intuitivo, ya que cada vista conectada a un delegado determinado puede recibir la señal closeEditor() e intentar acceder, modificar o cerrar un editor que ya se haya cerrado.

Véase también ` itemDelegate()`.

void QDataWidgetMapper::setModel(QAbstractItemModel *model)

Establece el modelo actual en « model ». Si se había establecido otro modelo, se borran todas las asignaciones a ese modelo anterior.

Véase también model().

void QDataWidgetMapper::setRootIndex(const QModelIndex &index)

Establece el elemento raíz en index. Esto se puede utilizar para mostrar una rama de un árbol. Pasa un índice de modelo no válido para mostrar la rama más superior.

Véase también rootIndex().

[slot] bool QDataWidgetMapper::submit()

Envía todos los cambios de los widgets asignados al modelo.

Para cada sección asignada, el delegado del elemento lee el valor actual del widget y lo establece en el modelo. Por último, se invoca el método submit() del modelo.

Devuelve ` true ` si se han enviado todos los valores; en caso contrario, devuelve `false`.

Nota: En el caso de los modelos de base de datos, se puede utilizar QSqlQueryModel::lastError() para recuperar el último error.

Véase también ` revert()` y ` setSubmitPolicy()`.

[slot] void QDataWidgetMapper::toFirst()

Rellena los widgets con los datos de la primera fila del modelo si la orientación es horizontal (por defecto); en caso contrario, con los datos de la primera columna.

Esto equivale a llamar a setCurrentIndex(0).

Véase también toLast() y setCurrentIndex().

[slot] void QDataWidgetMapper::toLast()

Rellena los widgets con los datos de la última fila del modelo si la orientación es horizontal (por defecto); en caso contrario, con los datos de la última columna.

Llama internamente a setCurrentIndex().

Véase también toFirst() y setCurrentIndex().

[slot] void QDataWidgetMapper::toNext()

Rellena los widgets con los datos de la siguiente fila del modelo si la orientación es horizontal (por defecto); en caso contrario, con los datos de la siguiente columna.

Llama internamente a setCurrentIndex(). No realiza ninguna acción si no hay una fila siguiente en el modelo.

Véanse también toPrevious() y setCurrentIndex().

[slot] void QDataWidgetMapper::toPrevious()

Rellena los widgets con los datos de la fila anterior del modelo si la orientación es horizontal (por defecto); en caso contrario, con los datos de la columna anterior.

Llama internamente a setCurrentIndex(). No realiza ninguna acción si no hay ninguna fila anterior en el modelo.

Véase también toNext() y setCurrentIndex().

© 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.