Qt 4.2 User's Guide: QDataWidgetMapper Class Reference

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}:

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.

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

Member Enumeration Documentation

enum QDataWidgetMapper::SubmitPolicy

This enum describes the possible submit policies a QDataWidgetMapper supports.

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

Definition at line 65 of file qdatawidgetmapper.h.

00065 { AutoSubmit, ManualSubmit };

Constructor & Destructor Documentation

QDataWidgetMapper::QDataWidgetMapper ( QObject * parent = 0 )

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 295 of file qdatawidgetmapper.cpp.

References setItemDelegate().

00296     : QObject(*new QDataWidgetMapperPrivate, parent)
00297 {
00298     setItemDelegate(new QItemDelegate(this));
00299 }

Here is the call graph for this function:

QDataWidgetMapper::~QDataWidgetMapper ( )

Destroys the object.

Definition at line 304 of file qdatawidgetmapper.cpp.

00305 {
00306 }

Member Function Documentation

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 314 of file qdatawidgetmapper.cpp.

References clearMapping(), QObject::connect(), d, QObject::destroyed(), QObject::disconnect(), model(), SIGNAL, and SLOT.

Referenced by BookWindow::BookWindow().

00315 {
00316     Q_D(QDataWidgetMapper);
00317 
00318     if (d->model == model)
00319         return;
00320 
00321     if (d->model) {
00322         disconnect(d->model, SIGNAL(dataChanged(QModelIndex,QModelIndex)), this,
00323                    SLOT(_q_dataChanged(QModelIndex,QModelIndex)));
00324         disconnect(d->model, SIGNAL(destroyed()), this,
00325                    SLOT(_q_modelDestroyed()));
00326     }
00327     clearMapping();
00328     d->rootIndex = QModelIndex();
00329     d->currentTopLeft = QModelIndex();
00330 
00331     d->model = model;
00332 
00333     connect(model, SIGNAL(dataChanged(QModelIndex,QModelIndex)),
00334             SLOT(_q_dataChanged(QModelIndex,QModelIndex)));
00335     connect(model, SIGNAL(destroyed()), SLOT(_q_modelDestroyed()));
00336 }

Here is the call graph for this function:

QAbstractItemModel * QDataWidgetMapper::model ( ) const

Returns the current model.

See also:: setModel()

Definition at line 343 of file qdatawidgetmapper.cpp.

References d, and QAbstractItemModelPrivate::staticEmptyModel().

Referenced by setModel().

00344 {
00345     Q_D(const QDataWidgetMapper);
00346     return d->model == QAbstractItemModelPrivate::staticEmptyModel()
00347             ? static_cast<QAbstractItemModel *>(0)
00348             : d->model;
00349 }

Here is the call graph for this function:

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().

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

Definition at line 359 of file qdatawidgetmapper.cpp.

References _q_closeEditor(), _q_commitData(), QObject::connect(), d, QObject::disconnect(), SIGNAL, and SLOT.

Referenced by BookWindow::BookWindow(), and QDataWidgetMapper().

00360 {
00361     Q_D(QDataWidgetMapper);
00362     QAbstractItemDelegate *oldDelegate = d->delegate;
00363     if (oldDelegate) {
00364         disconnect(oldDelegate, SIGNAL(commitData(QWidget*)), this, SLOT(_q_commitData(QWidget*)));
00365         disconnect(oldDelegate, SIGNAL(closeEditor(QWidget*,QAbstractItemDelegate::EndEditHint)),
00366                    this, SLOT(_q_closeEditor(QWidget*,QAbstractItemDelegate::EndEditHint)));
00367     }
00368 
00369     d->delegate = delegate;
00370 
00371     if (delegate) {
00372         connect(delegate, SIGNAL(commitData(QWidget*)), SLOT(_q_commitData(QWidget*)));
00373         connect(delegate, SIGNAL(closeEditor(QWidget*,QAbstractItemDelegate::EndEditHint)),
00374                 SLOT(_q_closeEditor(QWidget*,QAbstractItemDelegate::EndEditHint)));
00375     }
00376 
00377     d->flipEventFilters(oldDelegate, delegate);
00378 }

Here is the call graph for this function:

QAbstractItemDelegate * QDataWidgetMapper::itemDelegate ( ) const

Returns the current item delegate.

Definition at line 383 of file qdatawidgetmapper.cpp.

References d.

00384 {
00385     Q_D(const QDataWidgetMapper);
00386     return d->delegate;
00387 }

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 396 of file qdatawidgetmapper.cpp.

References d, and index.

00397 {
00398     Q_D(QDataWidgetMapper);
00399     d->rootIndex = index;
00400 }

