Das Qt-Ressourcensystem

Das Qt-Ressourcensystem ist ein plattformunabhängiger Mechanismus zur Bereitstellung von Ressourcendateien in einer Anwendung. Verwenden Sie es, wenn Ihre Anwendung immer einen bestimmten Satz von Dateien benötigt (z.B. Icons, Übersetzungsdateien, Bilder) und Sie keine systemspezifischen Mittel zum Verpacken und Auffinden dieser Ressourcen verwenden möchten.

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

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

Die Qt Resource Compiler (rcc)

Das Kommandozeilenwerkzeug Resource Compiler (rcc) liest Ressourcendateien und erzeugt 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 erzeugt der rcc C++-Quellcode, der dann als Teil einer ausführbaren Datei oder Bibliothek kompiliert wird. Die Option -g python generiert stattdessen Python-Quellcode. Die Option -binary erzeugt ein Binärarchiv, das in einer .rcc Datei gespeichert wird und zur Laufzeit geladen werden kann.

Qt-Ressourcen-Sammlungsdatei (.qrc)

Eine .qrc -Datei ist ein XML-Dokument, das lokale Dateien auflistet, die als Laufzeitressourcen eingebunden werden sollen. Sie dient als Eingabe für 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 in der XML-Datei identifiziert eine Datei im Quellbaum 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 titlebarLeft.png wird im Ressourcensystem als :/res/titlebarLeft.png oder qrc:/res/titlebarLeft.png verfügbar sein. Um diesen Standardnamen zur Laufzeit zu überschreiben, siehe Präfixe und Aliase.

Qt Creator, Qt Design Studio, Qt Widgets Designer, und Qt Visual Studio Tools ermöglichen es Ihnen, .qrc Dateien über eine komfortable Benutzeroberfläche zu erstellen, zu prüfen und zu bearbeiten. Mit Ausnahme von Qt Widgets Designer bieten sie auch Assistenten für Projekte, die das Qt-Ressourcensystem verwenden.

Integration des Build-Systems

Die Verarbeitung von Ressourcendateien mit rcc erfolgt in der Regel zum Zeitpunkt des Builds 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
)

Siehe CMake's AUTORCC Dokumentation für weitere Details über 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. Sie erlaubt es zum Beispiel, den Inhalt der Ressource direkt in der Projektdatei zu spezifizieren, ohne vorher eine .qrc Datei zu schreiben:

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 Übergabe von Ressourcen mit der RESOURCES-Variable. Wenn Sie der Variable einen .qrc Dateipfad hinzufügen, werden die aufgelisteten Ressourcendateien in die generierte Bibliothek oder ausführbare Datei eingebettet:

RESOURCES = application.qrc

Dies erzeugt eine Ressource aus mehreren .png Dateien, die wie folgt adressierbar sind: ":/res/titlebarLeft.png".

Wenn das Verzeichnislayout der Dateien, die Sie in die Ressource einbetten wollen, nicht den Erwartungen der Anwendung entspricht, können Sie resources.base angeben. base ist ein Pfadpräfix, das den Wurzelpunkt des Alias der Datei bezeichnet. Wenn im obigen Beispiel resources.base auf "res" gesetzt wird, dann ist titlebarLeft.png als ":/titlebarLeft.png" adressierbar.

Laufzeit-API

Die Qt-API, die sich mit der Iteration und dem Lesen von Dateien beschäftigt, hat eine eingebaute Unterstützung für das Qt Resource System. Sie können einen Ressourcenpfad anstelle eines lokalen Dateipfades an QFile und QDir übergeben, aber auch zum Beispiel an die QIcon, QImage und QPixmap Konstruktoren:

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

Das Präfix : macht deutlich, dass "/images/cut.png" aus dem Qt Resource System geladen werden soll.

Sie können das Qt Resource System auch über ein QUrl referenzieren. Verwenden Sie in diesem Fall das qrc Schema:

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

Erweiterte Themen

Präfixe

