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

#include <qdatawidgetmapper.h>

Inheritance diagram for QDataWidgetMapper:

Collaboration diagram for QDataWidgetMapper:

Public Types
enum	SubmitPolicy { AutoSubmit , ManualSubmit }

Public Slots
void	revert ()

bool	submit ()

void	toFirst ()

void	toLast ()

void	toNext ()

void	toPrevious ()

virtual void	setCurrentIndex (int index)

void	setCurrentModelIndex (const QModelIndex &index)

Public Slots inherited from QObject
void	deleteLater ()

Signals
void	currentIndexChanged (int index)

Signals inherited from QObject
void	destroyed (QObject *=nullptr)

void	objectNameChanged (const QString &objectName, QPrivateSignal)

Public Member Functions
	QDataWidgetMapper (QObject *parent=nullptr)

	~QDataWidgetMapper ()

void	setModel (QAbstractItemModel *model)

QAbstractItemModel *	model () const

void	setItemDelegate (QAbstractItemDelegate *delegate)

QAbstractItemDelegate *	itemDelegate () const

void	setRootIndex (const QModelIndex &index)

QModelIndex	rootIndex () const

void	setOrientation (Qt::Orientation aOrientation)

Qt::Orientation	orientation () const

void	setSubmitPolicy (SubmitPolicy policy)

SubmitPolicy	submitPolicy () const

void	addMapping (QWidget *widget, int section)

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

void	removeMapping (QWidget *widget)

int	mappedSection (QWidget *widget) const

QByteArray	mappedPropertyName (QWidget *widget) const

QWidget *	mappedWidgetAt (int section) const

void	clearMapping ()

int	currentIndex () const

Public Member Functions inherited from QObject
Q_INVOKABLE	QObject (QObject *parent=nullptr)

virtual	~QObject ()

virtual bool	event (QEvent *event)

virtual bool	eventFilter (QObject watched, QEvent event)

QString	objectName () const

void	setObjectName (const QString &name)

QBindable< QString >	bindableObjectName ()

bool	isWidgetType () const

bool	isWindowType () const

bool	signalsBlocked () const noexcept

bool	blockSignals (bool b) noexcept

QThread *	thread () const

void	moveToThread (QThread *thread)

int	startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)

void	killTimer (int id)

template<typename T >
T	findChild (const QString &aName=QString(), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

template<typename T >
QList< T >	findChildren (const QString &aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

template<typename T >
QList< T >	findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

const QObjectList &	children () const

void	setParent (QObject *parent)

void	installEventFilter (QObject *filterObj)

void	removeEventFilter (QObject *obj)

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const

bool	disconnect (const char signal=nullptr, const QObject receiver=nullptr, const char *member=nullptr) const

bool	disconnect (const QObject receiver, const char member=nullptr) const

void	dumpObjectTree () const

void	dumpObjectInfo () const

bool	setProperty (const char *name, const QVariant &value)

QVariant	property (const char *name) const

QList< QByteArray >	dynamicPropertyNames () const

QBindingStorage *	bindingStorage ()

const QBindingStorage *	bindingStorage () const

QObject *	parent () const

bool	inherits (const char *classname) const

Properties
int	currentIndex
	the current row or column More...

Qt::Orientation	orientation
	the orientation of the model More...

SubmitPolicy	submitPolicy
	the current submit policy More...

Properties inherited from QObject
QString	objectName
	the name of this object More...

Additional Inherited Members
Static Public Member Functions inherited from QObject
static QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char member, Qt::ConnectionType=Qt::AutoConnection)

static QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)

template<typename Func1 , typename Func2 >
static QMetaObject::Connection	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object receiver, Func2 slot, Qt::ConnectionType type=Qt::AutoConnection)

static QMetaObject::Connection ::type	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 slot)

static QMetaObject::Connection ::type	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const QObject context, Func2 slot, Qt::ConnectionType type=Qt::AutoConnection)

template<typename Func1 , typename Func2 >
static std::enable_if< QtPrivate::FunctionPointer< Func2 >::ArgumentCount==-1 &&!std::is_convertible_v< Func2, const char * >, QMetaObject::Connection >::type	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 slot)

template<typename Func1 , typename Func2 >
static std::enable_if< QtPrivate::FunctionPointer< Func2 >::ArgumentCount==-1 &&!std::is_convertible_v< Func2, const char * >, QMetaObject::Connection >::type	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const QObject context, Func2 slot, Qt::ConnectionType type=Qt::AutoConnection)

static bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char member)

static bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &member)

static bool	disconnect (const QMetaObject::Connection &)

template<typename Func1 , typename Func2 >
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object receiver, Func2 slot)

template<typename Func1 >
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const QObject receiver, void **zero)

