Класс QSessionManager

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

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

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

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

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

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

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

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

Взаимодействие с пользователем невозможно, если приложение не получило явного разрешения от менеджера сеансов. Вы запрашиваете разрешение, вызвав 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)
{
    connect(qApp, &QGuiApplication::commitDataRequest,
            this, &MyMainWidget::commitData);
}

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

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

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

const QStringList commands = mySession.discardCommand();
for (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:

const QStringList commands = mySession.restartCommand();
for (const QString &command : commands)
    do_something(command);

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

QSessionManager::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(QSessionManager::RestartHint hint)

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

Примечание: Эти флаги — только рекомендации, менеджер сеансов может их игнорировать.

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

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