Класс 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

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

Для перебора списка можно использовать псевдо-ключевое слово 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().