diff options
Diffstat (limited to 'src/location/doc/src/position.qdoc')
-rw-r--r-- | src/location/doc/src/position.qdoc | 191 |
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 + +*/ |