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

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

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

Свойства

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

Методы

• setValue(строка key, var value)
• sync()
• 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
    }
}

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

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

Прикладные настройки идентифицируются путём предоставления имени приложения name, организации organization и домена domain или путём указания 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.

sync()

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

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

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

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

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

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

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