|
Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions | |
The Qt Extended Whereabouts library provides developers of Location-Based Services with the essential components for distributing, receiving and processing location information. The library can be used to easily query and retrieve location information, and location updates can be received from either built-in or custom-added location data sources. Custom location data sources are added through Qt Extended's plugin mechanisms.
The main classes in the Whereabouts library are QWhereabouts, QWhereaboutsUpdate, QWhereaboutsPlugin and QWhereaboutsFactory:
In addition, QNmeaWhereabouts provides functionality for reading location data from NMEA data sources. Developers can use it to read NMEA data sources without the need to write NMEA parsing code in their plugin implementations.
The Whereabouts Simple Demo demonstrates how to create a QWhereabouts instance and use it to retrieve location updates:
class SimpleLocationDemo : public QObject
{
Q_OBJECT
public:
SimpleLocationDemo(QObject *parent = 0)
: QObject(parent)
{
QWhereabouts *whereabouts = QWhereaboutsFactory::create();
connect(whereabouts, SIGNAL(updated(QWhereaboutsUpdate)),
SLOT(updated(QWhereaboutsUpdate)));
whereabouts->startUpdates();
}
private slots:
void updated(const QWhereaboutsUpdate &update)
{
// respond to update here
}
};
The application simply calls QWhereabouts::startUpdates() to begin to receive regular location updates through the QWhereabouts::updated() signal.
Where does the location data come from? That depends on the QWhereabouts instance returned from QWhereaboutsFactory::create(). In this example, create() is called without any arguments, so the returned instance receives location data from the default data source. See below for details on using the default and custom data sources.
QWhereaboutsUpdate contains the various types of data that can be retrieved in a location update. At a minimum, an update includes a global coordinate position specified by a QWhereaboutsCoordinate object, and a timestamp specified by QWhereaboutsUpdate::updateDateTime() that indicates when the update was received. The update may also include other information such as altitude, ground speed and bearing. QWhereaboutsUpdate::dataValidityFlags() indicates the types of data contained in a particular update.
Coordinates are expected to be in the WGS84 datum, which is the most commonly used datum for GPS devices and is a standard datum for worldwide use. Also note that location data generally uses metric units; altitude is measured in metres and speed is measured in kilometres/hour.
The Whereabouts API uses Qt Extended's plugin mechanisms to allow location data to be retrieved from arbitrary sources, such as custom GPS hardware devices, AGPS sources, or previously logged location data. Developers can write plugins that retrieve data from their desired data source and then distribute this data through the Whereabouts API classes.
The desired location data source is specified by the argument to QWhereaboutsFactory::create(). If no argument is provided, the default data source is used. Otherwise, the argument can be set to the class name of the plugin that provides the location data.
As a convenience, the Whereabouts library has a built-in plugin, "gpsd", that retrieves data from GPSd daemons. GPSd is an open-source service daemon that connects to a specified GPS device and distributes the GPS data over a TCP port. The gpsd plugin connects to this daemon and then provides access to the data through the Whereabouts API. Naturally, the system integrator must ensure a GPSd daemon has been started on the defined GPSd port (2947) or else this plugin will not be able to receive any location data.
A default location data source can be specified through the "Plugins/Default" value in the $QPEDIR/etc/Settings/Trolltech/Whereabouts.conf settings file. For most Qt Extended device configurations, the default plugin is set to the built-in plugin, "gpsd". However, if your device has a supported Qt Extended device configuration and also has built-in GPS hardware, this default value may already be set to a plugin that can read from that hardware.
To use the default plugin, call QWhereaboutsFactory::create() without any arguments.
Whereabouts plugins can easily be added to retrieve location data from custom sources.
To add a Whereabouts plugin:
Once the plugin is installed, you can use it by calling QWhereaboutsFactory::create() with the plugin class name.
The Whereabouts Sample Plugin demonstrates the integration of a custom Whereabouts plugin. The examples/sampleplugin/locationplugin directory contains the plugin, and examples/sampleplugin/mylocationapp contains an application that uses the plugin to retrieve location updates.
First, we create a QWhereabouts subclass called LocationProvider:
class LocationProvider : public QWhereabouts
{
Q_OBJECT
public:
LocationProvider(QObject *parent = 0);
void requestUpdate();
void startUpdates();
void stopUpdates();
private:
QTimer *m_timer;
};
This LocationProvider class simply produces updates with the current date/time and latitude-longitude coordinates of (0, 0). It uses QTimer to implement timed updates for QWhereabouts::startUpdates() and QWhereabouts::stopUpdates(). Here is the implementation:
LocationProvider::LocationProvider(QObject *parent)
: QWhereabouts(QWhereabouts::TerminalBasedUpdate, parent),
m_timer(new QTimer(this))
{
connect(m_timer, SIGNAL(timeout()), SLOT(requestUpdate()));
}
void LocationProvider::requestUpdate()
{
QWhereaboutsUpdate update;
update.setCoordinate(QWhereaboutsCoordinate(0.0, 0.0));
update.setUpdateDateTime(QDateTime::currentDateTime());
emitUpdated(update);
}
void LocationProvider::startUpdates()
{
if (updateInterval() > 0)
m_timer->start(updateInterval());
else
m_timer->start(1000);
}
void LocationProvider::stopUpdates()
{
m_timer->stop();
}
Then we create a Whereaboutsplugin called LocationPlugin that is able to create and return instances of LocationProvider. Here is the class definition:
class QTOPIA_PLUGIN_EXPORT LocationPlugin : public QWhereaboutsPlugin
{
Q_OBJECT
public:
LocationPlugin(QObject *parent = 0);
QWhereabouts *create(const QString &source);
};
In the locationplugin.cpp file, we implement create() to return an instance of LocationProvider, and export the plugin using the QTOPIA_EXPORT_PLUGIN macro:
LocationPlugin::LocationPlugin(QObject *parent)
: QWhereaboutsPlugin(parent)
{
}
QWhereabouts *LocationPlugin::create(const QString &source)
{
Q_UNUSED(source);
return new LocationProvider;
}
QTOPIA_EXPORT_PLUGIN(LocationPlugin)
Then, once the plugin has been installed with qbuild image, you can use it by passing the class name to QWhereaboutsFactory::create(). (The class name argument is not case-sensitive.) So in the examples/sampleplugin/mylocationapp project, we create a MyLocationApp class that uses our custom plugin, like this:
MyLocationApp::MyLocationApp(QWidget *parent, Qt::WFlags flags)
: QMainWindow(parent, flags)
{
QWhereabouts *whereabouts = QWhereaboutsFactory::create("locationplugin");
connect(whereabouts, SIGNAL(updated(QWhereaboutsUpdate)),
SLOT(updated(QWhereaboutsUpdate)));
whereabouts->startUpdates();
}
void MyLocationApp::updated(const QWhereaboutsUpdate &update)
{
// Respond to update here
}
So MyLocationApp now receives updates through the LocationProvider we created.
To make this the default plugin to be returned if QWhereaboutsFactory::create() is called without any arguments, set the "Plugins/Default" value in $QPEDIR/etc/Settings/Trolltech/Whereabouts.conf to "locationplugin".
The Whereabouts Mapping Demo uses the Whereabouts API together with Google Maps to either track the user's current location, or provide a simulation of a previous journey using a NMEA data log.
| Copyright © 2009 Trolltech | Trademarks | Qt Extended 4.4.3 |