QSettings 类

QSettings 类提供平台无关的持久性应用程序设置。 更多...

头：	#include <QSettings>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake:	QT += core
继承：	QObject

• 所有成员列表，包括继承成员
• QSettings 属于 输入/输出和网络 .

注意： 此类的所有函数 可重入 .

注意： 这些函数也是 thread-safe :

• registerFormat (const QString &extension, QSettings::ReadFunc readFunc, QSettings::WriteFunc writeFunc, Qt::CaseSensitivity caseSensitivity)

公共类型

enum	Format { NativeFormat, Registry32Format, Registry64Format, IniFormat, WebLocalStorageFormat, …, InvalidFormat }
	ReadFunc
enum	Scope { UserScope, SystemScope }
	SettingsMap
enum	Status { NoError, AccessError, FormatError }
	WriteFunc

公共函数

	QSettings (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 (QSettings::Format format , QSettings::Scope scope , const QString & organization , const QString & application = QString(), QObject * parent = nullptr)
	QSettings (const QString & fileName , QSettings::Format format , QObject * parent = nullptr)
	QSettings (QObject * parent = nullptr)
	QSettings (QSettings::Scope scope , QObject * parent = nullptr)
virtual	~QSettings ()
QStringList	allKeys () const
QString	applicationName () const
void	beginGroup (QAnyStringView prefix )
int	beginReadArray (QAnyStringView prefix )
void	beginWriteArray (QAnyStringView prefix , int size = -1)
QStringList	childGroups () const
QStringList	childKeys () const
void	clear ()
bool	contains (QAnyStringView key ) const
void	endArray ()
void	endGroup ()
bool	fallbacksEnabled () const
QString	fileName () const
QSettings::Format	format () const
QString	group () const
bool	isAtomicSyncRequired () const
bool	isWritable () const
QString	organizationName () const
void	remove (QAnyStringView key )
QSettings::Scope	scope () const
void	setArrayIndex (int i )
void	setAtomicSyncRequired (bool enable )
void	setFallbacksEnabled (bool b )
void	setValue (QAnyStringView key , const QVariant & value )
QSettings::Status	status () const
void	sync ()
QVariant	value (QAnyStringView key , const QVariant & defaultValue ) const
QVariant	value (QAnyStringView key ) 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 和 GUI 类型

因为 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 () 拥有运算符为流化到和来自 QDataStream 可以使用 QSettings 来存储。

区间和键句法

设置键可以包含任何 Unicode 字符。Windows 注册表和 INI 文件使用不区分大小写的键，而在 macOS 和 iOS 上的 CFPreferences API 使用区分大小写的键。为避免可移植性问题，遵循这些简单规则：

1. 始终使用相同大小写，引用相同键。例如，若在代码中某个地方按 text fonts 引用键，就不要在其它地方按 Text Fonts 引用它。
2. 避免键名称恒等，除大小写外。例如，若拥有的键称为 MainWindow，就不要试着把另一个键另存为 mainwindow。
3. 不要使用斜线 (/ 和 \) 在区间和键名称中；反斜杠字符被用于分隔子键 (见下文)。在 Windows，\ 被 QSettings 转换成 /，从而使它们恒等。

可以使用 / 字符作为分隔符来形成分层键，类似 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 个位置：

1. 为 Star Runner 应用程序的特定用户位置
2. 由 MySoft 为所有应用程序的特定用户位置
3. 为 Star Runner 应用程序的系统范围位置
4. 由 MySoft 为所有应用程序的系统范围位置

(见 特定平台注意事项 了解在 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 。数值可以恢复使用 QString::toInt (), QString::toDouble () 和相关函数。

还原 GUI 应用程序的状态

QSettings 经常被用于存储 GUI 应用程序的状态。以下范例阐明如何使用 QSettings 去保存和还原应用程序主窗口的几何体。

void MainWindow::writeSettings()
{
    QSettings settings("Moose Soft", "Clipper");
    settings.beginGroup("MainWindow");
    settings.setValue("geometry", saveGeometry());
    settings.endGroup();
}
void MainWindow::readSettings()
{
    QSettings settings("Moose Soft", "Clipper");
    settings.beginGroup("MainWindow");
    const auto geometry = settings.value("geometry", QByteArray()).toByteArray();
    if (geometry.isEmpty())
        setGeometry(200, 200, 400, 400);
    else
        restoreGeometry(geometry)
    settings.endGroup();
}
					

见 窗口几何体 了解为什么更好的论述，调用 QWidget::resize () 和 QWidget::move () 而不是 QWidget::setGeometry () 去还原窗口几何体。

The 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::IniFormat ，它使用咨询文件锁定和智能合并算法，以确保数据的完整性。工作条件是可写配置文件必须为常规文件，且必须位于当前用户可以在其中创建新临时文件的目录下。若不是这种情况，就必须使用 setAtomicSyncRequired () 关闭安全性。

注意， sync () 导入由其它进程所造成的改变 (除从此 QSettings 写入改变外)。

特定平台注意事项

存储应用程序设置的位置

如提及在 回退机制 章节，QSettings 把应用程序设置存储在最多 4 位置，取决于设置是用户特定或系统范围，及设置是应用程序特定或组织范围。为简单起见，假定组织名为 MySoft，应用程序名为 Star Runner。

在 Unix 系统，若文件格式为 NativeFormat ，默认使用下列文件：

1. $HOME/.config/MySoft/Star Runner.conf
2. $HOME/.config/MySoft.conf
3. 对于每目录 <dir> 在 $XDG_CONFIG_DIRS： <dir>/MySoft/Star Runner.conf
4. 对于每目录 <dir> 在 $XDG_CONFIG_DIRS： <dir>/MySoft.conf

注意： 若 XDG_CONFIG_DIRS 未设置，默认值 /etc/xdg 被使用。

在 macOS 和 iOS，若文件格式为 NativeFormat ，默认情况下使用这些文件：

1. $HOME/Library/Preferences/com.MySoft.Star Runner.plist
2. $HOME/Library/Preferences/com.MySoft.plist
3. /Library/Preferences/com.MySoft.Star Runner.plist
4. /Library/Preferences/com.MySoft.plist

在 Windows， NativeFormat 设置存储在下列注册表路径：

1. HKEY_CURRENT_USER\Software\MySoft\Star Runner
2. HKEY_CURRENT_USER\Software\MySoft\OrganizationDefaults
3. HKEY_LOCAL_MACHINE\Software\MySoft\Star Runner
4. HKEY_LOCAL_MACHINE\Software\MySoft\OrganizationDefaults

注意： 在 Windows，对于运行在 WOW64 模式下的 32 位程序，设置存储在下列注册表路径： HKEY_LOCAL_MACHINE\Software\WOW6432node .

若文件格式为 NativeFormat ，这是 Settings/MySoft/Star Runner.conf 在应用程序 Home (主) 目录。

若文件格式为 IniFormat ，在 Unix、macOS 和 iOS 使用下列文件：

1. $HOME/.config/MySoft/Star Runner.ini
2. $HOME/.config/MySoft.ini
3. 对于每目录 <dir> 在 $XDG_CONFIG_DIRS： <dir>/MySoft/Star Runner.ini
4. 对于每目录 <dir> 在 $XDG_CONFIG_DIRS： <dir>/MySoft.ini

注意： 若 XDG_CONFIG_DIRS 未设置，默认值 /etc/xdg 被使用。

在 Windows，使用下列文件：

1. FOLDERID_RoamingAppData\MySoft\Star Runner.ini
2. FOLDERID_RoamingAppData\MySoft.ini
3. FOLDERID_ProgramData\MySoft\Star Runner.ini
4. 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 在应用程序 Home (主) 目录。

路径对于 .ini and .conf 文件可以改变使用 setPath ()。在 Unix、macOS 和 iOS，用户可以覆盖它们通过设置 XDG_CONFIG_HOME 环境变量；见 setPath () 了解细节。

直接访问 INI 和 .plist 文件

有时希望访问存储在特定文件 (或注册表路径) 中的设置。在所有平台，若希望直接读取 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 注册表

在 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 公共注册表设置

在 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 试图消除不同支持平台之间的差异，但要意识到当移植应用程序时仍有一些差异：

• Windows 系统注册表有以下限制：子键不能超过 255 个字符，条目的值不能超过 16,383 个字符，所有键的值不能超过 65,535 个字符。解决这些局限性的办法是存储设置使用 IniFormat 而不是 NativeFormat .
• 在 Windows，当使用 Windows 系统注册表时，QSettings 不保留值的原始类型。因此，值的类型可能改变，当设置新值时。例如，值采用类型 REG_EXPAND_SZ 将改变为 REG_SZ .
• 在 macOS 和 iOS， allKeys () 将为应用于所有应用程序的全局设置返回一些额外键。这些键可以被读取使用 value () 但无法改变，只有阴影。调用 setFallbacksEnabled (false) 将隐藏这些全局设置。
• 在 macOS 和 iOS，用于 QSettings 的 CFPreferences API 期望 Internet 域名，而不是组织名称。为提供统一 API, QSettings 从组织名称派生虚假域名 (除非该组织名称已经是域名，如 OpenOffice.org)。算法追加 .com 到公司名称，并采用连字符 (-) 替换空格和其它非法字符。若希望指定不同域名，调用 QCoreApplication::setOrganizationDomain (), QCoreApplication::setOrganizationName ()，和 QCoreApplication::setApplicationName () 在您的 main() 函数，然后使用默认 QSettings 构造函数。另一解决方案是使用预处理器指令，例如：

  #ifdef Q_OS_DARWIN
  
  
  QSettings
  
  
   settings(
  
  "grenoullelogique.fr"
  
  
  ,
  
  
  "Squash"
  
  );
  
  #else
  
  
  
  QSettings
  
  
   settings(
  
  "Grenoulle Logique"
  
  
  ,
  
  
  "Squash"
  
  );
  
  #endif
  
  							

• 在 macOS，访问不属于当前用户的设置的权限 (即 SystemScope ) 已于 10.7 (狮子) 版改变。在该版本之前，有 admin (管理员) 权限的用户可以访问这些。对于 10.7 和 10.8 (山狮) 版，只有 root 可以。然而，10.9 (小牛队) 版再次改变此规则，但只针对本机格式 (plist 文件)。

另请参阅 QVariant and QSessionManager .

成员类型文档编制

enum QSettings:: Format

此枚举类型指定存储格式，用于 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::WebLocalStorageFormat	4	WASM only: Store the settings in window.localStorage for the current origin. If cookies are not allowed, this falls back to the INI format. This provides up to 5MiB storage per origin, but access to it is synchronous and JSPI is not required.
QSettings::WebIndexedDBFormat	5	WASM only: Store the settings in an Indexed DB for the current origin. If cookies are not allowed, this falls back to the INI format. This requires JSPI, but provides more storage than WebLocalStorageFormat.
QSettings::InvalidFormat	16	特殊值的返回通过 registerFormat ().

在 Unix，NativeFormat 和 IniFormat 意味着相同事情，除文件扩展名不同外 ( .conf 为 NativeFormat， .ini 为 IniFormat)。

INI 文件格式是在所有平台 Qt 所支持的 Windows 文件格式。在缺乏 INI 标准的情况下，我们试着遵循 Microsoft 做法，但有以下例外：

• 若存储类型 QVariant 无法转换为 QString (如， QPoint , QRect ，和 QSize )，Qt 使用 @ 基句法以编码类型。例如：

  pos = @Point(100 100)
  							

  为最小化兼容性问题，任何 @ 未出现在值第一位置或之后未紧跟 Qt 类型 ( 点 , Rect , Size ，等) 被视为正常字符。

• 尽管反斜杠是 INI 文件中的特殊字符，但大多数 Windows 应用程序不转义反斜杠 ( \ ) 在文件路径：

  windir = C:\Windows
  							

  QSettings 始终视反斜杠为特殊字符，且不提供用于读取或写入这种条目的 API。

• INI 文件格式对键句法有严格限定。Qt 要解决这是通过使用 % 作为键中转义字符。此外，若保存顶层设置 (其中不带斜线的键，如 someKey)，它将出现在 INI 文件的 General 区间。为避免覆盖其它键，若使用如 General/someKey 的这种键保存某些事情，键将位于 %General 区间， not 在 General 区间。
• 与当今的大多数实现一样， QSettings will assume that 值 in the INI file are utf-8 encoded. This means that 值 will be decoded as utf-8 encoded entries and written back as utf-8. To retain backward compatibility with older Qt versions, keys in the INI file are written in %-encoded format, but can be read in both %-encoded and utf-8 formats.

兼容旧版 Qt

请注意，此行为方式不同于 QSettings behaved in versions of Qt prior to Qt 6. INI files written with Qt 5 or earlier are however fully readable by a Qt 6 based application (unless a ini codec different from utf8 had been set). But INI files written with Qt 6 will only be readable by older Qt versions if you set the "iniCodec" to a utf-8 textcodec.

另请参阅 registerFormat () 和 setPath ().

QSettings:: ReadFunc

Typedef 为指向采用以下签名的函数指针：

bool myReadFunc(QIODevice &device, QSettings::SettingsMap &map);
					

ReadFunc 用于 registerFormat() 作为指向读取一组键/值对的函数指针。 ReadFunc 应一次性读取所有选项，并返回所有设置在 SettingsMap 容器，其最初为空。

另请参阅 WriteFunc and registerFormat ().

enum QSettings:: Scope

此枚举指定设置是具体用户，还是由同一系统的所有用户共享。

常量	值	描述
QSettings::UserScope	0	将设置存储到当前用户的特定位置 (如：用户 Home 主目录)。
QSettings::SystemScope	1	将设置存储在全局位置，以便同一计算机中的所有用户访问相同设置集。

另请参阅 setPath ().

QSettings:: SettingsMap

typedef 对于 QMap < QString , QVariant >.

另请参阅 registerFormat ().

enum QSettings:: Status

下列状态值是可能的：

常量	值	描述
QSettings::NoError	0	没有出现错误。
QSettings::AccessError	1	发生访问错误 (如：试着写入只读文件)。
QSettings::FormatError	2	发生格式错误 (如：加载畸形 INI 文件)。

另请参阅 status ().

QSettings:: WriteFunc

Typedef 为指向采用以下签名的函数指针：

bool myWriteFunc(QIODevice &device, const QSettings::SettingsMap &map);
					

WriteFunc 用于 registerFormat() 作为指向写入一组键/值对的函数指针。 WriteFunc 仅调用一次，所以需要一次性输出设置。

另请参阅 ReadFunc and registerFormat ().

成员函数文档编制

QVariant QSettings:: value ( QAnyStringView key ) const

QVariant QSettings:: value ( QAnyStringView key , const QVariant & defaultValue ) const

返回值为设置 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
					

注意： In Qt versions prior to 6.4, this function took QString , not QAnyStringView .

另请参阅 setValue (), contains ()，和 remove ().

[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 () 和 回退机制 .

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

构造 QSettings 对象为访问应用程序设置称为 application 从组织称为 organization ，和采用父级 parent .

若 scope is QSettings::UserScope ，QSettings 对象首先搜索特定用户设置，在它搜索系统范围设置作为回退之前。若 scope is 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 is QSettings::UserScope ，QSettings 对象首先搜索特定用户设置，在它搜索系统范围设置作为回退之前。若 scope is QSettings::SystemScope ，QSettings 对象忽略特定用户设置并提供对系统范围设置的访问。

若 format is QSettings::NativeFormat ，本机 API 用于存储设置。若 format is QSettings::IniFormat ，使用 INI 格式。

若未给出应用程序名称，QSettings 对象将只访问组织范围的 locations .

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

构造 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，但可能失败当在发源于其它程序的这种文件中发现某些句法时。尤其，要意识到以下局限性：

• QSettings 不提供读取 INI path 条目 (即：带有未转义斜杠字符的条目) 的手段。这是由于这些条目有歧义，且无法自动解析。
• 在 INI 文件中，QSettings 使用 @ 字符作某些上下文元字符，以编码 Qt 特定数据类型 (如 @Rect )，因此，可能被误解当它出现在纯 INI 文件中时。

另请参阅 fileName ().

[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).

[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() 之前的状态。组可以嵌套。

注意： In Qt versions prior to 6.4, this function took QString , not QAnyStringView .

另请参阅 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 () 以首先写入数组。

注意： In Qt versions prior to 6.4, this function took QString , not QAnyStringView .

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

注意： In Qt versions prior to 6.4, this function took QString , not QAnyStringView .

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

返回 true 若存在设置被称为 key ；否则返回 false。

若组的设置是使用 beginGroup (), key 被认为是相对于该组的。

注意：Windows 注册表和 INI 文件使用不区分大小写的键，而 macOS 和 iOS 的 CFPreferences API 使用区分大小写的键。要避免可移植性问题，见 区间和键句法 规则。

注意： In Qt versions prior to 6.4, this function took QString , not QAnyStringView .

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

返回 true if QSettings 只允许履行设置的原子保存和重新加载 (同步)。返回 false 若允许将设置内容直接保存到配置文件。

默认为 true .

另请参阅 setAtomicSyncRequired () 和 QSaveFile .

bool QSettings:: isWritable () const

返回 true 若设置可以写入使用此 QSettings 对象；返回 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 .

The extension 是关联格式 (没有 .) 的文件扩展名。

The readFunc and writeFunc 参数是指向读写一组键/值对的函数指针。 QIODevice 读写函数参数始终以二进制模式打开 (即：没有 QIODevice::Text 标志)。

The 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 .

另请参阅 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 使用区分大小写的键。要避免可移植性问题，见 区间和键句法 规则。

注意： In Qt versions prior to 6.4, this function took QString , not QAnyStringView .

另请参阅 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 and scope ，到 path 。 format 可以是自定义格式。

下表汇总了默认值：

平台	格式	作用域	路径
Windows	IniFormat	UserScope	FOLDERID_RoamingAppData
		SystemScope	FOLDERID_ProgramData
Unix	NativeFormat , IniFormat	UserScope	$HOME/.config
		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 对象。

另请参阅 registerFormat ().

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

设置值为设置 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
					

注意： In Qt versions prior to 6.4, this function took QString , not QAnyStringView .

另请参阅 value (), remove ()，和 contains ().

QSettings::Status QSettings:: status () const

返回状态码指示遇到的首个错误通过 QSettings ，或 QSettings::NoError 若没有出现错误。

注意， QSettings 延迟履行某些操作。出于此原因，可能想要调用 sync () 以确保数据存储在 QSettings 被写入磁盘在调用 status() 之前。

另请参阅 sync ().

void QSettings:: sync ()

把任何未保存改变写入永久存储，并重新加载同时已被其它应用程序改变的任何设置。

此函数被自动调用从 QSettings 的析构函数和通过定期间隔的事件循环，因此，通常不需要自己调用它。

另请参阅 status ().

内容

• 公共类型

• 公共函数

• 静态公共成员

• 重实现保护函数

• 详细描述

• 基本用法

• QVariant 和 GUI 类型

• 区间和键句法

• 回退机制

• 还原 GUI 应用程序的状态

• 同时从多个线程 (或进程) 访问设置

• 特定平台注意事项