QSettings 类提供平台无关的持久性应用程序设置。 更多...
| 头： | #include <QSettings> |
| qmake: | QT += core |
| 继承： | QObject |
注意： 此类的所有函数 可重入 .
注意： 这些函数也是 thread-safe :
| enum | Format { NativeFormat, Registry32Format, Registry64Format, IniFormat, InvalidFormat } |
| typedef | ReadFunc |
| enum | Scope { UserScope, SystemScope } |
| typedef | SettingsMap |
| enum | Status { NoError, AccessError, FormatError } |
| typedef | WriteFunc |
| QSettings (QSettings::Scope scope , QObject * parent = nullptr) | |
| QSettings (QObject * parent = nullptr) | |
| QSettings (const QString & fileName , QSettings::Format format , QObject * parent = nullptr) | |
| QSettings (QSettings::Format format , QSettings::Scope scope , const QString & organization , const QString & application = QString(), QObject * parent = nullptr) | |
| QSettings (QSettings::Scope scope , const QString & organization , const QString & application = QString(), QObject * parent = nullptr) | |
| QSettings (const QString & organization , const QString & application = QString(), QObject * parent = nullptr) | |
| virtual | ~QSettings () |
| QStringList | allKeys () const |
| QString | applicationName () const |
| void | beginGroup (const QString & prefix ) |
| int | beginReadArray (const QString & prefix ) |
| void | beginWriteArray (const QString & prefix , int size = -1) |
| QStringList | childGroups () const |
| QStringList | childKeys () const |
| void | clear () |
| bool | contains (const QString & key ) const |
| void | endArray () |
| void | endGroup () |
| bool | fallbacksEnabled () const |
| QString | fileName () const |
| QSettings::Format | format () const |
| QString | group () const |
| QTextCodec * | iniCodec () const |
| bool | isAtomicSyncRequired () const |
| bool | isWritable () const |
| QString | organizationName () const |
| void | remove (const QString & key ) |
| QSettings::Scope | scope () const |
| void | setArrayIndex (int i ) |
| void | setAtomicSyncRequired (bool enable ) |
| void | setFallbacksEnabled (bool b ) |
| void | setIniCodec (QTextCodec * codec ) |
| void | setIniCodec (const char * codecName ) |
| void | setValue (const QString & key , const QVariant & value ) |
| QSettings::Status | status () const |
| void | sync () |
| QVariant | value (const QString & key , const QVariant & defaultValue = QVariant()) const |
| QSettings::Format | defaultFormat () |
| QSettings::Format | registerFormat (const QString & extension , QSettings::ReadFunc readFunc , QSettings::WriteFunc writeFunc , Qt::CaseSensitivity caseSensitivity = Qt::CaseSensitive) |
| void | setDefaultFormat (QSettings::Format format ) |
| void | setPath (QSettings::Format format , QSettings::Scope scope , const QString & path ) |
| virtual bool | event (QEvent * event ) override |
用户通常期望应用程序跨会话记住其设置 (窗口大小和位置、选项、等等)。此信息常存储在 Windows 的系统注册表中，macOS 和 iOS 的特性列表文件中。在缺乏标准的 Unix 系统，许多应用程序 (包括 KDE 应用程序) 使用 INI 文本文件。
QSettings 是围绕这些技术的抽象，使能够以可移植方式保存和还原应用程序设置。它还支持 自定义存储格式 .
QSettings 的 API 基于 QVariant ，允许保存大多数基于值的类型，譬如 QString , QRect ，和 QImage ，采用最少努力。
若需要的全是基于内存的非持久性结构，请考虑使用 QMap < QString , QVariant > 代替。
当创建 QSettings 对象时，必须传递公司 (或组织) 名称及应用程序名称。例如，若产品被称为 Star Runner 和公司被称为 MySoft，则构造 QSettings 对象如下：
QSettings settings("MySoft", "Star Runner");
QSettings 对象可以在堆栈或堆上被创建 (即：使用
new
)。构造和销毁 QSettings 对象是非常快的。
若在应用程序中许多地方使用 QSettings，可能希望指定组织名称 应用程序名称使用 QCoreApplication::setOrganizationName () 和 QCoreApplication::setApplicationName ()，然后使用默认 QSettings 构造函数：
QCoreApplication::setOrganizationName("MySoft");
QCoreApplication::setOrganizationDomain("mysoft.com");
QCoreApplication::setApplicationName("Star Runner");
...
QSettings settings;
(这里，我们还指定了组织的 Internet 域。当被设置时，Internet 域在 macOS 和 iOS 上被用于代替组织名称，因为 macOS 和 iOS 应用程序按照惯例会使用 Internet 域去标识它们自己。若未设置域，则从组织名称派生虚假域。见 特定平台注意事项 了解细节。)
QSettings 存储设置。构成每设置由 QString 指定设置的名称 ( key ) 和 QVariant 存储键关联数据。要写入设置，使用 setValue ()。例如：
settings.setValue("editor/wrapMargin", 68);
若已经存在具有相同键的设置，则现有值被新值所覆写。为提高效率，改变可能不会被立即保存到永久存储。(可以始终调用 sync () 去提交改变。)
可以获取设置的值使用 value ():
int margin = settings.value("editor/wrapMargin").toInt();
若没有采用指定名称的设置，QSettings 返回 null QVariant (其可以被转换成整数 0)。可以指定另一默认值通过把第 2 自变量传递给 value ():
int margin = settings.value("editor/wrapMargin", 80).toInt();
要测试给定键是否存在，调用 contains ()。要移除键关联设置，调用 remove ()。要获得所有键的列表，调用 allKeys ()。要移除所有键，调用 clear ().
因为
QVariant
属于 Qt Core 模块，它不能提供数据类型转换函数，如
QColor
,
QImage
，和
QPixmap
，其属于 Qt GUI。换句话说，没有
toColor()
,
toImage()
，或
toPixmap()
函数在
QVariant
.
相反，可以使用 QVariant::value () 模板函数。例如：
QSettings settings("MySoft", "Star Runner"); QColor color = settings.value("DataPump/bgcolor").value<QColor>();
反向转换 (如，从 QColor to QVariant ) 对于所有支持数据类型是自动通过 QVariant ，包括 GUI 相关类型：
QSettings settings("MySoft", "Star Runner"); QColor color = palette().background().color(); settings.setValue("DataPump/bgcolor", color);
自定义类型注册采用 qRegisterMetaType () 和 qRegisterMetaTypeStreamOperators () 可以使用 QSettings 来存储。
设置键可以包含任何 Unicode 字符。Windows 注册表和 INI 文件使用不区分大小写的键，而在 macOS 和 iOS 上的 CFPreferences API 使用区分大小写的键。为避免可移植性问题，遵循这些简单规则：
可以使用 / 字符作为分隔符来形成分层键，类似 Unix 文件路径。例如：
settings.setValue("mainwindow/size", win->size());
settings.setValue("mainwindow/fullScreen", win->isFullScreen());
settings.setValue("outputpanel/visible", panel->isVisible());
若希望保存 (或还原) 许多采用相同前缀的设置，可以指定前缀使用 beginGroup () 和调用 endGroup () 在末尾。这里又是相同范例，但此次使用组机制：
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();
若设置组使用 beginGroup ()，因此，大多数函数的行为改变。组可以被递归设置。
除组外，QSettings 还支持数组概念。见 beginReadArray () 和 beginWriteArray () 了解细节。
假定已采用组织名称 MySoft 和应用程序名称 Star Runner 创建 QSettings 对象。当查找值时，最多按以下次序搜索 4 个位置：
(见 特定平台注意事项 了解在 Qt 支持的不同平台，这些位置的有关信息。)
若在第一位置找不到键，则在第二位置继续搜索，依此类推。这使您能够存储系统范围 (或组织范围) 设置，并在每用户 (或每应用程序) 的基础上覆盖它们。要关闭此机制，调用 setFallbacksEnabled (false).
虽然来自所有 4 个位置的键都可用于读取，但仅第一个文件 (为手中应用程序的特定用户位置) 可写访问。要写入任何其它文件，省略应用程序名称和/或指定 QSettings::SystemScope (而不是 QSettings::UserScope ，默认)。
让我们看下范例：
QSettings obj1("MySoft", "Star Runner");
QSettings obj2("MySoft");
QSettings obj3(QSettings::SystemScope, "MySoft", "Star Runner");
QSettings obj4(QSettings::SystemScope, "MySoft");
下表汇总了 QSettings 对象的哪些访问位置。 X 意味着位置是 QSettings 对象关联的主要位置，且被用于读写；o 意味着位置被用作回退，当读取时。
| 位置 |
obj1
|
obj2
|
obj3
|
obj4
|
|---|---|---|---|---|
| 1. 用户、应用程序 | X | |||
| 2. 用户、组织 | o | X | ||
| 3. 系统、应用程序 | o | X | ||
| 4. 系统、组织 | o | o | o | X |
这种机制的妙处是它工作于由 Qt 支持的所有平台，且仍然给予很大灵活性，不要求指定任何文件名 (或注册表路径)。
若想要在所有平台使用 INI 文件而不是本机 API，可以传递 QSettings::IniFormat 作为第一自变量给 QSettings 构造函数，其后是作用域、组织名称及应用程序名称：
QSettings settings(QSettings::IniFormat, QSettings::UserScope,
"MySoft", "Star Runner");
注意：不预留类型信息，当从 INI 文件读取设置时；所有值将返回作为 QString .
设置编辑器 范例允许您试验不同设置位置，及启用或禁用回退。
QSettings 经常被用于存储 GUI 应用程序的状态。以下范例阐明如何使用 QSettings 去保存和还原应用程序主窗口的几何体。
void MainWindow::writeSettings() { QSettings settings("Moose Soft", "Clipper"); settings.beginGroup("MainWindow"); settings.setValue("size", size()); settings.setValue("pos", pos()); settings.endGroup(); } void MainWindow::readSettings() { QSettings settings("Moose Soft", "Clipper"); settings.beginGroup("MainWindow"); resize(settings.value("size", QSize(400, 400)).toSize()); move(settings.value("pos", QPoint(200, 200)).toPoint()); settings.endGroup(); }
见 窗口几何体 了解为什么更好的论述，调用 QWidget::resize () 和 QWidget::move () 而不是 QWidget::setGeometry () 去还原窗口几何体。
readSettings()
and
writeSettings()
函数必须从主窗口的构造函数调用，关闭事件处理程序如下所示：
MainWindow::MainWindow() { ... readSettings(); } void MainWindow::closeEvent(QCloseEvent *event) { if (userReallyWantsToQuit()) { writeSettings(); event->accept(); } else { event->ignore(); } }
见 应用程序 范例，了解使用 QSettings 的独立范例。
QSettings 可重入 。这意味着可以同时在不同线程中使用截然不同的 QSettings 对象。此保证继续有效，即使 QSettings 对象引用相同磁盘文件 (或相同系统注册表条目)。若透过某一 QSettings 对象修改了设置，变化将立即在任何操作相同位置且处于相同进程中的其它 QSettings 对象中可见。
QSettings 可以被用于从不同进程 (可以是同时运行的不同应用程序实例，或完全不同的应用程序) 安全地读写相同系统位置，当提供的某些条件被满足。对于 QSettings::IniFormat ，它使用咨询文件锁定和智能合并算法，以确保数据的完整性。工作条件是可写配置文件必须为常规文件，且必须位于当前用户可以在其中创建新临时文件的目录下。若不是这种情况，就必须使用 setAtomicSyncRequired () 关闭安全性。
注意， sync () 导入由其它进程所造成的改变 (除从此 QSettings 写入改变外)。
作为提及在 回退机制 章节，QSettings 把应用程序设置存储在最多 4 位置，取决于设置是用户特定或系统范围，及设置是应用程序特定或组织范围。为简单起见，假定组织名为 MySoft，应用程序名为 Star Runner。
在 Unix 系统，若文件格式为 NativeFormat ，默认使用下列文件：
$HOME/.config/MySoft/Star Runner.conf
(Qt for Embedded Linux:
$HOME/Settings/MySoft/Star Runner.conf
)
$HOME/.config/MySoft.conf
(Qt for Embedded Linux:
$HOME/Settings/MySoft.conf
)
<dir>/MySoft/Star Runner.conf
<dir>/MySoft.conf
注意：
若 XDG_CONFIG_DIRS 未设置，默认值
/etc/xdg
的使用。
在 macOS 第 10.2 和 10.3 版，默认使用这些文件：
$HOME/Library/Preferences/com.MySoft.Star Runner.plist
$HOME/Library/Preferences/com.MySoft.plist
/Library/Preferences/com.MySoft.Star Runner.plist
/Library/Preferences/com.MySoft.plist
在 Windows， NativeFormat 设置存储在下列注册表路径：
HKEY_CURRENT_USER\Software\MySoft\Star Runner
HKEY_CURRENT_USER\Software\MySoft\OrganizationDefaults
HKEY_LOCAL_MACHINE\Software\MySoft\Star Runner
HKEY_LOCAL_MACHINE\Software\MySoft\OrganizationDefaults
注意：
在 Windows，对于运行在 WOW64 模式下的 32 位程序，设置存储在下列注册表路径：
HKEY_LOCAL_MACHINE\Software\WOW6432node
.
若文件格式为 NativeFormat ，这是 Settings/MySoft/Star Runner.conf 在应用程序主目录下。
若文件格式为 IniFormat ，在 Unix、macOS 和 iOS 使用下列文件：
$HOME/.config/MySoft/Star Runner.ini
(Qt for Embedded Linux:
$HOME/Settings/MySoft/Star Runner.ini
)
$HOME/.config/MySoft.ini
(Qt for Embedded Linux:
$HOME/Settings/MySoft.ini
)
<dir>/MySoft/Star Runner.ini
<dir>/MySoft.ini
注意：
若 XDG_CONFIG_DIRS 未设置，默认值
/etc/xdg
的使用。
在 Windows，使用下列文件：
FOLDERID_RoamingAppData\MySoft\Star Runner.ini
FOLDERID_RoamingAppData\MySoft.ini
FOLDERID_ProgramData\MySoft\Star Runner.ini
FOLDERID_ProgramData\MySoft.ini
标识符加前缀通过
FOLDERID_
是要被传递给 Win32 API 函数的特殊项 ID 列表
SHGetKnownFolderPath()
以获取相应路径。
FOLDERID_RoamingAppData
通常指向
C:\Users\
User Name
\AppData\Roaming
，也可展示通过环境变量
%APPDATA%
.
FOLDERID_ProgramData
通常指向
C:\ProgramData
.
若文件格式为 IniFormat ，这是 Settings/MySoft/Star Runner.ini 在应用程序的主目录下。
路径对于
.ini
and
.conf
文件可以改变使用
setPath
()。在 Unix、macOS 和 iOS，用户可以覆盖它们通过设置
XDG_CONFIG_HOME
环境变量；见
setPath
() 了解细节。
有时希望访问存储在特定文件 (或注册表路径) 中的设置。在所有平台，若希望直接读取 INI 文件，可以使用 QSettings 构造函数把文件名作为第一自变量并传递 QSettings::IniFormat 作为第 2 自变量。例如：
QSettings settings("/home/petra/misc/myapp.ini", QSettings::IniFormat);
然后，可用使用 QSettings 对象读写文件中的设置。
在 macOS 和 iOS，可以访问特性列表
.plist
文件通过传递
QSettings::NativeFormat
作为第 2 自变量。例如：
QSettings settings("/Users/petra/misc/myapp.plist", QSettings::NativeFormat);
在 Windows，QSettings 允许访问在系统注册表中已采用 QSettings 写入的设置 (或支持格式的设置，如：字符串数据)。这是通过构造 QSettings 对象做到的，采用注册表路径和 QSettings::NativeFormat .
例如：
QSettings settings("HKEY_CURRENT_USER\\Software\\Microsoft\\Office", QSettings::NativeFormat);
可以照常透过 QSettings 对象读写出现在指定路径下的所有注册表条目 (使用正斜杠而非反斜杠)。例如：
settings.setValue("11.0/Outlook/Security/DontTrustInstalledFiles", 0);
注意：如前所述，QSettings 使用反斜杠字符分隔子键。其结果是，不能读写包含斜杠 (或反斜杠) 的 Windows 注册表条目；应该使用本机 windows API，若需要这样做。
在 Windows，键有值和子键两者是可能的。通过使用 Default 或 . 代替子键访问其默认值：
settings.setValue("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy", "Milkyway"); settings.setValue("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy\\Sun", "OurStar"); settings.value("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy\\Default"); // returns "Milkyway"
在 Windows 外的其他平台，Default 和 . 将被视为常规子键。
虽然 QSettings 试图消除不同支持平台之间的差异，但要意识到当移植应用程序时仍有一些差异：
REG_EXPAND_SZ
将改变为
REG_SZ
.
main()
函数，然后使用默认 QSettings 构造函数。另一解决方案是使用预处理器指令，例如：
#ifdef Q_OS_MAC QSettings settings("grenoullelogique.fr", "Squash"); #else QSettings settings("Grenoulle Logique", "Squash"); #endif
另请参阅 QVariant , QSessionManager , 设置编辑器范例 ，和 应用程序范例 .
此枚举类型指定存储格式，用于 QSettings .
| 常量 | 值 | 描述 |
|---|---|---|
QSettings::NativeFormat
|
0
|
使用最适合平台的存储格式存储设置。在 Windows，这意味着系统注册表；在 macOS 和 iOS，这意味着 CFPreferences API；在 Unix，这意味着以 INI 格式正文配置文件。 |
QSettings::Registry32Format
|
2
|
仅 Windows：从 64 位 Windows 运行 64 位应用程序明确访问 32 位系统注册表。在 32 位 Windows 或从 64 位 Windows 运行 32 位应用程序，这的工作如同指定 NativeFormat。该枚举值在 Qt 5.7 添加。 |
QSettings::Registry64Format
|
3
|
仅 Windows：从 64 位 Windows 运行 32 位应用程序明确访问 64 位系统注册表。在 32 位 Windows 或从 64 位 Windows 运行 64 位应用程序，这的工作如同指定 NativeFormat。该枚举值在 Qt 5.7 添加。 |
QSettings::IniFormat
|
1
|
把设置存储在 INI 文件中。注意，不预留类型信息，当从 INI 文件读取设置时；所有值将被返回作为 QString . |
QSettings::InvalidFormat
|
16
|
特殊值的返回通过 registerFormat (). |
在 Unix，NativeFormat 和 IniFormat 意味着相同事情，除文件扩展名不同外 (
.conf
为 NativeFormat，
.ini
为 IniFormat)。
INI 文件格式是在所有平台 Qt 所支持的 Windows 文件格式。在缺乏 INI 标准的情况下，我们试着遵循 Microsoft 做法，但有以下例外：
@
基句法以编码类型。例如：
pos = @Point(100 100)
为最小化兼容性问题，任何
@
未出现在值第一位置或之后未紧跟 Qt 类型 (
Point
,
Rect
,
Size
，等) 被视为正常字符。
\
) 在文件路径：
windir = C:\Windows
QSettings 始终视反斜杠为特殊字符，且不提供用于读取或写入这种条目的 API。
%
作为键中转义字符。此外，若保存顶层设置 (其中不带斜线的键，如 someKey)，它将出现在 INI 文件的 General 区间。为避免覆盖其它键，若使用如 General/someKey 的这种键保存某些事情，键将位于 %General 区间，
not
在 General 区间。
另请参阅 registerFormat () 和 setPath ().
Typedef 为指向采用以下签名的函数指针：
bool myReadFunc(QIODevice &device, QSettings::SettingsMap &map);
ReadFunc
用于
registerFormat()
作为指向读取一组键/值对的函数指针。
ReadFunc
应一次性读取所有选项，并返回所有设置在
SettingsMap
容器，其最初为空。
另请参阅 WriteFunc and registerFormat ().
此枚举指定设置是具体用户，还是由同一系统的所有用户共享。
| 常量 | 值 | 描述 |
|---|---|---|
QSettings::UserScope
|
0
|
将设置存储到当前用户的特定位置 (如：在用户主目录中)。 |
QSettings::SystemScope
|
1
|
将设置存储在全局位置，以便同一计算机中的所有用户访问相同设置集。 |
另请参阅 setPath ().
Typedef 为 QMap < QString , QVariant >.
另请参阅 registerFormat ().
下列状态值是可能的：
| 常量 | 值 | 描述 |
|---|---|---|
QSettings::NoError
|
0
|
没有出现错误。 |
QSettings::AccessError
|
1
|
发生访问错误 (如：试着写入只读文件)。 |
QSettings::FormatError
|
2
|
发生格式错误 (如：加载畸形 INI 文件)。 |
另请参阅 status ().
Typedef 为指向采用以下签名的函数指针：
bool myWriteFunc(QIODevice &device, const QSettings::SettingsMap &map);
WriteFunc
用于
registerFormat()
作为指向写入一组键/值对的函数指针。
WriteFunc
is only called once, so you need to output the settings in one go.
另请参阅 ReadFunc and registerFormat ().
构造 QSettings 对象以相同方式如 QSettings( QObject *parent) 但采用给定 scope .
该函数在 Qt 5.13 引入。
另请参阅 QSettings (QObject *parent).
构造 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 对象为将访问设置存储在文件中称为 fileName ，采用父级 parent 。若文件不存在，创建它。
若
format
is
QSettings::NativeFormat
，含义对于
fileName
从属平台。在 Unix，
fileName
是 INI 文件的名称。在 macOS 和 iOS，
fileName
是名称对于
.plist
文件。在 Windows，
fileName
是系统注册表路径。
若 format is QSettings::IniFormat , fileName 是 INI 文件的名称。
警告：
此函数为方便起见提供。它能很好地访问 INI 或
.plist
文件生成通过 Qt，但可能失败当在发源于其它程序的这种文件中发现某些句法时。尤其，要意识到以下局限性：
@
字符作某些上下文元字符，以编码 Qt 特定数据类型 (如
@Rect
)，因此，可能被误解当它出现在纯 INI 文件中时。
另请参阅 fileName ().
构造 QSettings 对象为访问应用程序设置称为 application 从组织称为 organization ，和采用父级 parent .
若 scope is QSettings::UserScope ，QSettings 对象首先搜索特定用户设置，在它搜索系统范围设置作为回退之前。若 scope is QSettings::SystemScope ，QSettings 对象忽略特定用户设置并提供对系统范围设置的访问。
若 format is QSettings::NativeFormat ，本机 API 用于存储设置。若 format is QSettings::IniFormat ，使用 INI 格式。
若未给出应用程序名称，QSettings 对象将只访问组织范围的 locations .
构造 QSettings 对象为访问应用程序设置称为 application 从组织称为 organization ，和采用父级 parent .
若 scope is QSettings::UserScope ，QSettings 对象首先搜索特定用户设置，在它搜索系统范围设置作为回退之前。若 scope is QSettings::SystemScope ，QSettings 对象忽略特定用户设置并提供对系统范围设置的访问。
存储格式被设为 QSettings::NativeFormat (即：调用 setDefaultFormat () 在调用此构造函数不起作用之前)。
若未给出应用程序名称，QSettings 对象将只访问组织范围的 locations .
另请参阅 setDefaultFormat ().
构造 QSettings 对象为访问应用程序设置称为 application 从组织称为 organization ，和采用父级 parent .
范例：
QSettings settings("Moose Tech", "Facturo-Pro");
作用域设置为 QSettings::UserScope ，和格式设置为 QSettings::NativeFormat (即：调用 setDefaultFormat () 在调用此构造函数不起作用之前)。
另请参阅 setDefaultFormat () 和 回退机制 .
[virtual]
QSettings::
~QSettings
()
销毁 QSettings 对象。
任何未保存的改变最后被写入永久存储。
另请参阅 sync ().
返回所有键的列表 (包括子键)，可以被读取使用 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 ().
返回用于存储设置的应用程序名称。
该函数在 Qt 4.4 引入。
另请参阅 QCoreApplication::applicationName (), format (), scope ()，和 organizationName ().
追加 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() 之前的状态。组可以嵌套。
添加 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 () to write the array in the first place.
另请参阅 beginWriteArray (), endArray ()，和 setArrayIndex ().
添加 prefix 到当前组并开始写入数组大小 size 。若 size 为 -1 (默认)，它是基于所写条目的索引自动确定的。
若某组键多次出现，则可以使用数组来让您的生活变得更轻松。例如，假设想要保存用户名和口令的可变长度列表。那么可以写：
struct Login { QString userName; QString password; }; QList<Login> logins; ... QSettings settings; settings.beginWriteArray("logins"); for (int i = 0; i < logins.size(); ++i) { settings.setArrayIndex(i); settings.setValue("userName", list.at(i).userName); settings.setValue("password", list.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 ().
返回包含可读取键的所有键顶层组的列表，读取使用 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 ().
返回所有顶层键的列表，可以被读取使用 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 ().
移除首要位置中的所有条目，关联此 QSettings 对象。
不移除回退位置条目。
若只想移除的条目在当前 group ()，使用 remove("") 代替。
另请参阅 remove () 和 setFallbacksEnabled ().
返回
true
若存在设置被称为
key
；否则返回 false。
若设置组使用 beginGroup (), key 被认为是相对于该组的。
注意：Windows 注册表和 INI 文件使用不区分大小写的键，而 macOS 和 iOS 的 CFPreferences API 使用区分大小写的键。要避免可移植性问题，见 区间和键句法 规则。
[static]
QSettings::Format
QSettings::
defaultFormat
()
返回用于存储设置的默认文件格式为 QSettings ( QObject *) 构造函数。若未设置默认格式， QSettings::NativeFormat 的使用。
该函数在 Qt 4.4 引入。
另请参阅 setDefaultFormat () 和 format ().
关闭已启动数组使用 beginReadArray () 或 beginWriteArray ().
另请参阅 beginReadArray () 和 beginWriteArray ().
重置组状态先前的相应 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).
返回
true
若回退被启用；返回
false
否则。
默认情况下，回退是启用的。
另请参阅 setFallbacksEnabled ().
返回写入设置的路径，使用此 QSettings 对象存储。
在 Windows，若格式为 QSettings::NativeFormat ，返回值是系统注册表路径，而非文件路径。
另请参阅 isWritable () 和 format ().
返回用于存储设置的格式。
该函数在 Qt 4.4 引入。
另请参阅 defaultFormat (), fileName (), scope (), organizationName ()，和 applicationName ().
返回当前组。
另请参阅 beginGroup () 和 endGroup ().
返回用于访问 INI 文件的编解码器。默认情况下，不使用编解码器，因此
nullptr
被返回。
该函数在 Qt 4.5 引入。
另请参阅 setIniCodec ().
返回
true
if
QSettings
只允许履行设置的原子保存和重新加载 (同步)。返回
false
若允许将设置内容直接保存到配置文件。
默认为
true
.
该函数在 Qt 5.10 引入。
另请参阅 setAtomicSyncRequired () 和 QSaveFile .
返回
true
若设置可以写入使用此
QSettings
对象；返回
false
否则。
为什么 isWritable() 可能返回 false 的原因之一是若 QSettings 运转于只读文件。
警告： 此函数并不完美可靠，因为文件权限可以随时改变。
另请参阅 fileName (), status ()，和 sync ().
返回用于存储设置的组织名称。
该函数在 Qt 4.4 引入。
另请参阅 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 and 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"); ... }
注意： 此函数是 thread-safe .
该函数在 Qt 4.1 引入。
另请参阅 setPath ().
移除设置 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 ().
返回用于存储设置的作用域。
该函数在 Qt 4.4 引入。
另请参阅 format (), organizationName ()，和 applicationName ().
将当前数组索引设为 i 。调用函数，譬如 setValue (), value (), remove ()，和 contains () 将操作该索引数组条目。
必须调用 beginReadArray () 或 beginWriteArray () 在可以调用此函数之前。
配置是否
QSettings
要求履行设置的原子保存和重新加载 (同步)。若
enable
自变量为
true
(默认)，
sync
() 只会履行同步原子操作。若这不可能，
sync
() 会失败且
status
() 将是错误条件。
把此特性设为
false
将允许
QSettings
直接写入配置文件并忽略任何错误尝试 (锁定它阻止试着同时写入的其它进程)。由于潜在破坏，应小心使用此选项，但在某些情况下是必需的，像
QSettings::IniFormat
配置文件 (存在于其它不可写目录下或 NTFS 备用数据流中)。
见 QSaveFile 了解有关特征的更多信息。
该函数在 Qt 5.10 引入。
另请参阅 isAtomicSyncRequired () 和 QSaveFile .
[static]
void
QSettings::
setDefaultFormat
(
QSettings::Format
format
)
将默认文件格式设为给定 format ，用于存储设置为 QSettings ( QObject *) 构造函数。
若未设置默认格式， QSettings::NativeFormat 被使用。见文档编制了解 QSettings 构造函数，查看构造函数是否会忽略此函数。
该函数在 Qt 4.4 引入。
另请参阅 defaultFormat () 和 format ().
把是否启用回退设为 b .
默认情况下，回退是启用的。
另请参阅 fallbacksEnabled ().
设置访问 INI 文件的编解码器 (包括
.conf
文件在 Unix) 到
codec
。编解码器被用于解码从 INI 文件读取的任何数据，和对写入文件的任何数据进行编码。默认情况下，不使用编解码器，和使用标准 INI 转义序列编码非 ASCII 字符。
警告： 之后必须立即设置编解码器当创建 QSettings 对象，在访问任何数据之前。
该函数在 Qt 4.5 引入。
另请参阅 iniCodec ().
这是重载函数。
设置访问 INI 文件的编解码器 (包括
.conf
文件在 Unix) 到
QTextCodec
为指定编码通过
codecName
。常见值对于
codecName
包括 ISO 8859-1、UTF-8 及 UTF-16。若编码无法识别，则什么都不发生。
该函数在 Qt 4.5 引入。
另请参阅 QTextCodec::codecForName ().
[static]
void
QSettings::
setPath
(
QSettings::Format
format
,
QSettings::Scope
scope
, const
QString
&
path
)
设置用于存储设置的路径为给定 format and scope ，到 path 。 format 可以是自定义格式。
下表汇总了默认值：
| 平台 | 格式 | 作用域 | Path |
|---|---|---|---|
| Windows | IniFormat | UserScope |
FOLDERID_RoamingAppData
|
| SystemScope |
FOLDERID_ProgramData
|
||
| Unix | NativeFormat , IniFormat | UserScope |
$HOME/.config
|
| SystemScope |
/etc/xdg
|
||
| Qt for Embedded Linux | NativeFormat , IniFormat | UserScope |
$HOME/Settings
|
| SystemScope |
/etc/xdg
|
||
| macOS 和 iOS | IniFormat | UserScope |
$HOME/.config
|
| SystemScope |
/etc/xdg
|
默认
UserScope
路径在 Unix、macOS 及 iOS (
$HOME/.config
或 $HOME/Settings) 可以由用户覆盖通过设置
XDG_CONFIG_HOME
环境变量。默认
SystemScope
路径在 Unix、macOS 及 iOS (
/etc/xdg
) 可以被覆盖当构建 Qt 库使用
configure
脚本的
-sysconfdir
标志 (见
QLibraryInfo
了解细节)。
设置 NativeFormat 路径在 Windows、macOS 及 iOS，无效。
警告： 此函数不影响现有 QSettings 对象。
该函数在 Qt 4.1 引入。
另请参阅 registerFormat ().
设置值为设置 key to 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 ，或 QSettings::NoError 若没有出现错误。
注意， QSettings 延迟履行某些操作。出于此原因，可能想要调用 sync () 以确保数据存储在 QSettings 被写入磁盘在调用 status() 之前。
另请参阅 sync ().
把任何未保存改变写入永久存储，并重新加载同时已被其它应用程序改变的任何设置。
此函数被自动调用从 QSettings 的析构函数和通过定期间隔的事件循环，因此，通常不需要自己调用它。
另请参阅 status ().
返回值为设置 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