1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example itemviews/simplewidgetmapper
\title Simple Widget Mapper Example
\brief The Simple Widget Mapper example shows how to use a widget mapper to display
data from a model in a collection of widgets.
\image simplewidgetmapper-example.png
The QDataWidgetMapper class allows information obtained from a
\l{Model Classes}{model} to be viewed and edited in a collection of
widgets instead of in an \l{View Classes}{item view}.
Any model derived from QAbstractItemModel can be used as the source of
data and almost any input widget can be used to display it.
The example itself is very simple: we create \c Window, a QWidget subclass
that we use to hold the widgets used to present the data, and show it. The
\c Window class will provide buttons that the user can click to show
different records from the model.
\section1 Window Class Definition
The class provides a constructor, a slot to keep the buttons up to date,
and a private function to set up the model:
\snippet examples/itemviews/simplewidgetmapper/window.h Window definition
In addition to the QDataWidgetMapper object and the controls used to make
up the user interface, we use a QStandardItemModel to hold our data.
We could use a custom model, but this standard implementation is sufficient
for our purposes.
\section1 Window Class Implementation
The constructor of the \c Window class can be explained in three parts.
In the first part, we set up the widgets used for the user interface:
\snippet examples/itemviews/simplewidgetmapper/window.cpp Set up widgets
We also set up the buddy relationships between various labels and the
corresponding input widgets.
Next, we set up the widget mapper, relating each input widget to a column
in the model specified by the call to \l{QDataWidgetMapper::}{setModel()}:
\snippet examples/itemviews/simplewidgetmapper/window.cpp Set up the mapper
We also connect the mapper to the \gui{Next} and \gui{Previous} buttons
via its \l{QDataWidgetMapper::}{toNext()} and
\l{QDataWidgetMapper::}{toPrevious()} slots. The mapper's
\l{QDataWidgetMapper::}{currentIndexChanged()} signal is connected to the
\c{updateButtons()} slot in the window which we'll show later.
In the final part of the constructor, we set up the layout, placing each
of the widgets in a grid (we could also use a QFormLayout for this):
\snippet examples/itemviews/simplewidgetmapper/window.cpp Set up the layout
Lastly, we set the window title and initialize the mapper by setting it to
refer to the first row in the model.
The model is initialized in the window's \c{setupModel()} function. Here,
we create a standard model with 5 rows and 3 columns, and we insert some
sample names, addresses and ages into each row:
\snippet examples/itemviews/simplewidgetmapper/window.cpp Set up the model
As a result, each row can be treated like a record in a database, and the
widget mapper will read the data from each row, using the column numbers
specified earlier to access the correct data for each widget. This is
shown in the following diagram:
\image widgetmapper-simple-mapping.png
Since the user can navigate using the buttons in the user interface, the
example is fully-functional at this point, but to make it a bit more
user-friendly, we implement the \c{updateButtons()} slot to show when the
user is viewing the first or last records:
\snippet examples/itemviews/simplewidgetmapper/window.cpp Slot for updating the buttons
If the mapper is referring to the first row in the model, the \gui{Previous}
button is disabled. Similarly, the \gui{Next} button is disabled if the
mapper reaches the last row in the model.
\section1 More Complex Mappings
The QDataWidgetMapper class makes it easy to relate information from a
model to widgets in a user interface. However, it is sometimes necessary
to use input widgets which offer choices to the user, such as QComboBox,
in conjunction with a widget mapper.
In these situations, although the mapping to input widgets remains simple,
more work needs to be done to expose additional data to the widget mapper.
This is covered by the \l{Combo Widget Mapper Example}{Combo Widget Mapper}
and \l{SQL Widget Mapper Example}{SQL Widget Mapper}
examples.
*/
|
