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
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
|
/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** 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 The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page location-maps-qml.html
\title Maps and Navigation (QML)
\brief Provides QtQuick user interfaces for displaying, navigating and
interacting with maps, as well as geocoding and navigation.
\b{Maps and Navigation} provides QtQuick user interface types for
displaying geographic information on a map, as well as allowing user
interaction with map overlay objects and the display itself. It also
contains utilities for geocoding (finding a geographic coordinate from a
street address) and navigation (including driving and walking directions).
It builds upon the API concepts and types in the \l{Positioning (QML)}{QML Positioning API}.
A more hands-on introduction of the Maps and Navigation types can be found in the
\l {QML Maps}{Maps and Navigation tutorial}.
\section1 Maps
\section2 Displaying Maps
Displaying a map is done using the \l{QtLocation::Map}{Map} QML types. The Map type supports
user interaction through the \l{QtLocation::MapGestureArea}{MapGestureArea} QML type. The Map
object draws the map on-screen using OpenGL (ES), allowing for hardware-accelerated rendering
where available.
\b{Key Types}
\table
\row
\li \l{QtLocation::Plugin}{Plugin}
\li A location-based services plugin provides data including map data which is then displayed in a Map object.
\row
\li \l{QtLocation::Map}{Map}
\li QtQuick item to display a map on-screen.
\row
\li \l{QtLocation::MapGestureArea}{MapGestureArea}
\li Interaction helper for panning, flicking and pinch-to-zoom gesture on a Map.
\endtable
Note that the client must create a \l{QtLocation::Plugin}{Plugin} object
prior to using a \l{QtLocation::Map}{Map} type in order to have access
to map data to display.
\section2 Putting Objects on a Map (Map Overlay Objects)
Maps can also contain map overlay objects, which are used to display information
on its surface. There is a set of basic pre-defined map overlay objects, as well
as the ability to implement custom map overlay objects using the
\l{QtLocation::MapQuickItem}{MapQuickItem} type, which can contain any
standard QtQuick item.
\b{Key Types}
\table
\row
\li \l{QtLocation::MapCircle}{MapCircle}
\li A geographic circle (all points at a set distance from a center), optionally with a border.
\row
\li \l{QtLocation::MapRectangle}{MapRectangle}
\li A rectangle whose top left and bottom right points are specified as
\l {coordinate} types, optionally with a border.
\row
\li \l{QtLocation::MapPolygon}{MapPolygon}
\li A polygon made of an arbitrary list of \l {coordinate}{coordinates}.
\row
\li \l{QtLocation::MapPolyline}{MapPolyline}
\li A polyline made of an arbitrary list of \l {coordinate}{coordinates}.
\row
\li \l{QtLocation::MapQuickItem}{MapQuickItem}
\li Turns any arbitrary QtQuick Item into a map overlay object. MapQuickItem is an enabler for specifying custom map overlay objects.
\endtable
\section2 Model-View Design with Map Overlay Objects
To automatically generate map overlay objects based on the contents of a QtQuick
model (for example a ListModel item), the \l{QtLocation::MapItemView}{MapItemView}
type is available. It accepts any map overlay object as its delegate, and can
only be created within a \l{QtLocation::Map}{Map}.
\b{Key Types}
\table
\row
\li \l{QtLocation::MapItemView}{MapItemView}
\li Populates a Map with map overlay objects based on the data provided by a model.
\endtable
\section2 Interaction with Map Overlay Objects
Properties of map overlay objects that influence their appearance on the display can
be changed at any time, and many can also be used in animations. Animating
coordinate-based map overlay objects, such as MapPolygon and MapPolyline, is not yet
available.
\section1 Geocoding -- Address to Coordinate and Vice Versa
Geocoding is the translation of geographic coordinates into addresses, or vice
versa. Such a translation usually involves sending the source data to a server
which then performs the translation and returns the results, although some
location-based service provider \l{QtLocation::Plugin}{plugins} may be able to
provide some geocoding functionality without sending data to a remote server.
The availability and accuracy of the translation usually depends on the location
or address being translated, as different areas of the Earth are mapped to
varying degrees of accuracy.
A geocoding query in QML is performed using the
\l{QtLocation::GeocodeModel}{GeocodeModel} type. For an address-to-coordinate
query, its \c{query} property may be set to either an
\l [QtPositioning]{Address} object or a string containing the textual
form of the address to search for. To perform the reverse, the same property
can be set to a \l {coordinate} instead. Results are made available in the
contents of the model.
\b{Key Types}
\table
\row
\li \l{QtLocation::Plugin}{Plugin}
\li A location-based services plugin provides data including geocoding translation results which are exposed to clients via a GeocodeModel.
\row
\li \l{QtLocation::GeocodeModel}{GeocodeModel}
\li Queries the Plugin for geocoding translations and provides access to results via indexes in the model.
\row
\li \l[QtPositioning]{Address}
\li Structured address for use in queries and results of geocoding.
\endtable
Note that the client must create a \l{QtLocation::Plugin}{Plugin} object
prior to using a \l{QtLocation::GeocodeModel}{GeocodeModel} object. This
will enable access to geocoding translation services and thus data to display.
\section1 Routing and Navigation
Routing is the determination of a navigable path from one point to another on
a map. Given a map that is aware of features that aid or hinder navigation, such as
bridges, waterways and so on, a series of segments that make
up the journey can be constructed. If these \l {RouteSegment}s are simple then we can
add navigation information at the connecting points, \l {RouteManeuver}s,
between the segments.
\b{Key Types}
\table
\row
\li \l{QtLocation::Route}{Route}
\li The entire path to be navigated.
\row
\li \l{QtLocation::RouteSegment}{RouteSegment}
\li The individual components of a route.
\row
\li \l{QtLocation::RouteManeuver}{RouteManeuver}
\li The navigation information that joins segments.
\row
\li \l{QtLocation::RouteModel}{RouteModel}
\li The means of making requests on the backend to supply route
information.
\endtable
*/
/*!
\page location-maps-cpp.html
\title Maps and Navigation (C++)
\brief Provides C++ classes for Geocoding and Navigation.
\b{Maps and Navigation} provides C++ utilities for geocoding (finding a
geographic coordinate from a street address) and navigation (including driving
and walking directions).
Currently it is not possible to interact with maps via C++. Mapping applications
must use the \l {Maps and Navigation (QML)} API.
\section1 Geocoding
In C++, an address-to-coordinate query is performed using the
\l{QGeoCodingManager::geocode()}{geocode()} method of the QGeoCodingManager
class. For coordinate-to-address queries, the
\l{QGeoCodingManager::reverseGeocode()}{reverseGeocode()} method is available
on the same class. Instances of QGeoCodingManager are available via
\l{QGeoServiceProvider}.
\b{Key Classes}
\table
\row
\li \l{QGeoServiceProvider}
\li Provides a QGeoCodingManager instance ready for use.
\row
\li \l{QGeoCodingManager}
\li Accepts queries and produces QGeoCodeReply objects.
\row
\li \l{QGeoCodeReply}
\li Contains the results of a geocoding query.
\endtable
\section1 Navigation
In C++, a route query is performed using the \l{QGeoRoutingManager::calculateRoute()}{calculate()}
method of the QGeoRoutingManager class. The returned route reply can contain
multiple routes to the same destination.
\b{Key Classes}
\table
\row
\li \l{QGeoServiceProvider}
\li Provides a QGeoCodingManager instance ready for use.
\row
\li \l{QGeoRoutingManager}
\li Accepts queries and produces QGeoRouteReply objects.
\row
\li \l{QGeoRouteReply}
\li Contains the results of a routing query.
\row
\li \l{QGeoRoute}
\li Contains information about a route.
\endtable
*/
|
