Importing QML Document Directories#
Description of directory import statements in QML
A local directory of QML files can be imported without any additional setup or configuration. A remote directory of QML files can also be imported, but requires a directory listing
qmldir file to exist. A local directory may optionally contain a directory listing
Local Directory Imports#
Any QML file on the local file system can import a local directory as using an import statement that refers to the directory’s absolute or relative file system path, enabling the file to use the object types defined within that directory.
If the local directory contains a directory listing
qmldir file, the types will be made available with the type names specified in the
qmldir file; otherwise, they will be made available with type names derived from the filenames of the QML documents. Only filenames beginning with an uppercase letter and ending with “.qml” will be exposed as types if no
qmldir file is specified in the directory.
Directory Imports rank below any module imports in precedence. If the same name is defined in a module and in a directory that are both imported into the same namespace, only the module’s type is made available.
Consider the following QML project directory structure. Under the top level directory
myapp, there are a set of common UI components in a sub-directory named
mycomponents, and the main application code in a sub-directory named
main, like this:
myapp |- mycomponents |- CheckBox.qml |- DialogBox.qml |- Slider.qml |- main |- application.qml
main/application.qml file can import the
mycomponents directory using the relative path to that directory, allowing it to use the QML object types defined within that directory:
The directory may be imported into a qualified local namespace, in which case uses of any types provided in the directory must be qualified:
The ability to import a local directory is convenient for cases such as in-application component sets and application prototyping, although any code that imports such modules must update their relevant
import statements if the module directory moves to another location. This can be avoided if QML modules are used instead, as an installed module is imported with a unique identifier string rather than a file system path.
The Implicit Import#
The directory a QML document resides in is automatically imported. You do not have to explicitly import
"." or similar.
You should make sure that the qmldir file that specifies the module a QML document belongs to resides in the same directory as the QML document itself. Otherwise the implicit import is different from the module the document belongs to. Then, for example, another QML document may be a singleton in the context of the module, but not a singleton in the context of the implicit import. This is a frequent source of mistakes.
Remotely Located Directories#
A directory of QML files can also be imported from a remote location if the directory contains a directory listing
This also holds for the implicit import of the directory a QML document resides in. If your QML documents are loaded from a remote location, you need to add qmldir files even if they don’t contain any explicit directory import statements. Otherwise your QML documents won’t see each other.
For example, if the
myapp directory in the previous example was hosted at “http://www.my-example-server.com”, and the
mycomponents directory contained a
qmldir file defined as follows:
CheckBox CheckBox.qml DialogBox DialogBox.qml Slider Slider.qml
Then, the directory could be imported using the URL to the remote
qmldir file located in the directory.
When importing directories from a remote server, developers should always be careful to only load directories from trusted sources to avoid loading malicious code.
Directory Listing qmldir Files#
A directory listing
qmldir file distinctly different from a module definition qmldir file . A directory listing
qmldir file allows a group of QML documents to be quickly and easily shared, but it does not define a type namespace into which the QML object types defined by the documents are registered, nor does it support versioning of those QML object types.
The syntax of a directory listing
qmldir file is as follows:
Object Type Declaration
An object type declaration allows a QML document to be exposed with the given
Internal Object Type Declaration
internal <TypeName> <FileName>
An internal object type declaration allows a QML document to be registered as a type which becomes available only to the other QML documents contained in the directory import. The internal type will not be made available to clients who import the directory.
Example:internal HighlightedButton HighlightedBtn.qml
A local file system directory may optionally include a