Тип настроек QML

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

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

Свойства

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

Методы

• setValue(строка key, var value)
• var value(строка key, var defaultValue)

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

Тип 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(строка key, var value)

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

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

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

var value(строка key, var defaultValue)

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

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

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