文章目錄

• 詳述
• • 基本用法
  • QVariant和GUI類型
  • Section 和 Key 的語法
  • 后備機制
  • 恢復GUI應用程序的狀態
  • 同時從多個線程或進程訪問設置
  • 特定于平臺的說明
  • • 應用程序設置的存儲位置
    • 直接訪問INI和.plist文件
    • 直接訪問Windows注冊表
    • 在Windows上訪問通用注冊表設置
    • 平臺限制
• 公共類型
• 公共函數
• 靜態公共函數
• 重新實現的受保護的函數

QSettings 類

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

Header:#include < QSettings >

qmake:	QT += core
Since:
Inherits:	QObject
Inherited By:

詳述

用戶通常希望應用程序在會話中記住它的設置(窗口大小和位置、選項等)。這些信息通常存儲在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域名時，在macOS和iOS上使用它而不是組織名稱，因為macOS和iOS應用程序通常使用Internet域名來標識自己。如果沒有設置域名，則從該組織名稱派生出一個假域名。有關詳細信息，請參閱下面特定于平臺的說明。)

QSettings存儲設置。每個設置由一個指定設置名稱(鍵)的QString和一個存儲與鍵關聯的數據的QVariant組成。要編寫設置，使用setValue()。例如:

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

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

你可以使用value()返回設置的值:

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

如果沒有指定名稱的設置，QSettings將返回一個空的QVariant(可以轉換為整數0)。

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

• 要測試給定的鍵是否存在，調用contains()。
• 要移除與鍵相關聯的設置，調用remove()。
• 要獲得所有鍵的列表，可以調用allKeys()。
• 要刪除所有鍵，調用clear()。

QVariant和GUI類型

因為QVariant是Qt核心模塊的一部分，所以它不能提供對QColor、QImage和QPixmap等數據類型的轉換功能，這些數據類型都是Qt GUI的一部分。換句話說，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);

使用qRegisterMetaType()和qregistermetatypestreamoperator()注冊的自定義類型可以使用QSettings存儲。

Section 和 Key 的語法

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

• 始終使用相同的大小寫引用相同的鍵。 例如，如果在代碼中的某個地方將鍵稱為“text fonts”，則不要在其他地方將其稱為“text fonts”。
• 避免使用除大小寫外相同的鍵名。 例如，如果您有一個名為 “MainWindow” 的鍵，請不要嘗試將另一個鍵另存為“ mainwindow”。
• 在節或鍵名中不要使用斜杠（“ /”和“ \”）； 反斜杠字符用于分隔子鍵（請參見下文）。 在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還支持 “array” 概念。 有關詳細信息，請參見beginReadArray() 和beginWriteArray() 。

后備機制

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

Star Runner應用程序的用戶特定位置

MySoft所有應用程序的用戶特定位置

Star Runner應用程序的系統范圍的位置

MySoft為所有應用程序提供的系統范圍的位置

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

如果在第一個位置無法找到一個鍵，則在第二個位置繼續搜索，依此類推。這使您能夠存儲系統范圍或組織范圍的設置，并在每個用戶或每個應用程序的基礎上覆蓋它們。要關閉這個機制，調用setFallbacksEnabled(false)。

盡管來自所有四個位置的鍵都可用于讀取，但只有第一個文件(當前應用程序的用戶特定位置)可用于寫入。要寫入任何其他文件，省略應用程序名稱和/或指定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返回。

Settings Editor example 允許您嘗試不同的設置位置，并打開或關閉后背機制。

恢復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() 來恢復窗口幾何的討論，請參見窗口幾何。

必須從主窗口的構造函數和close事件處理程序中調用readSettings() 和writeSettings() 函數，如下所示：

MainWindow::MainWindow(){...readSettings();}void MainWindow::closeEvent(QCloseEvent *event){if (userReallyWantsToQuit()) {writeSettings();event->accept();} else {event->ignore();}}

有關使用QSettings的獨立示例，請參見 “Application Example ” 示例。

同時從多個線程或進程訪問設置

QSettings是可重入的。這意味著您可以同時在不同的線程中使用不同的QSettings對象。即使QSettings對象引用磁盤上的相同文件（或系統注冊表中的相同條目），也可以保證這一點。如果通過一個QSettings對象修改了設置，則該更改將立即在任何在同一位置運行且處于同一進程中的其他QSettings對象中可見。

只要滿足某些條件，就可以從不同的進程（可以是同時運行的應用程序的不同實例，也可以是不同的應用程序）安全地使用QSettings來讀寫相同的系統位置。對于QSettings :: IniFormat，它使用咨詢文件鎖定和智能合并算法來確保數據完整性。工作的條件是可寫配置文件必須是常規文件，并且必須位于當前用戶可以在其中創建新的臨時文件的目錄中。如果不是這種情況，則必須使用setAtomicSyncRequired() 關閉安全裝置。

請注意，sync() 導入其他進程所做的更改（ 除了從此QSettings寫入更改之外 ）。

特定于平臺的說明

應用程序設置的存儲位置

如“后備機制”部分所述，QSettings會將應用程序的設置存儲在最多四個位置，具體取決于設置是用戶特定的還是系統范圍的，以及設置是特定于應用程序的還是組織范圍的。 為簡單起見，我們假設該組織稱為MySoft，而該應用程序稱為Star Runner。

在Unix系統上，如果文件格式為NativeFormat，則默認使用以下文件：

• $ HOME / .config / MySoft / Star Runner.conf（用于嵌入式Linux的Qt：$ HOME / Settings / MySoft / Star Runner.conf）
• $ HOME / .config / MySoft.conf（嵌入式Linux的Qt：?$HOME / Settings / MySoft.conf）
• 對于$ XDG_CONFIG_DIRS中的每個目錄< dir >：< dir> / MySoft / Star Runner.conf
• 對于$ XDG_CONFIG_DIRS中的每個目錄< dir>：< 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（用于嵌入式Linux的Qt：$ HOME / Settings / MySoft / Star Runner.ini）

$ HOME / .config / MySoft.ini（用于嵌入式Linux的Qt：$ HOME / Settings / MySoft.ini）

對于?$ XDG_CONFIG_DIRS中的每個目錄< dir>：< dir> / MySoft / Star Runner.ini

對于$ XDG_CONFIG_DIRS中的每個目錄< dir>：< 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_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，設置編輯器示例和應用程序示例。

公共類型

enum Format
QSettings使用的存儲格式。

typedef ReadFunc

enum Scope

typedef SettingsMap

enum Status

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

總結

以上是生活随笔為你收集整理的QSettings 类【官翻】的全部內容，希望文章能夠幫你解決所遇到的問題。

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