1/****************************************************************************
2**
3** Copyright (C) 2018 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    \qmlmodule QtLocation \QtVer
30    \title Qt Location QML Types
31    \ingroup qmlmodules
32    \brief Provides QML types for mapping and location information.
33
34    \section1 Overview
35
36    Provided that a position has been obtained, the Qt Location module
37    can add a \l{QtLocation::}{Map} with Places of Interest (POI) and
38    \l{QtLocation::Place}{Places}. The user can be made aware of nearby
39    features and related information, displayed on the map. These features
40    can be places of business, entertainment, and so on. They may include
41    paths, roads, or forms of transport, enabling navigation optimization
42    and assistance.
43
44    To perform navigation we need \l {Route}s from start to destination.
45    These routes are made up of segments, where each \l {QtLocation::}
46    {RouteSegment} can be considered a navigation subtask; for example,
47    "drive 100 meters", or "turn left". The beginning and end of each
48    segment is a \e waypoint, that is, one part of the journey.
49
50    A typical use case for the API is a user looking for a particular type of
51    place, such as a restaurant; the user enters a search string into the map
52    application and is presented with a list of results for restaurants
53    "near" the device. The application can then be used to navigate to the
54    chosen destination using a route that is optimized according to features
55    in the environment that may help or hinder the journey. The navigation then
56    proceeds with the user's progress monitored by means of the current
57    location.
58
59    In short, the main QML types and their roles are as follows:
60
61    \list
62
63        \li The \l [QML] Place instances hold information about the
64            destination and surrounding objects, including displayable
65            representations.
66
67        \li The \l [QML] Map enables the information contained in
68            \l [QML] {Place} objects to be displayed, panned, zoomed,
69            and so on.
70
71        \li The \l [QML] Route is be determined by a \e plugin, with each
72            \l [QML] RouteSegment holding the navigation instructions,
73            guided by the continuously updated current \l [QML] Location.
74
75    \endlist
76
77    \section2 Plugins
78
79    \l {Plugin}s supply the data required to calculate routes and navigation
80    instructions, and they are typically tied to a specific location-based
81    service. For example, a plugin may allow connecting to a service that
82    provides geocoding and routing information, which can be consumed by the
83    application.
84
85    There may be various GeoServices plugins for various tasks, with some
86    plugins providing more than one service. One QML \l Plugin instance must
87    be created for each GeoService plugin. Plugins are required for routing
88    and geocoding, maps, and places, however the default plugin handles all
89    four of these services. A plugin may require online access or it may
90    support on-board maps and data.
91
92    \note Plugins may not provide features such as paging or relevance hints.
93
94    \section2 Related Information
95
96    The following links provide more information about maps and places:
97
98    \table
99        \row
100            \li \l {Maps and Navigation (QML)}{Maps and Navigation}
101            \li Displaying maps and finding routes
102        \row
103            \li \l {QML Places API} {Places}
104            \li Searching for and managing points of interest
105    \endtable
106
107    \section1 Common QML Types
108
109    \annotatedlist qml-QtLocation5-common
110
111    \section1 Maps QML Types
112
113    \annotatedlist qml-QtLocation5-maps
114
115    \section1 Navigation and Routing QML Types
116
117    \annotatedlist qml-QtLocation5-routing
118
119    \section1 Geocoding QML Types
120
121    \annotatedlist qml-QtLocation5-geocoding
122
123    \section1 Places QML Types
124
125    \annotatedlist qml-QtLocation5-places
126
127    \section1 Alphabetical Listing of All QML Types
128*/
129