/usr/share/qt5/doc/qtqml/qtqml-modules-identifiedmodules.html is in qtdeclarative5-doc-html 5.9.5-0ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- identifiedmodules.qdoc -->
<title>Identified Modules | Qt QML 5.9</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.9</td><td ><a href="qtqml-index.html">Qt QML</a></td><td >Identified Modules</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.5 Reference Documentation</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="#locally-installed-identified-modules">Locally Installed Identified Modules</a></li>
<li class="level2"><a href="#an-example">An Example</a></li>
<li class="level1"><a href="#remotely-installed-identified-modules">Remotely Installed Identified Modules</a></li>
<li class="level1"><a href="#semantics-of-identified-modules">Semantics of Identified Modules</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Identified Modules</h1>
<span class="subtitle"></span>
<!-- $$$qtqml-modules-identifiedmodules.html-description -->
<div class="descr"> <a name="details"></a>
<p>Identified modules are modules that are installed and identifiable to the QML engine by a URI in the form of a dotted identifier string, which should be specified by the module in its <code>qmldir</code> file. This enables such modules to be imported with a unique identifier that remains the same no matter where the module is located on the local file system.</p>
<p>When importing an identified module, an unquoted identifier is used, with a mandatory version number:</p>
<pre class="qml">
import QtQuick 2.0
import com.nokia.qml.mymodule 1.0
</pre>
<p>Identified modules must be installed into the <a href="qtqml-syntax-imports.html#qml-import-path">import path</a> in order to be found by the QML engine.</p>
<a name="locally-installed-identified-modules"></a>
<h2 id="locally-installed-identified-modules">Locally Installed Identified Modules</h2>
<p>A directory of QML and/or C++ files can be shared as an identified module if it contains a <a href="qtqml-modules-qmldir.html">qmldir file</a> with the module metadata and is installed into the QML import path. Any QML file on the local file system can import this directory as a module by using an <a href="qtqml-syntax-imports.html">import</a> statement that refers to the module's URI, enabling the file to use the <a href="qtqml-typesystem-objecttypes.html">QML object types</a> and <a href="qtqml-javascript-resources.html">JavaScript resources</a> defined by the module.</p>
<p>The module's <code>qmldir</code> file must reside in a directory structure within the <a href="qtqml-syntax-imports.html#qml-import-path">import path</a> that reflects the URI dotted identifier string, where each dot (".") in the identifier reflects a sub-level in the directory tree. For example, the <code>qmldir</code> file of the module <code>com.mycompany.mymodule</code> must be located in the sub-path <code>com/mycompany/mymodule/qmldir</code> somewhere in the <a href="qtqml-syntax-imports.html#qml-import-path">import path</a>.</p>
<p>It is possible to store different versions of a module in subdirectories of its own. For example, a version 2.1 of a module could be located under <code>com/mycompany/mymodule.2/qmldir</code> or <code>com/mycompany/mymodule.2.1/qmldir</code>. The engine will automatically load the module which matches best.</p>
<p>Alternatively, versioning for different types can be defined within a qmldir file itself, however this can make updating such a module more difficult (as a <code>qmldir</code> file merge must take place as part of the update procedure).</p>
<a name="an-example"></a>
<h3 >An Example</h3>
<p>Consider the following QML project directory structure. Under the top level directory <code>myapp</code>, there are a set of common UI components in a sub-directory named <code>mycomponents</code>, and the main application code in a sub-directory named <code>main</code>, like this:</p>
<pre class="cpp">
myapp
<span class="operator">|</span><span class="operator">-</span> mycomponents
<span class="operator">|</span><span class="operator">-</span> CheckBox<span class="operator">.</span>qml
<span class="operator">|</span><span class="operator">-</span> DialogBox<span class="operator">.</span>qml
<span class="operator">|</span><span class="operator">-</span> Slider<span class="operator">.</span>qml
<span class="operator">|</span><span class="operator">-</span> main
<span class="operator">|</span><span class="operator">-</span> application<span class="operator">.</span>qml
</pre>
<p>To make the <code>mycomponents</code> directory available as an identified module, the directory must include a <a href="qtqml-modules-qmldir.html">qmldir file</a> that defines the module identifier, and describes the object types made available by the module. For example, to make the <code>CheckBox</code>, <code>DialogBox</code> and <code>Slider</code> types available for version 1.0 of the module, the <code>qmldir</code> file would contain the following:</p>
<pre class="cpp">
module myapp<span class="operator">.</span>mycomponents
CheckBox <span class="number">1.0</span> CheckBox<span class="operator">.</span>qml
DialogBox <span class="number">1.0</span> DialogBox<span class="operator">.</span>qml
Slider <span class="number">1.0</span> Slider<span class="operator">.</span>qml
</pre>
<p>Additionally, the location of the <code>qmldir</code> file in the <a href="qtqml-syntax-imports.html#qml-import-path">import path</a> must match the module's dotted identifier string. So, say the top level <code>myapp</code> directory is located in <code>C:\qml\projects</code>, and say the module should be identified as "myapp.mycomponents". In this case:</p>
<ul>
<li>The path <code>C:\qml\projects</code> should be added to the <a href="qtqml-syntax-imports.html#qml-import-path">import path</a></li>
<li>The qmldir file should be located under <code>C:\qml\projects\myapp\mycomponents\qmldir</code></li>
</ul>
<p>Once this is done, a QML file located anywhere on the local filesystem can import the module by referring to its URI and the appropriate version:</p>
<pre class="qml">
import myapp.mycomponents 1.0
<span class="type">DialogBox</span> {
<span class="type">CheckBox</span> {
<span class="comment">// ...</span>
}
<span class="type">Slider</span> {
<span class="comment">// ...</span>
}
}
</pre>
<a name="remotely-installed-identified-modules"></a>
<h2 id="remotely-installed-identified-modules">Remotely Installed Identified Modules</h2>
<p>Identified modules are also accessible as a network resource. In the previous example, if the <code>C:\qml\projects</code> directory was hosted as <code>http://www.some-server.com/qml/projects</code> and this URL was added to the QML import path, the module could be imported in exactly the same way.</p>
<p>Note that when a file imports a module over a network, it can only access QML and JavaScript resources provided by the module; it cannot access any types defined by C++ plugins in the module.</p>
<a name="semantics-of-identified-modules"></a>
<h2 id="semantics-of-identified-modules">Semantics of Identified Modules</h2>
<p>An identified module is provided with the following guarantees by the QML engine:</p>
<ul>
<li>other modules are unable to modify or override types in the module's namespace</li>
<li>other modules are unable to register new types into the module's namespace</li>
<li>usage of type names by clients will resolve deterministically to a given type definition depending on the versioning specified and the import order</li>
</ul>
<p>This ensures that clients which use the module can be certain that the object types defined in the module will behave as the module author documented.</p>
<p>An identified module has several restrictions upon it:</p>
<ul>
<li>an identified module must be installed into the <a href="qtqml-syntax-imports.html#qml-import-path">QML import path</a></li>
<li>the module identifier specified in the <a href="qtqml-modules-qmldir.html">module identifier directive</a> must match the install path of the module (relative to the QML import path, where directory separators are replaced with period characters)</li>
<li>the module must register its types into the module identifier type namespace</li>
<li>the module may not register types into any other module's namespace</li>
<li>clients must specify a version when importing the module</li>
</ul>
<p>For example, if an identified module is installed into <code>$QML2_IMPORT_PATH/ExampleModule</code>, the module identifier directive must be:</p>
<pre class="cpp">
module ExampleModule
</pre>
<p>If the strict module is installed into <code>$QML2_IMPORT_PATH/com/example/CustomUi</code>, the module identifier directive must be:</p>
<pre class="cpp">
module com<span class="operator">.</span>example<span class="operator">.</span>CustomUi
</pre>
<p>Clients will then be able to import the above module with the following import statement (assuming that the module registers types into version 1.0 of its namespace):</p>
<pre class="qml">
import com.example.CustomUi 1.0
</pre>
</div>
<!-- @@@qtqml-modules-identifiedmodules.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 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>
|