Класс QSessionManager

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

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

Типы public

Функции public

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

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

• 1 свойство, унаследованное от QObject
• 1 public слот, унаследованный от QObject
• 2 сигнала, унаследованные от QObject
• 1 public переменная, унаследованная от QObject
• 10 статических public членов, унаследованных от QObject
• 9 protected функций, унаследованных от QObject
• 2 protected переменных, унаследованных от 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().