簡介

QSettings類提供了持久的跨平臺應用程式設定。

使用者通常期望應用程式記住它的設定（視窗大小、位置等）所有會話。這些資訊通常儲存在Windows系統登錄檔，OS X和iOS的屬性列表檔案中。在Unix系統中，在缺乏標準的情況下，許多應用程式(包括KDE應用程式)使用INI文字檔案。

QSettings圍繞這些抽象技術，使我們能夠以便攜的方式儲存和恢復應用程式設定。它還支援自定義儲存格式。

QSettings API基於QVariant，可以儲存很多基礎的型別，比如 QString、QRect、QImage等。

如果你需要的是一個非永續性的基於記憶體結構，可以考慮使用QMap<QString, QVariant>

基本用法

當建立一個QSettings物件時，必須通過指定公司或組織名稱以及產品名稱，例如：公司名稱為：MySoft，產品名為：Star Runner，那麼可以用下列方式來構造QSettings物件：

QSettings settings("MySoft", "Star Runner");

QSettings物件既可以建立在棧上，也可以建立在堆（即使用new）上，構建和銷燬也非常快。

如果你的應用程式在很多地方使用QSettings，則可以使用QCoreApplication::setOrganizationName() 和 QCoreApplication::setApplicationName()

QCoreApplication::setOrganizationName("MySoft");
QCoreApplication::setOrganizationDomain("mysoft.com");
QCoreApplication::setApplicationName("Star Runner");
...
QSettings settings;

QSettings可以儲存一系列設定。每個設定包括指定設定名稱（鍵）的一個字串和一個與該鍵關聯的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() 刪除所有鍵

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

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();

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
• …

enum QSettings::Format

這個列舉型別指定QSettings所使用的儲存格式。

Unix中，NativeFor​​mat和IniFormat意思是一樣的，只是副檔名不同（NativeFor​​mat為.conf，IniFormat 為.ini）。

enum QSettings::Scope

該列舉指定設定是否使用者特定或同一系統的所有使用者共享。

void QSettings::setPath(Format format, Scope scope, const QString & path)

為給定格式和範圍設定用來儲存的路徑。對於路徑而言，該格式可以是自定義格式。

下表總結了預設值：

在Windows、OS X、iOS中設定NativeFormat沒有任何效果。

警告：此功能不會影響現有QSettings物件。

QVariant和GUI型別

因為QVariant是Qt Core模組的一部分，它不能提供轉換功能到資料型別-例如：QColor、QImage、 QPixmap，因為這是Qt GUI的一部分。換句話說，QVariant中沒有toColor()、toImage()、toPixmap()等介面。

相反，可以使用QVariant::value()或qVariantValue()模板函式。 例如：

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

逆轉換（例如，從QColor到QVariant）是自動通過QVariant支援的所有資料型別，包括GUI相關型別：

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

自定義型別註冊使用qRegisterMetaType()和qRegisterMetaTypeStreamOperators()可以使用QSettings儲存。

重點說明

設定中的鍵可以包含任何Unicode字元。Windows登錄檔和INI檔案使用對鍵不區分大小寫，而在OS X和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()設定，大多數功能的行為變化，組可以遞迴地設定。

後備機制

假設你用組織名MySoft、應用名Star Runner建立了一個QSettings物件，當檢視一個值時，依次搜尋四個地方：

1. 一個供Star Runner應用程式的使用者特定位置
2. 一個供MySoft所有應用程式的使用者特定位置
3. 一個供Star Runner應用程式的系統範圍位置
4. 一個供MySoft所有應用程式的系統範圍位置

如果一個鍵不能在第一位置被找到時，繼續在第二的位置搜尋，依此類推。這確保能夠儲存系統範圍或組織範圍內的設定，並在每個使用者或每個應用程式覆蓋它們，使用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”是指讀操作時被佔用當做後備。

這種機制的優點在於它可以在Qt支援的所有平臺執行，它仍然給我們一個很大的靈活性，無需指定任何檔名或登錄檔路徑。

如果想在所有平臺上不使用原生API來使用 INI檔案，可以通過 QSettings::IniFormat格式作為QSettings建構函式的第一個引數，其次是範圍，組織名，以及應用名：

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

可以參考：Settings Editor例子（可以體驗不同的設定-回退、開啟、關閉）。

儲存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();
}

可以參考： Window Geometry。為什麼呼叫QWidget::resize()和QWidget::move()更好，而不是QWidget::setGeometry()來恢復視窗的幾何形狀。

必須在MainWindow建構函式和關閉事件處理程式中呼叫readSettings()和writeSettings()函式，如下:

MainWindow::MainWindow()
{
    ...
    readSettings();
}

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

可以參考自帶的Application程式示例使用QSettings例子。

同時從多個執行緒或程序訪問QSettings

