當前位置：首頁 > 编程资源 > 编程问答 >内容正文

编程问答

QSettings Class:提供与平台无关的持久性应用程序设置

發布時間：2024/1/1 编程问答 27 豆豆

生活随笔收集整理的這篇文章主要介紹了 QSettings Class:提供与平台无关的持久性应用程序设置小編覺得挺不錯的,現在分享給大家,幫大家做個參考.

QSettings Class

QSettings類提供與平臺無關的持久性應用程序設置。

Header:	#include <QSettings>
qmake:	QT += core
Inherits:	QObject

注意：此類中的所有函數都是可重載的。

注意：這些函數也是線程安全的。

Public Types：

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

Public Functions：

?	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

Static Public Members

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)

Reimplemented Protected Functions保護方法

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和一個QVariant組成，該QString指定設置的名稱（鍵），該QVariant存儲與該鍵關聯的數據。要編寫設置，請使用setValue（）。例如：

settings.setValue("editor/wrapMargin", 68);

如果已經存在具有相同鍵的設置，則現有值將被新值覆蓋。為了提高效率，更改可能不會立即保存到永久存儲中。（您始終可以調用sync（）提交更改。）

您可以使用value（）返回設置的值：

int margin = settings.value("editor/wrapMargin").toInt();

如果沒有具有指定名稱的設置，則QSettings返回一個空QVariant（可以將其轉換為整數0）。您可以通過將第二個參數傳遞給value（）來指定另一個默認值：

int margin = settings.value("editor/wrapMargin", 80).toInt();

要測試給定鍵值是否存在，請調用contains（）。要刪除與鍵關聯的設置，請調用remove（）。要獲取所有鍵的列表，請調用allKeys（）。要刪除所有鍵，請調用clear（）。

QVariant和GUI類型

由于QVariant是Qt Core模塊的一部分，因此它無法提供對Qt GUI的一部分的數據類型（例如QColor，QImage和QPixmap）的轉換功能。換句話說，在QVariant中沒有toColor（），toImage（）或toPixmap（）函數。

相反，您可以使用QVariant :: value（）模板函數。例如：

QSettings settings("MySoft", "Star Runner"); QColor color = settings.value("DataPump/bgcolor").value<QColor>();

對于QVariant支持的所有數據類型，包括與GUI相關的類型，將自動進行逆轉換（例如，從QColor到QVariant）：

QSettings settings("MySoft", "Star Runner"); QColor color = palette().background().color(); settings.setValue("DataPump/bgcolor", color);

可以使用QSettings存儲使用qRegisterMetaType（）和qRegisterMetaTypeStreamOperators（）注冊的自定義類型。

Section and Key語法：鍵值和鍵語法

設置鍵可以包含任何Unicode字符。 Windows注冊表和INI文件使用不區分大小寫的鍵，而macOS和iOS上的CFPreferences API使用不區分大小寫的鍵。為避免可移植性問題，請遵循以下簡單規則：

總是使用相同的情況引用相同的鍵。
避免使用除大小寫外相同的鍵名。
不要在鍵值名或鍵名中使用斜杠（“/”和“\”）；反斜杠字符用于分隔子鍵（見下文）。在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（）。

后備機制

假設您已經創建了一個QSettings對象，其組織名稱為MySoft，應用程序名稱為Star Runner。查找值時，將按此順序搜索最多四個位置：

Star Runner應用程序的用戶特定位置
MySoft所有應用程序的用戶特定位置
Star Runner應用程序在系統范圍內的位置
MySoft在所有應用程序的系統范圍內的位置

（有關Qt支持的不同平臺上這些位置的信息，請參閱下面的特定于平臺的說明。）

如果在第一個位置找不到鍵，則在第二個位置繼續搜索，依此類推。這使您可以存儲系統范圍或組織范圍的設置，并可以基于每個用戶或每個應用程序覆蓋它們。要關閉此機制，請調用setFallbacksEnabled（false）。

盡管可以從所有四個位置讀取鍵，但是只能訪問第一個文件（應用程序的用戶特定位置）進行寫入。要寫入任何其他文件，請省略應用程序名稱 and/or 指定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”表示該位置在讀取時用作備用。

Locationsobj1obj2obj3obj4

1. User, Application	X	?	?	?
2. User, Organization	o	X	?	?
3. System, Application	o	?	X	?
4. System, Organization	o	o	o	X

這種機制的優點在于，它可以在Qt支持的所有平臺上運行，并且仍然為您提供了很大的靈活性，而無需您指定任何文件名或注冊表路徑。

