QGeoAreaMonitorSource Class

The QGeoAreaMonitorSource class enables the detection of proximity changes for a specified set of coordinates. 更多...

头：	#include <QGeoAreaMonitorSource>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Positioning) target_link_libraries(mytarget PRIVATE Qt6::Positioning)
qmake:	QT += positioning
继承：	QObject

所有成员列表，包括继承成员

公共类型

enum	AreaMonitorFeature { PersistentAreaMonitorFeature, AnyAreaMonitorFeature }
flags	AreaMonitorFeatures
enum	Error { AccessError, InsufficientPositionInfo, NoError, UnknownSourceError }

公共函数

	QGeoAreaMonitorSource (QObject * parent )
virtual	~QGeoAreaMonitorSource ()
virtual QList<QGeoAreaMonitorInfo>	activeMonitors () const = 0
virtual QList<QGeoAreaMonitorInfo>	activeMonitors (const QGeoShape & lookupArea ) const = 0
`(从 6.2 起)` virtual QVariant	backendProperty (const QString & name ) const
virtual QGeoAreaMonitorSource::Error	error () const = 0
virtual QGeoPositionInfoSource *	positionInfoSource () const
virtual bool	requestUpdate (const QGeoAreaMonitorInfo & monitor , const char * signal ) = 0
`(从 6.2 起)` virtual bool	setBackendProperty (const QString & name , const QVariant & value )
virtual void	setPositionInfoSource (QGeoPositionInfoSource * newSource )
QString	sourceName () const
virtual bool	startMonitoring (const QGeoAreaMonitorInfo & monitor ) = 0
virtual bool	stopMonitoring (const QGeoAreaMonitorInfo & monitor ) = 0
virtual QGeoAreaMonitorSource::AreaMonitorFeatures	supportedAreaMonitorFeatures () const = 0

信号

void	areaEntered (const QGeoAreaMonitorInfo & monitor , const QGeoPositionInfo & update )
void	areaExited (const QGeoAreaMonitorInfo & monitor , const QGeoPositionInfo & update )
void	errorOccurred (QGeoAreaMonitorSource::Error areaMonitoringError )
void	monitorExpired (const QGeoAreaMonitorInfo & monitor )

静态公共成员

QStringList	availableSources ()
QGeoAreaMonitorSource *	createDefaultSource (QObject * parent )
QGeoAreaMonitorSource *	createSource (const QString & sourceName , QObject * parent )

详细描述

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

成员类型文档编制

enum QGeoAreaMonitorSource:: AreaMonitorFeature
flags QGeoAreaMonitorSource:: AreaMonitorFeatures

Defines the types of area monitoring capabilities.

常量	值	描述
`QGeoAreaMonitorSource::PersistentAreaMonitorFeature`	`0x00000001`	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`	`0xffffffff`	Matches all possible area monitoring features.

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

enum QGeoAreaMonitorSource:: Error

Defines the types of positioning methods.

The Error enumeration represents the errors which can occur.

常量	值	描述
`QGeoAreaMonitorSource::AccessError`	`0`	The connection setup to the remote area monitoring backend failed because the application lacked the required privileges.
`QGeoAreaMonitorSource::InsufficientPositionInfo`	`1`	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`	`3`	没有出现错误。
`QGeoAreaMonitorSource::UnknownSourceError`	`2`	发生无法识别的错误。

成员函数文档编制

`[explicit]` QGeoAreaMonitorSource:: QGeoAreaMonitorSource ( QObject * parent )

Creates a monitor source with the given parent .

`[virtual noexcept]` QGeoAreaMonitorSource:: ~QGeoAreaMonitorSource ()

Destroys the monitor source.

`[pure virtual]` QList < QGeoAreaMonitorInfo > QGeoAreaMonitorSource:: activeMonitors () const

Returns the list of all active monitors known to the QGeoAreaMonitorSource 对象。

An active monitor was started via startMonitoring (). For every active monitor the source object will emit the required signals, such as areaEntered () 或 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.

`[pure virtual]` QList < QGeoAreaMonitorInfo > QGeoAreaMonitorSource:: activeMonitors (const QGeoShape & lookupArea ) const

Returns the list of all active monitors known to the QGeoAreaMonitorSource object whose center lies within lookupArea 。若 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.

另请参阅 QGeoShape .

`[signal]` void QGeoAreaMonitorSource:: areaEntered (const QGeoAreaMonitorInfo & monitor , const QGeoPositionInfo & update )

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.

