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

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

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 パラメータは、常にバイナリモードで開かれます（つまり、QIODevice::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()も参照してください 。