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
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
/****************************************************************************
**
** Copyright (C) 2013 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 declarative/mapviewer
\title Map Viewer (QML)
\ingroup qtlocation-examples
\brief The Map Viewer example shows how to display and interact with a map,
search for an address, and find driving directions.
This is a large example covering many basic uses of maps, positioning, and
navigation services in Qt Location. This page is divided into sections
covering each of these areas of functionality with snippets from the code.
The Map Viewer example can work with any of the available geo services plugins. However, some
plugins may require additional \l {QtLocation5::PluginParameter}{plugin parameters} in order to
function correctly. \l {QtLocation5::PluginParameter}{Plugin parameters} can be passed on the
command line using the \c {--plugin} argument, which takes the form:
\code
--plugin.<parameter name> <parameter value>
\endcode
Refer to the documentation for each of the geo services plugins for details on what plugin
parameters they support. The Nokia services plugin supplied with Qt requires an \e app_id and
\e token pair. See "\l {Qt Location Nokia Plugin}" for details.
QML types shown in this example:
\list
\li Displaying a map
\list
\li \l{QtLocation5::Map}{Map}
\li \l{QtLocation5::MapGestureArea}{MapGestureArea}
\li \l{coordinate}
\endlist
\li Finding an address
\list
\li \l{QtLocation5::GeocodeModel}{GeocodeModel}
\li \l{QtLocation5::MapItemView}{MapItemView}
\li \l{QtLocation5::MapCircle}{MapCircle}
\endlist
\li Directions and travel routes
\list
\li \l{QtLocation5::RouteModel}{RouteModel}
\li \l{QtLocation5::MapRoute}{MapRoute}
\endlist
\endlist
\image ../images/example-mapviewer.png
\section2 Displaying a Map
Drawing a map on-screen is accomplished using the Map type, as shown
below.
\snippet mapviewer/content/map/MapComponent.qml top
\snippet mapviewer/content/map/MapComponent.qml coord
\snippet mapviewer/content/map/MapComponent.qml end
In this example, we give the map an initial center \l {coordinate}
with a set latitude and longitude. We also set the initial zoom level to 50% (halfway between
the maximum and minimum).
The calls to "pinch" and "flick" are used to enable gestures on the map.
The flick gesture is also sometimes known as "kinetic panning", and provides
a more intuitive feel for panning the map both on touch screens and with
a mouse.
As we do not specify a plugin for supplying map data, the platform default
will be used. This is typically the "nokia" plugin, which provides data from
Nokia services. Additional licensing conditions do apply to the use of this data,
please see the documentation for further details.
\section2 Finding an Address (Geocoding)
To locate a certain address or place on the map uses a process called
geocoding. In order to perform a geocode operation, we first need to adjust
our Map object to be able to receive the result.
Receiving results of geocoding is done through a GeocodeModel, which is
typically instantiated as a property of the Map component:
\snippet mapviewer/content/map/MapComponent.qml geocodemodel0
\snippet mapviewer/content/map/MapComponent.qml geocodemodel1
Then, to display the contents of the GeocodeModel we use a MapItemView:
\snippet mapviewer/content/map/MapComponent.qml geocodeview
MapItemView uses an object called a "delegate" to act as a template for the
items it creates. This can contain any map object desired, but in this case
we show a MapCircle:
\snippet mapviewer/content/map/MapComponent.qml pointdel0
\snippet mapviewer/content/map/MapComponent.qml pointdel1
With these three objects, we have enough to receive Geocode responses and
display them on our Map. The final piece is to send the actual Geocode
request.
In this example, we have a utility component called Dialog which we use
to display the user interface requesting geocoding parameters. You can
create a similar component yourself using Dialog.qml in this example
as a reference, or drive the process using any other UI you wish.
To send a geocode request, first we create an Address object, and fill it
in with the desired parameters. Then we set "map.geocodeModel.query" to
the filled in Address, and call update() on the GeocodeModel.
\snippet mapviewer/mapviewer.qml geocode0
\snippet mapviewer/mapviewer.qml geocode1
\snippet mapviewer/mapviewer.qml geocode2
\section2 Directions and Travel Routes
Similar to the GeocodeModel, Qt Location also features the RouteModel type,
which allows information about routes (for example driving directions) between two
or more points, to be received and used with a Map.
Here again, we instantiate the RouteModel as a property of our Map:
\snippet mapviewer/content/map/MapComponent.qml routemodel0
\snippet mapviewer/content/map/MapComponent.qml routemodel3
To display the contents of a model to the user, we need a view. Once again
we will use a MapItemView, to display the Routes as objects on the Map:
\snippet mapviewer/content/map/MapComponent.qml routeview
To act as a template for the objects we wish the view to create, we create
a delegate component:
\snippet mapviewer/content/map/MapComponent.qml routedelegate0
\snippet mapviewer/content/map/MapComponent.qml routedelegate1
With the model, view and delegate now complete, the only missing component
is some kind of control over the model to begin the Route request process.
In the simplest case, we can fill out a Route request using two already
available \l {coordinate}{coordinates}, which we store inside the RouteDialog
component:
\snippet mapviewer/mapviewer.qml routedialog0
\snippet mapviewer/mapviewer.qml routedialog1
In the next snippet, we show how to set up the request object and instruct
the model to update. We also instruct the map to center on the start
coordinate for our routing request.
\snippet mapviewer/mapviewer.qml routerequest0
\snippet mapviewer/mapviewer.qml routerequest1
This is all that is required to display a Route on the Map. However, it is
also useful to be able to retrieve the written directions and explanation
of the travel route. In the example, these are displayed in the pull-out
on the left-hand side of the map. To create this pull-out's contents, we
use a standard \l {Models and Views in Qt Quick#ListModel}{ListModel} and
\l {ListView} pair. The data in the \l {Models and Views in Qt Quick#ListModel}{ListModel} is
built from the routeModel's output:
\snippet mapviewer/content/map/MapComponent.qml routeinfomodel
Inside the RouteModel, we add an
\l{QtLocation5::RouteModel::status}{onStatusChanged} handler, which
calls the \c{update()} function we defined on the model:
\snippet mapviewer/content/map/MapComponent.qml routemodel1
*/
|
