QDataWidgetMapper 类

QDataWidgetMapper 类提供在数据模型区间与 Widget 之间的映射。更多...

头：	#include <QDataWidgetMapper>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake:	QT += widgets
继承：	QObject

所有成员列表，包括继承成员

公共类型

enum	SubmitPolicy { AutoSubmit, ManualSubmit }

特性

currentIndex : int
orientation : Qt::Orientation
submitPolicy : SubmitPolicy

公共函数

	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

公共槽

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

信号

void	currentIndexChanged (int index )

详细描述

QDataWidgetMapper 可以用于通过将它们映射到项模型区间来创建数据感知的 Widget。区间是模型列，若取向为水平 (默认)，否则是行。

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 用户特性 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 QStyledItemDelegate 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	Qt Norway	Oslo
2	Qt Australia	Brisbane
3	Qt USA	Palo Alto
4	Qt China	Beijing
5	Qt Germany	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 显示值 1 , myLineEdit displays Qt Norway and myCountryChooser displays Oslo . The navigational functions toFirst (), toNext (), toPrevious (), toLast () 和 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 () 被调用。 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.

另请参阅 QAbstractItemModel and QAbstractItemDelegate .

成员类型文档编制

enum QDataWidgetMapper:: SubmitPolicy

This enum describes the possible submit policies a QDataWidgetMapper 支持。

常量	值	描述
`QDataWidgetMapper::AutoSubmit`	`0`	Whenever a widget loses focus, the widget's current value is set to the item model.
`QDataWidgetMapper::ManualSubmit`	`1`	The model is not updated until submit () 被调用。

特性文档编制

currentIndex : int

This property holds 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 .

访问函数：

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

通知程序信号：

void	currentIndexChanged (int index )

另请参阅 setCurrentModelIndex (), toFirst (), toNext (), toPrevious ()，和 toLast ().

orientation : Qt::Orientation

This property holds 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.

使用 Qt::Horizontal for tabular data that looks like this:

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

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.

使用 Qt::Vertical for tabular data that looks like this:

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

Changing the orientation clears all existing mappings.

访问函数：

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

submitPolicy : SubmitPolicy

This property holds the current submit policy

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

访问函数：

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

成员函数文档编制

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

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

另请参阅 setOrientation () 和 setSubmitPolicy ().

`[virtual noexcept]` QDataWidgetMapper:: ~QDataWidgetMapper ()

销毁对象。

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

Adds a mapping between a widget 和 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 :

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

注意事项：

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

另请参阅 removeMapping (), mappedSection ()，和 clearMapping ().

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

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

另请参阅 addMapping ().

void QDataWidgetMapper:: clearMapping ()

Clears all mappings.

另请参阅 addMapping () 和 removeMapping ().

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

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

注意： 通知程序信号对于特性 currentIndex .

另请参阅 currentIndex () 和 setCurrentIndex ().

QAbstractItemDelegate *QDataWidgetMapper:: itemDelegate () const

Returns the current item delegate.

另请参阅 setItemDelegate ().

QByteArray QDataWidgetMapper:: mappedPropertyName ( QWidget * widget ) const

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

另请参阅 mappedSection (), addMapping ()，和 removeMapping ().

int QDataWidgetMapper:: mappedSection ( QWidget * widget ) const

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

另请参阅 addMapping () 和 removeMapping ().

QWidget QDataWidgetMapper:: mappedWidgetAt ( int section* ) const

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

另请参阅 addMapping () 和 removeMapping ().

QAbstractItemModel *QDataWidgetMapper:: model () const

Returns the current model.

另请参阅 setModel ().

void QDataWidgetMapper:: removeMapping ( QWidget * widget )

Removes the mapping for the given widget .

另请参阅 addMapping () 和 clearMapping ().

`[slot]` void QDataWidgetMapper:: revert ()

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

另请参阅 submit () 和 setSubmitPolicy ().

