qml-position.qdoc

Go to the documentation of this file.

// Copyright (C) 2017 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\page location-positioning-qml.html
 
\title Positioning (QML)
\ingroup explanations-positioning
\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 Coordinates
 
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. The \l {QtPositioning::}{Location} contains this
\l coordinate in addition to a physical address and a bounding box.
\b {See also}: \l {Place::location}{retrieving a location}
 
\section2 Positions
 
In addition to the \l coordinate type, which holds the three-dimensional
position of an object, \l Position provides \l {Position::speed}{speed} and a
\l {Position::timestamp}{timestamp} to compute future positions.
\l Position validates sensible values for these properties, which are
exposed as the following properties:
\list
    \li \l {Position::latitudeValid}{latitudeValid}
    \li \l {Position::longitudeValid}{longitudeValid}
    \li \l {Position::altitudeValid}{altitudeValid}
    \li \l {Position::speedValid}{speedValid}
    \li \l {Position::horizontalAccuracyValid}{horizontalAccuracyValid}
    \li \l {Position::verticalAccuracyValid}{verticalAccuracyValid}
\endlist
 
\section2 PositionSource Type
 
We have a \l 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.
\l PositionSource supports multiple plugins, including an
\l {Qt Positioning NMEA plugin}{NMEA} plugin.
 
\l {http://en.wikipedia.org/wiki/NMEA}{NMEA} is a common text-based
protocol for specifying navigational data. The \l PositionSource
\l {Qt Positioning NMEA plugin}{NMEA} plugin supports multiple data sources,
including raw file or TCP socket. The source will emit updates according to the
time stamp of each NMEA sentence to produce a "replay" of the recorded data.
 
See the \l {Qt Positioning NMEA plugin}{plugin description} for usage examples.
 
\section2 Satellite Info Example
 
The \l {Satellite Info} example uses the \l PositionSource
and \l SatelliteSource QML types to get the satellite information relevant to
the current location.
 
*/