1/****************************************************************************
2**
3** Copyright (C) 2017 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:FDL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Free Documentation License Usage
18** Alternatively, this file may be used under the terms of the GNU Free
19** Documentation License version 1.3 as published by the Free Software
20** Foundation and appearing in the file included in the packaging of
21** this file. Please review the following information to ensure
22** the GNU Free Documentation License version 1.3 requirements
23** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29    \example mapviewer
30    \title Map Viewer (QML)
31    \ingroup qtlocation-examples
32
33    \brief The Map Viewer example shows how to display and interact with a map,
34           search for an address, and find driving directions.
35
36    \image mapviewer.png
37
38    This is a large example covering many basic uses of maps, positioning, and
39    navigation services in Qt Location. This page is divided into sections
40    covering each of these areas of functionality with snippets from the code.
41
42    \include examples-run.qdocinc
43
44    \include example-parameters.qdocinc
45
46    \section1 Overview
47
48    QML types shown in this example:
49
50    \list
51    \li Displaying a map
52        \list
53        \li \l{QtLocation::Map}{Map}
54        \li \l{QtLocation::MapGestureArea}{MapGestureArea}
55        \li \l[QML]{coordinate}
56        \endlist
57    \li Finding an address
58        \list
59        \li \l{QtLocation::GeocodeModel}{GeocodeModel}
60        \li \l{QtLocation::MapItemView}{MapItemView}
61        \li \l{QtLocation::MapCircle}{MapCircle}
62        \endlist
63    \li Directions and travel routes
64        \list
65        \li \l{QtLocation::RouteModel}{RouteModel}
66        \li \l{QtLocation::MapRoute}{MapRoute}
67        \endlist
68    \endlist
69
70    \section1 Displaying a Map
71
72    Drawing a map on-screen is accomplished using the Map type, as shown
73    below.
74
75    \snippet mapviewer/map/MapComponent.qml top
76    \snippet mapviewer/map/MapComponent.qml coord
77    \snippet mapviewer/map/MapComponent.qml end
78
79    In this example, we give the map an initial center \l [QML]{coordinate}
80    with a set latitude and longitude. We also set the initial zoom level to 50% (halfway between
81    the maximum and minimum).
82
83    \section1 Finding an Address (Geocoding)
84
85    To locate a certain address or place on the map uses a process called
86    geocoding. In order to perform a geocode operation, we first need to adjust
87    our Map object to be able to receive the result.
88
89    Receiving results of geocoding is done through a GeocodeModel:
90
91    \snippet mapviewer/map/MapComponent.qml geocodemodel0
92
93    To display the contents of the GeocodeModel we use a MapItemView:
94
95    \snippet mapviewer/map/MapComponent.qml geocodeview
96
97    MapItemView uses an object called a "delegate" to act as a template for the
98    items it creates. This can contain any map object desired, but in this case
99    we show a MapCircle:
100
101    \snippet mapviewer/map/MapComponent.qml pointdel0
102    \snippet mapviewer/map/MapComponent.qml pointdel1
103
104    With these three objects, we have enough to receive Geocode responses and
105    display them on our Map. The final piece is to send the actual Geocode
106    request.
107
108    To send a geocode request, first we create an \l [QML]{Address} object, and fill it
109    in with the desired parameters.
110
111    \snippet mapviewer/mapviewer.qml geocode0
112
113    Then we set "geocodeModel.query" to the filled in \l [QML]{Address},
114    and call update() on the GeocodeModel.
115
116    \snippet mapviewer/map/MapComponent.qml geocode1
117
118    \section1 Directions and Travel Routes
119
120    Similar to the GeocodeModel, Qt Location also features the RouteModel type,
121    which allows information about routes (for example driving directions) between two
122    or more points, to be received and used with a Map.
123
124    Here again, we instantiate the RouteModel as a property of our Map:
125
126    \snippet mapviewer/map/MapComponent.qml routemodel0
127
128    To display the contents of a model to the user, we need a view. Once again
129    we will use a MapItemView, to display the Routes as objects on the Map:
130
131    \snippet mapviewer/map/MapComponent.qml routeview0
132    \snippet mapviewer/map/MapComponent.qml routeview1
133
134    To act as a template for the objects we wish the view to create, we create
135    a delegate component:
136
137    \snippet mapviewer/map/MapComponent.qml routedelegate0
138    \snippet mapviewer/map/MapComponent.qml routedelegate1
139
140    With the model, view and delegate now complete, the only missing component
141    is some kind of control over the model to begin the Route request process.
142    In the simplest case, we can fill out a Route request using two already
143    available \l [QML]{coordinate}{coordinates}:
144
145    \snippet mapviewer/mapviewer.qml routecoordinate
146
147    In the next snippet, we show how to set up the request object and instruct
148    the model to update. We also instruct the map to center on the start
149    coordinate for our routing request.
150
151    \snippet mapviewer/map/MapComponent.qml routerequest0
152    \snippet mapviewer/map/MapComponent.qml routerequest1
153    \snippet mapviewer/map/MapComponent.qml routerequest2
154
155    This is all that is required to display a Route on the Map. However, it is
156    also useful to be able to retrieve the written directions and explanation
157    of the travel route. In the example, these are displayed in a \l {ListView} element.
158    To create this content, we use a standard \l {Models and Views in Qt Quick#Models}{ListModel} and
159    \l {ListView} pair. The data in the \l {Models and Views in Qt Quick#Models}{ListModel} is
160    built from the routeModel's output:
161
162    \snippet mapviewer/forms/RouteList.qml routeinfomodel0
163    \snippet mapviewer/forms/RouteList.qml routeinfomodel1
164    \snippet mapviewer/forms/RouteList.qml routeinfomodel3
165
166    Inside the RouteModel, as you can see above, we add an
167    \l{QtLocation::RouteModel::status}{onStatusChanged} handler, which
168    calls the \c{showRouteList()} which updates the \c{routeInfoModel}:
169
170    \snippet mapviewer/forms/RouteList.qml routeinfomodel2
171*/
172