QSettings 类

成员函数文档

返回设置 key 的值。如果设置不存在，则返回 defaultValue。

如果没有指定默认值，则返回默认 QVariant。

请注意，Windows 注册表和 INI 文件使用不区分大小写的键，而 macOS 和 iOS 的 CFPreferences API 使用区分大小写的键。为了防止可移植性问题，请参阅 部分和键语法 规则。

示例

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()。

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

构建一个 QSettings 对象，用于访问名为 application 的应用程序的设置，来自名为 organization 的组织，并具有父 parent。

示例

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

作用域设置为 QSettings::UserScope，格式设置为 QSettings::NativeFormat（即调用 setDefaultFormat() 在调用此构造函数之前没有效果）。

另请参阅setDefaultFormat() 和 回退机制。

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

构建一个 QSettings 对象，用于访问名为 application 的应用程序的设置，来自名为 organization 的组织，并具有父 parent。

如果 scope 是 QSettings::UserScope，则 QSettings 对象首先搜索用户特定的设置，然后再搜索系统范围的设置作为后备。如果 scope 是 QSettings::SystemScope，则 QSettings 对象忽略用户特定的设置并提供对系统范围的设置的访问。

存储格式被设置为 QSettings::NativeFormat（即，在调用此构造函数之前调用 setDefaultFormat() 没有作用）。

如果没有提供应用程序名称，QSettings 对象将只访问组织内的 位置。

另请参阅：setDefaultFormat。

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

构建一个 QSettings 对象，用于访问名为 application 的应用程序的设置，来自名为 organization 的组织，并具有父 parent。

如果 scope 是 QSettings::UserScope，则 QSettings 对象首先搜索用户特定的设置，然后再搜索系统范围的设置作为后备。如果 scope 是 QSettings::SystemScope，则 QSettings 对象忽略用户特定的设置并提供对系统范围的设置的访问。

如果 format 是 QSettings::NativeFormat，则用于存储设置的会使用本地 API。如果 format 是 QSettings::IniFormat，则使用 INI 格式。

如果没有提供应用程序名称，QSettings 对象将只访问组织内的 位置。

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

用于创建一个 QSettings 对象，该对象可访问由 fileName 命名的文件中存储的设置，并具有父对象 parent。如果文件不存在，则创建该文件。

如果 format 是 QSettings::NativeFormat，则 fileName 的含义取决于平台。在 Unix 上，fileName 是 INI 文件名。在 macOS 和 iOS 上，fileName 是 .plist 文件的名称。在 Windows 上，fileName 是系统注册表中的路径。

如果 format 是 QSettings::IniFormat，则 fileName 是 INI 文件的名称。

• QSettings 不提供读取 INI "路径" 条目的方式，即使用转义斜杠字符的条目。（这是因为这些条目是歧义的，不能自动解析。）
• 在一些情况下，QSettings 将使用 @ 字符作为元字符，来说明 Qt 特定的数据类型（例如，@Rect），因此可能会在纯 INI 文件中错误地解释它。

另请参阅：fileName。

[显式] QSettings::QSettings(QObject *parent = nullptr)

用于创建一个 QSettings 对象，以访问之前通过调用 QCoreApplication::setOrganizationName()、QCoreApplication::setOrganizationDomain() 和 QCoreApplication::setApplicationName() 设置的应用程序和组织设置。

作用域是 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。

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

以与 QSettings(QObject *parent) 相同的方式构造 QSettings 对象，但带有给定的 scope。

另请参阅 QSettings(QObject *parent).

[虚，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();

这将设置三个设置值

• 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设置了组，则返回该组的顶级键，不包含组前缀。

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 使用区分大小写的键。为了防止可移植性问题，请参阅 部分和键语法 规则。

另请参阅 value() 和 setValue()。

[静态] 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。

[重写虚保护] 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。

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

注册一个自定义存储格式。成功时返回一个特殊格式的值，然后可以将此值传递给 QSettings 构造函数。失败时返回 InvalidFormat。

extension 是与格式关联的文件扩展名（不带'.'）。

readFunc 和 writeFunc 参数是指向函数的指针，用于读取和写入一组键/值对。读取和写入函数中的 QIODevice 参数总是以二进制模式打开（即不带 QIODevice::Text 标志）。

caseSensitivity 参数指定键是否区分大小写。当使用 QSettings 查找值时，这很重要。默认是区分大小写。

默认情况下，如果您使用基于机构名称和应用程序名称的构造函数之一，所使用的文件系统位置与 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"]

请注意，如果在其中一个回退位置中包含具有相同键的设置，则在调用 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 使用区分大小写的键。为了防止可移植性问题，请参阅 部分和键语法 规则。

另请参阅：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)

配置是否需要使用原子保存和重新加载（同步）设置。如果enable参数为true（默认值），sync()将仅执行原子同步操作。如果无法这样做，sync()将失败，并且status()将为错误条件。

将此属性设置为false将允许QSettings直接写入配置文件并忽略尝试同时写入该文件的其他进程的任何锁定错误。由于存在损坏的潜在风险，这种选项应谨慎使用，但在某些条件下是必需的，例如一个存在于非可写目录中的QSettings::IniFormat配置文件或NTFS备用数据流。

有关此功能的更多信息，请参阅QSaveFile。

另请参阅isAtomicSyncRequired()和QSaveFile。

[静态] void QSettings::setDefaultFormat(QSettings::Format format)

将默认文件格式设置为指定的format，该格式用于存储用于QSettings(QObject *)构造函数的设置。

如果没有设置默认格式，则使用NativeFormat。请参阅您正在使用的QSettings构造函数的文档，以查看该构造函数是否会忽略此函数。

另请参阅defaultFormat()和format。

void QSettings::setFallbacksEnabled(bool b)

将回退启用设置设置为b。

默认情况下，回退是启用的。

另请参阅fallbacksEnabled。

[静态] 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）在构建 Qt 库时可以通过 configure 脚本的 -sysconfdir 标志来覆盖（详情见 QLibraryInfo）。

在 Windows、macOS 和 iOS 上设置 NativeFormat 路径没有任何效果。

另请参阅registerFormat。

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

将 key 的设置值设为 value。如果 key 已存在，则覆盖其之前的值。

请注意，Windows 注册表和 INI 文件使用不区分大小写的键，而 macOS 和 iOS 的 CFPreferences API 使用区分大小写的键。为了防止可移植性问题，请参阅 部分和键语法 规则。

示例

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() 确保在调用 status() 之前，存放在 QSettings 中的数据已经写入到磁盘。

另请参阅 sync。

void QSettings::sync()

将任何未保存的更改写入永久存储，并重新加载在此期间由其他应用程序更改的任何设置。

该函数会自动由 QSettings 的析构函数和事件循环在定期间隔中调用，所以通常您不需要自行调用它。

另请参阅状态。