Класс QSessionManager

Класс QSessionManager предоставляет доступ к менеджеру сеансов. Подробнее...

• Список всех членов, включая унаследованные

Типы публичного доступа

Функции публичного доступа

• 31 функция публичного доступа, унаследованная от QObject

Дополнительные унаследованные члены

• 1 свойство, унаследованное от QObject
• 1 публичный слот, унаследованный от QObject
• 2 сигнала, унаследованные от QObject
• 11 статические публичные члены, унаследованные от QObject
• 9 защищенные функции, унаследованные от QObject

Подробное описание

Класс 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, SIGNAL(commitDataRequest(QSessionManager)), SLOT(commitData(QSessionManager)));
}

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:

foreach (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:

foreach (const QString &command, mySession.restartCommand())
    do_something(command);

См. также setRestartCommand() и restartHint().

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(RestartHint hint)

Устанавливает совет по перезапуску приложения на hint. При запуске приложения совет установлен на RestartIfRunning.

Примечание: Эти флаги являются лишь советами, менеджер сессии может или не может их учитывать.

Рекомендуется устанавливать совет по перезапуску в QGuiApplication::saveStateRequest(), так как большинство менеджеров сессий выполняют контрольную точку вскоре после запуска приложения.

См. также restartHint().