1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
// Copyright (C) 2021 The Qt Company Ltd.
// Copyright (C) 2019 Luxoft Sweden AB
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page use-qt-resources.html
\title Using Qt Resources
\brief Discusses compiling, loading and accesses resources in your program's executable.
\ingroup qtappman
\l{The Qt Resource System} lets you store files in your program's executable. In some ways,
this feature resembles a dedicated file system, which we call \e{resource file system}. Usually,
this file system contains QML code and other assets like images. If you use the QML compiler, the
compiled code is always placed in the resource file system. This leads to a few application manager
specific considerations, especially when your application needs to support both single-process and
multi-process modes.
\section1 Compiling Resources
You can add resources as \l{External Resource Files}{external binary resources} or as
\l{Resource Collection Files}{compiled-in resources}; both can be generated from a \c .qrc file.
Typically, external binary resources are stored in a file with the \c .rcc extension, whereas
compiled-in resources are stored in libraries in the Application Manager context.
It's important to understand that each process has its own resource file system. Consequently, to
support multi-process mode, resources must be generated separately for the System UI and for each
application. Conversely, in single-process mode there is only one resource file system and you must
ensure that file paths don't clash. To prevent clashes, we recommend you prefix each application
file path with the unique application ID.
Consider the following application file structure:
\badcode
apps
|---- spaceinvaders
| |---- main.qml
| |---- spaceinvaders.qrc
| ...
|---- grandtheftdolphin
| |---- main.qml
| |---- grandtheftdolphin.qrc
| ...
\endcode
Without a prefix, in single-process mode, the \c main.qml files would clash. To avoid this, the
\c .qrc file for spaceinvaders should read like this:
\badcode
<!DOCTYPE RCC><RCC version="1.0">
<qresource prefix="spaceinvaders">
<file>main.qml</file>
</qresource>
</RCC>
\endcode
For \c grandtheftdolphin the prefix should be "grandtheftdolphin", respectively.
Generally, all files contained in any \c .qrc file should be unique; this also
includes files that the System UI uses.
The same applies when resources are added directly, without a \c .qrc file, for instance when
defining a QML module, \c RESOURCE_PREFIX should be set:
\badcode
qt_add_qml_module(spaceinvaders
URI "SpaceInvaders"
RESOURCE_PREFIX spaceinvaders
QML_FILES main.qml
)
\endcode
\section1 Loading Resources
In addition to the approaches described in \l{The Qt Resource System}, the Application Manager
provides configuration options to load resources, both -- external binary resources and
compiled-in resources in the form of a library.
Suppose you have a \c my.rcc binary file and a \c myplugin.so library file. These can be loaded
into the System UI by adding the following lines to the \c am-config.yaml file:
\badcode
ui:
resources: [ "${CONFIG_DIR}/my.rcc",
"${CONFIG_DIR}/myplugin" ]
\endcode
As you can see, the library file extension can be omitted. You can also load these two files into
an application by adding the following snippet to the \c info.yaml file:
\badcode
runtimeParameters:
resources: [ "my.rcc",
"myplugin.so" ]
\endcode
The resources are loaded when the System UI starts, before the QML engine is instantiated. In
multi-process mode the application resources are also loaded into the application process at
startup. In single-process mode, resources are loaded when the application first starts and then
reused on subsequent invocations; they are never unloaded.
\section1 Accessing Resources
The application manager allows for file access in the resource file system, either with the URL
scheme (\c{qrc}) or the file name prefix (\c{:}). Both these options require an absolute file path
in the resource file system, such as:
\list
\li \c{qrc:/spaceinvaders/main.qml} or \c{qrc:///spaceinvaders/main.qml}
\li \c{:/spaceinvaders/main.qml}
\endlist
While the Qt Application Manager accepts this relaxed naming structure, the QML engine
distinguishes between URLs and file names. For instance, an \l{Image::source}
{Image source} property only accepts the \c{qrc} scheme.
If you want to specify a relative path, don't use the scheme or file path prefix.
If your files aren't found in the resource file system, you can list the contents of the entire
resource file system with the following code snippet:
\code
QDirIterator it(u":"_s, QDirIterator::Subdirectories);
while (it.hasNext()) {
const QString fn = it.next();
if (!fn.startsWith(u":/qt-project.org"_s)) // exclude Qt internal files
qDebug() << fn;
}
\endcode
*/
|