Eine .qrc Datei kann ein Präfix setzen, das zu jedem lokalen Dateinamen, der in einem <file> Element angegeben wird, hinzugefügt wird, um den Namen zu erhalten, unter dem die Datei innerhalb des Ressourcensystems bekannt sein soll.

Präfixe ermöglichen es, die Ressourcen zu strukturieren und Konflikte zwischen Ressourcendateien zu vermeiden, die durch verschiedene .qrc Dateien in verschiedenen Bibliotheken oder Plugins hinzugefügt wurden.

Aliasnamen

Manchmal ist es zweckmäßig, eine Ressourcendatei zur Laufzeit unter einem anderen Pfad verfügbar zu machen. .qrc Dateien erlauben dies durch Setzen eines alias Attributs:

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

Die Datei ist dann von der Anwendung nur noch als :/cut-img.png oder qrc:/cut-img.png zugänglich.

Verwerfen des Dateiinhalts

Manchmal möchte man einen Dateiknoten zum Ressourcendateisystem hinzufügen, aber nicht den Inhalt der Datei. .qrc Dateien ermöglichen dies, indem das Attribut empty auf true gesetzt wird.

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

Die resultierende Datei ist dann immer noch von der Anwendung aus zugänglich, aber ihr Inhalt ist leer.

Dies ist nützlich, um QML-Quellcode aus einer binären Anwendung zu entfernen.

Sprachselektoren

Einige Ressourcen müssen sich basierend auf dem Gebietsschema des Benutzers ändern, wie z.B. Übersetzungsdateien oder Icons. Ressourcensammlungsdateien unterstützen dies durch ein lang -Attribut für das qresource -Tag, das eine geeignete Locale-Zeichenkette angibt. Zum Beispiel:

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

Wenn das Gebietsschema 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 Sprachumgebungen wird cut.jpg verwendet.

In der Dokumentation QLocale finden Sie eine Beschreibung des Formats, das für Locale-Strings zu verwenden ist.

Siehe QFileSelector für einen zusätzlichen Mechanismus zur Auswahl lokalspezifischer Ressourcen.

Große Dateien einbetten

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

Wenn der Compiler zu lange braucht oder sogar an einem Speicherüberlauf scheitert, können Sie sich für einen speziellen Modus entscheiden, bei dem die Ressourcen als Teil eines zweistufigen Prozesses eingebettet werden. Der C++-Compiler reserviert in der ausführbaren Zieldatei oder -bibliothek nur genügend Platz für die Ressourcen. Die eigentliche Einbettung des Inhalts und der Metadaten der Ressourcendatei erfolgt dann nach der Kompilierungs- und Linkingphase durch einen weiteren rcc-Aufruf.

Für CMake müssen Sie die Funktion qt_add_big_resources verwenden.

Externe Ressourcendateien

Eine Alternative zum Einbetten der Ressourcendateien in die Binärdatei ist es, sie in einer separaten .rcc Datei zu speichern. rcc erlaubt dies mit der Option -binary. Eine solche .rcc Datei muss dann zur Laufzeit mit QResource geladen werden.

Ein Satz von Ressourcendaten, der in einer .qrc Datei spezifiziert ist, kann zum Beispiel folgendermaßen kompiliert werden:

rcc -binary myresource.qrc -o myresource.rcc

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

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

Wenn Sie CMake verwenden, können Sie die Funktion qt_add_binary_resources verwenden, um den obigen 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 Ressourcensammlungsdatei wird mit Hilfe des Resource Compilers rcc in ein Python-Modul umgewandelt:

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 wird eine heuristische Prüfung durchgeführt, um festzustellen, ob sich die Komprimierung lohnt, und der Inhalt wird unkomprimiert gespeichert, wenn er nicht ausreichend komprimiert werden kann. Um den Schwellenwert zu steuern, können Sie die Option -threshold verwenden, die rcc den Prozentsatz der ursprünglichen Dateigröße angibt, der erreicht werden muss, 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).

