QSettings Class

メンバ関数のドキュメント

[explicit] QSettings::QSettings(QObject *parent = nullptr)

QCoreApplication::setOrganizationName()、QCoreApplication::setOrganizationDomain()、およびQCoreApplication::setApplicationName() の呼び出しによって以前に設定された、アプリケーションおよび組織の設定にアクセスするための QSettings オブジェクトを作成します。

スコープは `QSettings::UserScope `、フォーマットは `defaultFormat()` です（デフォルトは `QSettings::NativeFormat `）。このコンストラクタが使用するデフォルトのフォーマットを変更するには、このコンストラクタを呼び出す前に `setDefaultFormat()` を呼び出してください。

次のコード

QSettings settings("Moose Soft", "Facturo-Pro");

は、以下と同等です。

QCoreApplication::setOrganizationName("Moose Soft");
QCoreApplication::setApplicationName("Facturo-Pro");
QSettings settings;

QCoreApplication::setOrganizationName() およびQCoreApplication::setApplicationName() が事前に呼び出されていない場合、QSettings オブジェクトは設定の読み取りや書き込みを行うことができず、status() はAccessError を返します。

ドメイン（macOS および iOS ではデフォルトで使用される）と名前の両方を指定する必要がありますが、片方のみを指定してもコードは処理します。その場合、指定された方が（すべてのプラットフォームで）使用されますが、それがデフォルトではないプラットフォームでは、通常のファイル名付け規則とは矛盾することになります。

QCoreApplication::setOrganizationName()、QCoreApplication::setOrganizationDomain()、QCoreApplication::setApplicationName()、およびsetDefaultFormat()も参照してください 。

[explicit] QSettings::QSettings(QSettings::Scope scope, QObject *parent = nullptr)

QSettings(QObject *parent) と同様に QSettings オブジェクトを構築しますが、指定されたscope を使用します。

QSettings(QObject *parent)も参照してください 。

QSettings::QSettings(const QString &fileName, QSettings::Format format, QObject *parent = nullptr)

parent を親とする、fileName というファイルに保存されている設定にアクセスするための QSettings オブジェクトを作成します。ファイルがまだ存在しない場合は、作成されます。

format がQSettings::NativeFormat である場合、fileName の意味はプラットフォームによって異なります。Unix では、fileName は INI ファイルの名前です。macOS および iOS では、fileName は.plist ファイルの名前です。Windows では、fileName はシステムレジストリ内のパスです。

format がQSettings::IniFormat の場合、fileName はINIファイルの名前となります。

• QSettings には、INI の「パス」エントリ、すなわちエスケープされていないスラッシュ文字を含むエントリを読み取る機能はありません。（これは、これらのエントリが曖昧であり、自動的に解決できないためです。）
• INIファイルにおいて、QSettingsは特定の文脈で@ 文字をメタ文字として使用し、Qt固有のデータ型（例：@Rect ）をエンコードします。そのため、純粋なINIファイル内でこの文字が出現した場合、誤って解釈される可能性があります。

fileName()も参照してください 。

[explicit] QSettings::QSettings(const QString &organization, const QString &application = QString(), QObject *parent = nullptr)

organization という組織に属し、親がparent である、application というアプリケーションの設定にアクセスするための QSettings オブジェクトを作成します。

例：

QSettings settings("Moose Tech", "Facturo-Pro");

スコープはQSettings::UserScope に設定され、フォーマットはQSettings::NativeFormat に設定されます（つまり、このコンストラクタを呼び出す前にsetDefaultFormat() を呼び出しても効果はありません）。

関連項目： setDefaultFormat() およびFallback Mechanism 。

QSettings::QSettings(QSettings::Scope scope, const QString &organization, const QString &application = QString(), QObject *parent = nullptr)

「organization 」という組織に属し、親が「parent 」である「application 」というアプリケーションの設定にアクセスするための QSettings オブジェクトを作成します。

scope がQSettings::UserScope の場合、QSettings オブジェクトは、まずユーザー固有の設定を検索し、それが見つからない場合にのみ、フォールバックとしてシステム全体の設定を検索します。scope がQSettings::SystemScope の場合、QSettings オブジェクトはユーザー固有の設定を無視し、システム全体の設定へのアクセスを提供します。

保存形式はQSettings::NativeFormat に設定されています（つまり、このコンストラクタを呼び出す前にsetDefaultFormat() を呼び出しても何の効果もありません）。

