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

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

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

Свойства

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

Методы

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

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

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

Пользователи обычно ожидают, что приложение будет запоминать свои настройки (размеры и позиции окон, параметры и т.д.) между сессиями. Тип 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
    }
}

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

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

Настройки, специфичные для приложения, идентифицируются с помощью имени приложения name, организации и домена или путем задания 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 : строка

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

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

[с 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.