diff options
Diffstat (limited to 'src/positioning/doc/src/cpp-position.qdoc')
| -rw-r--r-- | src/positioning/doc/src/cpp-position.qdoc | 194 |
1 files changed, 0 insertions, 194 deletions
diff --git a/src/positioning/doc/src/cpp-position.qdoc b/src/positioning/doc/src/cpp-position.qdoc deleted file mode 100644 index a380f105..00000000 --- a/src/positioning/doc/src/cpp-position.qdoc +++ /dev/null @@ -1,194 +0,0 @@ -/**************************************************************************** -** -** 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-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 -\l QGeoCoordinate class, containing latitude, longitude and altitude in meters. -\l QGeoLocation contains a \l 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 \l QGeoPositionInfoSource and -providing \l QGeoPositionInfo objects through the -\l {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 -\l {QGeoPositionInfoSource::createDefaultSource()} to create an instance of the -default position source. The method returns \c nullptr if no default source is -available for the platform. - -If a problem occurs with access to the information source then an -\l {QGeoPositionInfoSource::errorOccurred()}{errorOccurred()} signal is emitted. - -The \l QGeoAreaMonitorSource class enables client applications to be notified -when the receiving device has moved into or out of a particular area, as -specified by a coordinate and radius. If the platform provides built-in support -for area monitoring, the \l {QGeoAreaMonitorSource::createDefaultSource()} -method returns an instance of the default area monitor. - -Satellite information can also be distributed through the -\l QGeoSatelliteInfoSource class. Call -\l {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 \l {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 \l {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. - -\l {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 -\l {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 -\l 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 \l {QGeoPositionInfoSource::createDefaultSource()}, along with the -\l 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 -\l QGeoPositionInfoSource to create a custom positioning source. - - -\section1 Examples - -\section3 \b{Flickr Example} - -The \l{GeoFlickr QML}{Flickr Example} uses the current location to download thumbnail -images from Flickr relevant to the current location. - - - -\section1 Positioning Classes - -\annotatedlist QtPositioning-positioning - -*/ |