アプリケーション名が指定されていない場合、QSettings オブジェクトは組織全体のlocations にのみアクセスします。

setDefaultFormat()も参照してください 。

QSettings::QSettings(QSettings::Format format, QSettings::Scope scope, const QString &organization, const QString &application = QString(), QObject *parent = nullptr)

「organization 」という組織に属し、親が「parent 」である、application というアプリケーションの設定にアクセスするための QSettings オブジェクトを作成します。

scope がQSettings::UserScope の場合、QSettingsオブジェクトは、まずユーザー固有の設定を検索し、それが見つからない場合にのみ、フォールバックとしてシステム全体の設定を検索します。scope がQSettings::SystemScope の場合、QSettingsオブジェクトはユーザー固有の設定を無視し、システム全体の設定へのアクセスを提供します。

format がQSettings::NativeFormat の場合、設定の保存にはネイティブAPIが使用されます。format がQSettings::IniFormat の場合、INI形式が使用されます。

アプリケーション名が指定されていない場合、QSettingsオブジェクトは組織全体のlocations にのみアクセスします。

[virtual noexcept] QSettings::~QSettings()

QSettings オブジェクトを破棄します。

保存されていない変更は、最終的に永続ストレージに書き込まれます。

sync()も参照してください 。

QStringList QSettings::allKeys() const

QSettings オブジェクトを使用して読み取ることができる、サブキーを含むすべてのキーのリストを返します。

例：

QSettings settings;
settings.setValue("fridge/color", QColor(Qt::white));
settings.setValue("fridge/size", QSize(32, 96));
settings.setValue("sofa", true);
settings.setValue("tv", false);

QStringList keys = settings.allKeys();
// keys: ["fridge/color", "fridge/size", "sofa", "tv"]

beginGroup() を使用してグループが設定されている場合、グループ内のキーのみが、グループのプレフィックスを除いて返されます:

settings.beginGroup("fridge");
keys = settings.allKeys();
// keys: ["color", "size"]

関連項目: childGroups() およびchildKeys()。

QString QSettings::applicationName() const

設定の保存に使用されるアプリケーション名を返します。

関連項目： QCoreApplication::applicationName()、format()、scope()、およびorganizationName()。

void QSettings::beginGroup(QAnyStringView prefix)

現在のグループに「prefix 」を追加します。

現在のグループは、QSettings で指定されたすべてのキーの先頭に自動的に付加されます。さらに、childGroups()、childKeys()、allKeys() などのクエリ関数は、このグループに基づいて動作します。デフォルトでは、グループは設定されていません。

グループを使用すると、同じ設定パスを何度も入力する手間を省くことができます。例えば：

settings.beginGroup("mainwindow");
settings.setValue("size", win->size());
settings.setValue("active", win->isActive());
settings.endGroup();

settings.beginGroup("outputpanel");
settings.setValue("visible", panel->isVisible());
settings.endGroup();

これにより、3つの設定値が設定されます：

• mainwindow/size
• mainwindow/active
• outputpanel/visible

endGroup() を呼び出すと、現在のグループが、対応する beginGroup() の呼び出し前の状態に戻ります。グループはネスト可能です。

endGroup() およびgroup()も参照してください 。

int QSettings::beginReadArray(QAnyStringView prefix)

prefix を現在のグループに追加し、配列からの読み取りを開始します。配列のサイズを返します。

例:

struct Login {
    QString userName;
    QString password;
};
QList<Login> logins;
//...
void some_function()
{
    //...
    QSettings settings;
    int size = settings.beginReadArray("logins");
    for (int i = 0; i < size; ++i) {
        settings.setArrayIndex(i);
        Login login;
        login.userName = settings.value("userName").toString();
        login.password = settings.value("password").toString();
        logins.append(login);
    }
    settings.endArray();
    //...
}

最初に配列を書き込むには、beginWriteArray() を使用します。

関連項目： beginWriteArray()、endArray()、およびsetArrayIndex()。

void QSettings::beginWriteArray(QAnyStringView prefix, int size = -1)

prefix を現在のグループに追加し、サイズsize の配列への書き込みを開始します。size が-1（デフォルト）の場合、書き込まれたエントリのインデックスに基づいてサイズが自動的に決定されます。

特定のキーの組み合わせが多数存在する場合は、配列を使用することで処理を簡略化できます。たとえば、長さが可変のユーザー名とパスワードのリストを保存したい場合を考えましょう。その場合は、次のように記述できます。

