1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
|
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page location-positioning.html
\title Location Positioning
\previouspage {qtlocation-cpp.html}{QtLocation}
\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
\o The date and time at which the position was reported
\o The velocity of the device that reported the position
\o The altitude of the reported position (height above sea level)
\o 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 ID positioning, which uses
the cell ID 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.
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.
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 Reading 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.
\section2 Example: Creating a custom location data source
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 sources.
The \c LogFilePositionSource class in \c examples/logfilepositionsource
shows how to subclass QGeoPositionInfoSource to create a custom location
data source.
This example class reads location data from a text file, \e log.txt. The
file specifies location data using a simple text format: it contains one
location update per line, where each line contains a date/time, a latitude
and a longitude, separated by spaces. The date/time is in ISO 8601 format
and the latitude and longitude are in degrees decimal format. Here is an
excerpt from \e log.txt:
\code
2009-08-24T22:25:01 -27.576082 153.092415
2009-08-24T22:25:02 -27.576223 153.092530
2009-08-24T22:25:03 -27.576364 153.092648
\endcode
The class reads this data and distributes it via the
\l{QGeoPositionInfoSource::positionUpdated()}{positionUpdated()} signal.
Here is the definition of the \c LogFilePositionSource class:
\quotefromfile logfilepositionsource/logfilepositionsource.h
\skipto class LogFilePositionSource
\printuntil };
The main methods overrided by the subclass are:
\list
\o \l{QGeoPositionInfoSource::startUpdates()}{startUpdates()}: called by client applications to start regular position updates
\o \l{QGeoPositionInfoSource::stopUpdates()}{stopUpdates()}: called by client applications to stop regular position updates
\o \l{QGeoPositionInfoSource::requestUpdate()}{requestUpdate()}: called by client applications to request a single update, with a specified timeout
\endlist
When a position update is available, the subclass emits the
\l{QGeoPositionInfoSource::positionUpdated()}{positionUpdated()} signal.
Here are the key methods in the class implementation:
\quotefromfile logfilepositionsource/logfilepositionsource.cpp
\skipto LogFilePositionSource::LogFilePositionSource
\printuntil /^\}/
\skipto LogFilePositionSource::startUpdates
\printuntil /^\}/
\skipto LogFilePositionSource::stopUpdates
\printuntil /^\}/
\skipto LogFilePositionSource::requestUpdate
\printuntil /^\}/
\printuntil LogFilePositionSource::readNextPosition
\printuntil /^\}/
The \l {Log File Position Source Example}{example} includes a \c ClientApplication class that requests updates
from the \c LogFilePositionSource class. Run the example to see the data
that is received by \c ClientApplication.
Before running the example, make sure you have done both \tt make
and \tt {make install}.
\section1 Examples
\section3 \bold{Flickr Example}
The \l{Declarative Flickr}{Flickr Example} uses the Location to download thumbnail
images from Flickr relevant to the current location.
\section1 Location Position classes
\annotatedlist QtLocation-positioning
*/
|
