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