struct Login {
    QString userName;
    QString password;
};
QList<Login> logins;
//...
void some_function()
{
    //...
    QSettings settings;
    settings.beginWriteArray("logins");
    for (qsizetype i = 0; i < logins.size(); ++i) {
        settings.setArrayIndex(i);
        settings.setValue("userName", logins.at(i).userName);
        settings.setValue("password", logins.at(i).password);
    }
    settings.endArray();
    //...
}

生成されるキーは次のような形式になります。

• logins/size
• logins/1/userName
• logins/1/password
• logins/2/userName
• logins/2/password
• logins/3/userName
• logins/3/password
• ...

配列を読み戻すには、beginReadArray() を使用します。

beginReadArray()、endArray()、およびsetArrayIndex()も参照してください 。

QStringList QSettings::childGroups() const

QSettings オブジェクトを使用して読み取ることができるキーを含む、すべての主要なトップレベルグループのリストを返します。

例:

QSettings settings;
settings.setValue("fridge/color", QColor(Qt::white));
settings.setValue("fridge/size", QSize(32, 96));
settings.setValue("sofa", true);
settings.setValue("tv", false);

QStringList groups = settings.childGroups();
// groups: ["fridge"]

beginGroup() を使用してグループが設定されている場合、そのグループ内の第1レベルのキーが、グループプレフィックスを除いて返されます。

settings.beginGroup("fridge");
groups = settings.childGroups();
// groups: []

childKeys() および childGroups() を再帰的に使用することで、設定階層全体をナビゲートできます。

childKeys() およびallKeys()も参照してください 。

QStringList QSettings::childKeys() const

QSettings オブジェクトを使用して読み取ることができるすべてのトップレベルキーのリストを返します。

例:

QSettings settings;
settings.setValue("fridge/color", QColor(Qt::white));
settings.setValue("fridge/size", QSize(32, 96));
settings.setValue("sofa", true);
settings.setValue("tv", false);

QStringList keys = settings.childKeys();
// keys: ["sofa", "tv"]

beginGroup() を使用してグループが設定されている場合、そのグループ内のトップレベルキーが、グループプレフィックスを除いて返されます：

settings.beginGroup("fridge");
keys = settings.childKeys();
// keys: ["color", "size"]

childKeys() およびchildGroups() を再帰的に使用することで、設定階層全体をナビゲートできます。

childGroups() およびallKeys()も参照してください 。

void QSettings::clear()

このQSettings オブジェクトに関連付けられているプライマリロケーション内のすべてのエントリを削除します。

フォールバックロケーション内のエントリは削除されません。

現在のgroup()内のエントリのみを削除したい場合は、代わりにremove("")を使用してください。

remove() およびsetFallbacksEnabled()も参照してください 。

bool QSettings::contains(QAnyStringView key) const

key という設定が存在する場合、true を返します。それ以外の場合は false を返します。

beginGroup() を使用してグループが設定されている場合、key はそのグループを基準とするものとみなされます。

キーの検索は、ファイル形式やオペレーティング・システムに応じて、大文字と小文字を区別する場合と区別しない場合があります。移植性の問題を回避するには、Section and Key Syntax のルールを参照してください。

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

[static] QSettings::Format QSettings::defaultFormat()

QSettings （QObject *）のコンストラクタで、設定の保存に使用されるデフォルトのファイル形式を返します。デフォルトの形式が設定されていない場合は、QSettings::NativeFormat が使用されます。

setDefaultFormat() およびformat()も参照してください 。

void QSettings::endArray()

beginReadArray() またはbeginWriteArray() を使用して開始した配列を閉じます。

beginReadArray() およびbeginWriteArray()も参照してください 。

void QSettings::endGroup()

グループを、対応するbeginGroup()の呼び出し前の状態に戻します。

例：

settings.beginGroup("alpha");
// settings.group() == "alpha"

settings.beginGroup("beta");
// settings.group() == "alpha/beta"

settings.endGroup();
// settings.group() == "alpha"

settings.endGroup();
// settings.group() == ""

beginGroup() およびgroup()も参照してください 。

[override virtual protected] bool QSettings::event(QEvent *event)

QObject::event(QEvent *e) を再実装します。

bool QSettings::fallbacksEnabled() const

フォールバックが有効になっている場合は `true ` を返し、そうでない場合は `false ` を返します。

