diff options
Diffstat (limited to 'src/positioning/doc/src/cpp-position.qdoc')
| -rw-r--r-- | src/positioning/doc/src/cpp-position.qdoc | 65 |
1 files changed, 34 insertions, 31 deletions
diff --git a/src/positioning/doc/src/cpp-position.qdoc b/src/positioning/doc/src/cpp-position.qdoc index 0205ad08..a380f105 100644 --- a/src/positioning/doc/src/cpp-position.qdoc +++ b/src/positioning/doc/src/cpp-position.qdoc @@ -35,9 +35,11 @@ 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. +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. @@ -66,9 +68,9 @@ 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 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 @@ -77,24 +79,25 @@ 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. +\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 QGeoAreaMonitorSource 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, QGeoAreaMonitorSource::createDefaultMonitor() returns an instance of -the default area monitor. +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 -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. +\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. @@ -106,7 +109,7 @@ 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(): +data source, as returned by \l {QGeoPositionInfoSource::createDefaultSource()}: \code class MyClass : public QObject @@ -135,20 +138,20 @@ private slots: \section2 Controlling Aspects of Data Sources -The QGeoPositionInfoSource::setUpdateInterval() method can be used to +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.) +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 +\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 -QGeoPositionInfoSource::SatellitePositioningMethods value. However, this +\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 @@ -158,7 +161,7 @@ the application. \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 +\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 @@ -166,13 +169,13 @@ 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 +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 QGeoPositionInfoSource -to create a custom positioning source. +The \l {Log File Position Source (C++)} example demonstrates how to subclass +\l QGeoPositionInfoSource to create a custom positioning source. \section1 Examples |