QSettings是可重入的，意味著可以同時在不同的執行緒中使用不同的QSettings物件，這保證QSettings物件操作同一磁碟上的檔案（或在系統登錄檔中的相同條目）。如果通過QSettings物件修改了一個設定，那麼對於操作在同一位置和存在相同的程序的其他QSettings物件來說，更改會立即可見。

QSettings可以由不同的程序（其可以是應用程式同時執行的不同例項或完全不同的應用程式）安全地使用-在相同的系統位置上進行讀寫，它使用勸告式檔案鎖和智慧合併演算法以確保資料的完整性，需要注意的是sync()由其他程序所做的更改。

特定平臺

應用程式設定的儲存位置

如上所提到的，在後背機制部分，QSettings為應用程式儲存的設定多達四個位置，這取決於設定是否是特定於使用者或系統範圍的，設定是否特定於應用或組織範圍的。為簡單起見，我們假設該組織被稱為MySoft並且應用程式被稱為Star Runner。

在Unix系統中，如果檔案格式是NativeFormat，預設使用以下檔案：

1. $HOME/.config/MySoft/Star Runner.conf (Qt for Embedded Linux: $HOME/Settings/MySoft/Star Runner.conf)
2. $HOME/.config/MySoft.conf (Qt for Embedded Linux: $HOME/Settings/MySoft.conf)
3. /etc/xdg/MySoft/Star Runner.conf
4. /etc/xdg/MySoft.conf

在Mac OS X版本10.2和10.3中，這些檔案所使用的預設值：

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

如果檔案格式是IniFormat,，以下檔案用於在Unix、Mac OS X，、和iOS：

1. $HOME/.config/MySoft/Star Runner.ini (Qt for Embedded Linux: $HOME/Settings/MySoft/Star Runner.ini)
2. $HOME/.config/MySoft.ini (Qt for Embedded Linux: $HOME/Settings/MySoft.ini)
3. /etc/xdg/MySoft/Star Runner.ini
4. /etc/xdg/MySoft.ini

在Windows中，使用以下檔案：

1. %APPDATA%\MySoft\Star Runner.ini
2. %APPDATA%\MySoft.ini
3. %COMMON_APPDATA%\MySoft\Star Runner.ini
4. %COMMON_APPDATA%\MySoft.ini

%APPDATA%路徑通常為：C:\Documents and Settings\All Users\Application Data
%COMMONAPPDATA%路徑通常為：C:\Documents and Settings\All Users\Application Data。

在黑莓手機只有一個檔案。如果檔案格式是IniFormat，這時”Settings/MySoft/Star Runner.ini”在應用程式的主目錄。

對於在.ini和conf檔案的路徑，可以使用的setPath()來改變。在Unix、Mac OS X、iOS中，使用者可以通過設定XDG_CONFIG_HOME環境變數替代他們。

訪問INI和.plist檔案

有時候，想在一個特定的檔案或登錄檔路徑中訪問儲存設定。在所有平臺上，如果想直接讀取INI檔案，可以使QSettings建構函式的第一個引數為檔名，第二個引數為QSettings::IniFormat。例如：

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

然後，就可以對檔案進行讀寫設定。
在OS X和iOS中，可以通過指定第二個引數為QSettings::NativeFormat訪問屬性列表的.plist檔案。例如：

QSettings settings("/Users/petra/misc/myapp.plist", QSettings::NativeFormat);

訪問Windows登錄檔

在Windows中，QSettings可以在系統登錄檔訪問由QSettings寫入的設定（或設定支援的格式，如字串資料）。通過使用一個登錄檔路徑和QSettings::NativeFormat來構建一個QSettings物件。例如：

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"

平臺限制

儘管QSettings試圖支援​​不同平臺，但還存在著一些差異，我們應該知道，當移植應用程式：

Windows系統登錄檔有以下限制：一個子項不能超過255個字元，一個條目的值不得超過16,383個字元，一個鍵的所有值不得超過65,535個字元。要解決這些侷限性的一種方法是使用IniFormat代替NativeFor​​mat儲存設定。

在OS X和iOS中，allKeys()將返回適用於所有應用程式的全域性設定一些額外的鍵。這些鍵可以使用value()讀取，但不能改變，只能跟蹤。呼叫setFallbacksEnabled(false) 將隱藏這些全域性設定。

在OS X和iOS，使用QSettings的CFPreferences API預計網際網路域名而不是組織名。為了提供一個統一的API，QSettings源於該組織名提供一個假域​​名（除非組織名已經是一個域名，如：OpenOffice.org）。該演算法追加”.com”到公司名，並用連字元替換空格和其他非法字元。如果你想指定不同的域名，在main()函式中呼叫QCoreApplication::setOrganizationDomain()、QCoreApplication::setOrganizationName()、QCoreApplication::setApplicationName()，然後使用預設的QSettings建構函式。
另一種解決方案是使用預處理指令，例如：

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