Класс QSessionManager

Класс 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, &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().