QWhereabouts Class Reference
[QtLocationModule]

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.

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.

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:

• int updateInterval () const
• void setUpdateInterval ( int interval )

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().