Класс QGeoAreaMonitorSource

Класс QGeoAreaMonitorSource позволяет определять изменения близости к заданному набору координат. Подробнее...

Этот класс был представлен в Qt 5.2.

• Список всех членов, включая унаследованные

Открытые типы

Открытые функции

Сигналы

Статические открытые члены

Подробное описание

Класс QGeoAreaMonitorSource излучает сигналы, когда текущее положение находится в пределах или вышло за пределы заданной области. Каждая область определяется объектом QGeoAreaMonitorInfo. Например:

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 следует паттерну синглтона. Каждый экземпляр класса с одинаковым именем sourceName() использует один и тот же бэкенд мониторинга областей. Если новый объект QGeoAreaMonitorInfo добавляется через startMonitoring() или requestUpdate(), его можно получить из другого экземпляра этого класса (при условии, что они используют один и тот же провайдер мониторинга областей). То же самое относится к экземпляру QGeoPositionInfoSource, используемому этим классом. Следующий фрагмент кода подчеркивает это поведение:

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

Документация по типам членов

перечисление QGeoAreaMonitorSource::AreaMonitorFeatureфлаги QGeoAreaMonitorSource::AreaMonitorFeatures

Определяет типы возможностей мониторинга областей.

Тип AreaMonitorFeatures является псевдонимом для QFlags<AreaMonitorFeature>. Он хранит комбинацию значений AreaMonitorFeature, полученную по правилу «или».

перечисление QGeoAreaMonitorSource::Error

Определяет типы методов определения местоположения.

Перечисление Error представляет ошибки, которые могут возникнуть.

Документация по функциям-членам

QGeoAreaMonitorSource::QGeoAreaMonitorSource(QObject *parent)

Создает монитор с заданным parent.

сигнал void QGeoAreaMonitorSource::areaEntered(const QGeoAreaMonitorInfo &monitor, const QGeoPositionInfo &update)

Излучается, когда текущее положение переместилось из позиции вне активного monitor в позицию внутри отслеживаемой области.

update содержит новое положение.

сигнал void QGeoAreaMonitorSource::areaExited(const QGeoAreaMonitorInfo &monitor, const QGeoPositionInfo &update)

Излучается, когда текущее положение переместилось из позиции внутри активного monitor в позицию вне отслеживаемой области.

update содержит новое положение.

сигнал void QGeoAreaMonitorSource::error(QGeoAreaMonitorSource::Error areaMonitoringError)

Этот сигнал излучается после возникновения ошибки. Параметр areaMonitoringError описывает тип произошедшей ошибки.

Примечание: Сигнал error перегружен в этом классе. Для подключения к этому сигналу с использованием синтаксиса указателя функции Qt предоставляет удобный помощник для получения указателя функции, как показано в этом примере:

connect(geoAreaMonitorSource, QOverload<QGeoAreaMonitorSource::Error>::of(&QGeoAreaMonitorSource::error),
    [=](QGeoAreaMonitorSource::Error areaMonitoringError){ /* ... */ });

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

Вызывается, когда monitor истек. Истекший монитор области автоматически удаляется из списка activeMonitors().

См. также activeMonitors().

[virtual] 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.

[static] QStringList QGeoAreaMonitorSource::availableSources()

Возвращает список доступных плагинов мониторинга, включая системный бэкенд по умолчанию, если он доступен.

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

Создаёт и возвращает монитор с заданным parent, который отслеживает области, используя ресурсы на базовой системе.

Возвращает 0, если система не поддерживает мониторинг позиций.

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

Создаёт и возвращает монитор с заданным parent, загружая плагин с именем sourceName.

Возвращает 0, если плагин не найден.

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

Возвращает тип последней ошибки.

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

Возвращает текущий QGeoPositionInfoSource, используемый этим объектом QGeoAreaMonitorSource. Функция вернёт QGeoPositionInfoSource::createDefaultSource(), если не был задан другой объект.

Функция возвращает 0, если даже системный QGeoPositionInfoSource по умолчанию не существует.

Любое использование возвращаемого экземпляра 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 не удаётся, если бэкенд мониторинга областей не поддерживает QGeoAreaMonitorSource::PersistentAreaMonitorFeature.

Если monitor уже зарегистрирован через startMonitoring(), он преобразуется в однократное поведение.

См. также startMonitoring() и stopMonitoring().

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

Устанавливает новый QGeoPositionInfoSource для использования этим объектом QGeoAreaMonitorSource. Бэкенд мониторинга области становится новым родителем QObject для newSource. Предыдущий объект QGeoPositionInfoSource будет удалён. Все экземпляры QGeoAreaMonitorSource, основанные на том же sourceName(), используют один и тот же экземпляр QGeoPositionInfoSource.

Это может быть полезно, когда необходимо манипулировать системой позиционирования, используемой движком мониторинга областей.

Обратите внимание, что управление владением должно выполняться подклассами QGeoAreaMonitorSource. Из-за паттерна синглтон за этим классом newSource может быть перемещён в новый поток.

См. также positionInfoSource().

QString QGeoAreaMonitorSource::sourceName() const

Возвращает уникальное имя используемой реализации источника мониторинга области.

Это то же самое имя, которое можно передать в createSource() для создания нового экземпляра конкретной реализации источника мониторинга области.

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

Возвращает true если мониторинг monitor удалось успешно запустить; в противном случае возвращает false. Причина невозможности запуска мониторинга может заключаться в недоступности соответствующего источника информации о местоположении по умолчанию, если альтернативный QGeoPositionInfoSource не задан через setPositionInfoSource().

Если monitor уже активен, существующий объект монитора будет заменён новой ссылкой monitor. Идентификация экземпляров QGeoAreaMonitorInfo происходит через QGeoAreaMonitorInfo::identifier(). Поэтому эту функцию также можно использовать для обновления активных мониторов.

Если срок действия monitor истек, функция возвращает false. Вызов этой функции для уже зарегистрированного через requestUpdate() однократного монитора переключает монитор в режим постоянного мониторинга.

Запрос постоянного мониторинга на экземпляре QGeoAreaMonitorSource не удаётся, если бэкенд мониторинга областей не поддерживает QGeoAreaMonitorSource::PersistentAreaMonitorFeature.

См. также stopMonitoring().

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

Возвращает true, если monitor был успешно удален из списка activeMonitors; в противном случае возвращает false. Это поведение независимо от того, был ли monitor зарегистрирован с помощью startMonitoring() или requestUpdate().

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

Возвращает доступные функции мониторинга области для этого источника.