如果要在所有平臺上使用INI文件而不是本機API，則可以將QSettings :: IniFormat作為第一個參數傳遞給QSettings構造函數，然后是范圍，組織名稱和應用程序名稱：

QSettings settings(QSettings::IniFormat, QSettings::UserScope,"MySoft", "Star Runner");

請注意，從INI文件讀取設置時不會保留類型信息。所有值將作為QString返回。

設置編輯器示例可讓您嘗試不同的設置位置，以及啟用或禁用后備機制。

恢復GUI應用程序的狀態

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（）來恢復窗口幾何的討論，請參見窗口幾何：Window Geometry?。

必須從主窗口的構造函數和close事件處理程序中調用readSettings（）和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會將應用程序的設置最多存儲在四個位置，具體取決于設置是用戶特定的還是系統范圍的，以及設置是特定于應用程序的還是組織范圍的。為了簡單起見，我們假設該組織稱為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)

for each directory <dir> in $XDG_CONFIG_DIRS:?<dir>/MySoft/Star Runner.conf

for each directory <dir> in $XDG_CONFIG_DIRS:?<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)

for each directory <dir> in $XDG_CONFIG_DIRS:?<dir>/MySoft/Star Runner.ini

for each directory <dir> in $XDG_CONFIG_DIRS:?<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_為前綴的標識符是特殊項目ID列表，將傳遞給Win32 API函數SHGetKnownFolderPath（）以獲得相應的路徑。

FOLDERID_RoamingAppData通常指向C：\ Users \ User Name \ AppData \ Roaming，也由環境變量％APPDATA％顯示。

FOLDERID_ProgramData通常指向C：\ ProgramData。

如果文件格式為IniFormat，則在應用程序的主目錄中為“ Settings / MySoft / Star Runner.ini”。

.ini和.conf文件的路徑可以使用setPath（）進行更改。在Unix，macOS和iOS上，用戶可以通過設置XDG_CONFIG_HOME環境變量來覆蓋它們。有關詳細信息，請參見setPath（）。

直接訪問INI和.plist文件

有時您確實想訪問存儲在特定文件或注冊表路徑中的設置。在所有平臺上，如果要直接讀取INI文件，則可以使用QSettings構造函數，該構造函數以文件名作為第一個參數，并傳遞QSettings :: IniFormat作為第二個參數。例如：

QSettings settings("/home/petra/misc/myapp.ini",QSettings::IniFormat);

然后，您可以使用QSettings對象讀取和寫入文件中的設置。

在macOS和iOS上，您可以通過傳遞QSettings :: NativeFormat作為第二個參數來訪問屬性列表.plist文件。例如：

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上，鍵可能同時具有值和子鍵。通過使用“默認”或“”可以訪問其默認值。代替子項：

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”，并用連字符替換空格和其他非法字符。如果要指定其他域名，請在main（）函數中調用QCoreApplication :: setOrganizationDomain（），QCoreApplication :: setOrganizationName（）和QCoreApplication :: setApplicationName（），然后使用默認的QSettings構造函數。另一種解決方案是使用預處理器指令，例如：

#ifdef Q_OS_MACQSettings settings("grenoullelogique.fr", "Squash"); #elseQSettings settings("Grenoulle Logique", "Squash"); #endif

在macOS上，訪問不屬于當前用戶（即SystemScope）的設置的權限已隨10.7（Lion）更改。在該版本之前，具有管理員權限的用戶可以訪問這些權限。對于10.7和10.8（Mountain Lion），只有root可以。但是，10.9（Mavericks）再次更改了該規則，但僅適用于本機格式（plist文件）。

另請參見QVariant，QSessionManager，設置編輯器示例和應用程序示例。

成員類型文檔

枚舉QSettings :: Format

此枚舉類型指定QSettings使用的存儲格式。

ConstantValueDescription

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的操作，但以下情況除外：

如果您存儲QVariant無法轉換為QString的類型（例如QPoint，QRect和QSize），則Qt使用基于@的語法對類型進行編碼。例如：

pos = @Point(100 100)

為了最大程度地減少兼容性問題，任何未出現在值的第一個位置或其后沒有Qt類型（點，矩形，大小等）的@均被視為普通字符。

盡管反斜杠是INI文件中的特殊字符，但是大多數Windows應用程序都不會在文件路徑中轉義反斜杠（\）：

windir = C:\Windows

QSettings始終將反斜杠視為特殊字符，并且不提供用于讀取或寫入此類條目的API。

