QGeoAreaMonitorSource

The QGeoAreaMonitorSource class enables the detection of proximity changes for a specified set of coordinates. More…

Inheritance diagram of PySide2.QtPositioning.QGeoAreaMonitorSource

Synopsis

Functions

Virtual functions

Signals

Static functions

Detailed Description

A QGeoAreaMonitorSource emits signals when the current position is in range, or has moved out of range, of a specified area. Each area is specified by a QGeoAreaMonitorInfo object. For example:

public:
    MyClass() : QObject()
    {
        QGeoAreaMonitorSource *monitor = QGeoAreaMonitorSource::createDefaultSource(this);
        if (monitor) {
            connect(monitor, SIGNAL(areaEntered(QGeoAreaMonitorInfo,QGeoPositionInfo)),
                    this, SLOT(areaEntered(QGeoAreaMonitorInfo,QGeoPositionInfo)));
            connect(monitor, SIGNAL(areaExited(QGeoAreaMonitorInfo,QGeoPositionInfo)),
                    this, SLOT(areaExited(QGeoAreaMonitorInfo,QGeoPositionInfo)));

            QGeoAreaMonitorInfo bigBen("Big Ben");
            QGeoCoordinate position(51.50104, -0.124632);
            bigBen.setArea(QGeoCircle(position, 100));

            monitor->startMonitoring(bigBen);

        } else {
            qDebug() << "Could not create default area monitor";
        }
    }

public Q_SLOTS:
    void areaEntered(const QGeoAreaMonitorInfo &mon, const QGeoPositionInfo &update)
    {
        Q_UNUSED(mon);

        qDebug() << "Now within 100 meters, current position is" << update.coordinate();
    }

    void areaExited(const QGeoAreaMonitorInfo &mon, const QGeoPositionInfo &update)
    {
        Q_UNUSED(mon);

        qDebug() << "No longer within 100 meters, current position is" << update.coordinate();
    }

QGeoAreaMonitorSource follows a singleton pattern. Each instance of the class with the same sourceName() shares the same area monitoring backend. If a new QGeoAreaMonitorInfo object is added via startMonitoring() or requestUpdate() it can be retrieved by another instance of this class (provided that they are sourced from the same area monitor provider plug-in). The same singleton pattern applies to the QGeoPositionInfoSource instance used by this class. The following code snippet emphasizes the behavior:

QGeoAreaMonitorSource *s1 = QGeoAreaMonitorSource::createSource("blah", this);
QGeoAreaMonitorSource *s2 = QGeoAreaMonitorSource::createSource("blah", this);
QVERIFY(s1->positionInfoSource() == s2->positionInfoSource);
class PySide2.QtPositioning.QGeoAreaMonitorSource(parent)
param parent:

PySide2.QtCore.QObject

Creates a monitor with the given parent .

PySide2.QtPositioning.QGeoAreaMonitorSource.Error

Defines the types of positioning methods.

The Error enumeration represents the errors which can occur.

Constant

Description

QGeoAreaMonitorSource.AccessError

The connection setup to the remote area monitoring backend failed because the application lacked the required privileges.

QGeoAreaMonitorSource.InsufficientPositionInfo

The area monitoring source could not retrieve a location fix or the accuracy of the fix is not high enough to provide an effective area monitoring.

QGeoAreaMonitorSource.NoError

No error has occurred.

QGeoAreaMonitorSource.UnknownSourceError

An unidentified error occurred.
PySide2.QtPositioning.QGeoAreaMonitorSource.AreaMonitorFeature

Defines the types of area monitoring capabilities.

Constant

Description

QGeoAreaMonitorSource.PersistentAreaMonitorFeature

QGeoAreaMonitorInfo instances can be made persistent. A persistent monitor continues to be active even when the application managing the monitor is not running.

QGeoAreaMonitorSource.AnyAreaMonitorFeature

Matches all possible area monitoring features.
PySide2.QtPositioning.QGeoAreaMonitorSource.activeMonitors()
Return type:

Returns the list of all active monitors known to the QGeoAreaMonitorSource object.

An active monitor was started via startMonitoring() the source object will emit the required signals such as areaEntered() or areaExited() . Multiple QGeoAreaMonitorSource instances within the same application share the same active monitor objects.

Unless an active QGeoAreaMonitorInfo isPersistent() an active QGeoAreaMonitorInfo will be stopped once the current application terminates.

PySide2.QtPositioning.QGeoAreaMonitorSource.activeMonitors(lookupArea)
Parameters:

lookupArea – PySide2.QtPositioning.QGeoShape

Return type:

Returns the list of all active monitors known to the QGeoAreaMonitorSource object whose center lies within lookupArea . If lookupArea is empty the returned list will be empty.

An active monitor was started via startMonitoring() and the source object will emit the required signals such as areaEntered() or areaExited() . Multiple QGeoAreaMonitorSource instances within the same application share the same monitor objects.

Unless an active QGeoAreaMonitorInfo isPersistent() an active QGeoAreaMonitorInfo will be stopped once the current application terminates.

See also

QGeoShape

PySide2.QtPositioning.QGeoAreaMonitorSource.areaEntered(monitor, update)
Parameters:
PySide2.QtPositioning.QGeoAreaMonitorSource.areaExited(monitor, update)
Parameters:
static PySide2.QtPositioning.QGeoAreaMonitorSource.availableSources()
Return type:

list of strings

Returns a list of available monitor plugins, including the default system backend if one is available.

static PySide2.QtPositioning.QGeoAreaMonitorSource.createDefaultSource(parent)
Parameters:

