QSettings Class

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

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

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

Windows のレジストリと INI ファイルは大文字小文字を区別しないキーを使用しますが、macOS と iOS の CFPreferences API は大文字小文字を区別するキーを使用することに注意してください。移植性の問題を避けるために、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()も参照してください 。

[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の "path "エントリ、つまりエスケープされていないスラッシュ文字を含むエントリを読む方法を提供しません。QSettings は INI の "パス" エントリ、つまりエスケープされていないスラッシュ文字を含むエントリを読み取る方法を提供しません (これはこれらのエントリが曖昧で、自動的に解決できないためです)。
• INI ファイルでは、QSettings は@ 文字をメタ文字として使用し、Qt 固有のデータ型 (@Rect など) をエンコードしています。

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

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

organization parent という組織から というアプリケーションの設定にアクセスするための QSettings オブジェクトを構築します。application

例

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 という組織からapplication というアプリケーションの設定にアクセスするための QSettings オブジェクトを構築し、親はparent です。

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 という組織からapplication というアプリケーションの設定にアクセスするための QSettings オブジェクトを構築し、親はparent です。

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("fullScreen", win->isFullScreen());
settings.endGroup();

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

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

• mainwindow/size
• mainwindow/fullScreen
• outputpanel/visible

endGroup （）を呼び出して、現在のグループを、対応するbeginGroup()を呼び出す前の状態にリセットする。グループは入れ子にすることができます。

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

int QSettings::beginReadArray(QAnyStringView prefix)

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

例

struct Login {
    QString userName;
    QString password;
};
QList<Login> logins;
...

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;
...

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 はそのグループからの相対キーとみなされる。

Windows のレジストリと INI ファイルは大文字小文字を区別しないキーを使用しますが、macOS と iOS の CFPreferences API は大文字小文字を区別するキーを使用することに注意してください。移植性の問題を避けるために、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を返す可能性がある理由の1つは、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 を使用して値を検索する場合に違いが生じる。デフォルトは大文字小文字を区別する。

デフォルトでは、組織名とアプリケーション名で動作するコンストラクタの 1 つを使用する場合、使用されるファイルシステムの場所は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");
settings.setValue("monkey", 1);
settings.setValue("monkey/sea", 2);
settings.setValue("monkey/doe", 4);

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

例: フォールバック・ロケーションの 1 つに同じキーを持つ設定が含まれている場合、 remove() を呼び出した後にその設定が表示されることに注意してください。

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

QSettings settings;
settings.setValue("ape");
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"]

Windows のレジストリと INI ファイルは大文字小文字を区別しないキーを使用しますが、macOS と iOS の CFPreferences API は大文字小文字を区別するキーを使用することに注意してください。移植性の問題を避けるために、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)

QSettings(QObject *) コンストラクタの設定を格納するために使用されるデフォルトのファイル・フォーマットを、指定されたformat に設定します。

デフォルトフォーマットが設定されていない場合は、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 にはカスタムフォーマットを指定できます。

以下の表は、デフォルト値をまとめたものです：

Unix、macOS、iOS のデフォルトのUserScope パス ($HOME/.config または $HOME/Settings) は、XDG_CONFIG_HOME 環境変数を設定することで、ユーザーがオーバーライドできます。Unix、macOS、iOS のデフォルトのSystemScope パス (/etc/xdg) は、configure スクリプトの-sysconfdir フラグを使用して Qt ライブラリをビルドするときにオーバーライドできます (詳細はQLibraryInfo を参照)。

Windows、macOS、iOS でNativeFormat のパスを設定しても効果はありません。

registerFormat()も参照 。

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

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

WindowsのレジストリとINIファイルは大文字と小文字を区別しないキーを使用しますが、macOSとiOSのCFPreferences APIは大文字と小文字を区別するキーを使用することに注意してください。移植性の問題を避けるために、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 、一部の操作の実行が遅れることに注意。このため、sync() を呼び出して、QSettings に格納されているデータが status() を呼び出す前にディスクに書き込まれるようにするとよい。

sync()も参照のこと 。

void QSettings::sync()

未保存の変更を永久記憶装置に書き込み、その間に他のアプリケーションによって変更された設定を再読み込みします。

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

status()も参照 。