`[signal]` void QGeoAreaMonitorSource:: areaExited (const QGeoAreaMonitorInfo & monitor , const QGeoPositionInfo & update )

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]` QStringList QGeoAreaMonitorSource:: availableSources ()

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

`[virtual, since 6.2]` QVariant QGeoAreaMonitorSource:: backendProperty (const QString & name ) const

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

该函数在 Qt 6.2 引入。

另请参阅 setBackendProperty ().

`[static]` QGeoAreaMonitorSource QGeoAreaMonitorSource:: createDefaultSource ( QObject parent )

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

返回 nullptr if the system has no support for position monitoring.

`[static]` QGeoAreaMonitorSource QGeoAreaMonitorSource:: createSource (const QString & sourceName* , QObject * parent )

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

返回 nullptr if the plugin cannot be found.

`[pure virtual]` QGeoAreaMonitorSource::Error QGeoAreaMonitorSource:: error () const

返回最后发生的错误类型。

注意： Since Qt6 the last error is always reset when calling startMonitoring () 或 requestUpdate ().

`[signal]` void QGeoAreaMonitorSource:: errorOccurred ( QGeoAreaMonitorSource::Error areaMonitoringError )

此信号发射，在发生错误后。 areaMonitoringError 参数描述出现错误的类型。

`[signal]` void QGeoAreaMonitorSource:: monitorExpired (const QGeoAreaMonitorInfo & monitor )

发射当 monitor has expired. An expired area monitor is automatically removed from the list of activeMonitors ().

另请参阅 activeMonitors ().

`[虚拟]` QGeoPositionInfoSource *QGeoAreaMonitorSource:: positionInfoSource () const

返回当前 QGeoPositionInfoSource used by this QGeoAreaMonitorSource object. The function will return QGeoPositionInfoSource::createDefaultSource () if no other object has been set.

函数返回 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.

另请参阅 QGeoPositionInfoSource and setPositionInfoSource ().

`[pure virtual]` bool QGeoAreaMonitorSource:: requestUpdate (const QGeoAreaMonitorInfo & monitor , const char * signal )

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 ()。若 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 () 和 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 QGeoAreaMonitorSource::PersistentAreaMonitorFeature .

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

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

另请参阅 startMonitoring () 和 stopMonitoring ().

`[virtual, since 6.2]` bool QGeoAreaMonitorSource:: setBackendProperty (const QString & name , const QVariant & value )

Sets the backend-specific property named name to value 。返回 true on success, otherwise returns false . Backend-specific properties can be used to configure the area monitoring subsystem behavior at runtime.

该函数在 Qt 6.2 引入。

另请参阅 backendProperty ().

`[虚拟]` void QGeoAreaMonitorSource:: setPositionInfoSource ( QGeoPositionInfoSource * newSource )

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 实例。

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.

另请参阅 positionInfoSource ().

QString QGeoAreaMonitorSource:: sourceName () const

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.

`[pure virtual]` bool QGeoAreaMonitorSource:: startMonitoring (const QGeoAreaMonitorInfo & monitor )

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

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

若 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 QGeoAreaMonitorSource::PersistentAreaMonitorFeature .

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

另请参阅 stopMonitoring ().

`[pure virtual]` bool QGeoAreaMonitorSource:: stopMonitoring (const QGeoAreaMonitorInfo & monitor )

返回 true 若 monitor was successfully removed from the list of activeMonitors (); otherwise returns false. This behavior is independent on whether monitor was registered via startMonitoring () 或 requestUpdate ().

`[pure virtual]` QGeoAreaMonitorSource::AreaMonitorFeatures QGeoAreaMonitorSource:: supportedAreaMonitorFeatures () const

Returns the area monitoring features available to this source.

QGeoAreaMonitorSource Class

公共类型

公共函数

信号

静态公共成员

详细描述

成员类型文档编制

enum QGeoAreaMonitorSource:: AreaMonitorFeature flags QGeoAreaMonitorSource:: AreaMonitorFeatures

enum QGeoAreaMonitorSource:: Error

成员函数文档编制

[explicit] QGeoAreaMonitorSource:: QGeoAreaMonitorSource ( QObject * parent )

[virtual noexcept] QGeoAreaMonitorSource:: ~QGeoAreaMonitorSource ()

[pure virtual] QList < QGeoAreaMonitorInfo > QGeoAreaMonitorSource:: activeMonitors () const

[pure virtual] QList < QGeoAreaMonitorInfo > QGeoAreaMonitorSource:: activeMonitors (const QGeoShape & lookupArea ) const

[signal] void QGeoAreaMonitorSource:: areaEntered (const QGeoAreaMonitorInfo & monitor , const QGeoPositionInfo & update )

[signal] void QGeoAreaMonitorSource:: areaExited (const QGeoAreaMonitorInfo & monitor , const QGeoPositionInfo & update )

[static] QStringList QGeoAreaMonitorSource:: availableSources ()

[virtual, since 6.2] QVariant QGeoAreaMonitorSource:: backendProperty (const QString & name ) const

[static] QGeoAreaMonitorSource *QGeoAreaMonitorSource:: createDefaultSource ( QObject * parent )

[static] QGeoAreaMonitorSource *QGeoAreaMonitorSource:: createSource (const QString & sourceName , QObject * parent )

[pure virtual] QGeoAreaMonitorSource::Error QGeoAreaMonitorSource:: error () const

[signal] void QGeoAreaMonitorSource:: errorOccurred ( QGeoAreaMonitorSource::Error areaMonitoringError )

[signal] void QGeoAreaMonitorSource:: monitorExpired (const QGeoAreaMonitorInfo & monitor )

[虚拟] QGeoPositionInfoSource *QGeoAreaMonitorSource:: positionInfoSource () const

[pure virtual] bool QGeoAreaMonitorSource:: requestUpdate (const QGeoAreaMonitorInfo & monitor , const char * signal )

[virtual, since 6.2] bool QGeoAreaMonitorSource:: setBackendProperty (const QString & name , const QVariant & value )

[虚拟] void QGeoAreaMonitorSource:: setPositionInfoSource ( QGeoPositionInfoSource * newSource )