Das Qt-Ressourcensystem

Das Qt-Ressourcensystem ist ein plattformunabhängiger Mechanismus zum Einbinden von Ressourcendateien in eine Anwendung. Verwenden Sie es, wenn Ihre Anwendung stets einen bestimmten Satz an Dateien (wie Symbole, Übersetzungsdateien, Bilder) benötigt und Sie keine systemspezifischen Mittel zum Verpacken und Auffinden dieser Ressourcen nutzen möchten.

In der Regel werden die Ressourcendateien in die ausführbare Datei Ihrer Anwendung oder in Bibliotheken und Plugins eingebettet, die von der ausführbaren Datei der Anwendung geladen werden. Alternativ können die Ressourcendateien auch in einer externen Ressourcendatei gespeichert werden.

Das Ressourcensystem basiert auf einer engen Zusammenarbeit zwischen dem Qt-Resource Compiler „rcc“, dem Build-System und der Qt-Laufzeit-API.

Resource Compiler Der Qt XML-ph-0000@deepl.internaler (rcc)

Das Befehlszeilentool „Resource Compiler “ (rcc) liest Ressourcendateien ein und generiert entweder eine C++- oder Python-Quelldatei oder eine „ .rcc “-Datei.

Die Liste der Dateien und der zugehörigen Metadaten wird in Form einer Qt-Ressourcensammlungsdatei an rcc übergeben.

Standardmäßig generiert rcc C++-Quellcode, der anschließend als Teil einer ausführbaren Datei oder einer Bibliothek kompiliert wird. Die Option „ -g python “ generiert stattdessen Python-Quellcode. Die Option „ -binary “ generiert ein Binärarchiv, das üblicherweise in einer „ .rcc “-Datei gespeichert wird und zur Laufzeit geladen werden kann.

Qt-Ressourcensammlungsdatei (.qrc)

Eine „ .qrc “-Datei ist ein XML-Dokument, das lokale Dateien auflistet, die als Laufzeitressourcen eingebunden werden sollen. Sie dient als Eingabe für den Befehl „ rcc “.

Hier ist ein Beispiel für eine „ .qrc “-Datei:

<RCC>
    <qresource prefix="/">
        <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>

Jedes „ <file> “-Element im XML identifiziert eine Datei im Quellcode-Verzeichnisbaum der Anwendung. Der Pfad wird relativ zu dem Verzeichnis aufgelöst, das die Datei „ .qrc “ enthält.

Der Pfad wird standardmäßig auch verwendet, um den Inhalt der Datei zur Laufzeit zu identifizieren. Das heißt, die Datei „ copy.png “ ist im Ressourcensystem als „ :/images/copy.png “ oder „ qrc:/images/copy.png “ verfügbar. Informationen zum Überschreiben dieses Standardnamens zur Laufzeit finden Sie unter „Präfixe und Aliase“.

Qt Creator, Qt Design Studio, Qt Widgets Designer, Qt Extension for Visual Studio Code, und Qt Visual Studio Tools ermöglichen es Ihnen, „ .qrc “-Dateien über eine benutzerfreundliche Oberfläche zu erstellen, zu überprüfen und zu bearbeiten. Mit Ausnahme von „ Qt Widgets Designer “ bieten sie auch Assistenten für Projekte, die das Qt-Ressourcensystem nutzen.

Integration in das Build-System

Die Verarbeitung von Ressourcendateien mit „ rcc “ erfolgt in der Regel zum Zeitpunkt der Erstellung der Anwendung. Mehrere Build-Tools bieten hierfür spezielle Unterstützung, darunter CMake und qmake.

CMake

Wenn „ CMAKE_AUTORCC “ aktiviert ist, können Sie einfach „ .qrc “-Dateien als Quellen zu Ihrer ausführbaren Datei oder Bibliothek hinzufügen. Die referenzierten Ressourcendateien werden dann in die Binärdatei eingebettet:

set(CMAKE_AUTORCC ON)

qt_add_executable(my_app
    application.qrc
    main.cpp
)

Weitere Informationen zu AUTORCC finden Sie in der CMake-Dokumentation zu AUTORCC.

Eine Alternative zu AUTORCC ist die Verwendung der CMake-Funktion `qt_add_resources` von Qt6Core, die mehr Kontrolle über die Erstellung von Ressourcen bietet. So können Sie beispielsweise den Inhalt der Ressource direkt in der Projektdatei angeben, ohne zuvor eine ` .qrc `-Datei erstellen zu müssen:

