This repository has been archived by the owner on Sep 4, 2019. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 23
/
Copy pathsqlwidgetmapper.qdoc
125 lines (91 loc) · 6.03 KB
/
sqlwidgetmapper.qdoc
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) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page sqlwidgetmapper
\example sqlwidgetmapper
\title SQL Widget Mapper Example
\section1 Description
The SQL Widget Mapper example shows how to use a DataControlMapper to map information from a
database to controls in a form.
\image sqlwidgetmapper-example.png
\section1 Overview
In this example we'll learn how to access an SQLite database and map the single rows of a SQL table
to a set of Cascades controls.
While the standard way in Cascades of visualizing data from a SQL database is to display them in a ListView,
there might be use cases where you want to display and edit one row at a time.
Such a functionality can be implemented in a reusable component, which will be done in this sample application.
\section1 The UI
The UI of this example consists of three text fields that show the first name, last name and a quote. These data come
from a SQLite database. Additionally the UI provides a 'Previous' and 'Next' button that are used to navigate between
the database entries. A status label shows the current and the total number of quotes.
The business logic of the application is encapsulated in the class DataControlMapper, which is
exported to the UI as '_dataMapper'.
The text fields in the QML file have all the 'objectName' property set, so that they can be referenced from within C++.
\snippet sqlwidgetmapper/assets/main.qml 0
Whenever the user clicks the 'Previous' button, the toPrevious() slot of the DataControlMapper object is invoked.
The button is only enabled if the current row is not the first one.
\snippet sqlwidgetmapper/assets/main.qml 2
Whenever the user clicks the 'Next' button, the toNext() slot of the DataControlMapper object is invoked.
The button is only enabled if the current row is not the last one.
\snippet sqlwidgetmapper/assets/main.qml 1
The text of the status label is assembled from the 'currentIndex' and 'count' properties of the DataControlMapper.
\section1 ControlDataMapper
The ControlDataMapper is the central class in this application and contains all the business logic of mapping entries
from a data model to a set of Cascades controls.
It has been designed to be reusable, so any data model can be used, not only one based on a SQLite database.
The ControlDataMapper has the semantics of a cursor that can be moved between the rows of a data model. It provides
methods to jump to the first or last row and methods to go to the next or previous row. The single fields (sections) of a row
can be bound against Cascades controls. The ControlDataMapper will update the content of the controls automatically
with the data from the current row.
For this purpose the ControlDataMapper contains a list of mapping objects that have the following structure:
\snippet sqlwidgetmapper/src/datacontrolmapper.cpp 0
The 'control' is a pointer to the Cascades control that is associated with this mapping, the 'section' is the field name in the
current row that should be mapped, and the 'propertyName' is the name of the property in 'control' that should be set.
After we created a new instance of the DataControlMapper in our application, we set the model it should work with.
Now we can load the main.qml file, create the UI objects and lookup the text fields that we have marked with the 'objectName' properties.
In the next step the mappings between the Cascades controls and the section names (in this case the column names of the SQL table) can
be configured.
\snippet sqlwidgetmapper/src/main.cpp 0
The addMapping() call will determine the type of the Cascades control and call an overloaded addMapping() method with the default
property names for the specific control type.
\snippet sqlwidgetmapper/src/datacontrolmapper.cpp 3
The overloaded addMapping() method will check whether a mapping for the given control exists already and updates the mapping information,
otherwise it adds a new mapping to the internal list.
\snippet sqlwidgetmapper/src/datacontrolmapper.cpp 4
Whenever the mapping has changed or the current index (cursor) has been changed, the update() method is called.
\snippet sqlwidgetmapper/src/datacontrolmapper.cpp 2
This method retrieves the data of the current index from the data model. The returned value is expected to be a QVariantMap where
the keys are the same names as used for the 'section' property in the mappings. For the SQL model that will be the column names of
a SQL table.
Now the update() method iterates over all available mappings, extracts the value for the mapped section from the data model and sets
the value of the specified property on the Cascades control.
\snippet sqlwidgetmapper/src/datacontrolmapper.cpp 7
The navigation methods (e.g. toFirst()) just call the setCurrentIndex() method with the appropriated new index.
\snippet sqlwidgetmapper/src/datacontrolmapper.cpp 6
Inside setCurrentIndex() we only do some sanity checks to avoid an out-of-range access, update the member variable that
contains the current index with the new value and call update() again to update the content of the mapped Cascades controls.
*/