QSettings Class

成员函数文档

[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(QObject *parent) 相同的方式构建一个 QSettings 对象，但使用给定的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 对象，用于访问名为application 的应用程序的设置，该应用程序所属的组织名为organization ，且父组织为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 对象，用于访问名为application 的应用程序的设置，该应用程序所属的组织名为organization ，且父组织为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("active", win->isActive());
settings.endGroup();

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

这将设置三个配置项的值：

• 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()` 设置了一个组，则返回该组中的第一级键，且不包含组前缀。

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)

注册自定义存储格式。成功时，返回一个特殊的 Format 值，该值随后可传递给 `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", 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() 之前，建议先调用sync()，以确保QSettings 中存储的数据已写入磁盘。

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