INI文件格式對密鑰的語法有嚴格的限制。 Qt通過使用％作為鍵中的轉義字符來解決此問題。另外，如果您保存一個頂級設置（其中沒有斜杠的鍵，例如“ someKey”），它將顯示在INI文件的“常規”部分中。為避免覆蓋其他鍵，如果使用諸如“ General / someKey”之類的鍵進行保存，則該鍵將位于“％General”部分，而不是“ General”部分。
遵循我們應該在接受的內容上保持自由，在生成的內容上保持保守的理念，QSettings將接受Latin-1編碼的INI文件，但生成純ASCII文件，其中非ASCII值使用標準INI轉義序列進行編碼。為了使INI文件更具可讀性（但兼容性可能較低），請調用setIniCodec（）。

另請參見registerFormat（）和setPath（）。

typedef QSettings::ReadFunc

Typedef指向具有以下簽名的函數的指針：

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

ReadFunc在registerFormat（）中用作指向讀取一組鍵/值對的函數的指針。 ReadFunc應該一次性讀取所有選項，并返回SettingsMap容器中的所有設置，該容器最初為空。

另請參見WriteFunc和registerFormat（）。

enum QSettings::Scope

該枚舉指定設置是用戶特定的還是由同一系統的所有用戶共享的。

ConstantValueDescription