デフォルトでは、フォールバックが有効になっています。

setFallbacksEnabled()も参照してください 。

QString QSettings::fileName() const

このQSettings オブジェクトを使用して書き込まれた設定が保存されているパスを返します。

Windows では、形式が `QSettings::NativeFormat` の場合、戻り値はファイルパスではなく、システムレジストリのパスになります。

isWritable() およびformat()も参照してください 。

QSettings::Format QSettings::format() const

設定の保存に使用される形式を返します。

defaultFormat()、fileName()、scope()、organizationName()、およびapplicationName()も参照してください 。

QString QSettings::group() const

現在のグループを返します。

beginGroup() およびendGroup()も参照してください 。

bool QSettings::isAtomicSyncRequired() const

QSettings が設定の原子的な保存および読み込み（同期）のみを実行できる場合は、true を返します。設定内容を直接設定ファイルに保存できる場合は、false を返します。

デフォルトは `true` です。

setAtomicSyncRequired() およびQSaveFileも参照してください 。

bool QSettings::isWritable() const

この `QSettings ` オブジェクトを使用して設定を書き込むことができる場合は `true ` を返し、そうでない場合は `false ` を返します。

isWritable() が false を返す理由の一つとして、QSettings が読み取り専用ファイルに対して操作を行っている場合が挙げられます。

fileName()、status()、およびsync()も参照してください 。

QString QSettings::organizationName() const

設定の保存に使用される組織名を返します。

関連項目： QCoreApplication::organizationName()、format()、scope()、およびapplicationName()。

[static] QSettings::Format QSettings::registerFormat(const QString &extension, QSettings::ReadFunc readFunc, QSettings::WriteFunc writeFunc, Qt::CaseSensitivity caseSensitivity = Qt::CaseSensitive)

カスタムストレージ形式を登録します。成功した場合、QSettings のコンストラクタに渡すことができる特別なFormat値を返します。失敗した場合、InvalidFormat を返します。

extension は、そのフォーマットに関連付けられたファイル拡張子（「.」を除く）です。

readFunc およびwriteFunc パラメータは、キー/値のペアのセットを読み書きする関数へのポインタです。読み取りおよび書き込み関数に対するQIODevice パラメータは、常にバイナリモード（つまり、QIODeviceBase::Text フラグなし）で開かれます。

caseSensitivity パラメータは、キーの大文字小文字を区別するかどうかを指定します。これは、QSettings を使用して値を検索する際に影響します。デフォルトでは大文字小文字が区別されます。Unixシステムでは、このパラメータはQt::CaseSensitive でなければなりません。

デフォルトでは、組織名とアプリケーション名に基づいて動作するコンストラクタのいずれかを使用する場合、使用されるファイルシステムの場所は `IniFormat` と同じになります。他の場所を指定するには、`setPath()` を使用してください。

例:

bool readXmlFile(QIODevice &device, QSettings::SettingsMap &map);
bool writeXmlFile(QIODevice &device, const QSettings::SettingsMap &map);

int main(int argc, char *argv[])
{
    const QSettings::Format XmlFormat =
            QSettings::registerFormat("xml", readXmlFile, writeXmlFile);

    QSettings settings(XmlFormat, QSettings::UserScope, "MySoft",
                       "Star Runner");

    //...
}

注： この関数はスレッドセーフです。

関連項目: setPath()。

void QSettings::remove(QAnyStringView key)

設定「key 」および「key 」のすべてのサブ設定を削除します。

例：

QSettings settings;
settings.setValue("ape", 0);
settings.setValue("monkey", 1);
settings.setValue("monkey/sea", 2);
settings.setValue("monkey/doe", 4);

settings.remove("monkey");
QStringList keys = settings.allKeys();
// keys: ["ape"]

フォールバックの場所のいずれかに同じキーを持つ設定が含まれている場合、remove() を呼び出した後もその設定は表示されることに注意してください。

key が空の文字列の場合、現在のgroup() 内のすべてのキーが削除されます。例：

QSettings settings;
settings.setValue("ape", 0);
settings.setValue("monkey", 1);
settings.setValue("monkey/sea", 2);
settings.setValue("monkey/doe", 4);

settings.beginGroup("monkey");
settings.remove("");
settings.endGroup();

QStringList keys = settings.allKeys();
// keys: ["ape"]

