Тип QML Settings

Предоставляет постоянные независимые от платформы настройки приложения. Подробнее...

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

Свойства

• category : строка
• fileName : строка

Методы

• setValue(ключ, var значение)
• sync()
• var value(ключ, var значениеПоУмолчанию)

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

Тип Settings предоставляет постоянные независимые от платформы настройки приложения.

Примечание: Этот тип доступен после импорта модуля Qt.labs.settings. Типы в модуле Qt.labs не гарантируют совместимость в будущих версиях.

Пользователи обычно ожидают, что приложение будет запоминать свои настройки (размеры и позиции окон, параметры и т.д.) между сеансами. Тип Settings позволяет сохранять и восстанавливать такие настройки приложения с минимальными усилиями.

Значения отдельных настроек задаются путем объявления свойств в элементе Settings. Поддерживаются все свойства базовых типов. Рекомендуется использовать псевдонимы свойств для автоматического обновления свойств в обоих направлениях. Следующий пример показывает, как использовать Settings для сохранения и восстановления геометрии окна.

import QtQuick.Window 2.1
import Qt.labs.settings 1.0

Window {
    id: window

    width: 800
    height: 600

    Settings {
        property alias x: window.x
        property alias y: window.y
        property alias width: window.width
        property alias height: window.height
    }
}

При первом запуске приложения окно получает размеры по умолчанию, указанные как 800x600. Обратите внимание, что позиция по умолчанию не указана — мы позволяем менеджеру окон обрабатывать ее. Позже, при изменении геометрии окна, новые значения будут автоматически сохранены в постоянных настройках. При повторном запуске приложения будут получены начальные значения из постоянных настроек, возвращая окно в предыдущее положение и размер.

Полностью декларативный синтаксис, достигаемый с помощью псевдонимов свойств, влечет за собой сохранение постоянных настроек всякий раз, когда изменяются значения связанных свойств. Для получения более точного контроля над сохранением постоянных настроек можно использовать обычные свойства. Следующий пример иллюстрирует сохранение настройки при уничтожении компонента.

import QtQuick 2.1
import Qt.labs.settings 1.0

Item {
    id: page

    state: settings.state

    states: [
        State {
            name: "active"
            // ...
        },
        State {
            name: "inactive"
            // ...
        }
    ]

    Settings {
        id: settings
        property string state: "active"
    }

    Component.onDestruction: {
        settings.state = page.state
    }
}

Обратите внимание, что значение по умолчанию теперь указано в свойстве постоянной настройки, а фактическое свойство связано с настройкой, чтобы получить начальное значение из постоянных настроек.

Идентификаторы приложений

Настройки, специфичные для приложения, идентифицируются путем указания имени приложения, наименования организации, домена организации или путем указания fileName.

#include <QGuiApplication>
#include <QQmlApplicationEngine>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    app.setOrganizationName("Some Company");
    app.setOrganizationDomain("somecompany.com");
    app.setApplicationName("Amazing Application");

    QQmlApplicationEngine engine("main.qml");
    return app.exec();
}

Обычно они задаются в C++ в начале main(), но также могут контролироваться в QML с помощью следующих свойств:

• Qt.application.name,
• Qt.application.organization и
• Qt.application.domain.

Категории

Настройки приложения могут быть разделены на логические категории путем указания имени категории через свойство category. Использование логических категорий не только обеспечивает более чистую структуру настроек, но и предотвращает возможные конфликты между ключами настроек.

Если требуется несколько категорий, используйте несколько объектов Settings, каждый со своей категорией:

Item {
    id: panel

    visible: true

    Settings {
        category: "OutputPanel"
        property alias visible: panel.visible
        // ...
    }

    Settings {
        category: "General"
        property alias fontSize: fontSizeSpinBox.value
        // ...
    }
}

Вместо обеспечения уникальных имен для всех настроек в приложении, настройки могут быть разделены на уникальные категории, которые затем могут содержать настройки с одинаковыми именами, используемыми в других категориях — без конфликтов.

Примечания

Текущая реализация основана на QSettings. Это накладывает определенные ограничения, такие как отсутствие уведомлений об изменениях. Запись значения настройки с помощью одного экземпляра Settings не обновляет значение в другом экземпляре Settings, даже если они ссылаются на одну и ту же настройку в одной и той же категории.

Информация хранится в системном реестре Windows и в файлах XML-предпочтений на macOS. На других системах Unix, в отсутствие стандарта, используются текстовые файлы INI. Подробнее см. в документации QSettings.

См. также QSettings.

Документация по свойствам

category : строка

Это свойство содержит имя категории настроек.

Категории могут быть использованы для группирования связанных настроек вместе.

fileName : строка

Это свойство содержит путь к файлу настроек. Если файл еще не существует, он создается.

Это свойство было добавлено в Qt 5.12.

См. также QSettings::fileName и QSettings::IniFormat.

Документация по методам

setValue(ключ, var значение)

Устанавливает значение настройки key в значение. Если ключ уже существует, предыдущее значение перезаписывается.

Этот метод был добавлен в Qt 5.12.

См. также value() и QSettings::setValue.

sync()

Записывает все несохраненные изменения в постоянное хранилище и перезагружает любые настройки, которые были изменены в это время другим приложением.

Эта функция вызывается автоматически из деструктора QSettings и циклом событий через равные промежутки времени, поэтому обычно вам не нужно вызывать ее самостоятельно.

См. также QSettings::sync.

var value(ключ, var значениеПоУмолчанию)

Возвращает значение для настройки ключ. Если настройка не существует, возвращает значениеПоУмолчанию.

Этот метод был добавлен в Qt 5.12.

См. также setValue() и QSettings::value.