Settings QML Type

プラットフォームに依存しない、永続的なアプリケーション設定を提供します。詳細...

• 継承されたメンバーを含む、すべてのメンバーの一覧

プロパティ

• category : string
• location : url

方法

• void setValue(string key, var value)
• void sync()
• var value(string key, var defaultValue)

詳細な説明

「Settings」型は、プラットフォームに依存しない永続的なアプリケーション設定を提供します。

通常、ユーザーはアプリケーションがセッションをまたいで設定（ウィンドウのサイズや位置、オプションなど）を記憶していることを期待します。「Settings」タイプを使用すると、最小限の手間でそのようなアプリケーション設定を保存および復元できます。

個々の設定値は、Settings 要素内でプロパティを宣言することで指定されます。QSettings で認識される値型のみがサポートされています。双方向でのプロパティの自動更新を行うには、プロパティエイリアスを使用することをお勧めします。次の例は、Settings を使用してウィンドウのジオメトリを保存および復元する方法を示しています。

import QtCore
import QtQuick

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 と指定されたデフォルトの寸法が設定されます。 デフォルトの位置は指定されていない点に注意してください。これはウィンドウマネージャに処理を任せています。その後、ウィンドウのジオメトリが変更されると、新しい値が永続設定に自動的に保存されます。アプリケーションを2回目に実行すると、永続設定から初期値が取得され、ウィンドウは以前の位置とサイズに戻ります。

プロパティエイリアスを使用することで実現される完全に宣言型の構文には、エイリアスされたプロパティの値が変更されるたびに永続設定を保存しなければならないという代償が伴います。通常のプロパティを使用することで、永続設定の保存をよりきめ細かく制御することができます。次の例は、コンポーネントの破棄時に設定を保存する方法を示しています。

import QtCore
import QtQuick

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 を指定するか、location を指定することで識別されます。

#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
        // ...
    }
}

アプリケーション内のすべての設定に一意の名前を付ける代わりに、設定を一意のカテゴリに分割することで、他のカテゴリで使用されているのと同じ名前を持つ設定を含めても、競合が発生することはありません。

設定のシングルトン

すべての QML ファイルで利用可能なシングルトンとして設定を用意することは、しばしば有用です。その例については、「To Do List」サンプルを参照してください。具体的には、AppSettings.qmlがシングルトンであり、CMakeLists.txt ファイル内では、set_source_files_properties を通じて、そのファイルの `QT_QML_SINGLETON_TYPE ` プロパティが `TRUE ` に設定されています。

注記

現在の実装はQSettings に基づいています。これにより、変更通知がないなど、特定の制限が生じます。ある Settings インスタンスを使用して設定値を書き込んでも、たとえそれらが同じカテゴリ内の同じ設定を参照している場合でも、別の Settings インスタンスの値は更新されません。

この情報は、Windows ではシステムレジストリに、macOS では XML 形式の環境設定ファイルに保存されます。その他の Unix システムでは、標準規格がないため、INI 形式のテキストファイルが使用されます。詳細については、QSettings のドキュメントを参照してください。

QSettingsも参照してください 。

プロパティのドキュメント

category : string

このプロパティには、設定カテゴリの名前が格納されます。

カテゴリを使用すると、関連する設定をまとめてグループ化することができます。

「QSettings::group」も参照してください 。

location : url

このプロパティには、設定ファイルへのパスが格納されます。ファイルがまだ存在しない場合は、作成されます。

このプロパティが空の場合（デフォルト）、QSettings::defaultFormat() が使用されます。それ以外の場合は、QSettings::IniFormat が使用されます。

QSettings::fileName 、QSettings::defaultFormat 、およびQSettings::IniFormatも参照してください 。

メソッドのドキュメント

void setValue(string key, var value)

key の設定値をvalue に設定します。キーがすでに存在する場合、以前の値は上書きされます。

value() およびQSettings::setValueも参照してください 。

void sync()

保存されていない変更を永続ストレージに書き込み、その間に他のアプリケーションによって変更された設定を再読み込みします。

この関数は、QSettings のデストラクタおよびイベントループによって定期的に自動的に呼び出されるため、通常は自分で呼び出す必要はありません。

QSettings::syncも参照してください 。

var value(string key, var defaultValue)

key の設定値を返します。設定が存在しない場合は、defaultValue を返します。

setValue() およびQSettings::valueも参照してください 。