Тип настроек 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
import Qt.labs.settings

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
import Qt.labs.settings

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 : строка

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

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

[since Qt 5.12] fileName : строка

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

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

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

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

[since Qt 5.12] setValue(строка key, var value)

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

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

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

sync()

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

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

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

[since Qt 5.12] var value(строка key, var defaultValue)

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

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

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