キーの検索は、ファイル形式やオペレーティングシステムに応じて、大文字小文字を区別する場合と区別しない場合があります。移植性の問題を回避するには、Section and Key Syntax のルールを参照してください。

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

QSettings::Scope QSettings::scope() const

設定の保存に使用されるスコープを返します。

format()、organizationName()、およびapplicationName()も参照してください 。

void QSettings::setArrayIndex(int i)

現在の配列のインデックスを `i` に設定します。setValue()、value()、remove()、contains() などの関数を呼び出すと、そのインデックスにある配列要素に対して処理が行われます。

この関数を呼び出すには、事前にbeginReadArray() またはbeginWriteArray() を呼び出す必要があります。

void QSettings::setAtomicSyncRequired(bool enable)

QSettings が設定の原子的な保存および再読み込み（同期）を行う必要があるかどうかを設定します。enable 引数がtrue （デフォルト）の場合、sync()は原子的な同期操作のみを実行します。これが不可能な場合、sync()は失敗し、status()はエラー状態となります。

このプロパティを `false ` に設定すると、QSettings が設定ファイルに直接書き込みを行い、同時に書き込みを試みる他のプロセスとの競合によるロックエラーを無視できるようになります。 データ破損の可能性があるため、このオプションは慎重に使用する必要がありますが、書き込み不可のディレクトリにある `QSettings::IniFormat ` 設定ファイルや、NTFS 代替データストリームなど、特定の状況ではこのオプションが必要となります。

この機能の詳細については、QSaveFile を参照してください。

isAtomicSyncRequired() およびQSaveFileも参照してください 。

[static] void QSettings::setDefaultFormat(QSettings::Format format)

デフォルトのファイル形式を、指定されたformat に設定します。これは、QSettings （QObject *）コンストラクタの設定を保存するために使用されます。

デフォルトの形式が設定されていない場合は、QSettings::NativeFormat が使用されます。使用しているQSettings コンストラクタのドキュメントを参照し、そのコンストラクタがこの関数を無視するかどうかを確認してください。

defaultFormat() およびformat()も参照してください 。

void QSettings::setFallbacksEnabled(bool b)

b へのフォールバックを有効にするかどうかを設定します。

デフォルトでは、フォールバックは有効になっています。

fallbacksEnabled()も参照してください 。

[static] void QSettings::setPath(QSettings::Format format, QSettings::Scope scope, const QString &path)

指定されたformat およびscope の設定を保存するために使用されるパスを、path に設定します。format は、任意の形式に指定できます。

以下の表にデフォルト値をまとめます：

Qt をビルドする際、configure スクリプトに `-sysconfdir ` を渡すことで、デフォルトのSystemScope パスを上書きできます（詳細についてはQLibraryInfo を参照してください）。

関連項目 ：registerFormat()

void QSettings::setValue(QAnyStringView key, const QVariant &value)

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

キーの検索は、ファイル形式やオペレーティングシステムに応じて、大文字と小文字を区別する場合と区別しない場合があります。移植性の問題を回避するには、「Section and Key Syntax 」の規則を参照してください。

例:

QSettings settings;
settings.setValue("interval", 30);
settings.value("interval").toInt();     // returns 30

settings.setValue("interval", 6.55);
settings.value("interval").toDouble();  // returns 6.55

関連項目： value()、remove()、およびcontains()。

QSettings::Status QSettings::status() const

QSettings で最初に発生したエラーを示すステータスコードを返します。エラーが発生しなかった場合は、QSettings::NoError を返します。

QSettings では、一部の操作の実行が遅延されることに注意してください。このため、status() を呼び出す前に、QSettings に格納されたデータが確実にディスクに書き込まれるように、sync() を呼び出すことをお勧めします。

sync()も参照してください 。

void QSettings::sync()

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

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

status()も参照してください 。

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

デフォルト値が指定されていない場合、デフォルトのQVariant が返されます。

キーの検索は、ファイル形式やオペレーティングシステムに応じて、大文字と小文字を区別する場合と区別しない場合があります。移植性の問題を回避するには、「Section and Key Syntax 」のルールを参照してください。

例：

QSettings settings;
settings.setValue("animal/snake", 58);
settings.value("animal/snake", 1024).toInt();   // returns 58
settings.value("animal/zebra", 1024).toInt();   // returns 1024
settings.value("animal/zebra").toInt();         // returns 0

関連項目： setValue()、contains()、およびremove()。