QResource Class
Die Klasse „QResource“ bietet eine Schnittstelle zum direkten Lesen aus Ressourcen. Mehr...
| Header: | #include <QResource> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
- Liste aller Mitglieder, einschließlich geerbter Mitglieder
- QResource ist Teil der Module „Eingabe/Ausgabe“ und „Netzwerk“.
Hinweis: Alle Funktionen dieser Klasse sind reentrant.
Öffentliche Typen
| enum | Compression { NoCompression, ZlibCompression, ZstdCompression } |
Öffentliche Funktionen
| QResource(const QString &file = QString(), const QLocale &locale = QLocale()) | |
| ~QResource() | |
| QString | absoluteFilePath() const |
| QResource::Compression | compressionAlgorithm() const |
| const uchar * | data() const |
| QString | fileName() const |
| bool | isValid() const |
| QDateTime | lastModified() const |
| QLocale | locale() const |
| void | setFileName(const QString &file) |
| void | setLocale(const QLocale &locale) |
| qint64 | size() const |
| QByteArray | uncompressedData() const |
| qint64 | uncompressedSize() const |
Statische öffentliche Mitglieder
| bool | registerResource(const QString &rccFileName, const QString &mapRoot = QString()) |
| bool | registerResource(const uchar *rccData, const QString &mapRoot = QString()) |
| bool | unregisterResource(const QString &rccFileName, const QString &mapRoot = QString()) |
| bool | unregisterResource(const uchar *rccData, const QString &mapRoot = QString()) |
Geschützte Funktionen
Ausführliche Beschreibung
QResource ist ein Objekt, das eine Datenmenge (und möglicherweise untergeordnete Elemente) darstellt, die sich auf eine einzelne Ressourcenentität beziehen. QResource ermöglicht den direkten Zugriff auf die Bytes im Rohformat. Auf diese Weise ermöglicht der direkte Zugriff das Lesen von Daten ohne Pufferkopieren oder Indirektion. Indirektion ist oft nützlich, wenn mit der Ressourcenentität so interagiert wird, als wäre sie eine Datei; dies lässt sich mit ` QFile` erreichen. Die Daten und untergeordneten Elemente hinter einem `QResource` werden normalerweise in eine Anwendung oder Bibliothek kompiliert, es ist jedoch auch möglich, eine Ressource zur Laufzeit zu laden. Beim Laden zur Laufzeit wird die Ressourcendatei als ein großer Datensatz geladen und anschließend stückweise über Verweise in den Ressourcenbaum ausgegeben.
Ein `QResource`-Objekt kann entweder über einen absoluten Pfad geladen werden – entweder als Dateisystempfad, der mit dem Zeichen ` / ` beginnt, oder in der Ressourcen-Notation, die mit dem Zeichen ` : ` beginnt. Es kann auch eine relative Ressource geöffnet werden, die in der Liste der Pfade zu finden ist, die von ` QDir::searchPaths()` zurückgegeben wird.
Eine QResource, die eine Datei darstellt, verfügt über zugrunde liegende Daten; diese Daten können möglicherweise komprimiert sein. In diesem Fall muss qUncompress() verwendet werden, um auf die tatsächlichen Daten zuzugreifen; dies geschieht implizit, wenn der Zugriff über eine QFile erfolgt. Eine QResource, die ein Verzeichnis darstellt, enthält nur untergeordnete Elemente und keine Daten.
Dynamisches Laden von Ressourcen
Eine Ressource kann aus der Binärdatei einer Anwendung weggelassen und bei Bedarf zur Laufzeit mithilfe der Funktion ` registerResource()` geladen werden. Die an ` registerResource()` übergebene Ressourcendatei muss eine von `rcc` erstellte Binärressource sein. Weitere Informationen zu Binärressourcen finden Sie in der Dokumentation zum Qt-Ressourcensystem.
Dies kann oft nützlich sein, wenn eine große Anzahl von Anwendungssymbolen geladen wird, die sich je nach einer Einstellung ändern können oder die vom Benutzer bearbeitet und später neu erstellt werden können. Die Ressource wird sofort in den Speicher geladen, entweder als Ergebnis eines einzelnen Dateilesevorgangs oder als speicherabgebildete Datei.
Dieser Ansatz kann zu einer erheblichen Leistungssteigerung führen, da nur eine einzige Datei geladen wird und die Daten über den in ` setFileName()` angeforderten Pfad ausgegeben werden.
Die Funktion ` unregisterResource()` entfernt einen Verweis auf eine bestimmte Datei. Wenn es `QResource`-Objekte gibt, die derzeit auf Ressourcen verweisen, die mit der abgemeldeten Datei in Verbindung stehen, bleiben diese weiterhin gültig; die Ressourcendatei selbst wird jedoch aus den Ressourcenstammverzeichnissen entfernt, sodass keine weiteren `QResource`-Objekte erstellt werden können, die auf diese Ressourcendaten verweisen. Die Ressource selbst wird aus dem Speicher freigegeben, sobald das letzte QResource-Objekt, das auf sie verweist, zerstört wird.
Datenbeschädigung und Sicherheit
Die Klasse `QResource` führt einige Prüfungen an der übergebenen Datei durch, um festzustellen, ob diese von der aktuellen Version von Qt unterstützt wird. Diese Prüfungen dienen lediglich dazu, sicherzustellen, dass der Datei-Header keine Funktionen (wie z. B. Zstandard-Dekomprimierung) anfordert, die nicht kompiliert wurden, oder dass die Datei nicht aus einer zukünftigen Version von Qt stammt. Sie bestätigen nicht die Gültigkeit der gesamten Datei.
QResource sollte nicht für Dateien verwendet werden, deren Herkunft nicht vertrauenswürdig ist. Anwendungen sollten so konzipiert sein, dass sie versuchen, nur Ressourcendateien zu laden, deren Herkunft mindestens ebenso vertrauenswürdig ist wie die der Anwendung selbst oder ihrer Plugins.
Siehe auch „Das Qt-Ressourcensystem“, QFile, QDir und QFileInfo.
Dokumentation zu Mitgliedstypen
enum QResource::Compression
Diese Enumeration wird von ` compressionAlgorithm()` verwendet, um anzugeben, welchen Algorithmus das RCC-Tool zur Komprimierung der Nutzdaten verwendet hat.
| Konstante | Wert | Beschreibung |
|---|---|---|
QResource::NoCompression | 0 | Der Inhalt ist nicht komprimiert |
QResource::ZlibCompression | 1 | Der Inhalt wurde mit zlib komprimiert und kann mit der Funktion ` qUncompress()` dekomprimiert werden. |
QResource::ZstdCompression | 2 | Der Inhalt ist mit zstd komprimiert. Verwenden Sie zum Dekomprimieren die Funktion ` ZSTD_decompress ` aus der zstd-Bibliothek. |
Siehe auch ` compressionAlgorithm()`.
Dokumentation zu den Member-Funktionen
QResource::QResource(const QString &file = QString(), const QLocale &locale = QLocale())
Erstellt eine QResource, die auf file verweist. locale wird verwendet, um eine bestimmte Lokalisierung von Ressourcendaten zu laden.
Siehe auch QFileInfo, QDir::searchPaths(), setFileName() und setLocale().
[noexcept] QResource::~QResource()
Gibt die Ressourcen des Objekts „ QResource “ frei.
QString QResource::absoluteFilePath() const
Gibt den tatsächlichen Pfad zurück, den diese QResource darstellt. Wurde die Ressource über die Funktion QDir::searchPaths() gefunden, wird dies im Pfad angegeben.
Siehe auch fileName().
[protected] QStringList QResource::children() const
Gibt eine Liste aller Ressourcen in diesem Verzeichnis zurück; wenn es sich bei der Ressource um eine Datei handelt, ist die Liste leer.
Siehe auch ` isDir()`.
QResource::Compression QResource::compressionAlgorithm() const
Gibt den Komprimierungstyp zurück, mit dem diese Ressource komprimiert wurde, sofern dies der Fall ist. Ist sie nicht komprimiert, gibt diese Funktion „ QResource::NoCompression “ zurück.
Wenn diese Funktion „ QResource::ZlibCompression “ zurückgibt, können Sie die Daten mit der Funktion „ qUncompress()“ dekomprimieren. Bis Qt 5.13 war dies der einzig mögliche Komprimierungsalgorithmus.
Gibt diese Funktion „ QResource::ZstdCompression “ zurück, müssen Sie die Zstandard-Bibliotheksfunktionen (Header „<zstd.h> “) verwenden. Qt stellt keinen Wrapper bereit.
Siehe Zstandard-Handbuch.
Siehe auch „ data()“ und „ isFile()“.
const uchar *QResource::data() const
Gibt direkten Zugriff auf einen Abschnitt schreibgeschützter Daten zurück, den diese Ressource darstellt. Ist die Ressource komprimiert, sind die zurückgegebenen Daten ebenfalls komprimiert. Der Aufrufer muss die Daten dann dekomprimieren oder die Funktion „ uncompressedData()“ verwenden. Handelt es sich bei der Ressource um ein Verzeichnis, wird „ nullptr “ zurückgegeben.
Siehe auch uncompressedData(), size() und isFile().
QString QResource::fileName() const
Gibt den vollständigen Pfad zu der Datei zurück, die dieser QResource darstellt, so wie sie übergeben wurde.
Siehe auch setFileName() und absoluteFilePath().
[protected] bool QResource::isDir() const
Gibt „ true “ zurück, wenn die Ressource ein Verzeichnis darstellt und somit möglicherweise „ children()“ enthält; andernfalls „false“, wenn es sich um eine Datei handelt.
Siehe auch isFile().
[protected] bool QResource::isFile() const
Gibt „ true “ zurück, wenn die Ressource eine Datei darstellt und somit mit Daten hinterlegt ist; andernfalls „false“, wenn es sich um ein Verzeichnis handelt.
Siehe auch isDir().
bool QResource::isValid() const
Gibt „ true “ zurück, wenn die Ressource tatsächlich in der Ressourcenhierarchie vorhanden ist, andernfalls „false“.
QDateTime QResource::lastModified() const
Gibt das Datum und die Uhrzeit zurück, zu der die Datei zuletzt geändert wurde, bevor sie in eine Ressource gepackt wurde.
QLocale QResource::locale() const
Gibt die Locale zurück, die zum Auffinden der Daten für die Funktion „ QResource “ verwendet wurde.
Siehe auch setLocale().
[static] bool QResource::registerResource(const QString &rccFileName, const QString &mapRoot = QString())
Registriert die Ressource mit der angegebenen URL rccFileName an der durch mapRoot angegebenen Stelle im Ressourcenbaum und gibt true zurück, wenn die Datei erfolgreich geöffnet wurde; andernfalls wird false zurückgegeben.
Siehe auch unregisterResource().
[static] bool QResource::registerResource(const uchar *rccData, const QString &mapRoot = QString())
Registriert die Ressource unter der angegebenen rccData an der durch mapRoot festgelegten Stelle im Ressourcenbaum und gibt true zurück, wenn die Datei erfolgreich geöffnet wurde; andernfalls wird false zurückgegeben.
Warnung: Die Daten müssen während der gesamten Lebensdauer aller „ QFile “, die möglicherweise auf die Ressourcendaten verweisen, gültig bleiben.
Siehe auch unregisterResource().
void QResource::setFileName(const QString &file)
Legt einen „ QResource “ so fest, dass er auf „ file “ verweist. „ file “ kann entweder absolut sein – in diesem Fall wird die Datei direkt geöffnet – oder relativ; im letzteren Fall wird versucht, die Datei über „ QDir::searchPaths()“ zu finden.
Siehe auch fileName() und absoluteFilePath().
void QResource::setLocale(const QLocale &locale)
Legt eine „ QResource “ so fest, dass nur die Lokalisierung der Ressource für „ locale “ geladen wird. Wird keine Ressource für die jeweilige Locale gefunden, wird die C-Locale verwendet.
Siehe auch locale() und setFileName().
qint64 QResource::size() const
Gibt die Größe der hinter der Ressource gespeicherten Daten zurück.
Ist die Ressource komprimiert, gibt diese Funktion die Größe der komprimierten Daten zurück. Informationen zur unkomprimierten Größe finden Sie unter uncompressedSize().
Siehe auch data(), uncompressedSize() und isFile().
QByteArray QResource::uncompressedData() const
Gibt die Ressourcendaten zurück, wobei diese zunächst dekomprimiert werden, falls sie komprimiert gespeichert wurden. Handelt es sich bei der Ressource um ein Verzeichnis oder tritt beim Dekomprimieren ein Fehler auf, wird ein Null- QByteArray zurückgegeben.
Hinweis: Waren die Daten komprimiert, wird die Komprimierung bei jedem Aufruf dieser Funktion aufgehoben. Das Ergebnis wird zwischen den Aufrufen nicht zwischengespeichert.
Siehe auch uncompressedSize(), size(), compressionAlgorithm() und isFile().
qint64 QResource::uncompressedSize() const
Gibt die Größe der Daten in dieser Ressource zurück. Wenn die Daten nicht komprimiert wurden, liefert diese Funktion dasselbe Ergebnis wie size(). Wenn sie komprimiert wurden, ermittelt diese Funktion die Größe der ursprünglichen, unkomprimierten Daten aus dem gespeicherten Stream.
Siehe auch size(), uncompressedData() und isFile().
[static] bool QResource::unregisterResource(const QString &rccFileName, const QString &mapRoot = QString())
Hebt die Registrierung der Ressource mit der angegebenen rccFileName an der durch mapRoot festgelegten Stelle im Ressourcenbaum auf und gibt true zurück, wenn die Ressource erfolgreich entladen wurde und keine Verweise auf die Ressource bestehen; andernfalls wird false zurückgegeben.
Siehe auch registerResource().
[static] bool QResource::unregisterResource(const uchar *rccData, const QString &mapRoot = QString())
Hebt die Registrierung der Ressource mit der angegebenen rccData an der durch mapRoot angegebenen Stelle im Ressourcenbaum auf und gibt true zurück, wenn die Ressource erfolgreich entladen wurde und keine Verweise auf die Ressource bestehen; andernfalls wird false zurückgegeben.
Siehe auch registerResource().
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
