1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
6\page location-maps-qml.html
7\title Maps and Navigation (QML)
9\brief Provides QtQuick user interfaces for displaying, navigating and
10 interacting with maps, as well as geocoding and navigation.
12\b{Maps and Navigation} provides QtQuick user interface types for
13displaying geographic information on a map, as well as allowing user
14interaction with map overlay objects and the display itself. It also
15contains utilities for geocoding (finding a geographic coordinate from a
16street address) and navigation (including driving and walking directions).
18To perform navigation we need \l {route}s from start to destination. These
19routes are made up of segments, where each \l {QtLocation::}{routeSegment} can
20be considered a navigation subtask; for example, "drive 100 meters", or "turn
21left". The beginning and end of each segment is a \e waypoint, that is, one part
24A typical use case for the API is a user looking for a particular type of place,
25such as a restaurant; the user enters a search string into the map application
26and is presented with a list of results for restaurants "near" the device. The
27application can then be used to navigate to the chosen destination using a route
28that is optimized according to features in the environment that may help or
29hinder the journey. The navigation then proceeds with the user's progress
30monitored by means of the current location.
32The types build upon the API concepts and types in the
33\l{Positioning (QML)}{QML Positioning API}. A more hands-on introduction of the
34Maps and Navigation types can be found in the
35\l {QML Maps}{Maps and Navigation tutorial}.
39\section2 Displaying Maps
41Displaying a map is done using the \l{QtLocation::Map}{Map} QML types. The Map type supports
42user interaction through the \l{QtLocation::MapView}{MapView} QML type. The Map
43object draws the map on-screen using OpenGL (ES), allowing for hardware-accelerated rendering
49 \li \l{QtLocation::Plugin}{Plugin}
50 \li A location-based services plugin provides data including map data which is then displayed in a Map object.
52 \li \l{QtLocation::Map}{Map}
53 \li QtQuick item to display a map on-screen.
55 \li \l{QtLocation::MapView}{MapView}
56 \li Interaction helper for panning, flicking and pinch-to-zoom gesture on a Map.
59Note that the client must create a \l{QtLocation::Plugin}{Plugin} object
60prior to using a \l{QtLocation::Map}{Map} type in order to have access
61to map data to display.
63\section2 Putting Objects on a Map (Map Overlay Objects)
65Maps can also contain map overlay objects, which are used to display information
66on its surface. There is a set of basic pre-defined map overlay objects, as well
67as the ability to implement custom map overlay objects using the
68\l{QtLocation::MapQuickItem}{MapQuickItem} type, which can contain any
74 \li \l{QtLocation::MapCircle}{MapCircle}
75 \li A geographic circle (all points at a set distance from a center), optionally with a border.
77 \li \l{QtLocation::MapRectangle}{MapRectangle}
78 \li A rectangle whose top left and bottom right points are specified as
79 \l {coordinate} types, optionally with a border.
81 \li \l{QtLocation::MapPolygon}{MapPolygon}
82 \li A polygon made of an arbitrary list of \l {coordinate}{coordinates}.
84 \li \l{QtLocation::MapPolyline}{MapPolyline}
85 \li A polyline made of an arbitrary list of \l {coordinate}{coordinates}.
87 \li \l{QtLocation::MapQuickItem}{MapQuickItem}
88 \li Turns any arbitrary QtQuick Item into a map overlay object. MapQuickItem is an enabler for specifying custom map overlay objects.
91\section2 Model-View Design with Map Overlay Objects
93To automatically generate map overlay objects based on the contents of a QtQuick
94model (for example a ListModel item), the \l{QtLocation::MapItemView}{MapItemView}
95type is available. It accepts any map overlay object as its delegate, and can
96only be created within a \l{QtLocation::Map}{Map}.
101 \li \l{QtLocation::MapItemView}{MapItemView}
102 \li Populates a Map with map overlay objects based on the data provided by a model.
105\section2 Interaction with Map Overlay Objects
107Properties of map overlay objects that influence their appearance on the display can
108be changed at any time, and many can also be used in animations. Animating
109coordinate-based map overlay objects, such as MapPolygon and MapPolyline, is not yet
112\section1 Geocoding -- Address to Coordinate and Vice Versa
114Geocoding is the translation of geographic coordinates into addresses, or vice
115versa. Such a translation usually involves sending the source data to a server
116which then performs the translation and returns the results, although some
117location-based service provider \l{QtLocation::Plugin}{plugins} may be able to
118provide some geocoding functionality without sending data to a remote server.
119The availability and accuracy of the translation usually depends on the location
120or address being translated, as different areas of the Earth are mapped to
121varying degrees of accuracy.
123A geocoding query in QML is performed using the
124\l{QtLocation::GeocodeModel}{GeocodeModel} type. For an address-to-coordinate
125query, its \c{query} property may be set to either an
126\l [QtPositioning]{Address} object or a string containing the textual
127form of the address to search for. To perform the reverse, the same property
128can be set to a \l {coordinate} instead. Results are made available in the
129contents of the model.
134 \li \l{QtLocation::Plugin}{Plugin}
135 \li A location-based services plugin provides data including geocoding translation results which are exposed to clients via a GeocodeModel.
137 \li \l{QtLocation::GeocodeModel}{GeocodeModel}
138 \li Queries the Plugin for geocoding translations and provides access to results via indexes in the model.
140 \li \l[QtPositioning]{Address}
141 \li Structured address for use in queries and results of geocoding.
144Note that the client must create a \l{QtLocation::Plugin}{Plugin} object
145prior to using a \l{QtLocation::GeocodeModel}{GeocodeModel} object. This
146will enable access to geocoding translation services and thus data to display.
148\section1 Routing and Navigation
150Routing is the determination of a navigable path from one point to another on
151a map. Given a map that is aware of features that aid or hinder navigation, such as
152bridges, waterways and so on, a series of segments that make
153up the journey can be constructed. If these \l {routeSegment}s are simple then we can
154add navigation information at the connecting points, \l {routeManeuver}s,
161 \li The entire path to be navigated.
163 \li \l{QtLocation::routeSegment}{routeSegment}
164 \li The individual components of a route.
166 \li \l{QtLocation::routeManeuver}{routeManeuver}
167 \li The navigation information that joins segments.
169 \li \l{QtLocation::RouteModel}{RouteModel}
170 \li The means of making requests on the backend to supply route
183\page location-maps-cpp.html
184\title Maps and Navigation (C++)
186\brief Provides C++ classes for Geocoding and Navigation.
188\b{Maps and Navigation} provides C++ utilities for geocoding (finding a
189geographic coordinate from a street address) and navigation (including driving
190and walking directions).
192Currently it is not possible to interact with maps via C++. Mapping applications
193must use the \l {Maps and Navigation (QML)} API.
198In C++, an address-to-coordinate query is performed using the
199\l{QGeoCodingManager::geocode()}{geocode()} method of the QGeoCodingManager
200class. For coordinate-to-address queries, the
201\l{QGeoCodingManager::reverseGeocode()}{reverseGeocode()} method is available
202on the same class. Instances of QGeoCodingManager are available via
203\l{QGeoServiceProvider}.
208 \li \l{QGeoServiceProvider}
209 \li Provides a QGeoCodingManager instance ready for use.
211 \li \l{QGeoCodingManager}
212 \li Accepts queries and produces QGeoCodeReply objects.
214 \li \l{QGeoCodeReply}
215 \li Contains the results of a geocoding query.
220In C++, a route query is performed using the \l{QGeoRoutingManager::calculateRoute()}{calculate()}
221method of the QGeoRoutingManager class. The returned route reply can contain
222multiple routes to the same destination.
227 \li \l{QGeoServiceProvider}
228 \li Provides a QGeoCodingManager instance ready for use.
230 \li \l{QGeoRoutingManager}
231 \li Accepts queries and produces QGeoRouteReply objects.
233 \li \l{QGeoRouteReply}
234 \li Contains the results of a routing query.
237 \li Contains information about a route.