Класс QSessionManager

Класс QSessionManager предоставляет доступ к менеджеру сеансов. Подробнее...

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

Типы публичного доступа

Функции публичного доступа

• 32 функции публичного доступа, унаследованные от QObject

Дополнительные унаследованные члены

• 1 свойство, унаследованное от QObject
• 1 публичный слот, унаследованный от QObject
• 2 сигнала, унаследованные от QObject
• 11 статические члены публичного доступа, унаследованные от QObject
• 9 защищенных функций, унаследованные от QObject

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

Класс QSessionManager предоставляет доступ к менеджеру сеансов.

Менеджер сеансов в настольной среде (в которой работают приложения Qt GUI) отслеживает сеанс, который представляет собой группу запущенных приложений, каждое из которых имеет определённое состояние. Состояние приложения содержит (в первую очередь) открытые документы, положение и размер окон.

Менеджер сеансов используется для сохранения сеанса, например, при выключении компьютера, и для восстановления сеанса, например, при включении компьютера. Рекомендуется использовать QSettings для сохранения настроек приложения, таких как расположение окон, недавно использованные файлы и т. д. При перезапуске приложения менеджером сеансов вы можете восстановить настройки.

QSessionManager предоставляет интерфейс между приложением и менеджером сеансов платформы. В Qt запросы к менеджеру сеансов обрабатываются двумя сигналами QGuiApplication::commitDataRequest() и QGuiApplication::saveStateRequest(). Оба принимают в качестве аргумента объект QSessionManager. К менеджеру сеансов можно получить доступ только в слотах, вызываемых этими сигналами.

Предупреждение: Если вы используете QSessionManager, вам следует отключить резервный менеджмент сеансов: QGuiApplication::setFallbackSessionManagementEnabled().

Взаимодействие с пользователем возможно только в том случае, если приложение получило явное разрешение от менеджера сеансов. Вы запрашиваете разрешение, вызывая allowsInteraction() или, если это действительно срочно, allowsErrorInteraction(). Qt это не контролирует, но менеджер сеансов может.

Вы можете попытаться прервать процесс завершения работы, вызвав cancel().

Для сложных менеджеров сеансов, предоставляемых на Unix/X11, QSessionManager предлагает дополнительные возможности для настройки поведения управления сеансами приложения: setRestartCommand(), setDiscardCommand(), setRestartHint(), setProperty(), requestPhase2(). Подробные сведения см. в описаниях соответствующих функций.

См. также QGuiApplication и Управление сеансами.

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

перечисление QSessionManager::RestartHint

Это перечисление определяет обстоятельства, при которых это приложение хочет быть перезапущено менеджером сеансов. Текущие значения:

Значение по умолчанию - RestartIfRunning.

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

bool QSessionManager::allowsErrorInteraction()

Возвращает true если взаимодействие при ошибках разрешено; в противном случае возвращает false.

Это аналогично allowsInteraction(), но также позволяет приложению сообщать пользователю об ошибках, которые произошли. Менеджеры сеансов могут отдавать приоритет запросам взаимодействия при ошибках, что означает, что разрешение на взаимодействие при ошибке будет предоставлено более вероятно. Тем не менее, вам по-прежнему не гарантируется, что менеджер сеансов позволит взаимодействие.

См. также allowsInteraction(), release() и cancel().

bool QSessionManager::allowsInteraction()

Запрашивает разрешение у менеджера сеансов на взаимодействие с пользователем. Возвращает true, если взаимодействие разрешено; в противном случае возвращает false.

Причина этого механизма заключается в том, чтобы сделать возможным синхронизировать взаимодействие пользователя во время завершения работы. Расширенные менеджеры сеансов могут попросить все приложения одновременно передать свои данные, что приведет к гораздо более быстрому завершению работы.

После завершения взаимодействия настоятельно рекомендуется освободить семафор взаимодействия с пользователем с помощью вызова release(). Таким образом, другие приложения могут получить возможность взаимодействовать с пользователем, пока ваше приложение все еще занято сохранением данных. (Семафор неявно освобождается при выходе из приложения.)

Если пользователь решит отменить процесс завершения работы во время фазы взаимодействия, вы должны сообщить менеджеру сеансов, что это произошло, вызвав cancel().

Вот пример того, как может быть реализован QGuiApplication::commitDataRequest() приложения:

MyMainWidget::MyMainWidget(QWidget *parent)
    :QWidget(parent)
{
    QGuiApplication::setFallbackSessionManagementEnabled(false);
    connect(qApp, SIGNAL(commitDataRequest(QSessionManager)), SLOT(commitData(QSessionManager)));
}

void MyMainWidget::commitData(QSessionManager& manager)
{
    if (manager.allowsInteraction()) {
        int ret = QMessageBox::warning(
                    mainWindow,
                    tr("My Application"),
                    tr("Save changes to document?"),
                    QMessageBox::Save | QMessageBox::Discard | QMessageBox::Cancel);

        switch (ret) {
        case QMessageBox::Save:
            manager.release();
            if (!saveDocument())
                manager.cancel();
            break;
        case QMessageBox::Discard:
            break;
        case QMessageBox::Cancel:
        default:
            manager.cancel();
        }
    } else {
        // we did not get permission to interact, then
        // do something reasonable instead
    }
}

