1 files changed, 107 insertions, 0 deletions
diff --git a/src/positioning/doc/src/qml-position.qdoc b/src/positioning/doc/src/qml-position.qdoc
new file mode 100644
index 00000000..850bdd35
--- /dev/null
+++ b/src/positioning/doc/src/qml-position.qdoc
@@ -0,0 +1,107 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+\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, the source will emit updates according to the time stamp of each NMEA sentence to produce a "replay" of the recorded data.
+
+
+
+\section2 \b{Flickr Example}
+
+The \l{Flickr (QML)}{Flickr Example} uses the Location to download thumbnail
+images from Flickr relevant to the current location.
+
+*/