Класс QSessionManager

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

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

Типы public

Функции public

• 31 функция public, унаследованная от QObject

Статические члены public

• 9 статических public членов, унаследованных от QObject

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

• 1 свойство, унаследованное от QObject
• 1 public слот, унаследованный от QObject
• 2 сигнала, унаследованные от 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().

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().