Es ist möglich, die Komprimierung zu deaktivieren, falls gewünscht. Dies kann nützlich sein, wenn Ihre Ressourcen bereits ein komprimiertes Format enthalten, wie z. B. .png Dateien, und Sie die CPU-Kosten bei der Erstellung nicht auf sich nehmen wollen, um zu bestätigen, dass die Datei nicht komprimiert werden kann. Ein weiterer Grund ist, wenn die Festplattennutzung kein Problem darstellt und die Anwendung den Inhalt lieber als saubere Speicherseiten zur Laufzeit behalten möchte. Dies erreichen Sie mit dem Befehlszeilenargument -no-compress.

rcc -no-compress myresources.qrc

rcc gibt Ihnen auch eine gewisse Kontrolle über den Komprimierungsgrad und den Komprimierungsalgorithmus, zum Beispiel:

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

Es ist auch möglich, compress, threshold als Attribute in einem .qrc file Tag zu verwenden. Um den Algorithmus auszuwählen, setzen Sie das Attribut compression-algorithm.

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

Im obigen Beispiel wird der Algorithmus zstd mit der Komprimierungsstufe 1 ausgewählt.

rcc unterstützt die folgenden Kompressionsalgorithmen und Kompressionsstufen:

• bestDer beste der unten aufgeführten Algorithmen wird mit der höchsten Komprimierungsstufe verwendet, um die höchste Komprimierung zu erreichen, auch wenn dafür viel CPU-Zeit beim Kompilieren benötigt wird. Dieser Wert ist in der XML-Datei nützlich, um anzugeben, dass eine Datei am stärksten komprimiert werden soll, unabhängig davon, welche Algorithmen rcc unterstützt.
• zstdZstandard: verwendet die Zstandard-Bibliothek zur Komprimierung von Inhalten. Gültige Komprimierungsstufen reichen von 1 bis 19, wobei 1 für die geringste Komprimierung (geringste CPU-Zeit) und 19 für die höchste Komprimierung (höchste CPU-Zeit) steht. Die Standardstufe ist 14. Ein spezieller Wert von 0 weist die Bibliothek zstd an, eine implementierungsdefinierte Vorgabe zu wählen.
• zlibzlib: Verwenden Sie die zlib-Bibliothek, um Inhalte zu komprimieren. Gültige Komprimierungsstufen reichen von 1 bis 9, wobei 1 die geringste Komprimierung (geringste CPU-Zeit) und 9 die höchste Komprimierung (höchste CPU-Zeit) bedeutet. Der spezielle Wert 0 bedeutet "keine Kompression" und sollte nicht verwendet werden. Der Standardwert ist implementierungsabhängig, ist aber normalerweise Stufe 6.
• none: keine Kompression. Dies ist dasselbe wie die Option -no-compress.

Die Unterstützung für Zstandard und zlib ist optional. Wenn eine bestimmte Bibliothek zur Kompilierzeit nicht erkannt wurde, führt der Versuch, -compress-algo für diese Bibliothek zu übergeben, zu einem Fehler. Der Standard-Komprimierungsalgorithmus ist zstd, wenn er aktiviert ist, und zlib, wenn nicht.

Explizites Laden und Entladen von eingebetteten Ressourcen

Ressourcen, die in C++-Code oder Bibliotheken eingebettet sind, werden automatisch im Qt-Ressourcensystem in einem Konstruktor für eine interne globale Variable registriert. Da die globalen Variablen vor der Ausführung von main() initialisiert werden, sind die Ressourcen verfügbar, wenn das Programm zu laufen beginnt.

Wenn Sie Ressourcen in statische Bibliotheken einbetten, kann es sein, dass der C++ Linker die statischen Variablen, die die Ressourcen registrieren, entfernt. Wenn Sie Ressourcen in eine statische Bibliothek einbetten, müssen Sie daher Ihre Ressourcen 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, zum Beispiel beim Entladen eines Plugins. Verwenden Sie dazu Q_CLEANUP_RESOURCE().

Hinweis: Da die von rcc erzeugten Ressourceninitialisierer im globalen Namespace deklariert sind, müssen Ihre Aufrufe an Q_INIT_RESOURCE() und Q_CLEANUP_RESOURCE() außerhalb eines Namespaces erfolgen.