QModelIndex QDataWidgetMapper::rootIndex ( ) const

Returns the current root index.

See also:: setRootIndex()

Definition at line 407 of file qdatawidgetmapper.cpp.

References d.

00408 {
00409     Q_D(const QDataWidgetMapper);
00410     return d->rootIndex;
00411 }

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

Definition at line 718 of file qdatawidgetmapper.cpp.

References clearMapping(), and d.

00719 {
00720     Q_D(QDataWidgetMapper);
00721 
00722     if (d->orientation == orientation)
00723         return;
00724 
00725     clearMapping();
00726     d->orientation = orientation;
00727 }

Here is the call graph for this function:

Qt::Orientation QDataWidgetMapper::orientation ( ) const

Definition at line 729 of file qdatawidgetmapper.cpp.

References d.

00730 {
00731     Q_D(const QDataWidgetMapper);
00732     return d->orientation;
00733 }

void QDataWidgetMapper::setSubmitPolicy ( SubmitPolicy policy )

Definition at line 742 of file qdatawidgetmapper.cpp.

References d, and revert().

00743 {
00744     Q_D(QDataWidgetMapper);
00745     if (policy == d->submitPolicy)
00746         return;
00747 
00748     revert();
00749     d->submitPolicy = policy;
00750 }

QDataWidgetMapper::SubmitPolicy QDataWidgetMapper::submitPolicy ( ) const

Definition at line 752 of file qdatawidgetmapper.cpp.

References d.

00753 {
00754     Q_D(const QDataWidgetMapper);
00755     return d->submitPolicy;
00756 }

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 containing the name of a person, the second column his age. The first column is mapped to the QLineEdit nameLineEdit and the second to the QSpinBox {ageSpinBox}:

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

Note: If the widget is already mapped to a section, the old mapping will be replaced by the new one. A widget can never be mapped to more than one section at a time.

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

Definition at line 437 of file qdatawidgetmapper.cpp.

References d, and removeMapping().

Referenced by BookWindow::BookWindow().

00438 {
00439     Q_D(QDataWidgetMapper);
00440 
00441     removeMapping(widget);
00442     d->widgetMap.append(QDataWidgetMapperPrivate::WidgetMapper(widget, section));
00443     widget->installEventFilter(d->delegate);
00444 }

Here is the call graph for this function:

void QDataWidgetMapper::removeMapping ( QWidget * widget )

Removes the mapping for the given widget.

See also:: addMapping(), clearMapping()

Definition at line 451 of file qdatawidgetmapper.cpp.

References d, and QObject::removeEventFilter().

Referenced by addMapping().

00452 {
00453     Q_D(QDataWidgetMapper);
00454 
00455     int idx = d->findWidget(widget);
00456     if (idx == -1)
00457         return;
00458 
00459     d->widgetMap.removeAt(idx);
00460     widget->removeEventFilter(d->delegate);
00461 }

Here is the call graph for this function:

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 469 of file qdatawidgetmapper.cpp.

References d.

00470 {
00471     Q_D(const QDataWidgetMapper);
00472 
00473     int idx = d->findWidget(widget);
00474     if (idx == -1)
00475         return -1;
00476 
00477     return d->widgetMap.at(idx).section;
00478 }

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 486 of file qdatawidgetmapper.cpp.

References d, and i.

00487 {
00488     Q_D(const QDataWidgetMapper);
00489 
00490     for (int i = 0; i < d->widgetMap.count(); ++i) {
00491         if (d->widgetMap.at(i).section == section)
00492             return d->widgetMap.at(i).widget;
00493     }
00494 
00495     return 0;
00496 }

void QDataWidgetMapper::clearMapping ( )

Clears all mappings.

See also:: addMapping(), removeMapping()

Definition at line 673 of file qdatawidgetmapper.cpp.

References d, and w.

Referenced by setModel(), and setOrientation().

00674 {
00675     Q_D(QDataWidgetMapper);
00676 
00677     while (!d->widgetMap.isEmpty()) {
00678         QWidget *w = d->widgetMap.takeLast().widget;
00679         if (w)
00680             w->removeEventFilter(d->delegate);
00681     }
00682 }

int QDataWidgetMapper::currentIndex ( ) const

Definition at line 627 of file qdatawidgetmapper.cpp.

References d.

00628 {
00629     Q_D(const QDataWidgetMapper);
00630     return d->currentIdx();
00631 }

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 504 of file qdatawidgetmapper.cpp.

References d.

Referenced by setSubmitPolicy().

