QGeoAreaMonitorSource Class

成员函数文档

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

使用给定的parent 创建一个监视源。

[virtual noexcept] QGeoAreaMonitorSource::~QGeoAreaMonitorSource()

销毁监视器源。

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

返回QGeoAreaMonitorSource 对象所知的所有活动监视器的列表。

活动监视器是通过startMonitoring() 启动的。对于每个活动监视器，源对象都会发出相应的信号，例如areaEntered() 或areaExited()。同一应用程序中的多个QGeoAreaMonitorSource 实例共享相同的活动监视器对象。

除非活跃的QGeoAreaMonitorInfo 调用了isPersistent()，否则一旦当前应用程序终止，活跃的QGeoAreaMonitorInfo 将被停止。

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

返回QGeoAreaMonitorSource 对象所知的所有、中心位于lookupArea 范围内的活动监视器列表。如果lookupArea 为空，则返回的列表也为空。

活动监视器是通过startMonitoring() 启动的。对于每个活动监视器，源对象都会发出相应的信号，例如areaEntered() 或areaExited()。同一应用程序中的多个QGeoAreaMonitorSource 实例共享相同的活动监视器对象。

除非活跃的QGeoAreaMonitorInfo 调用了isPersistent()，否则活跃的QGeoAreaMonitorInfo 将在当前应用程序终止时停止运行。

另请参阅 QGeoShape 。

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

当当前位置从活动monitor 外的区域移动到被监控区域内时触发此事件。

update 保存了新位置。

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

当当前位置从活动monitor 内的位置移动到监控区域外时触发。

update 中保存了新位置。

[static] QStringList QGeoAreaMonitorSource::availableSources()

返回一个包含可用监控插件的列表，其中包括系统默认后端（如果存在的话）。

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

如果存在名为name 的后端特定属性，则返回该属性的值；否则，返回的值将无效。

该函数在 Qt 6.2 中引入。

另请参阅 setBackendProperty()。

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

创建并返回一个监视源，该监视源具有给定的parent ，用于监视底层系统中使用资源的区域。

如果系统不支持位置监控，则返回nullptr 。

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

通过加载名为sourceName 的插件，创建并返回一个具有给定parent 的监视源。

如果找不到该插件，则返回nullptr 。

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

返回上次发生的错误类型。

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

该信号在发生错误后发出。areaMonitoringError 参数描述了发生的错误类型。

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

当monitor 过期时触发。过期的区域监视器会自动从activeMonitors()列表中移除。

另请参阅 activeMonitors()。

[virtual] QGeoPositionInfoSource *QGeoAreaMonitorSource::positionInfoSource() const

返回此QGeoAreaMonitorSource 对象当前使用的QGeoPositionInfoSource 。如果未设置其他对象，该函数将返回QGeoPositionInfoSource::createDefaultSource()。

如果甚至不存在默认的QGeoPositionInfoSource ，该函数将返回nullptr 。

使用返回的QGeoPositionInfoSource 实例时，应考虑到它可能位于不同的线程中。

另请参阅 QGeoPositionInfoSource 和setPositionInfoSource()。

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

启用单次触发区域监视。针对monitor 的区域监视将持续进行，直至该QGeoAreaMonitorSource 实例首次发出signal 信号。一旦信号发出，monitor 将自动从activeMonitors()列表中移除。如果monitor 无效或其到期日期已过，该函数将返回false 。

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

上述singleShotMonitor 对象在首次发出areaExited() 信号后将停止发送更新。在此之前，其他任何信号均可根据区域上下文被发出零次或多次。

无法同时为同一个监视对象的多个信号请求更新。对该函数的最后一次调用将决定停止继续更新的信号。在此阶段，仅可使用areaEntered()和areaExited()信号来终止监视过程。

如果区域监视后端不支持 `QGeoAreaMonitorSource::PersistentAreaMonitorFeature`，则对 `QGeoAreaMonitorSource ` 实例请求持久监视将失败。

如果monitor 已经通过startMonitoring() 注册，则将其转换为单次触发行为。

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

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

将名为name 的后端特定属性设置为value 。成功时返回true ，否则返回false 。后端特定属性可用于在运行时配置区域监控子系统的行为。

该函数在 Qt 6.2 中引入。

另请参阅 backendProperty()。

[virtual] void QGeoAreaMonitorSource::setPositionInfoSource(QGeoPositionInfoSource *newSource)

设置此QGeoAreaMonitorSource 对象将使用的新QGeoPositionInfoSource 。该区域监控后端将成为newSource 的新QObject 父对象。之前的QGeoPositionInfoSource 对象将被删除。所有基于同一sourceName()的QGeoAreaMonitorSource 实例将共享同一个QGeoPositionInfoSource 实例。

当需要操作区域监控引擎所使用的定位系统时，这可能会很有用。

请注意，所有权必须由QGeoAreaMonitorSource 的子类负责管理。由于该类采用单例模式，newSource 可能会被移至新的线程中。

另请参阅 positionInfoSource()。

QString QGeoAreaMonitorSource::sourceName() const

返回当前正在使用的区域监视器源实现的唯一名称。

该名称与传递给createSource()以创建特定区域监视器源实现的新实例时所使用的名称相同。

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

如果成功启动了对monitor 的监控，则返回true ；否则返回false 。无法启动监控的原因可能是：未通过setPositionInfoSource() 设置备用QGeoPositionInfoSource ，且没有可用的默认位置信息源。

如果monitor 已处于活动状态，现有的监控对象将被新的monitor 引用所替换。QGeoAreaMonitorInfo 实例的识别是通过QGeoAreaMonitorInfo::identifier()实现的。因此，该函数也可用于更新已活动的监控。

如果monitor 的过期日期已过，该函数将返回 false。对于已通过requestUpdate() 注册的单次监控，调用此函数将使监控切换为永久监控模式。

如果区域监控后端不支持QGeoAreaMonitorSource::PersistentAreaMonitorFeature ，则对QGeoAreaMonitorSource 实例请求持久监控将失败。

另请参阅 stopMonitoring()。

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

如果已成功将monitor 从activeMonitors()列表中移除，则返回true；否则返回false。此行为与monitor 是通过startMonitoring()还是requestUpdate()注册的无关。

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

返回该源可用的区域监控功能。