Тип QML Settings

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

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

Свойства

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

Методы

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

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

Тип 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(ключ, значение значение)

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

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

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

sync()

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

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

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

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

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

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

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