/****************************************************************************
**
** 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$
**
****************************************************************************/

/*!
    \qmlmodule QtLocation 5.0
    \title Qt Location QML Types
    \ingroup qmlmodules
    \brief Provides QML types for mapping and location information

\section1 Overview

The identifying string for this module is \e QtLocation. To use include the following import
statement in the QML file.

\snippet declarative/plugin.qml Plugin import

\section2 Location QML Concepts

Provided that a position has been obtained this module can
add a \l {QtLocation::Map}{Map} with positions of interest and
\l {QtLocation::Place}{Places}. The user can be made aware of nearby features and related
information, displayed graphically. Features on the \l Map may be places of business, entertainment
and so on.  They may include paths, roads, or forms of transport leading so that
navigation optimization and assistance are possible.

To perform navigation we need \l {Route}s from start to destination. These routes
are made up of segments. Each \l {QtLocation::RouteSegment}{RouteSegment}
can be considered a navigation sub-task: drive 100 meters, turn left. The beginning and
end of each segment is a \e waypoint, that is, one part of our journey.

A typical use case for the API is a user looking for a particular type of
place, say a restaurant. The user could enter a search string into the map
application and respond to a list or display of results for restaurants
"near" the device. The application could then be used to navigate to the
restaurant using an optimized route that is aware of features in the
environment that can help or hinder the journey. The navigation then
proceeds with the user's progress monitored by means of the current
\l Location. In the context of this API the map application would be aware
of the location and size of various places and the location of the user.
Plugins would supply the data used by the application to determine routes and
navigation instructions. The \l Place types would hold information about the
destination and surrounding objects including displayable representations.
The \l Map type would enable this information to be displayed, panned,
zoomed and so on. The \l Route would be determined by a plugin with each
\l RouteSegment holding the navigation instructions guided by the updated
current \l Location.

\l {Plugin}s are a means of specifying which Location based service to use. For example,
a plugin may allow connection to a provider's service that handles geocoding and routing
that the API and application can use. There may be various GeoServices plugins for various tasks
with some plugins providing more than one service. One QML \l Plugin should be created
for each required GeoService plugin. Plugins are required for maps, routing and geocoding,
however the default plugin handles all three of these services. A plugin may
require online access or may support on-board maps and data. The default "nokia"
plugin only supports online use. The connection would be managed by QNetworkInfo and
QNetworkConfigurationManager.

\note: Plugins may not provide various features such as paging or relevance hints.
Since plugins may be supplied by other providers, support for these aspects is
dependent on the provider's implementation.

The following table provides links to more detailed information on sections of the Qt Location QML
API.

\table
    \row
        \li \l {Maps and Navigation (QML)}{Maps and Navigation}
        \li Displaying maps and finding routes.
    \row
        \li \l {QML PLaces API} {Places}
        \li Searching for and managing points of interest.
\endtable

\section1 Common QML Types

\annotatedlist qml-QtLocation5-common

\section1 Maps QML Types

\annotatedlist qml-QtLocation5-maps

\section1 Navigation and Routing QML Types

\annotatedlist qml-QtLocation5-routing

\section1 Geocoding QML Types

\annotatedlist qml-QtLocation5-geocoding

\section1 Places QML Types

\annotatedlist qml-QtLocation5-places

\section1 Alphabetical Listing of all QML Types
*/