qt_add_resources(my_app "app_images"
    PREFIX "/"
    FILES
        images/copy.png
        images/cut.png
        images/new.png
        images/open.png
        images/paste.png
        images/save.png
)

Schließlich können Sie mit ` qt_add_qml_module ` ` Qt Quick `-Ressourcen in das Ressourcensystem Ihrer Anwendung einbetten. Die Funktion ist in der Komponente „ Qml “ des CMake-Pakets „ Qt6 “ definiert.

qmake

qmake unterstützt die Verwaltung von Ressourcen über die Variable `RESOURCES`. Wenn Sie der Variablen einen Pfad zu einer ` .qrc `-Datei hinzufügen, werden die aufgeführten Ressourcendateien in die generierte Bibliothek oder das ausführbare Programm eingebettet:

RESOURCES = application.qrc

Bei einfachen Anwendungen ist es auch möglich, die ` .qrc `-Datei von qmake generieren zu lassen, wodurch die Pflege einer zusätzlichen Datei entfällt:

resources.files = \
    images/copy.png \
    images/cut.png \
    images/new.png \
    images/open.png \
    images/paste.png \
    images/save.png
resources.prefix = /

RESOURCES = resources

Dadurch wird eine Ressource mit mehreren ` .png `-Dateien erstellt, auf die wie folgt zugegriffen werden kann: ` ":/images/copy.png"`.

Wenn die Verzeichnisstruktur der Dateien, die Sie in die Ressource einbinden möchten, nicht den Erwartungen der Anwendung entspricht, können Sie ` resources.base` angeben. ` base ` ist ein Pfadpräfix, das den Stammpunkt des Alias der Datei angibt. Im folgenden Beispiel ist ` resources.base ` auf ` "images"` gesetzt; dann ist ` copy.png ` unter ` ":/copy.png"` erreichbar.

Laufzeit-API

Die Qt-API, die sich mit dem Durchlaufen und Lesen von Dateien befasst, bietet integrierte Unterstützung für das Qt-Ressourcensystem. Sie können anstelle eines lokalen Dateipfads einen Ressourcenpfad an die Funktionen ` QFile ` und ` QDir` übergeben, aber auch beispielsweise an die Konstruktoren von ` QIcon`, ` QImage` und ` QPixmap `:

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

Das Präfix „ : “ macht deutlich, dass „/images/cut.png“ aus dem Qt-Ressourcensystem geladen werden soll.

Sie können auch über ein „ QUrl “ auf das Qt-Ressourcensystem verweisen. Verwenden Sie in diesem Fall das Schema „ qrc “:

    QQmlApplicationEngine engine;
    engine.load(QUrl("qrc:/myapp/main.qml"));

Fortgeschrittene Themen

Präfixe

In einer „ .qrc “-Datei kann ein Präfix festgelegt werden, das jedem lokalen Dateinamen hinzugefügt wird, der im Element „ <file> “ angegeben ist, um den Namen zu erhalten, unter dem die Datei innerhalb des Ressourcensystems bekannt sein soll.

Präfixe ermöglichen es Ihnen, die Ressourcen zu strukturieren und so Konflikte zwischen Ressourcendateien zu vermeiden, die über verschiedene „ .qrc “-Dateien in unterschiedlichen Bibliotheken oder Plugins hinzugefügt wurden.

Aliase

Manchmal ist es praktisch, eine Ressourcendatei zur Laufzeit unter einem anderen Pfad verfügbar zu machen. .qrc -Dateien ermöglichen dies durch das Setzen eines alias -Attributs:

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

Die Datei ist dann aus der Anwendung heraus nur unter :/cut-img.png oder qrc:/cut-img.png zugänglich.

Verwerfen des Dateiinhalts

Manchmal möchte man einen Dateiknoten zum Ressourcen-Dateisystem hinzufügen, ohne jedoch den Dateiinhalt tatsächlich hinzuzufügen. „ .qrc “-Dateien ermöglichen dies, indem das Attribut „ empty “ auf „ true “ gesetzt wird.

<file empty="true">Button.qml</file>

Auf die resultierende Datei kann dann weiterhin von der Anwendung aus zugegriffen werden, ihr Inhalt ist jedoch leer.

Dies ist nützlich, um QML-Quellcode aus einer Anwendungsbinärdatei zu entfernen.

Sprachauswahl

