En esta página

QGeoAreaMonitorSource Class

La clase `QGeoAreaMonitorSource` permite detectar cambios en la proximidad respecto a un conjunto determinado de coordenadas. Más información...

Encabezado: #include <QGeoAreaMonitorSource>
CMake: find_package(Qt6 REQUIRED COMPONENTS Positioning)
target_link_libraries(mytarget PRIVATE Qt6::Positioning)
qmake: QT += positioning
Heredado de: QObject

Tipos públicos

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

Funciones públicas

QGeoAreaMonitorSource(QObject *parent)
virtual ~QGeoAreaMonitorSource()
virtual QList<QGeoAreaMonitorInfo> activeMonitors() const = 0
virtual QList<QGeoAreaMonitorInfo> activeMonitors(const QGeoShape &lookupArea) const = 0
(since 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
(since 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

Señales

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)

Miembros públicos estáticos

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

Descripción detallada

Un QGeoAreaMonitorSource emite señales cuando la posición actual se encuentra dentro del rango de un área especificada o cuando se ha salido de dicho rango. Cada área se especifica mediante un objeto ` QGeoAreaMonitorInfo `. Por ejemplo:

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 sigue el patrón singleton. Cada instancia de la clase con el mismo sourceName() comparte el mismo backend de monitorización de área. Si se añade un nuevo objeto QGeoAreaMonitorInfo mediante startMonitoring() o requestUpdate(), otra instancia de esta clase podrá recuperarlo (siempre que provengan del mismo complemento de proveedor de monitorización de área). El mismo patrón singleton se aplica a la instancia de ` QGeoPositionInfoSource ` utilizada por esta clase. El siguiente fragmento de código ilustra este comportamiento:

QGeoAreaMonitorSource *s1 = QGeoAreaMonitorSource::createSource("blah", this);
QGeoAreaMonitorSource *s2 = QGeoAreaMonitorSource::createSource("blah", this);
QVERIFY(s1->positionInfoSource() == s2->positionInfoSource);

Documentación sobre los tipos de miembros

enum QGeoAreaMonitorSource::AreaMonitorFeature
flags QGeoAreaMonitorSource::AreaMonitorFeatures

Define los tipos de capacidades de vigilancia de zonas.

ConstanteValorDescripción
QGeoAreaMonitorSource::PersistentAreaMonitorFeature0x00000001QGeoAreaMonitorInfo Las instancias pueden hacerse persistentes. Un monitor persistente sigue activo incluso cuando la aplicación que lo gestiona no se está ejecutando.
QGeoAreaMonitorSource::AnyAreaMonitorFeature0xffffffffSe ajusta a todas las características posibles de supervisión de área.

El tipo AreaMonitorFeatures es una definición de tipo (typedef) para QFlags<AreaMonitorFeature>. Almacena una combinación OR de valores de AreaMonitorFeature.

enum QGeoAreaMonitorSource::Error

Define los tipos de métodos de posicionamiento.

La enumeración Error representa los errores que pueden producirse.

ConstanteValorDescripción
QGeoAreaMonitorSource::AccessError0El establecimiento de la conexión con el servidor de monitorización de área remota ha fallado porque la aplicación carecía de los privilegios necesarios.
QGeoAreaMonitorSource::InsufficientPositionInfo1La fuente de monitorización de área no ha podido obtener una posición o la precisión de la misma no es lo suficientemente alta como para proporcionar una monitorización de área eficaz.
QGeoAreaMonitorSource::NoError3No se ha producido ningún error.
QGeoAreaMonitorSource::UnknownSourceError2Se ha producido un error no identificado.

Documentación de la función miembro

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

Crea una fuente de monitorización con el parent indicado.

[virtual noexcept] QGeoAreaMonitorSource::~QGeoAreaMonitorSource()

Elimina la fuente del monitor.

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

Devuelve la lista de todos los monitores activos conocidos por el objeto QGeoAreaMonitorSource.

Un monitor activo se ha iniciado mediante startMonitoring(). Para cada monitor activo, el objeto fuente emitirá las señales necesarias, como areaEntered() o areaExited(). Varias instancias de QGeoAreaMonitorSource dentro de la misma aplicación comparten los mismos objetos de monitor activo.

A menos que un QGeoAreaMonitorInfo isPersistent () esté activo, un QGeoAreaMonitorInfo activo se detendrá una vez que la aplicación actual finalice.

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

Devuelve la lista de todos los monitores activos conocidos por el objeto ` QGeoAreaMonitorSource ` cuyo centro se encuentre dentro de ` lookupArea`. Si ` lookupArea ` está vacío, la lista devuelta estará vacía.

Un monitor activo se inicia mediante startMonitoring(). Por cada monitor activo, el objeto de origen emitirá las señales necesarias, como areaEntered() o areaExited(). Varias instancias de QGeoAreaMonitorSource dentro de la misma aplicación comparten los mismos objetos de monitor activo.

A menos que un QGeoAreaMonitorInfo isPersistent () esté activo, un QGeoAreaMonitorInfo se detendrá una vez que la aplicación actual finalice.

Véase también QGeoShape.

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

Se emite cuando la posición actual ha pasado de encontrarse fuera del « monitor » activo a situarse dentro del área supervisada.

El « update » registra la nueva posición.

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

Se emite cuando la posición actual ha pasado de encontrarse dentro del área de vigilancia ( monitor ) a situarse fuera de ella.

El « update » registra la nueva posición.

[static] QStringList QGeoAreaMonitorSource::availableSources()

Devuelve una lista de complementos de monitorización disponibles, incluido el backend predeterminado del sistema, si hay alguno disponible.

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

Devuelve el valor de la propiedad específica del backend denominada « name », si existe. De lo contrario, el valor devuelto no será válido.

Esta función se introdujo en Qt 6.2.

Véase también setBackendProperty().

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

Crea y devuelve una fuente de monitorización con el parent especificado, que supervisa las áreas que utilizan recursos en el sistema subyacente.

Devuelve « nullptr » si el sistema no admite la supervisión de posiciones.

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

Crea y devuelve una fuente de monitorización con el parent especificado, cargando el complemento denominado sourceName.

Devuelve ` nullptr ` si no se encuentra el complemento.

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

Devuelve el tipo de error que se ha producido por última vez.

Nota: A partir de Qt6, el último error siempre se restablece al llamar a ` startMonitoring()` o ` requestUpdate()`.

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

Esta señal se emite cuando se produce un error. El parámetro « areaMonitoringError » describe el tipo de error que se ha producido.

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

Se emite cuando ha caducado un monitor de área ( monitor ). Un monitor de área caducado se elimina automáticamente de la lista de monitores de área ( activeMonitors()).

Véase también activeMonitors().

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

Devuelve el QGeoPositionInfoSource actual utilizado por este objeto QGeoAreaMonitorSource. La función devolverá QGeoPositionInfoSource::createDefaultSource() si no se ha establecido ningún otro objeto.

La función devuelve nullptr si ni siquiera existe un QGeoPositionInfoSource predeterminado.

Cualquier uso de la instancia de ` QGeoPositionInfoSource ` devuelta debe tener en cuenta que puede residir en un hilo diferente.

Véase también QGeoPositionInfoSource y setPositionInfoSource().

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

Permite la monitorización de área de un solo disparo. La monitorización de área para monitor se llevará a cabo hasta que esta instancia de QGeoAreaMonitorSource emita signal por primera vez. Una vez emitida la señal, monitor se elimina automáticamente de la lista de activeMonitors(). Si monitor no es válido o su fecha de caducidad ha vencido, esta función devuelve false.

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

El objeto singleShotMonitor mencionado anteriormente dejará de enviar actualizaciones una vez que se haya emitido por primera vez la señal areaExited(). Hasta ese momento, cualquier otra señal podrá emitirse cero o más veces, dependiendo del contexto de área.

No es posible solicitar simultáneamente actualizaciones para más de una señal del mismo objeto de monitorización. La última llamada a esta función determina la señal tras la cual cesan las actualizaciones. En esta fase, solo se pueden utilizar las señales « areaEntered()» y « areaExited()» para dar por terminado el proceso de monitorización.

La solicitud de monitorización persistente en una instancia de QGeoAreaMonitorSource falla si el backend de monitorización del área no admite QGeoAreaMonitorSource::PersistentAreaMonitorFeature.

Si monitor ya se había registrado mediante startMonitoring(), se convierte en un comportamiento de un solo disparo.

Nota: A partir de Qt6, este método siempre restablece el último error a NoError antes de iniciar la supervisión.

Véase también startMonitoring() y stopMonitoring().

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

Establece la propiedad específica del backend denominada « name » en « value ». Devuelve « true » si la operación se realiza correctamente; en caso contrario, devuelve « false ». Las propiedades específicas del backend pueden utilizarse para configurar el comportamiento del subsistema de supervisión de áreas en tiempo de ejecución.

Esta función se introdujo en Qt 6.2.

Véase también backendProperty().

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

Establece el nuevo QGeoPositionInfoSource que utilizará este objeto QGeoAreaMonitorSource. El backend de monitorización de área se convierte en el nuevo QObject padre de newSource. El objeto QGeoPositionInfoSource anterior se eliminará. Todas las instancias de QGeoAreaMonitorSource basadas en el mismo sourceName() comparten la misma instancia de QGeoPositionInfoSource.

Esto puede resultar útil cuando se desee manipular el sistema de posicionamiento utilizado por el motor de monitorización de áreas.

Ten en cuenta que las subclases de QGeoAreaMonitorSource deben encargarse de la propiedad. Debido al patrón singleton que subyace a esta clase, newSource puede trasladarse a un nuevo hilo.

Véase también ` positionInfoSource()`.

QString QGeoAreaMonitorSource::sourceName() const

Devuelve el nombre único de la implementación de la fuente del monitor de área que se está utilizando.

Se trata del mismo nombre que se puede pasar a la función createSource() para crear una nueva instancia de una implementación concreta de la fuente del monitor de área.

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

Devuelve « true » si se ha podido iniciar correctamente la supervisión de « monitor »; en caso contrario, devuelve « false ». Una de las razones por las que no se haya podido iniciar la supervisión podría ser la falta de disponibilidad de una fuente de información de posición predeterminada adecuada, sin que se haya configurado una alternativa « QGeoPositionInfoSource » mediante « setPositionInfoSource()».

Si monitor ya está activo, el objeto de monitorización existente se sustituirá por la nueva referencia monitor. La identificación de las instancias de QGeoAreaMonitorInfo se realiza mediante QGeoAreaMonitorInfo::identifier(). Por lo tanto, esta función también puede utilizarse para actualizar monitores activos.

Si monitor tiene una fecha de caducidad que ya ha vencido, esta función devuelve «false». Al llamar a esta función para un monitor de un solo uso ya registrado mediante requestUpdate(), el monitor pasa a un modo de supervisión permanente.

La solicitud de monitorización persistente en una instancia de QGeoAreaMonitorSource falla si el backend de monitorización de áreas no es compatible con QGeoAreaMonitorSource::PersistentAreaMonitorFeature.

Nota: A partir de Qt6, este método siempre restablece el último error a ` NoError ` antes de iniciar la supervisión.

Véase también ` stopMonitoring()`.

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

Devuelve «true» si se ha eliminado correctamente « monitor » de la lista de « activeMonitors()»; en caso contrario, devuelve «false». Este comportamiento es independiente de si « monitor » se registró mediante « startMonitoring()» o « requestUpdate()».

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

Devuelve las funciones de supervisión de áreas disponibles para esta fuente.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.