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