QModelIndex QDataWidgetMapper:: rootIndex () const

Returns the current root index.

另请参阅 setRootIndex ().

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

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

调用 setCurrentIndex () internally. This convenience slot can be connected to the signal currentRowChanged () 或 currentColumnChanged () of another view's selection model .

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

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

另请参阅 currentIndex ().

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 () 和 QAbstractItemDelegate::setModelData ().

任何现有委托将被移除，但不被删除。 QDataWidgetMapper 未拥有所有权对于 delegate .

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

警告： 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 closeEditor () 信号，且试图访问、修改或关闭已关闭的编辑器。

另请参阅 itemDelegate ().

void QDataWidgetMapper:: setModel ( QAbstractItemModel * model )

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

另请参阅 model ().

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.

另请参阅 rootIndex ().

`[slot]` bool QDataWidgetMapper:: submit ()

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 submit () method is invoked.

返回 true if all the values were submitted, otherwise false.

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

另请参阅 revert () 和 setSubmitPolicy ().

`[slot]` void QDataWidgetMapper:: toFirst ()

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.

这相当于调用 setCurrentIndex(0) .

另请参阅 toLast () 和 setCurrentIndex ().

`[slot]` void QDataWidgetMapper:: toLast ()

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.

调用 setCurrentIndex () internally.

另请参阅 toFirst () 和 setCurrentIndex ().

`[slot]` void QDataWidgetMapper:: toNext ()

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.

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

另请参阅 toPrevious () 和 setCurrentIndex ().

`[slot]` void QDataWidgetMapper:: toPrevious ()

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.

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

另请参阅 toNext () 和 setCurrentIndex ().

QDataWidgetMapper 类

公共类型

特性

公共函数

公共槽

信号

详细描述

成员类型文档编制

enum QDataWidgetMapper:: SubmitPolicy

特性文档编制

currentIndex : int

orientation : Qt::Orientation

submitPolicy : SubmitPolicy

成员函数文档编制

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

[virtual noexcept] QDataWidgetMapper:: ~QDataWidgetMapper ()

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

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

void QDataWidgetMapper:: clearMapping ()

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

QAbstractItemDelegate *QDataWidgetMapper:: itemDelegate () const

QByteArray QDataWidgetMapper:: mappedPropertyName ( QWidget * widget ) const

int QDataWidgetMapper:: mappedSection ( QWidget * widget ) const

QWidget *QDataWidgetMapper:: mappedWidgetAt ( int section ) const

QAbstractItemModel *QDataWidgetMapper:: model () const

void QDataWidgetMapper:: removeMapping ( QWidget * widget )

[slot] void QDataWidgetMapper:: revert ()

QModelIndex QDataWidgetMapper:: rootIndex () const

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

void QDataWidgetMapper:: setItemDelegate ( QAbstractItemDelegate * delegate )

void QDataWidgetMapper:: setModel ( QAbstractItemModel * model )

void QDataWidgetMapper:: setRootIndex (const QModelIndex & index )

[slot] bool QDataWidgetMapper:: submit ()

[slot] void QDataWidgetMapper:: toFirst ()

[slot] void QDataWidgetMapper:: toLast ()

[slot] void QDataWidgetMapper:: toNext ()

[slot] void QDataWidgetMapper:: toPrevious ()

内容

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

`[virtual noexcept]` QDataWidgetMapper:: ~QDataWidgetMapper ()

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

QWidget QDataWidgetMapper:: mappedWidgetAt ( int section* ) const

`[slot]` void QDataWidgetMapper:: revert ()

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

`[slot]` bool QDataWidgetMapper:: submit ()

`[slot]` void QDataWidgetMapper:: toFirst ()

`[slot]` void QDataWidgetMapper:: toLast ()

`[slot]` void QDataWidgetMapper:: toNext ()

`[slot]` void QDataWidgetMapper:: toPrevious ()