Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions codeless banner

QWhereabouts Class Reference
[QtLocationModule]

The QWhereabouts class is a base class for providing regular updates about one's global position, and other related information, at a particular point in time. More...

    #include <QWhereabouts>

Inherits QObject.

Inherited by QNmeaWhereabouts.

Public Types

Properties

Public Functions

Public Slots

Signals

Protected Functions

Additional Inherited Members


Detailed Description

The QWhereabouts class is a base class for providing regular updates about one's global position, and other related information, at a particular point in time.

Call QWhereaboutsFactory::create() to get a QWhereabouts object, then call startUpdates() or requestUpdate() to receive positional data through the updated() signal.

An example:

    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
        }
    };

Subclassing QWhereabouts

When startUpdates() or requestUpdate() is first called, a QWhereabouts subclass instance should change state to QWhereabouts::Initializing. If initialization succeeds, the state should change to QWhereabouts::Available, and then to QWhereabouts::PositionFixAcquired once a position fix is acquired and updates are possible. Otherwise, if initialization fails, the state should return to QWhereabouts::NotAvailable.

Note that updated() should only be emitted while the state is QWhereabouts::PositionFixAcquired, and the provided update should always have valid date & time and coordinate values. Receivers of the signal should be able to assume that the provided update is valid without additional verification.

Subclasses can call emitUpdated() to set the value of lastUpdate() and emit updated().

See also QWhereaboutsFactory, QWhereaboutsPlugin, and Location Services.


Member Type Documentation

enum QWhereabouts::State

This enum defines the possible states for a whereabouts object.

ConstantValueDescription
QWhereabouts::NotAvailable0Positional data cannot be retrieved. This is the default state.
QWhereabouts::Initializing1The object is in the initialization stage. It will change to the Available state when it is successfully initialized.
QWhereabouts::Available2The object is able to receive position data, but it is not currently able to provide position updates as there is no position fix.
QWhereabouts::PositionFixAcquired3A position fix has been acquired and position updates can now be provided.

enum QWhereabouts::UpdateMethod
flags QWhereabouts::UpdateMethods

This enum defines the methods that may be used to calculate and retrieve the information to provide a QWhereaboutsUpdate.

ConstantValueDescription
QWhereabouts::AssistedUpdate0x01Position data is calculated using assistance data from an AGPS module. (This is generally used to obtain faster and more accurate fixes.)
QWhereabouts::NetworkBasedUpdate0x02The position data is calculated by a remote server.
QWhereabouts::TerminalBasedUpdate0x04The position data is calculated by the terminal (i.e. the mobile device).

The UpdateMethods type is a typedef for QFlags<UpdateMethod>. It stores an OR combination of UpdateMethod values.


Property Documentation

updateInterval : int

This property holds this property holds the interval between each update, in milliseconds.

If setUpdateInterval() is called after startUpdates(), the interval change will not take effect until startUpdates() is called again.

The default update interval is 0. An update interval of 0 means that updated() is emitted as soon as a valid update becomes available.

Access functions:


Member Function Documentation

QWhereabouts::QWhereabouts ( UpdateMethods updateMethods = 0, QObject * parent = 0 )

Constructs a whereabouts object with the given updateMethods and parent.

QWhereabouts::~QWhereabouts ()   [virtual]

Destroys the whereabouts object.

void QWhereabouts::emitUpdated ( const QWhereaboutsUpdate & update )   [protected]

Sets the value of lastUpdate() to update and emits updated().

Note that updated() should only be emitted while the state is QWhereabouts::PositionFixAcquired, and the provided update should always have valid date/time and coordinate values. Receivers of the signal should be able to assume that the provided update is valid without additional verification.

QWhereaboutsUpdate QWhereabouts::lastUpdate () const

Returns the last update that was emitted through updated(), or an invalid update if no updates have been emitted yet.

The returned update may contain out-of-date information if updated() has not been emitted for some time. Use requestUpdate() if you require fresh positional data.

See also startUpdates() and emitUpdated().

void QWhereabouts::requestUpdate ()   [pure virtual slot]

Requests that updated() be emitted with the current whereabouts if possible. This can be called regardless of whether startUpdates() has already been called.

This is useful if you need to retrieve the current whereabouts but you do not need the periodic updates offered by startUpdates().

If the state is currently QWhereabouts::NotAvailable, the object will first be initialized and will begin to provide updates once it is in the QWhereabouts::PositionFixAcquired state.

See also startUpdates() and lastUpdate().

void QWhereabouts::setState ( State state )   [protected]

Sets the current state to state and emits stateChanged() if necessary.

See also state().

void QWhereabouts::startUpdates ()   [pure virtual slot]

Starts emitting updated() with the interval specified by updateInterval(), or less frequently if updates are not available at a particular time. If updateInterval() is 0, updated() is emitted as soon as a valid update becomes available.

If startUpdates() has already been called, this restarts with updateInterval() as the new update interval.

If the state is currently QWhereabouts::NotAvailable, the object will first be initialized and will begin to provide updates once it is in the QWhereabouts::PositionFixAcquired state.

See also stopUpdates().

void QWhereabouts::startUpdates ( int msec )   [slot]

This is an overloaded member function, provided for convenience.

Starts providing updates with an update interval of msec milliseconds.

State QWhereabouts::state () const

Returns the current state.

See also setState().

void QWhereabouts::stateChanged ( QWhereabouts::State state )   [signal]

This signal is emitted when the whereabouts object's state changes to state.

See also setState().

void QWhereabouts::stopUpdates ()   [pure virtual slot]

Stops emitting updated() at regular intervals.

See also startUpdates().

UpdateMethods QWhereabouts::updateMethods () const

Returns the methods that this whereabouts object uses to retrieve positional data.

void QWhereabouts::updated ( const QWhereaboutsUpdate & update )   [signal]

This signal is emitted to notify recipients of a newly available update.

See also startUpdates(), stopUpdates(), and requestUpdate().


Copyright © 2009 Nokia Trademarks
Qt Extended 4.4.3