class QGeoAreaMonitorSource¶

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

Synopsis¶

Methods¶

def __init__()
def sourceName()

Virtual methods¶

def activeMonitors()
def backendProperty()
def error()
def positionInfoSource()
def requestUpdate()
def setBackendProperty()
def setPositionInfoSource()
def startMonitoring()
def stopMonitoring()
def supportedAreaMonitorFeatures()

Static functions¶

def availableSources()
def createDefaultSource()
def createSource()

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description¶

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

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

        monitor = QGeoAreaMonitorSource.createDefaultSource(self)
        if monitor:
            connect(monitor, SIGNAL(areaEntered(QGeoAreaMonitorInfo,QGeoPositionInfo)),
                    self, SLOT(areaEntered(QGeoAreaMonitorInfo,QGeoPositionInfo)))
            connect(monitor, SIGNAL(areaExited(QGeoAreaMonitorInfo,QGeoPositionInfo)),
                    self, SLOT(areaExited(QGeoAreaMonitorInfo,QGeoPositionInfo)))
            bigBen = QGeoAreaMonitorInfo("Big Ben")
            position = QGeoCoordinate(51.50104, -0.124632)
            bigBen.setArea(QGeoCircle(position, 100))
            monitor.startMonitoring(bigBen)
        else:
            print("Could not create default area monitor")


public Q_SLOTS:
    def areaEntered(mon, update):

        Q_UNUSED(mon)
        print("Now within 100 meters, current position is", update.coordinate())

    def areaExited(mon, update):

        Q_UNUSED(mon)
        print("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 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.

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.

class AreaMonitorFeature¶

(inherits enum.Flag) 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.

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.

__init__(parent)¶

Parameters:: parent – QObject

Creates a monitor source with the given parent.

abstract activeMonitors()¶

Return type:: .list of QGeoAreaMonitorInfo

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

An active monitor was started via startMonitoring() . For every active monitor 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.

abstract activeMonitors(lookupArea)

Parameters:: lookupArea – QGeoShape
Return type:: .list of QGeoAreaMonitorInfo

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.

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

See also

QGeoShape

areaEntered(monitor, update)¶

Parameters:

monitor – QGeoAreaMonitorInfo
update – QGeoPositionInfo

Emitted when the current position has moved from a position outside of the active monitor to a position within the monitored area.

The update holds the new position.

areaExited(monitor, update)¶

Parameters:

monitor – QGeoAreaMonitorInfo
update – QGeoPositionInfo

Emitted when the current position has moved from a position within the active monitor to a position outside the monitored area.

The update holds the new position.

static availableSources()¶

Return type:: list of strings

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

backendProperty(name)¶

Parameters:: name – str
Return type:: object

Returns the value of the backend-specific property named name, if present. Otherwise the returned value will be invalid.

See also

setBackendProperty()

static createDefaultSource(parent)¶

Parameters:: parent – QObject
Return type:: QGeoAreaMonitorSource

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

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

static createSource(sourceName, parent)¶

Parameters:

sourceName – str
parent – QObject

Return type:

QGeoAreaMonitorSource

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

Returns nullptr if the plugin cannot be found.

abstract error()¶

Return type:: Error

Returns the type of error that last occurred.

Note

Since Qt6 the last error is always reset when calling startMonitoring() or requestUpdate() .

errorOccurred(error)¶

Parameters:: error – Error

This signal is emitted after an error occurred. The areaMonitoringError parameter describes the type of error that occurred.

monitorExpired(monitor)¶

Parameters:: monitor – QGeoAreaMonitorInfo

Emitted when monitor has expired. An expired area monitor is automatically removed from the list of activeMonitors() .

See also

activeMonitors()

positionInfoSource()¶

Return type:: 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 nullptr 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()

abstract requestUpdate(monitor, signal)¶

Parameters:

monitor – QGeoAreaMonitorInfo
signal – str

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.

Note

Since Qt6 this method always resets the last error to NoError before starting monitoring.