The Qt Resource System

Qt資源體系采用平臺獨立機制來存儲應用程序執行時的二進制文件。這種機制在應用程序需要一些確定的文件(圖標、翻譯文件等等)而且又不想冒丟失文件的風險時是有用的。

資源體系依賴于 qmake, rcc (Qt's resource compiler), 和 QFile 的緊密協作。Qt 3 的 qembed 工具和 image collection 機制被廢除。

Resource Collection Files (.qrc)

與應用程序關聯的應用程序由 .qrc 文件來指定，它用XML記錄硬盤上的文件和對應的隨意指定的資源名稱，應用程序通過資源名稱來訪問資源。

一個.qrc 文件的例子：

 <!DOCTYPE RCC><RCC version="1.0">
<qresource>
<file>images/copy.png</file>
<file>images/cut.png</file>
<file>images/new.png</file>
<file>images/open.png</file>
<file>images/paste.png</file>
<file>images/save.png</file>
</qresource>
</RCC>

 .qrc 文件中列出的資源文件是程序的源碼樹的一部分。指定的路徑是 .qrc 文件所在目錄的相對路徑。注意，列出的資源文件必須位于 .qrc 文件所在目錄或者其子目錄下。

資源數據也能被編譯進二進制文件中，因此應用程序代碼可以立即訪問；也可以創建一個二進制資源，稍后在程序中登記了資源體系的代碼中指定。

缺省時，程序可以用資源在源碼樹中的名稱加一個 :/ 前綴來訪問它。例如，在程序的源碼樹中是 images/cut.png 的文件可以通過 :/images/cut.png 來訪問。但也可以用 file 標簽中的 alias 屬性來指定：

 <file alias="cut-img.png">images/cut.png</file>

這時該文件可以通過 :/cut-img.png 來訪問。也可以在 .qrc 文件中用 qresource 標簽的 prefix 屬性：它可以為 .qrc 文件中所有文件指定一個前綴：

 <qresource prefix="/myresources">
<file alias="cut-img.png">images/cut.png</file>
</qresource>

這時該文件可以用 :/myresources/cut-img.png 訪問。

有些資源，像翻譯文件和圖標，需要隨著用戶的本地配置而變化。這可以在 qresource 標簽的 lang 屬性中指定一個合適的本地化字串來實現。例如：

 <qresource>
<file>cut.jpg</file>
</qresource>
<qresource lang="fr">
<file alias="cut.jpg">cut_fr.jpg</file>
</qresource>

如果用戶的本地化設置是 French (也就是說，QLocale::system().name() returns "fr_FR")，:/cut.jpg 就會引用 cut_fr.jpg 圖像。對于其他本地化設置，仍然用 cut.jpg 。

本地化字串的使用格式參見 QLocale 文檔。

External Binary Resources

為創建一個外部二進制資源，需要通過向 rcc 傳遞 -binary 開關來生成資源數據(一般是.rcc擴展名)。然后可以用 QResource API 來注冊資源。

例如，一個 .qrc 文件指定的資源數據集可以用下面方法編譯：

 rcc -binary myresource.qrc -o myresource.rcc

應用程序中，用下面的代碼注冊資源：

 QResource::registerResource("/path/to/myresource.rcc");

Compiled-In Resources

必須在應用程序的 .pro 文件中指定.qrc 文件， qmake 才能知道并將資源編譯進二進制文件。例如：

 RESOURCES     = application.qrc

qmake 將產生make規則來生成一個叫做 qrc_application.cpp 的文件并把它鏈接到應用程序中。該文件中，圖像和其他資源的所有數據被以壓縮二進制數據存進靜態C++數組中。 .qrc 文件被改變或者它引用的文件中的某一個被改變時， qrc_application.cpp 自動重新生成。若你沒有使用 .pro 文件，你也可以手動調用 rcc 或者在你的編譯系統中添加創建規則。

通常，Qt直接將數據存儲在可執行文件中，甚至在Windows和Mac OS X這些提供資源本地支持的操作系統中也是這樣。這可能會在未來的Qt版本中改變。

Using Resources in the Application

應用程序中，絕大多數地方都可以用資源路徑代替原始文件系統路徑。尤其是在 QIcon, QImage, or QPixmap 構造器中可以傳遞資源路徑來代替文件名稱：

     cutAct = new QAction(QIcon(":/images/cut.png"), tr("Cu&t"), this);

參見示例Application，它用Qt資源體系存儲圖標。

在內存中，資源被用資源對象樹來描述。該樹在啟動時自動構建并用QFile來解析資源路徑。可以用":/" 初始化的 QDir 來從資源樹的根部開始瀏覽。

Qt資源支持搜索路徑列表概念。若用 ":"代替":/"做前綴來引用一個資源，資源將被用搜索路徑列表查詢。啟動時搜索路徑列表是空的，調用 QDir::addResourceSearchPath() 可以添加路徑。

If you have resources in a static library，必須用.qrc 文件的base name作參數調用 Q_INIT_RESOURCE() 來強制初始化資源。例如：

     int main(int argc, char *argv[])
{
QApplication app(argc, argv);
Q_INIT_RESOURCE(graphlib);
...
return app.exec();
}

同樣地，若你需要顯式卸載一個資源集(因插件被卸載或資源失效)，需要用與前面相同的base name為參數調用Q_CLEANUP_RESOURCE() 來強制移除資源。