Einige Ressourcen müssen je nach der Locale des Benutzers angepasst werden, beispielsweise Übersetzungsdateien oder Symbole. Ressourcen-Sammlungsdateien unterstützen dies über das Attribut „ lang “ des Tags „ qresource “, mit dem eine passende Locale-Zeichenkette angegeben wird. Beispiel:

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

Wenn die Spracheinstellung des Benutzers Französisch ist (d. h., QLocale::system().language() ist Französisch), wird :/cut.jpg oder qrc:/cut.jpg zu einem Verweis auf das Bild cut_fr.jpg. Für andere Spracheinstellungen wird cut.jpg verwendet.

Eine Beschreibung des für Locale-Zeichenfolgen zu verwendenden Formats finden Sie in der Dokumentation zu „ QLocale “.

Unter QFileSelector finden Sie einen zusätzlichen Mechanismus zur Auswahl lokalisierungsspezifischer Ressourcen.

Einbetten großer Dateien

Standardmäßig bindet rcc die Ressourcendateien in Form von C++-Arrays in ausführbare Dateien ein. Dies kann insbesondere bei großen Ressourcen problematisch sein.

Falls der Compiler zu lange benötigt oder sogar aufgrund eines Speicherüberlaufs fehlschlägt, können Sie einen speziellen Modus aktivieren, in dem die Ressourcen in einem zweistufigen Prozess eingebettet werden. Der C++-Compiler reserviert in der Zielausführungsdatei oder -Bibliothek zunächst nur ausreichend Platz für die Ressourcen. Die eigentliche Einbettung des Inhalts und der Metadaten der Ressourcendatei erfolgt dann nach der Kompilierungs- und Verknüpfungsphase durch einen weiteren rcc-Aufruf.

Für qmake wird dies aktiviert, indem „ resources_big “ zur Variablen „ CONFIG “ hinzugefügt wird:

CONFIG += resources_big

Bei CMake müssen Sie die Funktion ` qt_add_big_resources ` verwenden.

Externe Ressourcendateien

Eine Alternative zum Einbetten der Ressourcendateien in die Binärdatei ist die Speicherung in einer separaten „ .rcc “-Datei. „ rcc “ ermöglicht dies mit der Option „ -binary “. Eine solche „ .rcc “-Datei muss dann zur Laufzeit mit „ QResource “ geladen werden.

Beispielsweise kann eine Reihe von Ressourcendaten, die in einer „ .qrc “-Datei angegeben sind, auf folgende Weise kompiliert werden:

rcc -binary myresource.qrc -o myresource.rcc

In der Anwendung würde diese Ressource mit Code wie dem folgenden registriert werden:

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

Wenn Sie CMake verwenden, können Sie die Funktion `qt_add_binary_resources` nutzen, um den oben genannten Aufruf von ` rcc ` zu planen:

qt_add_binary_resources(resources application.qrc DESTINATION application.rcc)
add_dependencies(my_app resources)

Ressourcen in einer „ Qt for Python “-Anwendung

Die Ressourcensammeldatei wird mithilfe des Resource Compilers rcc in ein Python-Modul konvertiert:

rcc -g python mainwindow.qrc > mainwindow_rc.py

Das Modul kann dann in die Anwendung importiert werden:

import mainwindow_rc.py

Komprimierung

rcc versucht, den Inhalt zu komprimieren, um die Speicherplatznutzung in den endgültigen Binärdateien zu optimieren. Standardmäßig führt es eine heuristische Prüfung durch, um festzustellen, ob sich eine Komprimierung lohnt, und speichert den Inhalt unkomprimiert, wenn eine ausreichende Komprimierung nicht möglich ist. Um den Schwellenwert festzulegen, können Sie die Option „ -threshold “ verwenden, die „ rcc “ mitteilt, wie viel Prozent der ursprünglichen Dateigröße eingespart werden müssen, damit die Datei in komprimierter Form gespeichert wird.

rcc -threshold 25 myresources.qrc

Der Standardwert ist „70“, was bedeutet, dass die komprimierte Datei 70 % kleiner als das Original sein muss (nicht mehr als 30 % der ursprünglichen Dateigröße).

Die Komprimierung lässt sich bei Bedarf deaktivieren. Dies kann nützlich sein, wenn Ihre Ressourcen bereits ein komprimiertes Format enthalten, wie z. B. „ .png “-Dateien, und Sie die CPU-Belastung während der Erstellung vermeiden möchten, um zu überprüfen, ob eine Komprimierung möglich ist. Ein weiterer Grund ist, wenn der Speicherplatzbedarf kein Problem darstellt und die Anwendung den Inhalt zur Laufzeit lieber als freie Speicherseiten vorhalten möchte. Dies erreichen Sie durch die Angabe des Befehlszeilenarguments „ -no-compress “.