parent – PySide2.QtCore.QObject

Return type:

PySide2.QtPositioning.QGeoAreaMonitorSource

Creates and returns a monitor with the given parent that monitors areas using resources on the underlying system.

Returns 0 if the system has no support for position monitoring.

static PySide2.QtPositioning.QGeoAreaMonitorSource.createSource(sourceName, parent)
Parameters:
Return type:

PySide2.QtPositioning.QGeoAreaMonitorSource

Creates and returns a monitor with the given parent , by loading the plugin named sourceName .

Returns 0 if the plugin cannot be found.

PySide2.QtPositioning.QGeoAreaMonitorSource.error()
Return type:

Error

Returns the type of error that last occurred.

PySide2.QtPositioning.QGeoAreaMonitorSource.error(error)
Parameters:

error – Error

PySide2.QtPositioning.QGeoAreaMonitorSource.monitorExpired(monitor)
Parameters:

monitor – PySide2.QtPositioning.QGeoAreaMonitorInfo

PySide2.QtPositioning.QGeoAreaMonitorSource.positionInfoSource()
Return type:

PySide2.QtPositioning.QGeoPositionInfoSource

Returns the current QGeoPositionInfoSource used by this QGeoAreaMonitorSource object. The function will return createDefaultSource() if no other object has been set.

The function returns 0 if not even a default QGeoPositionInfoSource exists.

Any usage of the returned QGeoPositionInfoSource instance should account for the fact that it may reside in a different thread.

See also

QGeoPositionInfoSource setPositionInfoSource()

PySide2.QtPositioning.QGeoAreaMonitorSource.requestUpdate(monitor, signal)
Parameters:
Return type:

bool

Enables single shot area monitoring. Area monitoring for monitor will be performed until this QGeoAreaMonitorSource instance emits signal for the first time. Once the signal was emitted, monitor is automatically removed from the list of activeMonitors() . If monitor is invalid or has an expiry date that has been passed this function returns false.

QGeoAreaMonitor singleShotMonitor;
QGeoAreaMonitorSource * source = QGeoAreaMonitorSource::createDefaultSource(this);
//...
bool ret = source->requestUpdate(singleShotMonitor,
                      SIGNAL(areaExited(QGeoAreaMonitor,QGeoPositionInfo)));

The above singleShotMonitor object will cease to send updates once the areaExited() signal was emitted for the first time. Until this point in time any other signal may be emitted zero or more times depending on the area context.

It is not possible to simultanously request updates for more than one signal of the same monitor object. The last call to this function determines the signal upon which the updates cease to continue. At this stage only the areaEntered() and areaExited() signals can be used to terminate the monitoring process.

Requesting persistent monitoring on a QGeoAreaMonitorSource instance fails if the area monitoring backend doesn’t support PersistentAreaMonitorFeature .

If monitor was already registered via startMonitoring() it is converted to a single shot behavior.

See also

startMonitoring() stopMonitoring()

PySide2.QtPositioning.QGeoAreaMonitorSource.setPositionInfoSource(source)
Parameters:

source – PySide2.QtPositioning.QGeoPositionInfoSource

Sets the new QGeoPositionInfoSource to be used by this QGeoAreaMonitorSource object. The area monitoring backend becomes the new QObject parent for newSource . The previous QGeoPositionInfoSource object will be deleted. All QGeoAreaMonitorSource instances based on the same sourceName() share the same QGeoPositionInfoSource instance.

This may be useful when it is desirable to manipulate the positioning system used by the area monitoring engine.

Note that ownership must be taken care of by subclasses of QGeoAreaMonitorSource . Due to the singleton pattern behind this class newSource may be moved to a new thread.

See also

positionInfoSource()

PySide2.QtPositioning.QGeoAreaMonitorSource.sourceName()
Return type:

str

Returns the unique name of the area monitor source implementation in use.

This is the same name that can be passed to createSource() in order to create a new instance of a particular area monitor source implementation.

PySide2.QtPositioning.QGeoAreaMonitorSource.startMonitoring(monitor)
Parameters:

monitor – PySide2.QtPositioning.QGeoAreaMonitorInfo

Return type:

bool

Returns true if the monitoring of monitor could be successfully started; otherwise returns false. A reason for not being able to start monitoring could be the unavailability of an appropriate default position info source while no alternative QGeoPositionInfoSource has been set via setPositionInfoSource() .

If monitor is already active the existing monitor object will be replaced by the new monitor reference. The identification of QGeoAreaMonitorInfo instances happens via identifier() . Therefore this function can also be used to update active monitors.

If monitor has an expiry date that has been passed this function returns false. Calling this function for an already via requestUpdate() registered single shot monitor switches the monitor to a permanent monitoring mode.

Requesting persistent monitoring on a QGeoAreaMonitorSource instance fails if the area monitoring backend doesn’t support PersistentAreaMonitorFeature .

See also

stopMonitoring()

PySide2.QtPositioning.QGeoAreaMonitorSource.stopMonitoring(monitor)
Parameters:

monitor – PySide2.QtPositioning.QGeoAreaMonitorInfo

Return type:

bool

Returns true if monitor was successfully removed from the list of activeMonitors() ; otherwise returns false. This behavior is independent on whether monitor was registered via startMonitoring() or requestUpdate() .

PySide2.QtPositioning.QGeoAreaMonitorSource.supportedAreaMonitorFeatures()
Return type:

AreaMonitorFeatures

Returns the area monitoring features available to this source.