Если при сохранении данных приложения произошла ошибка, вы можете попробовать allowsErrorInteraction() вместо этого.

См. также QGuiApplication::commitDataRequest(), release() и cancel().

void QSessionManager::cancel()

Сообщает менеджеру сессии о необходимости отмены процесса завершения. Приложения не должны вызывать эту функцию без предварительного запроса у пользователя.

См. также allowsInteraction() и allowsErrorInteraction().

QStringList QSessionManager::discardCommand() const

Возвращает текущую команду отбрасывания.

Для перебора списка можно использовать псевдоключевое слово foreach:

foreach (const QString &command, mySession.discardCommand())
    do_something(command);

См. также setDiscardCommand(), restartCommand() и setRestartCommand().

bool QSessionManager::isPhase2() const

Возвращает true, если менеджер сессии в данный момент выполняет вторую фазу управления сессией; в противном случае возвращает false.

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

void QSessionManager::release()

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

См. также allowsInteraction() и allowsErrorInteraction().

void QSessionManager::requestPhase2()

Запрашивает вторую фазу управления сессией для приложения. После этого приложение может немедленно вернуться из функции QGuiApplication::commitDataRequest() или QApplication::saveStateRequest(), и они будут вызваны снова, когда большинство или все другие приложения завершат свои задачи управления сессией.

Две фазы полезны для приложений, таких как менеджер окон X11, которым необходимо хранить информацию о окнах другого приложения, и поэтому необходимо ждать, пока эти приложения завершат свои задачи управления сессией.

Примечание: Если другое приложение запросило вторую фазу, оно может быть вызвано до, одновременно с или после второй фазы вашего приложения.

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

QStringList QSessionManager::restartCommand() const

Возвращает текущую команду перезапуска.

Для перебора списка можно использовать псевдоключевое слово foreach:

foreach (const QString &command, mySession.restartCommand())
    do_something(command);

См. также setRestartCommand() и restartHint().

RestartHint QSessionManager::restartHint() const

Возвращает текущий совет по перезапуску приложения. По умолчанию RestartIfRunning.

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

QString QSessionManager::sessionId() const

Возвращает идентификатор текущей сессии.

Если приложение было восстановлено из предыдущей сессии, этот идентификатор совпадает с идентификатором предыдущей сессии.

См. также sessionKey() и QGuiApplication::sessionId().

QString QSessionManager::sessionKey() const

Возвращает ключ сессии в текущей сессии.

Если приложение было восстановлено из предыдущей сессии, этот ключ совпадает с ключом, существовавшим в конце предыдущей сессии.

Ключ сессии изменяется при каждом вызове commitData() или saveState().

См. также sessionId() и QGuiApplication::sessionKey().

void QSessionManager::setDiscardCommand(const QStringList &command)

Устанавливает команду отбрасывания на заданную command.

См. также discardCommand() и setRestartCommand().

void QSessionManager::setManagerProperty(const QString &name, const QStringList &value)

Уровень низкоуровневого доступа для сохранения идентификации и состояния приложения в менеджере сессии.

Значение свойства с именем name устанавливается в список строк value.

void QSessionManager::setManagerProperty(const QString &name, const QString &value)

Это перегруженная функция.

Низкоуровневый доступ для записи идентификации и данных состояния приложения сохраняются в менеджере сессии.

Значение свойства с именем name устанавливается в строку value.

void QSessionManager::setRestartCommand(const QStringList &command)

Если менеджер сессии способен восстанавливать сессии, он выполнит command для восстановления приложения. Команда по умолчанию

appname -session id

Опция -session обязательна; в противном случае QGuiApplication не сможет определить, было ли приложение восстановлено или какой идентификатор сессии используется в данный момент. Подробности см. в QGuiApplication::isSessionRestored() и QGuiApplication::sessionId().

Если ваше приложение очень простое, возможно, можно хранить все состояние приложения в дополнительных параметрах командной строки. Обычно это очень плохая идея, так как командные строки часто ограничены несколькими сотнями байт. Вместо этого используйте QSettings, временные файлы или базу данных для этой цели. Пометив данные уникальным идентификатором sessionId(), вы сможете восстановить приложение в будущей сессии.

См. также restartCommand(), setDiscardCommand() и setRestartHint().

void QSessionManager::setRestartHint(RestartHint hint)

Устанавливает совет по перезапуску приложения на hint. При запуске приложения совет установлен на RestartIfRunning.

Примечание: Эти флаги являются лишь советами, менеджер сессии может или не может их учитывать.

Рекомендуется устанавливать совет по перезапуску в QGuiApplication::saveStateRequest(), так как большинство менеджеров сессий выполняют контрольную точку вскоре после запуска приложения.

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