<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- imports.qdoc -->
<title>Import Statements | Qt QML 5.12.6</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.12</td><td ><a href="qtqml-index.html">Qt QML</a></td><td >Import Statements</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qtqml-index.html">Qt 5.12.6 Reference Documentation</a></td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#syntax-of-an-import-statement">Syntax of an Import Statement</a></li>
<li class="level2"><a href="#import-types">Import Types</a></li>
<li class="level1"><a href="#qml-import-path">QML Import Path</a></li>
<li class="level1"><a href="#debugging">Debugging</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Import Statements</h1>
<span class="subtitle"></span>
<!-- $$$qtqml-syntax-imports.html-description -->
<div class="descr"> <a name="details"></a>
<a name="syntax-of-an-import-statement"></a>
<h2 id="syntax-of-an-import-statement">Syntax of an Import Statement</h2>
<p>An import statement allows clients to tell the engine which modules, JavaScript resources and component directories are used within a QML document. The types which may be used within a document depends on which modules, resources and directories are imported by the document.</p>
<a name="import-types"></a>
<h3 id="import-types">Import Types</h3>
<p>There are three different types of imports. Each import type has a slightly different syntax, and different semantics apply to different import types.</p>
<a name="module-namespace-imports"></a>
<h4 id="module-namespace-imports">Module (Namespace) Imports</h4>
<p>The most common type of import is a module import. Clients can import <a href="qtqml-modules-identifiedmodules.html">QML modules</a> which register QML object types and JavaScript resources into a given namespace.</p>
<p>The generic form of a module import is as follows:</p>
<pre class="cpp">
import <span class="operator"><</span>ModuleIdentifier<span class="operator">></span> <span class="operator"><</span>Version<span class="operator">.</span>Number<span class="operator">></span> <span class="operator">[</span>as <span class="operator"><</span>Qualifier<span class="operator">></span><span class="operator">]</span>
</pre>
<ul>
<li>The <code><ModuleIdentifier></code> is an identifier specified in dotted URI notation, which uniquely identifies the type namespace provided by the module.</li>
<li>The <code><Version.Number></code> is a version of the form <code>MajorVersion.MinorVersion</code> which specifies which definitions of various object types and JavaScript resources will be made available due to the import.</li>
<li>The <code><Qualifier></code> is an optional local namespace identifier into which the object types and JavaScript resources provided by the module will be installed, if given. If omitted, the object types and JavaScript resources provided by the module will be installed into the global namespace.</li>
</ul>
<p>An example of an unqualified module import is as follows:</p>
<pre class="cpp">
import <span class="type">QtQuick</span> <span class="number">2.0</span>
</pre>
<p>This import allows the use of all of the types provided by the <code>QtQuick</code> module without needing to specify a qualifier. For example, the client code to create a rectangle is as follows:</p>
<pre class="qml">
</pre>
<p>An example of a qualified module import is as follows:</p>
<pre class="cpp">
import <span class="type">QtQuick</span> <span class="number">2.0</span> as Quick
</pre>
<p>This import allows multiple modules which provide conflicting type names to be imported at the same time, however since each usage of a type provided by a module which was imported into a qualified namespace must be preceded by the qualifier, the conflict is able to be resolved unambiguously by the QML engine.</p>
<p>An example of client code which creates a rectangle after using a qualified module import is as follows:</p>
<pre class="qml">
</pre>
<p>For more information about qualified imports, see the upcoming section on <a href="qtqml-syntax-imports.html#importing-into-a-qualified-local-namespace">Importing Into A Qualified Local Namespace</a>.</p>
<p>Note that if a QML document does not import a module which provides a particular QML object type, but attempts to use that object type anyway, an error will occur. For example, the following QML document does not import <code>QtQuick</code> and thus attempting to use the <code>Rectangle</code> type will fail:</p>
<pre class="qml">
</pre>
<p>In this case, the engine will emit an error and refuse to load the file.</p>
<a name="non-module-namespace-imports"></a>
<h5 id="non-module-namespace-imports">Non-module Namespace Imports</h5>
<p>Types can also be registered into namespaces directly via the various registration functions in C++ (such as <a href="qqmlengine.html#qmlRegisterType">qmlRegisterType</a>()). The types which have been registered into a namespace in this way may be imported by importing the namespace, as if the namespace was a module identifier.</p>
<p>This is most common in client applications which define their own QML object types in C++ and register them with the QML type system manually.</p>
<a name="importing-into-a-qualified-local-namespace"></a>
<h5 id="importing-into-a-qualified-local-namespace">Importing into a Qualified Local Namespace</h5>
<p>The <code>import</code> statement may optionally use the <code>as</code> keyword to specify that the types should be imported into a particular document-local namespace. If a namespace is specified, then any references to the types made available by the import must be prefixed by the local namespace qualifier.</p>
<p>Below, the <code>QtQuick</code> module is imported into the namespace "CoreItems". Now, any references to types from the <code>QtQuick</code> module must be prefixed with the <code>CoreItems</code> name:</p>
<pre class="qml">
</pre>
<p>A namespace acts as an identifier for a module within the scope of the file. The namespace does not become an attribute of the root object that can be referred to externally as can be done with properties, signals and methods.</p>
<p>The namespaced import is useful if there is a requirement to use two QML types that have the same name but are located in different modules. In this case the two modules can be imported into different namespaces to ensure the code is referring to the correct type:</p>
<pre class="qml">
</pre>
<p>Note that multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace. For example:</p>
<pre class="qml">
import QtQuick 2.0 as Project
import QtMultimedia 5.0 as Project
Project.Rectangle {
width: 100; height: 50
Project.Audio {
source: "music.wav"
autoPlay: true
}
}
</pre>
<a name="directory-imports"></a>
<h4 id="directory-imports">Directory Imports</h4>
<p>A directory which contains QML documents may also be imported directly in a QML document. This provides a simple way for QML types to be segmented into reusable groupings: directories on the filesystem.</p>
<p>The generic form of a directory import is as follows:</p>
<pre class="qml">
</pre>
<p><b>Note: </b>Import paths are network transparent: applications can import documents from remote paths just as simply as documents from local paths. See the general URL resolution rules for <a href="qtqml-documents-networktransparency.html">Network Transparency</a> in QML documents. If the directory is remote, it must contain a <a href="qtqml-syntax-directoryimports.html#directory-listing-qmldir-files">directory import listing qmldir file</a> as the QML engine cannot determine the contents of a remote directory if that <code>qmldir</code> file does not exist.</p><p>Similar semantics for the <code><Qualifier></code> apply to directory imports as for module imports; for more information on the topic, please see the previous section about <a href="qtqml-syntax-imports.html#importing-into-a-qualified-local-namespace">Importing into a Qualified Local Namespace</a>.</p>
<p>For more information about directory imports, please see the in-depth documentation about <a href="qtqml-syntax-directoryimports.html">directory imports</a>.</p>
<a name="javascript-resource-imports"></a>
<h4 id="javascript-resource-imports">JavaScript Resource Imports</h4>
<p>JavaScript resources may be imported directly in a QML document. Every JavaScript resource must have an identifier by which it is accessed.</p>
<p>The generic form of a JavaScript resource import is as follows:</p>
<pre class="cpp">
import <span class="string">"<JavaScriptFile>"</span> as <span class="operator"><</span>Identifier<span class="operator">></span>
</pre>
<p>Note that the <code><Identifier></code> must be unique within a QML document, unlike the local namespace qualifier which can be applied to module imports.</p>
<a name="javascript-resources-from-modules"></a>
<h5 id="javascript-resources-from-modules">JavaScript Resources from Modules</h5>
<p>Javascript files can be provided by modules, by adding identifier definitions to the <code>qmldir</code> file which specifies the module.</p>
<p>For example, if the <code>projects.MyQMLProject.MyFunctions</code> module is specified with the following <code>qmldir</code> file, and installed into the QML import path:</p>
<pre class="cpp">
module projects<span class="operator">.</span>MyQMLProject<span class="operator">.</span>MyFunctions
SystemFunctions <span class="number">1.0</span> SystemFunctions<span class="operator">.</span>js
UserFunctions <span class="number">1.0</span> UserFunctions<span class="operator">.</span>js
</pre>
<p>a client application is able to import the JavaScript resources declared in the module by importing the module and using the identifier associated with a declared resource:</p>
<pre class="qml">
</pre>
<p>If the module was imported into a document-local namespace, the JavaScript resource identifiers must be prefixed with the namespace qualifier in order to be used:</p>
<pre class="qml">
</pre>
<a name="further-information"></a>
<h5 id="further-information">Further Information</h5>
<p>For more information about JavaScript resources, please see the documentation about <a href="qtqml-javascript-resources.html">defining JavaScript resources in QML</a>, and for more information about how to import JavaScript resources, and how imports can be used from within JavaScript resources, please see the in-depth documentation about <a href="qtqml-javascript-imports.html">importing JavaScript resources in QML</a>.</p>
<a name="qml-import-path"></a>
<h2 id="qml-import-path">QML Import Path</h2>
<p>When an <a href="qtqml-modules-identifiedmodules.html">identified module</a> is imported, the QML engine searches the <i>import path</i> for a matching module.</p>
<p>This import path, as returned by <a href="qqmlengine.html#importPathList">QQmlEngine::importPathList</a>(), defines the default locations to be searched by the engine. By default, this list contains:</p>
<ul>
<li>The directory of the current file</li>
<li>The location specified by QLibraryInfo::Qml2ImportsPath</li>
<li>Paths specified by the <code>QML2_IMPORT_PATH</code> environment variable</li>
<li>The qrc:/qt-project.org/imports path inside the resources.</li>
</ul>
<p>Additional import paths can be added through <a href="qqmlengine.html#addImportPath">QQmlEngine::addImportPath</a>() or the <code>QML2_IMPORT_PATH</code> environment variable. When running the qmlscene tool, you can also use the <code>-I</code> option to add an import path.</p>
<a name="debugging"></a>
<h2 id="debugging">Debugging</h2>
<p>The <code>QML_IMPORT_TRACE</code> environment variable can be useful for debugging when there are problems with finding and loading modules. See Debugging module imports for more information.</p>
</div>
<!-- @@@qtqml-syntax-imports.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2019 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br/> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br/> 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. </p>
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-updates
>
by-pkgid
>
6e2327ca1c896c6d674ae53117299f21
>
files
>
350
