/****************************************************************************
**
** 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-positioning-qml.html

\title Positioning (QML)

\brief The Location Positioning API enables location positioning by means of
GPS or an NMEA data source.

\section1 Location Positioning

Location data involves a precisely specified position on the Earth's
surface \unicode {0x2014} as provided by a latitude-longitude coordinate
\unicode {0x2014} along with associated data, such as:

    \list
    \li The date and time at which the position was reported
    \li The velocity of the device that reported the position
    \li The altitude of the reported position (height above sea level)
    \li The bearing of the device in degrees, relative to true north
    \endlist

For more information see
\l {http://en.wikipedia.org/wiki/Geographic_coordinate}{Geographic Coordinate}.

This data can be extracted through a variety of methods. One of the most
well known methods of positioning is GPS (Global Positioning System), a
publicly available system that uses radiowave signals received from
Earth-orbiting satellites to calculate the precise position and time of
the receiver. Another popular method is 'Cell Identifier Positioning', which uses
the cell identifier of the cell site that is currently serving the receiving
device to calculate its approximate location. These and other positioning
methods can all be used with the Location API; the only requirement for a
location data source within the API is that it provides a
latitude-longitude coordinate with a date/time value, with the option of
providing the other attributes listed above.

\section2 Coordinate

The \l {coordinate} is a basic unit of geographical information. The
\l {coordinate} type has attributes to hold the \c {latitude},
\c longitude and \c altitude.

\section2 Position

The three dimensional position of an object such as a mobile device can be specified by giving
the latitude, longitude and altitude.  That is the values held in the
l\ {coordinate} type.  Additionally for computation of future
positions we would like to know if the object is moving, what \l {Position::speed}{speed} it is
doing and what is the \l {Position::timestamp}{timestamp} of the last position data.  Position
therefore includes values for the \l {Position::coordinate}{coordinate},
\l {Position::speed}{speed} and a \l {Position::timestamp}{timestamp}.  \l Position also takes
responsibility for validation of sensible values for these properties.  These are exposed as
the \l {Position::latitudeValid}{latitudeValid}, \l {Position::longitudeValid}{longitudeValid},
\l {Position::altitudeValid}{altitudeValid}, \l {Position::speedValid}{speedValid},
\l {Position::horizontalAccuracyValid}{horizontalAccuracyValid}, and
\l {Position::verticalAccuracyValid}{verticalAccuracyValid} properties.


\section2 PositionSource

We have a Position type, a \l {coordinate} type but where does the data come from?
Also it is a good idea to be able to indicate alternative sources.
Perhaps instead of directly picking up GPS satellites it might be desirable to do
some testing using a datafile.

The \l PositionSource type provides the developer with control,
within the limits allowed by the platform, of the source of the
geographical data. Apart from tradtional sources such as GPS and cell data the positional data can be
sourced from a logfile which is in NMEA format.

\l {http://en.wikipedia.org/wiki/NMEA}{NMEA} is a common text-based
protocol for specifying navigational data. For convenience, the \l
{PositionSource::nmeaSource}{nmeaSource} property is provided to enable
QML applications to read NMEA data from a log file or a TCP socket, the
source will emit updates according to the time stamp of each NMEA sentence
to produce a "replay" of the recorded data. To use a TCP socket set the
"socket" uri scheme.

\code
PositionSource {
    nmeaSource: "socket://127.0.0.1:12345"
}
\endcode



\section2 \b{GeoFlickr Example}

The \l{GeoFlickr (QML)}{GeoFlickr Example} uses the Location to download thumbnail
images from Flickr relevant to the current location.

*/