QSettings::UserScope	0	Store settings in a location specific to the current user (e.g., in the user's home directory).
QSettings::SystemScope	1	Store settings in a global location, so that all users on the same machine access the same set of settings.

另請參見setPath（）。

typedef QSettings::SettingsMap

Typedef for?QMap<QString,?QVariant>.

另請參見registerFormat（）。

enum QSettings::Status

可以使用以下狀態值：

ConstantValueDescription

QSettings::NoError	0	沒有發生錯誤。
QSettings::AccessError	1	發生訪問錯誤（例如，嘗試寫入只讀文件）。
QSettings::FormatError	2	發生格式錯誤（例如，加載格式錯誤的INI文件）。

另請參見status（）。

typedef QSettings::WriteFunc

Typedef指向具有以下簽名的函數的指針：

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

WriteFunc在registerFormat（）中用作指向寫入一組鍵/值對的函數的指針。 WriteFunc僅被調用一次，因此您需要一次性輸出設置。

另請參見ReadFunc和registerFormat（）。

成員函數文檔

QSettings::QSettings(QSettings::Scope?scope,?QObject?*parent?= nullptr)

構造QSettings對象的方式與QSettings（QObject*parent）相同，但具有給定的作用域。

Qt 5.13中引入了此功能。
另請參見QSettings（QObject*parent）。

QSettings::QSettings(QObject?*parent?= nullptr)

構造一個QSettings對象，用于通過調用QCoreApplication：：setOrganizationName（）、QCoreApplication：：setOrganizationDomain（）和QCoreApplication：：setApplicationName（）訪問先前設置的應用程序和組織的設置。

作用域是QSettings：：UserScope，格式是default format（）（默認為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(const?QString?&fileName,?QSettings::Format?format,?QObject?*parent?= nullptr)

構造一個QSettings對象，用于使用父級訪問文件fileName中存儲的設置。如果文件不存在，則創建該文件。

如果format是QSettings：：NativeFormat，則fileName的含義取決于平臺。在Unix上，file name是INI文件的名稱。在macOS和iOS上，file name是.plist文件的名稱。在Windows上，fileName是系統注冊表中的一個路徑。

如果format是QSettings：：IniFormat，file name是INI文件的名稱。

警告：提供此功能是為了方便。它可以很好地訪問Qt生成的INI或.plist文件，但在其他程序生成的此類文件中發現的某些語法可能會失敗。尤其要注意以下限制：

QSettings不提供讀取INI“path”條目的方法，即帶有非轉義斜線字符的條目。（這是因為這些條目不明確，無法自動解析。）
在INI文件中，QSettings在某些上下文中使用@字符作為元字符來編碼Qt特定的數據類型（例如，@Rect），因此當它出現在純INI文件中時，可能會誤解它。

另請參見fileName（）。

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

構造一個QSettings對象，用于從名為organization的組織和父級訪問名為application的應用程序的設置。

如果作用域是QSettings：：user scope，則QSettings對象首先搜索用戶特定的設置，然后作為回退搜索系統范圍的設置。如果scope是QSettings：：SystemScope，那么QSettings對象將忽略用戶特定的設置并提供對系統范圍設置的訪問。

存儲格式設置為QSettings：：NativeFormat（即在調用此構造函數之前調用setDefaultFormat（）無效）。

如果未指定應用程序名稱，則QSettings對象將僅訪問組織范圍的位置。

另請參見setDefaultFormat（）。

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

構造一個QSettings對象，用于從名為organization的組織和父級訪問名為application的應用程序的設置。

例子：

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

作用域設置為QSettings：：UserScope，格式設置為QSettings：：NativeFormat（即在調用此構造函數之前調用setDefaultFormat（）無效）。

另請參見setDefaultFormat（）和回退機制。

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

返回用于存儲設置的應用程序名。
Qt 4.4中引入了此功能。
另請參見QCoreApplication：：applicationName（）、format（）、scope（）和organizationName（）。

void?QSettings::beginGroup(const?QString?&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

Call endGroup（）將當前組重置為相應beginGroup（）調用之前的值。可以嵌套組。

另請參見endGroup（）和group（）。

int?QSettings::beginReadArray(const?QString?&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(const?QString?&prefix,?int?size?= -1)

將前綴添加到當前組并開始寫入大小為的數組。如果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（）。

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對象讀取的所有頂級鍵的列表。

實例：

如果使用beginGroup（）設置組，則返回該組中的頂級鍵，而不帶組前綴：

settings.beginGroup("fridge"); keys = settings.childKeys(); // keys: ["color", "size"]

可以遞歸地使用childKeys（）和childGroups（）導航整個設置層次結構。

另請參見childGroups（）和allKeys（）。

void?QSettings::clear()

刪除與此QSettings對象關聯的主位置中的所有條目。

?不會刪除回退位置中的條目。

?如果只想刪除當前組（）中的條目，請改用remove（“”）。

另請參見remove（）和setFallBackenabled（）。

bool?QSettings::contains(const?QString?&key) const

如果存在名為key的設置，則返回true；否則返回false。

如果使用beginGroup（）設置組，則鍵將被視為相對于該組。

請注意，Windows注冊表和INI文件使用不區分大小寫的鍵，而macOS和iOS上的CFPreferences API使用區分大小寫的鍵。要避免可移植性問題，請參閱一節和關鍵語法規則。

另請參見value（）和setValue（）。

[static]QSettings::Format?QSettings::defaultFormat()

返回用于存儲QSettings（QObject*）構造函數設置的默認文件格式。如果未設置默認格式，則使用QSettings：：NativeFormat。

Qt 4.4中引入了此功能。

另請參見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)?????? [override virtual protected]

重新實現：QObject：：event（QEvent*e）。

bool?QSettings::fallbacksEnabled() const

如果啟用了回退，則返回true；否則返回false。

默認情況下，啟用回退。

另請參見setFallbackenabled（）。

QString?QSettings::fileName() const

返回存儲使用此QSettings對象寫入的設置的路徑。

在Windows上，如果格式是QSettings：：NativeFormat，則返回值是系統注冊表路徑，而不是文件路徑。

另請參見isWritable（）和format（）。

QSettings::Format?QSettings::format() const

返回用于存儲設置的格式。

Qt 4.4中引入了此功能。

另請參見defaultFormat（）、fileName（）、scope（）、organizationName（）和applicationName（）。

QString?QSettings::group() const

返回當前組。

另請參見beginGroup（）和endGroup（）。

QTextCodec?*QSettings::iniCodec() const

返回用于訪問INI文件的編解碼器。默認情況下，不使用編解碼器，因此返回nullptr。

Qt 4.5中引入了此功能。

另請參見setIniCodec（）。

bool?QSettings::isAtomicSyncRequired() const

如果僅允許QSettings執行設置的原子保存和重新加載（同步），則返回true。如果允許將設置內容直接保存到配置文件，則返回false。

默認值為true。

Qt 5.10中引入了此功能。

另請參見setAtomicSyncRequired（）和QSaveFile。

bool?QSettings::isWritable() const

如果可以使用此QSettings對象寫入設置，則返回true；否則返回false。

isWritable（）可能返回false的一個原因是如果QSettings對只讀文件進行操作。

警告：此功能不完全可靠，因為文件權限可以隨時更改。

另請參見fileName（）、status（）和sync（）。

QString?QSettings::organizationName() const

返回用于存儲設置的組織名稱。

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。

擴展名是與格式關聯的文件擴展名（不帶“.”）。

readFunc和writeFunc參數是指向讀寫一組鍵/值對的函數的指針。讀寫函數的QIODevice參數始終以二進制模式打開（即，不帶QIODevice：：Text標志）。

case sensitive參數指定鍵是否區分大小寫。這在使用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");... }

注意：這個函數是線程安全的。

Qt 4.1中引入了此函數。

另請參見setPath（）。

void?QSettings::remove(const?QString?&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（）中的所有key。例如：

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"]

另請參見setValue（）、value（）和contains（）。

QSettings::Scope?QSettings::scope() const

返回用于存儲設置的作用域。

Qt 4.4中引入了此功能。

另請參見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直接寫入配置文件，并忽略試圖將其鎖定在其他同時嘗試寫入的進程上的任何錯誤。由于可能會損壞，應小心使用此選項，但在某些情況下是必需的，例如存在于其他不可寫目錄或NTFS備用數據流中的QSettings：：IniFormat配置文件。

有關此功能的詳細信息，請參見QSaveFile。

Qt 5.10中引入了此功能。

另請參見isAtomicSyncRequired（）和QSaveFile。

[static]void?QSettings::setDefaultFormat(QSettings::Format?format)

將默認文件格式設置為給定格式，該格式用于存儲QSettings（QObject*）構造函數的設置。
如果未設置默認格式，則使用QSettings：：NativeFormat。請參閱您正在使用的QSettings構造函數的文檔，以查看該構造函數是否會忽略此函數。

Qt 4.4中引入了此功能。

另請參見defaultFormat（）和format（）。

void?QSettings::setFallbacksEnabled(bool?b)

設置是否對b啟用回退。

默認情況下，啟用回退。

另請參見fallbackenabled（）。

void?QSettings::setIniCodec(QTextCodec?*codec)

將用于訪問INI文件（包括Unix上的.conf文件）的編解碼器設置為編解碼器。編解碼器用于對從INI文件讀取的任何數據進行解碼，并對寫入該文件的任何數據進行編碼。默認情況下，不使用編解碼器，非ASCII字符使用標準INI轉義序列進行編碼。

警告：必須在創建QSettings對象后立即設置編解碼器，然后才能訪問任何數據。

Qt 4.5中引入了此功能。

另請參見iniCodec（）。

void?QSettings::setIniCodec(const?char?*codecName)

這是一個重載函數。

將用于訪問INI文件（包括Unix上的.conf文件）的編解碼器設置為由codecename指定的編碼的QTextCodec。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)

將用于存儲給定格式和范圍的設置的路徑設置為path。格式可以是自定義格式。
下表總結了默認值：

PlatformFormatScopePath

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 and iOS	IniFormat	UserScope	$HOME/.config
		SystemScope	/etc/xdg

用戶可以通過設置XDG\u config\u HOME環境變量來覆蓋Unix、macOS和iOS上的默認UserScope路徑（$HOME/.config或$HOME/Settings）。在使用configure腳本的-sysconfdir標志構建Qt庫時，可以覆蓋Unix、macOS和iOS上的默認SystemScope路徑（/etc/xdg）（有關詳細信息，請參閱QLibraryInfo）。

在Windows、macOS和iOS上設置NativeFormat路徑沒有效果。

警告：此函數不影響現有的QSettings對象。

Qt 4.1中引入了此函數。

另請參見registerFormat（）。

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

將“設置鍵”的值設置為“值”。如果鍵名已存在，則覆蓋上一個值。

?請注意，Windows注冊表和INI文件使用不區分大小寫的鍵，而macOS和iOS上的CFPreferences API使用區分大小寫的鍵。要避免可移植性問題，請參閱一節和關鍵語法規則。

實例：

QSettings settings; settings.setValue("interval", 30); settings.value("interval").toInt(); // returns 30settings.setValue("interval", 6.55); settings.value("interval").toDouble(); // returns 6.55

另請參見value（）、remove（）和contains（）。

QSettings::Status?QSettings::status() const

返回一個狀態代碼，指示QSettings遇到的第一個錯誤，如果沒有發生錯誤，則返回QSettings：：no error。
請注意，QSettings會延遲執行某些操作。因此，可能需要調用sync（）以確保在調用status（）之前將存儲在QSettings中的數據寫入磁盤。

另請參見sync（）。

void?QSettings::sync()

將任何未保存的更改寫入永久存儲，并重新加載同時由其他應用程序更改的任何設置。

這個函數是由QSettings的析構函數和事件循環定期自動調用的，所以通常不需要自己調用它。

另請參見?status().

QVariant?QSettings::value(const?QString?&key, const?QVariant?&defaultValue?= QVariant()) const

返回設置鍵的值。如果設置不存在，則返回defaultValue。

?如果未指定默認值，則返回默認的QVariant。

實例：

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 Class:提供与平台无关的持久性应用程序设置的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。

上一篇：爱普生6轴机械手原点调整 RC+7,0
下一篇：数位板驱动安装