Protected Member Functions inherited from QObject
QObject *	sender () const

int	senderSignalIndex () const

int	receivers (const char *signal) const

bool	isSignalConnected (const QMetaMethod &signal) const

virtual void	timerEvent (QTimerEvent *event)

virtual void	childEvent (QChildEvent *event)

virtual void	customEvent (QEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	disconnectNotify (const QMetaMethod &signal)

	QObject (QObjectPrivate &dd, QObject *parent=nullptr)

Protected Attributes inherited from QObject
QScopedPointer< QObjectData >	d_ptr

Related Functions inherited from QObject
template< class T > T	qobject_cast (const QObject *object)

template< typename T > T	qFindChildqFindChildren (const QObject *obj, const QString &name)()

template< typename T > QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()

	QObjectList

Detailed Description

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

Since: 4.2

\inmodule QtWidgets

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 \l{Q_PROPERTY()}{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:

\table \row

1
Qt Norway
Oslo \row
2
Qt Australia
Brisbane \row
3
Qt USA
Palo Alto \row
4
Qt China
Beijing \row
5
Qt Germany
Berlin \endtable

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

After the call to toFirst(), mySpinBox displays the value {1}, myLineEdit displays {Qt Norway} 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, QAbstractItemDelegate

Definition at line 55 of file qdatawidgetmapper.h.

Member Enumeration Documentation

◆ SubmitPolicy

enum QDataWidgetMapper::SubmitPolicy

This enum describes the possible submit policies a QDataWidgetMapper supports.

\value AutoSubmit Whenever a widget loses focus, the widget's current value is set to the item model. \value ManualSubmit The model is not updated until submit() is called.

Enumerator
AutoSubmit
ManualSubmit

Definition at line 79 of file qdatawidgetmapper.h.

Constructor & Destructor Documentation

◆ QDataWidgetMapper()

QDataWidgetMapper::QDataWidgetMapper ( QObject * parent = nullptr )

explicit

Constructs a new QDataWidgetMapper with parent object parent. By default, the orientation is horizontal and the submit policy is {AutoSubmit}.

See also: setOrientation(), setSubmitPolicy()

Definition at line 327 of file qdatawidgetmapper.cpp.

Here is the call graph for this function:

◆ ~QDataWidgetMapper()

QDataWidgetMapper::~QDataWidgetMapper ( )

Destroys the object.

Definition at line 336 of file qdatawidgetmapper.cpp.

Member Function Documentation

◆ addMapping() [1/2]

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

Adds a mapping between a widget and a section from the model. The section is a column in the model if the orientation is horizontal (the default), otherwise a row.

For the following example, we assume a model myModel that has two columns: the first one contains the names of people in a group, and the second column contains their ages. The first column is mapped to the QLineEdit nameLineEdit, and the second is mapped to the QSpinBox {ageSpinBox}:

{Notes:} \list

If the widget is already mapped to a section, the old mapping will be replaced by the new one.
Only one-to-one mappings between sections and widgets are allowed. It is not possible to map a single section to multiple widgets, or to map a single widget to multiple sections. \endlist

See also: removeMapping(), mappedSection(), clearMapping()

Definition at line 477 of file qdatawidgetmapper.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ addMapping() [2/2]

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

Since: 4.3

Essentially the same as addMapping(), but adds the possibility to specify the property to use specifying propertyName.

See also: addMapping()

Definition at line 495 of file qdatawidgetmapper.cpp.

Here is the call graph for this function:

◆ clearMapping()

void QDataWidgetMapper::clearMapping ( )

Clears all mappings.

See also: addMapping(), removeMapping()

Definition at line 745 of file qdatawidgetmapper.cpp.

Here is the caller graph for this function:

◆ currentIndex()

int QDataWidgetMapper::currentIndex ( ) const

Definition at line 703 of file qdatawidgetmapper.cpp.

◆ currentIndexChanged

void QDataWidgetMapper::currentIndexChanged ( int index )

signal

This signal is emitted after the current index has changed and all widgets were populated with new data. index is the new current index.

See also: currentIndex(), setCurrentIndex()

Here is the caller graph for this function:

◆ itemDelegate()

QAbstractItemDelegate * QDataWidgetMapper::itemDelegate ( ) const

Returns the current item delegate.

Definition at line 423 of file qdatawidgetmapper.cpp.

◆ mappedPropertyName()

QByteArray QDataWidgetMapper::mappedPropertyName ( QWidget * widget ) const

Since: 4.3 Returns the name of the property that is used when mapping data to the given widget.

See also: mappedSection(), addMapping(), removeMapping()

Definition at line 546 of file qdatawidgetmapper.cpp.

Here is the call graph for this function:

◆ mappedSection()

int QDataWidgetMapper::mappedSection ( QWidget * widget ) const

Returns the section the widget is mapped to or -1 if the widget is not mapped.

See also: addMapping(), removeMapping()

Definition at line 527 of file qdatawidgetmapper.cpp.

◆ mappedWidgetAt()

QWidget * QDataWidgetMapper::mappedWidgetAt ( int section ) const

Returns the widget that is mapped at section, or 0 if no widget is mapped at that section.

See also: addMapping(), removeMapping()

Definition at line 566 of file qdatawidgetmapper.cpp.

◆ model()

QAbstractItemModel * QDataWidgetMapper::model ( ) const

Returns the current model.

See also: setModel()

Definition at line 375 of file qdatawidgetmapper.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ orientation()

Qt::Orientation QDataWidgetMapper::orientation ( ) const

Definition at line 802 of file qdatawidgetmapper.cpp.

◆ removeMapping()

void QDataWidgetMapper::removeMapping ( QWidget * widget )

Removes the mapping for the given widget.

See also: addMapping(), clearMapping()

Definition at line 509 of file qdatawidgetmapper.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ revert

void QDataWidgetMapper::revert ( )

slot

Repopulates all widgets with the current data of the model. All unsubmitted changes will be lost.

See also: submit(), setSubmitPolicy()

Definition at line 584 of file qdatawidgetmapper.cpp.

Here is the caller graph for this function:

◆ rootIndex()

QModelIndex QDataWidgetMapper::rootIndex ( ) const

Returns the current root index.

See also: setRootIndex()

Definition at line 447 of file qdatawidgetmapper.cpp.

◆ setCurrentIndex

void QDataWidgetMapper::setCurrentIndex ( int index )

virtualslot

Definition at line 689 of file qdatawidgetmapper.cpp.

Here is the caller graph for this function:

◆ setCurrentModelIndex

void QDataWidgetMapper::setCurrentModelIndex ( const QModelIndex & index )

slot

Sets the current index to the row of the index if the orientation is horizontal (the default), otherwise to the column of the index.

Calls setCurrentIndex() internally. This convenience slot can be connected to the signal \l {QItemSelectionModel::}{currentRowChanged()} or \l {QItemSelectionModel::}{currentColumnChanged()} of another view's \l {QItemSelectionModel}{selection model}.

The following example illustrates how to update all widgets with new data whenever the selection of a QTableView named myTableView changes:

See also: currentIndex()

Definition at line 728 of file qdatawidgetmapper.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setItemDelegate()

void QDataWidgetMapper::setItemDelegate ( QAbstractItemDelegate * delegate )

Sets the item delegate to delegate. The delegate will be used to write data from the model into the widget and from the widget to the model, using QAbstractItemDelegate::setEditorData() and QAbstractItemDelegate::setModelData().

Any existing delegate will be removed, but not deleted. QDataWidgetMapper does not take ownership of delegate.

The delegate also decides when to apply data and when to change the editor, using QAbstractItemDelegate::commitData() and QAbstractItemDelegate::closeEditor().

Warning: You should not share the same instance of a delegate between widget mappers or views. Doing so can cause incorrect or unintuitive editing behavior since each view connected to a given delegate may receive the \l{QAbstractItemDelegate::}{closeEditor()} signal, and attempt to access, modify or close an editor that has already been closed.

Definition at line 399 of file qdatawidgetmapper.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setModel()

void QDataWidgetMapper::setModel ( QAbstractItemModel * model )

Sets the current model to model. If another model was set, all mappings to that old model are cleared.

See also: model()

Definition at line 346 of file qdatawidgetmapper.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setOrientation()

void QDataWidgetMapper::setOrientation ( Qt::Orientation aOrientation )

Definition at line 791 of file qdatawidgetmapper.cpp.

Here is the call graph for this function:

◆ setRootIndex()

void QDataWidgetMapper::setRootIndex ( const QModelIndex & index )

Sets the root item to index. This can be used to display a branch of a tree. Pass an invalid model index to display the top-most branch.

See also: rootIndex()

Definition at line 436 of file qdatawidgetmapper.cpp.

◆ setSubmitPolicy()

void QDataWidgetMapper::setSubmitPolicy ( SubmitPolicy policy )

Definition at line 815 of file qdatawidgetmapper.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ submit

bool QDataWidgetMapper::submit ( )

slot

Submits all changes from the mapped widgets to the model.

For every mapped section, the item delegate reads the current value from the widget and sets it in the model. Finally, the model's \l {QAbstractItemModel::}{submit()} method is invoked.

Returns true if all the values were submitted, otherwise false.

Note: For database models, QSqlQueryModel::lastError() can be used to retrieve the last error.

See also: revert(), setSubmitPolicy()

Definition at line 605 of file qdatawidgetmapper.cpp.

◆ submitPolicy()

QDataWidgetMapper::SubmitPolicy QDataWidgetMapper::submitPolicy ( ) const

Definition at line 825 of file qdatawidgetmapper.cpp.

◆ toFirst

void QDataWidgetMapper::toFirst ( )

slot

Populates the widgets with data from the first row of the model if the orientation is horizontal (the default), otherwise with data from the first column.

This is equivalent to calling setCurrentIndex(0).

See also: toLast(), setCurrentIndex()

Definition at line 626 of file qdatawidgetmapper.cpp.

Here is the call graph for this function:

◆ toLast

void QDataWidgetMapper::toLast ( )

slot

Populates the widgets with data from the last row of the model if the orientation is horizontal (the default), otherwise with data from the last column.

Calls setCurrentIndex() internally.

See also: toFirst(), setCurrentIndex()

Definition at line 640 of file qdatawidgetmapper.cpp.

Here is the call graph for this function:

◆ toNext

void QDataWidgetMapper::toNext ( )

slot

Populates the widgets with data from the next row of the model if the orientation is horizontal (the default), otherwise with data from the next column.

Calls setCurrentIndex() internally. Does nothing if there is no next row in the model.

See also: toPrevious(), setCurrentIndex()

Definition at line 657 of file qdatawidgetmapper.cpp.

Here is the call graph for this function:

◆ toPrevious

void QDataWidgetMapper::toPrevious ( )

slot

Populates the widgets with data from the previous row of the model if the orientation is horizontal (the default), otherwise with data from the previous column.

Calls setCurrentIndex() internally. Does nothing if there is no previous row in the model.

See also: toNext(), setCurrentIndex()

Definition at line 673 of file qdatawidgetmapper.cpp.

Here is the call graph for this function:

Property Documentation

◆ currentIndex

QDataWidgetMapper::currentIndex

readwrite

the current row or column

The widgets are populated with with data from the row at index if the orientation is horizontal (the default), otherwise with data from the column at index.

See also: setCurrentModelIndex(), toFirst(), toNext(), toPrevious(), toLast()

Definition at line 119 of file qdatawidgetmapper.h.

◆ orientation

QDataWidgetMapper::orientation

readwrite

the orientation of the model

If the orientation is Qt::Horizontal (the default), a widget is mapped to a column of a data model. The widget will be populated with the model's data from its mapped column and the row that currentIndex() points at.

Use Qt::Horizontal for tabular data that looks like this:

\table \row

1
Qt Norway
Oslo \row
2
Qt Australia
Brisbane \row
3
Qt USA
Silicon Valley \row
4
Qt China
Beijing \row
5
Qt Germany
Berlin \endtable

If the orientation is set to Qt::Vertical, a widget is mapped to a row. Calling setCurrentIndex() will change the current column. The widget will be populates with the model's data from its mapped row and the column that currentIndex() points at.

Use Qt::Vertical for tabular data that looks like this:

\table \row

1
2
3
4
5 \row
Qt Norway
Qt Australia
Qt USA
Qt China
Qt Germany \row
Oslo
Brisbane
Silicon Valley
Beijing
Berlin \endtable

Changing the orientation clears all existing mappings.

Definition at line 119 of file qdatawidgetmapper.h.

◆ submitPolicy

QDataWidgetMapper::submitPolicy

readwrite

the current submit policy

Changing the current submit policy will revert all widgets to the current data from the model.

Definition at line 119 of file qdatawidgetmapper.h.

The documentation for this class was generated from the following files:

src/widgets/itemviews/qdatawidgetmapper.h
src/widgets/itemviews/qdatawidgetmapper.cpp

Public Types

Public Slots

Signals

Public Member Functions

Properties

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ SubmitPolicy

Constructor & Destructor Documentation

◆ QDataWidgetMapper()

◆ ~QDataWidgetMapper()

Member Function Documentation

◆ addMapping() [1/2]

◆ addMapping() [2/2]

◆ clearMapping()

◆ currentIndex()

◆ currentIndexChanged

◆ itemDelegate()

◆ mappedPropertyName()

◆ mappedSection()

◆ mappedWidgetAt()

◆ model()

◆ orientation()

◆ removeMapping()

◆ revert

◆ rootIndex()

◆ setCurrentIndex

◆ setCurrentModelIndex

◆ setItemDelegate()

◆ setModel()

◆ setOrientation()

◆ setRootIndex()

◆ setSubmitPolicy()

◆ submit

◆ submitPolicy()

◆ toFirst

◆ toLast

◆ toNext

◆ toPrevious

Property Documentation

◆ currentIndex

◆ orientation

◆ submitPolicy