00505 {
00506     Q_D(QDataWidgetMapper);
00507 
00508     d->populate();
00509 }

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 {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 525 of file qdatawidgetmapper.cpp.

References d, i, and m.

00526 {
00527     Q_D(QDataWidgetMapper);
00528 
00529     for (int i = 0; i < d->widgetMap.count(); ++i) {
00530         const QDataWidgetMapperPrivate::WidgetMapper &m = d->widgetMap.at(i);
00531         if (m.widget.isNull())
00532             continue;
00533         if (!m.currentIndex.isValid())
00534             return false;
00535         d->delegate->setModelData(m.widget, d->model, m.currentIndex);
00536     }
00537 
00538     return d->model->submit();
00539 }

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 550 of file qdatawidgetmapper.cpp.

References setCurrentIndex().

00551 {
00552     setCurrentIndex(0);
00553 }

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 564 of file qdatawidgetmapper.cpp.

References d, and setCurrentIndex().

00565 {
00566     Q_D(QDataWidgetMapper);
00567     setCurrentIndex(d->itemCount() - 1);
00568 }

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 581 of file qdatawidgetmapper.cpp.

References d, and setCurrentIndex().

00582 {
00583     Q_D(QDataWidgetMapper);
00584     setCurrentIndex(d->currentIdx() + 1);
00585 }

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 597 of file qdatawidgetmapper.cpp.

References d, and setCurrentIndex().

00598 {
00599     Q_D(QDataWidgetMapper);
00600     setCurrentIndex(d->currentIdx() - 1);
00601 }

void QDataWidgetMapper::setCurrentIndex ( int index ) [virtual, slot]

Definition at line 613 of file qdatawidgetmapper.cpp.

References currentIndexChanged(), d, emit, and Qt::Horizontal.

Referenced by setCurrentModelIndex(), toFirst(), toLast(), toNext(), and toPrevious().

00614 {
00615     Q_D(QDataWidgetMapper);
00616 
00617     if (index < 0 || index >= d->itemCount())
00618         return;
00619     d->currentTopLeft = d->orientation == Qt::Horizontal
00620                             ? d->model->index(index, 0, d->rootIndex)
00621                             : d->model->index(0, index, d->rootIndex);
00622     d->populate();
00623 
00624     emit currentIndexChanged(index);
00625 }

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 {QItemSelectionModel::}{currentRowChanged()} or {QItemSelectionModel::}{currentColumnChanged()} of another view's {QItemSelectionModel}{selection model}.

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

    QDataWidgetMapper *mapper = new QDataWidgetMapper();
    connect(myTableView->selectionModel(), SIGNAL(currentRowChanged(QModelIndex)),
            mapper, SLOT(setCurrentModelIndex(QModelIndex)));

See also:: currentIndex()

Definition at line 656 of file qdatawidgetmapper.cpp.

References d, Qt::Horizontal, index, and setCurrentIndex().

00657 {
00658     Q_D(QDataWidgetMapper);
00659 
00660     if (!index.isValid()
00661         || index.model() != d->model
00662         || index.parent() != d->rootIndex)
00663         return;
00664 
00665     setCurrentIndex(d->orientation == Qt::Horizontal ? index.row() : index.column());
00666 }

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()

Referenced by setCurrentIndex().


Public Types
enum	SubmitPolicy
Public Slots
void	revert ()
bool	submit ()
void	toFirst ()
void	toLast ()
void	toNext ()
void	toPrevious ()
virtual void	setCurrentIndex (int index)
void	setCurrentModelIndex (const QModelIndex &index)
Signals
void	currentIndexChanged (int index)
Public Member Functions
	QDataWidgetMapper (QObject *parent=0)
	~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	removeMapping (QWidget *widget)
int	mappedSection (QWidget *widget) const
QWidget *	mappedWidgetAt (int section) const
void	clearMapping ()
int	currentIndex () const
Private Member Functions
	Q_PRIVATE_SLOT (d_func(), void _q_dataChanged(const QModelIndex &, const QModelIndex &)) Q_PRIVATE_SLOT(d_func()
void	_q_commitData (QWidget *)) Q_PRIVATE_SLOT(d_func()
void void	_q_closeEditor (QWidget *, QAbstractItemDelegate::EndEditHint)) Q_PRIVATE_SLOT(d_func()

QDataWidgetMapper::Q_PRIVATE_SLOT	(	d_func()	,
		void	_q_dataChanged(const QModelIndex &, const QModelIndex &)
	)			`[private]`

void void QDataWidgetMapper::_q_closeEditor	(	QWidget *	,
		QAbstractItemDelegate::EndEditHint
	)			`[private]`

QDataWidgetMapper Class Reference

Detailed Description

Public Types

Public Slots

Signals

Public Member Functions

Private Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation