|  | Home · Overviews · Examples |

# QDataWidgetMapper Class Reference
[com.trolltech.qt.gui module]

The `QDataWidgetMapper` class provides mapping between a section of a data model to widgets. More...

Inherits `QObject`.

## Detailed Description

The `QDataWidgetMapper` class provides mapping between a section of a data model to widgets.

`QDataWidgetMapper` can be used to create data-aware widgets by mapping them to sections of an item model. A section is a column of a model if the orientation is horizontal (the default), otherwise a row.

Every time the current index changes, each widget is updated with data from the model via the property specified when its mapping was made. If the user edits the contents of a widget, the changes are read using the same property and written back to the model. By default, each widget's user property is used to transfer data between the model and the widget. Since Qt 4.3, an additional `addMapping` function enables a named property to be used instead of the default user property.

It is possible to set an item delegate to support custom widgets. By default, a `QItemDelegate` is used to synchronize the model with the widgets.

Let us assume that we have an item model named `model` with the following contents:

1 | Trolltech ASA | Oslo
2 | Trolltech Pty | Brisbane
3 | Trolltech Inc | Palo Alto
4 | Trolltech China | Beijing
5 | Trolltech GmbH | Berlin

The following code will map the columns of the model to widgets called `mySpinBox`, `myLineEdit` and `myCountryChooser`:

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

After the call to `toFirst`, `mySpinBox` displays the value `1`, `myLineEdit` displays `Trolltech ASA` and `myCountryChooser` displays `Oslo`. The navigational functions `toFirst`, `toNext`, `toPrevious`, `toLast` and `setCurrentIndex` can be used to navigate in the model and update the widgets with contents from the model.

The `setRootIndex` function enables a particular item in a model to be specified as the root index - children of this item will be mapped to the relevant widgets in the user interface.

`QDataWidgetMapper` supports two submit policies, `AutoSubmit` and `ManualSubmit`. `AutoSubmit` will update the model as soon as the current widget loses focus, `ManualSubmit` will not update the model unless `submit` is called. `ManualSubmit` is useful when displaying a dialog that lets the user cancel all modifications. Also, other views that display the model won't update until the user finishes all their modifications and submits.

Note that `QDataWidgetMapper` keeps track of external modifications. If the contents of the model are updated in another module of the application, the widgets are updated as well.

See also `QAbstractItemModel` and `QAbstractItemDelegate`.