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