QSettings Class

成员函数文档

返回设置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()。

[explicit] 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()。

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

构造一个 QSettings 对象，方法与 QSettings(QObject *parent)相同，但使用给定的scope 。

另请参阅 QSettings(QObject *parent)。

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 "路径 "条目，即带有未转义斜线字符的条目。(这是因为这些条目模棱两可，无法自动解决）。
• 在 INI 文件中，QSettings 在某些上下文中将@ 字符用作元字符，以编码 Qt 特有的数据类型（如@Rect ），因此当它出现在纯 INI 文件中时，可能会被误解。

另请参见 fileName().

[explicit] 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() 和Fallback Mechanism 。

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

构造一个 QSettings 对象，用于从名为organization 的机构访问名为application 的应用程序的设置，其父机构为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)

构造一个 QSettings 对象，用于从名为organization 的机构访问名为application 的应用程序的设置，其父机构为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();

这将设置三个设置的值：

• 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 将被视为相对于该组。

根据文件格式和操作系统的不同，键查找对大小写敏感或不敏感。为避免可移植性问题，请参阅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 构造函数。如果失败，则返回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");
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"]

根据文件格式和操作系统的不同，键查找对大小写敏感或不敏感。为避免可移植性问题，请参阅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 可以是自定义格式。

下表总结了默认值：

用户可以通过设置XDG_CONFIG_HOME 环境变量来覆盖 Unix、macOS 和 iOS 上默认的UserScope 路径（$HOME/.config 或 $HOME/Settings）。Unix、macOS 和 iOS 上的默认SystemScope 路径 (/etc/xdg) 可在构建 Qt XML 库时使用configure 脚本的-sysconfdir 标志覆盖（详情请参见QLibraryInfo ）。

在 Windows、macOS 和 iOS 上设置NativeFormat 路径没有影响。

另请参阅 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() 之前，您可能需要调用sync() 以确保存储在QSettings 中的数据已写入磁盘。

另请参阅 sync()。

void QSettings::sync()

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

QSettings 的析构函数会自动调用该函数，事件循环也会定期调用该函数，因此通常不需要自己调用。

另请参阅 status()。