rcc -no-compress myresources.qrc

rcc Außerdem haben Sie damit eine gewisse Kontrolle über den Komprimierungsgrad und den Komprimierungsalgorithmus, zum Beispiel:

rcc -compress 2 -compress-algo zlib myresources.qrc

Es ist außerdem möglich, „ compress “ und „ threshold “ als Attribute im Tag „ file “ einer .qrc-Datei zu verwenden. Um den Algorithmus auszuwählen, setzen Sie das Attribut „ compression-algorithm “.

<qresource>
    <file compress="1" compression-algorithm="zstd">data.txt</file>
</qresource>

Damit wird der Algorithmus „ zstd “ mit der Komprimierungsstufe 1 ausgewählt.

rcc unterstützt die folgenden Komprimierungsalgorithmen und Komprimierungsstufen:

• best: Verwendet den besten der unten aufgeführten Algorithmen mit der höchsten Komprimierungsstufe, um die größtmögliche Komprimierung zu erzielen, was jedoch auf Kosten einer hohen CPU-Auslastung während der Kompilierung geht. Dieser Wert ist in der XML-Datei nützlich, um anzugeben, dass eine Datei so stark wie möglich komprimiert werden soll, unabhängig davon, welche Algorithmen „ rcc “ unterstützt.
• zstd: Verwende die Zstandard-Bibliothek, um Inhalte zu komprimieren. Gültige Komprimierungsstufen reichen von 1 bis 19, wobei 1 die geringste Komprimierung (geringste CPU-Zeit) und 19 die höchste Komprimierung (höchste CPU-Zeit) darstellt. Die Standardstufe ist 14. Ein spezieller Wert von 0 weist die Bibliothek „ zstd “ an, einen implementierungsabhängigen Standardwert zu wählen.
• zlib: Verwendet die zlib-Bibliothek zur Komprimierung der Inhalte. Gültige Komprimierungsstufen reichen von 1 bis 9, wobei 1 die geringste Komprimierung (geringste CPU-Zeit) und 9 die stärkste Komprimierung (höchste CPU-Zeit) bedeutet. Der Sonderwert 0 bedeutet „keine Komprimierung“ und sollte nicht verwendet werden. Der Standardwert ist implementierungsabhängig, beträgt jedoch in der Regel Stufe 6.
• none: keine Komprimierung. Dies entspricht der Option „ -no-compress “.

Die Unterstützung sowohl für „Zstandard“ als auch für „zlib“ ist optional. Wenn eine bestimmte Bibliothek zur Kompilierungszeit nicht erkannt wurde, führt der Versuch, „ -compress-algo “ für diese Bibliothek zu übergeben, zu einem Fehler. Der Standard-Komprimierungsalgorithmus ist „ zstd “, sofern dieser aktiviert ist, andernfalls „ zlib “.

Explizites Laden und Entladen eingebetteter Ressourcen

Ressourcen, die in C++-Programmcode oder Bibliothekscode eingebettet sind, werden automatisch im Qt-Ressourcensystem über den Konstruktor einer internen globalen Variablen registriert. Da die globalen Variablen vor der Ausführung von `main()` initialisiert werden, stehen die Ressourcen bereits bei Programmstart zur Verfügung.

Beim Einbetten von Ressourcen in statische Bibliotheken kann es vorkommen, dass der C++-Linker die statischen Variablen entfernt, die die Ressourcen registrieren. Wenn Sie Ressourcen in eine statische Bibliothek einbetten, müssen Sie Ihre Ressourcen daher explizit registrieren, indem Sie ` Q_INIT_RESOURCE()` mit dem Basisnamen der Datei ` .qrc ` aufrufen. Zum Beispiel:

MyClass::MyClass() : BaseClass()
{
    Q_INIT_RESOURCE(resources);

    QFile file(":/myfile.dat");
    //...
}

Sie können registrierte Ressourcen auch explizit aus der Anwendung entfernen, beispielsweise beim Entladen eines Plugins. Verwenden Sie hierfür ` Q_CLEANUP_RESOURCE()`.

Hinweis: Da die von rcc generierten Ressourceninitialisierer im globalen Namensraum deklariert sind, müssen Ihre Aufrufe von ` Q_INIT_RESOURCE()` und ` Q_CLEANUP_RESOURCE()` außerhalb eines Namensraums erfolgen.