1 files changed, 191 insertions, 0 deletions
diff --git a/src/location/doc/src/position.qdoc b/src/location/doc/src/position.qdoc
new file mode 100644
index 00000000..75f54c31
--- /dev/null
+++ b/src/location/doc/src/position.qdoc
@@ -0,0 +1,191 @@
+/****************************************************************************
+**
+** 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-cpp.html
+
+\title Positioning (C++)
+
+\brief The Location Positioning API enables location positioning by means of
+GPS or an NMEA data source.
+
+\section1 Positioning
+
+The Positioning component of the Qt Location API is about the geographical position, size
+and address of some place. Positioning contains a QGeoCoordinate class, containing latitude, longitude and altitude in meters. QGeoLocation contains a QGeoCoordinate plus address
+and size information (a bounding box) so that positions can be more than mathematical points.
+Movement into or out of the defined bounding box areas can be monitored. The API
+also allows the developer to control the source of the positional information
+as well.
+
+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
+
+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.
+
+
+Location data sources are created by subclassing QGeoPositionInfoSource and
+providing QGeoPositionInfo objects through the
+QGeoPositionInfoSource::positionUpdated() signal. Clients that require
+location data can connect to the
+\l{QGeoPositionInfoSource::positionUpdated()}{positionUpdated()} signal and
+call \l{QGeoPositionInfoSource::startUpdates()}{startUpdates()} or
+\l{QGeoPositionInfoSource::requestUpdate()}{requestUpdate()} to trigger the
+distribution of location data. The location data distribution can be stopped by
+calling the \l {QGeoPositionInfoSource::stopUpdates()}{stopUpdates()} function.
+
+A default position source may be available on some platforms. Call
+QGeoPositionInfoSource::createDefaultSource() to create an instance of the default
+position source; the method returns 0 if no default source is available for
+the platform.
+
+If a problem occurs with access to the information source then an
+\l {QGeoPositionInfoSource::error()}{error()} signal is emitted.
+
+The QGeoAreaMonitor class enables client applications to be notified when
+the receiving device has moved in or out of a particular area, as specified
+by a coordinate and radius. If the platform provides built-in support for
+area monitoring, QGeoAreaMonitor::createDefaultMonitor() returns an instance of
+the default area monitor.
+
+Satellite information can also be distributed through the
+QGeoSatelliteInfoSource class. Call QGeoSatelliteInfoSource::createDefaultSource() to
+create an instance of the default satellite data source for the platform,
+if one is available. Alternatively, clients can subclass it to provide a
+custom satellite data source.
+
+
+
+\section2 Requesting Location Data from Data Sources
+
+To receive data from a source, connect to its
+\l{QGeoPositionInfoSource::positionUpdated()}{positionUpdated()} signal,
+then call either \l{QGeoPositionInfoSource::startUpdates()}{startUpdates()}
+or \l{QGeoPositionInfoSource::requestUpdate()}{requestUpdate()} to begin.
+
+Here is an example of a client that receives data from the default location
+data source, as returned by QGeoPositionInfoSource::createDefaultSource():
+
+\code
+class MyClass : public QObject
+{
+    Q_OBJECT
+public:
+    MyClass(QObject *parent = 0)
+        : QObject(parent)
+    {
+        QGeoPositionInfoSource *source = QGeoPositionInfoSource::createDefaultSource(this);
+        if (source) {
+            connect(source, SIGNAL(positionUpdated(QGeoPositionInfo)),
+                    this, SLOT(positionUpdated(QGeoPositionInfo)));
+            source->startUpdates();
+        }
+    }
+
+private slots:
+    void positionUpdated(const QGeoPositionInfo &info)
+    {
+        qDebug() << "Position updated:" << info;
+    }
+};
+
+\endcode
+
+\section2 Controlling Aspects of Data Sources
+
+The QGeoPositionInfoSource::setUpdateInterval() method can be used to
+control the rate at which position updates are received. For example, if
+the client application only requires updates once every 30 seconds, it can
+call \c setUpdateInterval(30000). (If no update interval is set, or
+\l {QGeoPositionInfoSource::}{setUpdateInterval()} is called with a value of 0, the source uses a default
+interval or some other internal logic to determine when updates should be
+provided.)
+
+QGeoPositionInfoSource::setPreferredPositioningMethods() enables client
+applications to request that a certain type of positioning method be used.
+For example, if the application prefers to use only satellite positioning,
+which offers fairly precise outdoor positioning but can be a heavy user of
+power resources, it can call this method with the
+QGeoPositionInfoSource::SatellitePositioningMethods value. However, this
+method should only be used in specialized client applications; in most
+cases, the default positioning methods should not be changed, as a source
+may internally use a variety of positioning methods that can be useful to
+the application.
+
+\section2 NMEA Data
+
+\l {http://en.wikipedia.org/wiki/NMEA_0183}{NMEA} is a common text-based
+protocol for specifying navigational data. For convenience, the
+QNmeaPositionInfoSource is provided to enable client applications to read
+and distribute NMEA data in either real-time mode (for example, when
+streaming from a GPS device) or simulation mode (for example, when reading
+from a NMEA log file). In simulation mode, the source will emit updates
+according to the time stamp of each NMEA sentence to produce a "replay"
+of the recorded data.
+
+Generally, the capabilities provided by the default position source as
+returned by QGeoPositionInfoSource::createDefaultSource(), along with the
+QNmeaPositionInfoSource class, are sufficient for retrieving location
+data. However, in some cases developers may wish to write their own custom
+location data source.
+
+The \l {Log File Position Source (C++)} example demonstrates how to subclass QGeoPositionInfoSource
+to create a custom positioning source.
+
+
+\section1 Examples
+
+\section3 \b{Flickr Example}
+
+The \l{Flickr QML}{Flickr Example} uses the Location to download thumbnail
+images from Flickr relevant to the current location.
+
+
+
+\section1 Location Position Classes
+
+\annotatedlist QtLocation-positioning
+
+*/