<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- modules.qdoc -->
<title>Qt 4.8: Modules</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>Modules</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#qml-modules">QML Modules</a></li>
<li class="level1"><a href="#located-modules">Located Modules</a></li>
<li class="level1"><a href="#installed-modules">Installed Modules</a></li>
<li class="level2"><a href="#creating-installed-modules">Creating Installed Modules</a></li>
<li class="level2"><a href="#creating-installed-modules-in-c">Creating Installed Modules in C++</a></li>
<li class="level1"><a href="#namespaces-using-named-imports">Namespaces: Using Named Imports</a></li>
<li class="level2"><a href="#javascript-files">JavaScript Files</a></li>
<li class="level1"><a href="#writing-a-qmldir-file">Writing a qmldir File</a></li>
<li class="level1"><a href="#debugging">Debugging</a></li>
<li class="level1"><a href="#writing-a-qmltypes-file">Writing a qmltypes file</a></li>
</ul>
</div>
<h1 class="title">Modules</h1>
<span class="subtitle"></span>
<!-- $$$qdeclarativemodules.html-description -->
<div class="descr"> <a name="details"></a>
<a name="qml-modules"></a>
<h2>QML Modules</h2>
<p>A module is a set of QML content files that can be imported as a unit into a QML application. Modules can be used to organize QML content into independent units, and they can use a versioning mechanism that allows for independent upgradability of the modules.</p>
<p>While QML component files within the same directory are automatically accessible within the global namespace, components defined elsewhere must be imported explicitly using the <tt>import</tt> statement to import them as modules. For example, an <tt>import</tt> statement is required to use:</p>
<ul>
<li>A component defined in another QML file that is not in the same directory</li>
<li>A component defined in a QML file located on a remote server</li>
<li>A <a href="qdeclarativeextensionplugin.html">QML extension plugin</a> library (unless the plugin is installed in the same directory)</li>
<li>A JavaScript file (note this must be imported using <a href="#namespaces">named imports</a>)</li>
</ul>
<p>An <tt>import</tt> statement includes the module name, and possibly a version number. This can be seen in the snippet commonly found at the top of QML files:</p>
<pre class="qml"> import QtQuick 1.0</pre>
<p>This imports version 1.0 of the "QtQuick" module into the global namespace. (The QML library itself must be imported to use any of the <a href="qdeclarativeelements.html">QML Elements</a>, as they are not included in the global namespace by default.)</p>
<p>The <tt>Qt</tt> module is an <i>installed</i> module; it is found in the <a href="#import-path">import path</a>. There are two types of QML modules: located modules (defined by a URL) and installed modules (defined by a URI).</p>
<a name="located-modules"></a>
<h2>Located Modules</h2>
<p>Located modules can reside on the local filesystem or a network resource, and are referred to by a quoted location URL that specifies the filesystem or network URL. They allow any directory with QML content to be imported as a module, whether the directory is on the local filesystem or a remote server.</p>
<p>For example, a QML project may have a separate directory for a set of custom UI components. These components can be accessed by importing the directory using a relative or absolute path, like this:</p>
<table class="generic">
<tr valign="top" class="odd"><td >Directory structure</td><td >Contents of application.qml</td></tr>
<tr valign="top" class="even"><td ><pre class="cpp"> MyQMLProject
<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> Slider<span class="operator">.</span>qml
<span class="operator">|</span><span class="operator">-</span> Window<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>
</td><td ><pre class="qml"> import "../MyComponents"
<span class="type">Window</span> {
<span class="type">Slider</span> {
<span class="comment">// ...</span>
}
<span class="type">CheckBox</span> {
<span class="comment">// ...</span>
}
}</pre>
</td></tr>
</table>
<p>Similarly, if the directory resided on a network source, it could be imported like this:</p>
<pre class="qml"> import "http://www.my-server.com/MyQMLProject/MyComponents"
import "http://www.my-server.com/MyQMLProject/MyComponents" 1.0</pre>
<p>A located module can also be imported as a network resource if it has a <a href="#writing-a-qmldir-file">qmldir file</a> in the directory that specifies the QML files to be made available by the module. For example, if the <tt>MyComponents</tt> directory contained a <tt>qmldir</tt> file defined like this:</p>
<pre class="cpp"> Slider <span class="number">1.0</span> Slider<span class="operator">.</span>qml
CheckBox <span class="number">1.0</span> CheckBox<span class="operator">.</span>qml
Window <span class="number">1.0</span> Window<span class="operator">.</span>qml</pre>
<p>If the <tt>MyComponents</tt> directory was then hosted as a network resource, it could be imported as a module, like this:</p>
<pre class="qml"> import "http://the-server-name.com/MyQMLProject/MyComponents"
<span class="type">Window</span> {
<span class="type">Slider</span> {
<span class="comment">// ...</span>
}
<span class="type">CheckBox</span> {
<span class="comment">// ...</span>
}
}</pre>
<p>with an optional "1.0" version specification. Notice the import would fail if a later version was used, as the <tt>qmldir</tt> file specifies that these elements are only available in the 1.0 version.</p>
<p>Note that modules imported as a network resource allow only access to components defined in QML files; components defined by C++ <a href="qdeclarativeextensionplugin.html">QML extension plugins</a> are not available.</p>
<a name="import-path"></a><a name="installed-modules"></a>
<h2>Installed Modules</h2>
<p>Installed modules are modules that are made available through the QML import path, as defined by <a href="qdeclarativeengine.html#importPathList">QDeclarativeEngine::importPathList</a>(), or modules defined within C++ application code. An installed module is referred to by a URI, which allows the module to be imported from QML code without specifying a complete filesystem path or network resource URL.</p>
<p>When importing an installed module, an un-quoted URI is used, with a mandatory version number:</p>
<pre class="qml"> import QtQuick 1.0
import com.nokia.qml.mymodule 1.0</pre>
<p>When a module is imported, the QML engine searches the QML import path for a matching module. The root directory of the module must contain a <a href="#writing-a-qmldir-file">qmldir file</a> that defines the QML files and/or C++ QML extension plugins that are made available to the module.</p>
<p>Modules that are installed into the import path translate the URI into directory names. For example, the qmldir file of the module <tt>com.nokia.qml.mymodule</tt> must be located in the subpath <tt>com/nokia/qml/mymodule/qmldir</tt> somewhere in the QML import path. In addition it is possible to store different versions of the module in subdirectories of its own. For example, a version 2.1 of the module could be located under <tt>com/nokia/qml/mymodule.2/qmldir</tt> or <tt>com/nokia/qml/mymodule.2.1/qmldir</tt>. The engine will automatically load the module which matches best.</p>
<p>The import path, as returned by <a href="qdeclarativeengine.html#importPathList">QDeclarativeEngine::importPathList</a>(), defines the default locations to be searched by the QML engine for a matching module. By default, this list contains:</p>
<ul>
<li>The directory of the current file</li>
<li>The location specified by <a href="qlibraryinfo.html#LibraryLocation-enum">QLibraryInfo::ImportsPath</a></li>
<li>Paths specified by the <tt>QML_IMPORT_PATH</tt> environment variable</li>
</ul>
<p>Additional import paths can be added through <a href="qdeclarativeengine.html#addImportPath">QDeclarativeEngine::addImportPath</a>() or the <tt>QML_IMPORT_PATH</tt> environment variable. When running the <a href="qmlviewer.html">QML Viewer</a>, you can also use the <tt>-I</tt> option to add an import path.</p>
<a name="creating-installed-modules"></a>
<h3>Creating Installed Modules</h3>
<p>As an example, suppose the <tt>MyQMLProject</tt> directory in the <a href="#located-modules">previous example</a> was located on the local filesystem at <tt>C:\qml\projects\MyQMLProject</tt>. The <tt>MyComponents</tt> subdirectory could be made available as an installed module by adding a <a href="#writing-a-qmldir-file">qmldir file</a> to the <tt>MyComponents</tt> directory that looked like this:</p>
<pre class="cpp"> Slider <span class="number">1.0</span> Slider<span class="operator">.</span>qml
CheckBox <span class="number">1.0</span> CheckBox<span class="operator">.</span>qml
Window <span class="number">1.0</span> Window<span class="operator">.</span>qml</pre>
<p>Providing the path <tt>C:\qml</tt> is added to the QML import path using any of the methods listed previously, a QML file located anywhere on the local filesystem can then import the module as shown below, without referring to the module's absolute filesystem location:</p>
<pre class="qml"> import projects.MyQMLProject.MyComponents 1.0
<span class="type">Window</span> {
<span class="type">Slider</span> {
<span class="comment">// ...</span>
}
<span class="type">CheckBox</span> {
<span class="comment">// ...</span>
}
}</pre>
<p>Installed modules are also accessible as a network resource. If the <tt>C:\qml</tt> directory was hosted as <tt>http://www.some-server.com/qml</tt> and this URL was added to the QML import path, the above QML code would work just the same.</p>
<p>Note that modules imported as a network resource allow only access to components defined in QML files; components defined by C++ <a href="qdeclarativeextensionplugin.html">QML extension plugins</a> are not available.</p>
<a name="creating-installed-modules-in-c"></a>
<h3>Creating Installed Modules in C++</h3>
<p>C++ applications can define installed modules directly within the application using <a href="qdeclarativeengine.html#qmlRegisterType">qmlRegisterType</a>(). For example, the <a href="qml-extending-tutorial-index.html">Writing QML extensions with C++ tutorial</a> defines a C++ class named <tt>PieChart</tt> and makes this type available to QML by calling <a href="qdeclarativeengine.html#qmlRegisterType">qmlRegisterType</a>():</p>
<pre class="cpp"> qmlRegisterType<span class="operator"><</span>PieChart<span class="operator">></span>(<span class="string">"Charts"</span><span class="operator">,</span> <span class="number">1</span><span class="operator">,</span> <span class="number">0</span><span class="operator">,</span> <span class="string">"PieChart"</span>);</pre>
<p>This allows the application's QML files to use the <tt>PieChart</tt> type by importing the declared <tt>Charts</tt> module:</p>
<pre class="qml"> import Charts 1.0</pre>
<p>For <a href="qdeclarativeextensionplugin.html">QML plugins</a>, the module URI is automatically passed to <a href="qdeclarativeextensionplugin.html#registerTypes">QDeclarativeExtensionPlugin::registerTypes</a>(). This method can be reimplemented by the developer to register the necessary types for the module. Below is the <tt>registerTypes()</tt> implementation from the <a href="declarative-cppextensions-plugins.html">QML plugins</a> example:</p>
<pre class="cpp"> <span class="keyword">class</span> <span class="type">QExampleQmlPlugin</span> : <span class="keyword">public</span> <span class="type"><a href="qdeclarativeextensionplugin.html">QDeclarativeExtensionPlugin</a></span>
{
Q_OBJECT
<span class="keyword">public</span>:
<span class="type">void</span> registerTypes(<span class="keyword">const</span> <span class="type">char</span> <span class="operator">*</span>uri)
{
Q_ASSERT(uri <span class="operator">=</span><span class="operator">=</span> QLatin1String(<span class="string">"com.nokia.TimeExample"</span>));
qmlRegisterType<span class="operator"><</span>TimeModel<span class="operator">></span>(uri<span class="operator">,</span> <span class="number">1</span><span class="operator">,</span> <span class="number">0</span><span class="operator">,</span> <span class="string">"Time"</span>);
}
};</pre>
<p>Once the plugin is built and installed, and includes a <a href="#writing-a-qmldir-file">qmldir file</a>, the module can be imported from QML, like this:</p>
<pre class="qml"> import com.nokia.TimeExample 1.0</pre>
<p>Unlike QML types defined by QML files, a QML type defined in a C++ extension plugin cannot be loaded by a module that is imported as a network resource.</p>
<a name="namespaces"></a><a name="namespaces-using-named-imports"></a>
<h2>Namespaces: Using Named Imports</h2>
<p>By default, when a module is imported, its contents are imported into the global namespace. You may choose to import the module into another namespace, either to allow identically-named types to be referenced, or purely for readability.</p>
<p>To import a module into a specific namespace, use the <i>as</i> keyword:</p>
<pre class="qml"> import QtQuick 1.0 as QtLibrary
import "../MyComponents" as MyComponents
import com.nokia.qml.mymodule 1.0 as MyModule</pre>
<p>Types from these modules can then only be used when qualified by the namespace:</p>
<pre class="qml"> <span class="type">QtLibrary</span>.Rectangle {
<span class="comment">// ...</span>
}
<span class="type">MyComponents</span>.Slider {
<span class="comment">// ...</span>
}
<span class="type">MyModule</span>.SomeComponent {
<span class="comment">// ...</span>
}</pre>
<p>Multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace:</p>
<pre class="qml"> import QtQuick 1.0 as Nokia
import Ovi 1.0 as Nokia</pre>
<a name="javascript-files"></a>
<h3>JavaScript Files</h3>
<p>JavaScript files must always be imported with a named import:</p>
<pre class="qml"> import "somescript.js" as MyScript
<span class="type"><a href="qml-item.html">Item</a></span> {
<span class="comment">//...</span>
<span class="name">Component</span>.onCompleted: <span class="name">MyScript</span>.<span class="name">doSomething</span>()
}</pre>
<p>The qualifier ("MyScript" in the above example) must be unique within the QML document. Unlike ordinary modules, multiple scripts cannot be imported into the same namespace.</p>
<a name="writing-a-qmldir-file"></a>
<h2>Writing a qmldir File</h2>
<p>A <tt>qmldir</tt> file is a metadata file for a module that maps all type names in the module to versioned QML files. It is required for installed modules, and located modules that are loaded from a network source.</p>
<p>It is defined by a plain text file named "qmldir" that contains one or more lines of the form:</p>
<pre class="cpp"> <span class="preprocessor"># <Comment></span>
<span class="operator"><</span>TypeName<span class="operator">></span> <span class="operator">[</span><span class="operator"><</span>InitialVersion<span class="operator">></span><span class="operator">]</span> <span class="operator"><</span>File<span class="operator">></span>
internal <span class="operator"><</span>TypeName<span class="operator">></span> <span class="operator"><</span>File<span class="operator">></span>
plugin <span class="operator"><</span>Name<span class="operator">></span> <span class="operator">[</span><span class="operator"><</span>Path<span class="operator">></span><span class="operator">]</span>
typeinfo <span class="operator"><</span>File<span class="operator">></span></pre>
<p><b># <Comment></b> lines are used for comments. They are ignored by the QML engine.</p>
<p><b><TypeName> [<InitialVersion>] <File></b> lines are used to add QML files as types. <TypeName> is the type being made available, the optional <InitialVersion> is a version number, and <File> is the (relative) file name of the QML file defining the type.</p>
<p>Installed files do not need to import the module of which they are a part, as they can refer to the other QML files in the module as relative (local) files, but if the module is imported from a remote location, those files must nevertheless be listed in the <tt>qmldir</tt> file. Types which you do not wish to export to users of your module may be marked with the <tt>internal</tt> keyword: <b>internal <TypeName> <File></b>.</p>
<p>The same type can be provided by different files in different versions, in which case later versions (e.g. 1.2) must precede earlier versions (e.g. 1.0), since the <i>first</i> name-version match is used and a request for a version of a type can be fulfilled by one defined in an earlier version of the module. If a user attempts to import a version earlier than the earliest provided or later than the latest provided, the import produces a runtime error, but if the user imports a version within the range of versions provided, even if no type is specific to that version, no error will occur.</p>
<p>A single module, in all versions, may only be provided in a single directory (and a single <tt>qmldir</tt> file). If multiple are provided, only the first in the search path will be used (regardless of whether other versions are provided by directories later in the search path).</p>
<p>The versioning system ensures that a given QML file will work regardless of the version of installed software, since a versioned import <i>only</i> imports types for that version, leaving other identifiers available, even if the actual installed version might otherwise provide those identifiers.</p>
<p><b>plugin <Name> [<Path>]</b> lines are used to add <a href="qdeclarativeextensionplugin.html">QML C++ plugins</a> to the module. <Name> is the name of the library. It is usually not the same as the file name of the plugin binary, which is platform dependent; e.g. the library <tt>MyAppTypes</tt> would produce <tt>libMyAppTypes.so</tt> on Linux and <tt>MyAppTypes.dll</tt> on Windows.</p>
<p><Path> is an optional argument specifying either an absolute path to the directory containing the plugin file, or a relative path from the directory containing the <tt>qmldir</tt> file to the directory containing the plugin file. By default the engine searches for the plugin library in the directory that contains the <tt>qmldir</tt> file. The plugin search path can be queried with <a href="qdeclarativeengine.html#pluginPathList">QDeclarativeEngine::pluginPathList</a>() and modified using <a href="qdeclarativeengine.html#addPluginPath">QDeclarativeEngine::addPluginPath</a>(). When running the <a href="qmlviewer.html">QML Viewer</a>, use the <tt>-P</tt> option to add paths to the plugin search path.</p>
<p><b>typeinfo <File></b> lines add <a href="#writing-a-qmltypes-file">type description files</a> to the module that can be read by QML tools such as Qt Creator to get information about the types defined by the module's plugins. <File> is the (relative) file name of a .qmltypes file.</p>
<p>Without such a file QML tools may be unable to offer features such as code completion for the types defined in your plugins.</p>
<a name="debugging"></a>
<h2>Debugging</h2>
<p>The <tt>QML_IMPORT_TRACE</tt> environment variable can be useful for debugging when there are problems with finding and loading modules. See <a href="qdeclarativedebugging.html#debugging-module-imports">Debugging module imports</a> for more information.</p>
<a name="writing-a-qmltypes-file"></a>
<h2>Writing a qmltypes file</h2>
<p>QML modules may refer to one or more type information files in their <a href="#writing-a-qmldir-file">qmldir</a> file. These usually have the .qmltypes extension and are read by external tools to gain information about types defined in plugins.</p>
<p>As such qmltypes files have no effect on the functionality of a QML module. Their only use is to allow tools such as Qt Creator to provide code completion, error checking and other functionality to users of your module.</p>
<p>Any module that uses plugins should also ship a type description file.</p>
<p>The best way to create a qmltypes file for your module is to generate it using the <tt>qmlplugindump</tt> tool that is provided with Qt.</p>
<p>Example: If your module is in <tt>/tmp/imports/My/Module</tt>, you could run</p>
<pre class="cpp"> qmlplugindump My<span class="operator">.</span>Module <span class="number">1.0</span> <span class="operator">/</span>tmp<span class="operator">/</span>imports <span class="operator">></span> <span class="operator">/</span>tmp<span class="operator">/</span>imports<span class="operator">/</span>My<span class="operator">/</span>Module<span class="operator">/</span>mymodule<span class="operator">.</span>qmltypes</pre>
<p>to generate type information for your module. Afterwards, add the line</p>
<pre class="cpp"> typeinfo mymodule<span class="operator">.</span>qmltypes</pre>
<p>to <tt>/tmp/imports/My/Module/qmldir</tt> to register it.</p>
<p>While the qmldump tool covers most cases, it does not work if:</p>
<ul>
<li>The plugin uses a QDeclarativeCustomParser. The component that uses the custom parser will not get its members documented.</li>
<li>The plugin can not be loaded. In particular if you cross-compiled the plugin for a different architecture, qmldump will not be able to load it.</li>
</ul>
<p>In case you have to create a qmltypes file manually or need to adjust an existing one, this is the file format:</p>
<pre class="qml"> import QtQuick.tooling 1.1
<span class="comment">// There always is a single Module object that contains all</span>
<span class="comment">// Component objects.</span>
<span class="type">Module</span> {
<span class="comment">// A Component object directly corresponds to a type exported</span>
<span class="comment">// in a plugin with a call to qmlRegisterType.</span>
<span class="type"><a href="qml-component.html">Component</a></span> {
<span class="comment">// The name is a unique identifier used to refer to this type.</span>
<span class="comment">// It is recommended you simply use the C++ type name.</span>
<span class="name">name</span>: <span class="string">"QDeclarativeAbstractAnimation"</span>
<span class="comment">// The name of the prototype Component.</span>
<span class="name">prototype</span>: <span class="string">"QObject"</span>
<span class="comment">// The name of the default property.</span>
<span class="name">defaultProperty</span>: <span class="string">"animations"</span>
<span class="comment">// The name of the type containing attached properties</span>
<span class="comment">// and methods.</span>
<span class="name">attachedType</span>: <span class="string">"QDeclarativeAnimationAttached"</span>
<span class="comment">// The list of exports determines how a type can be imported.</span>
<span class="comment">// Each string has the format "URI/Name version" and matches the</span>
<span class="comment">// arguments to qmlRegisterType. Usually types are only exported</span>
<span class="comment">// once, if at all.</span>
<span class="comment">// If the "URI/" part of the string is missing that means the</span>
<span class="comment">// type should be put into the package defined by the URI the</span>
<span class="comment">// module was imported with.</span>
<span class="comment">// For example if this module was imported with 'import Foo 4.8'</span>
<span class="comment">// the Animation object would be found in the package Foo and</span>
<span class="comment">// QtQuick.</span>
<span class="name">exports</span>: [
<span class="string">"Animation 4.7"</span>,
<span class="string">"QtQuick/Animation 1.0"</span>
]
<span class="type">Property</span> {
<span class="name">name</span>: <span class="string">"animations"</span>;
<span class="name">type</span>: <span class="string">"QDeclarativeAbstractAnimation"</span>
<span class="comment">// defaults to false, whether this property is read only</span>
<span class="name">isReadonly</span>: <span class="number">true</span>
<span class="comment">// defaults to false, whether the type of this property was a pointer in C++</span>
<span class="name">isPointer</span>: <span class="number">true</span>
<span class="comment">// defaults to false: whether the type actually is a QDeclarativeListProperty<type></span>
<span class="name">isList</span>: <span class="number">true</span>
<span class="comment">// defaults to 0: the minor version that introduced this property</span>
<span class="name">revision</span>: <span class="number">1</span>
}
<span class="type">Property</span> { <span class="name">name</span>: <span class="string">"loops"</span>; <span class="name">type</span>: <span class="string">"int"</span> }
<span class="type">Property</span> { <span class="name">name</span>: <span class="string">"name"</span>; <span class="name">type</span>: <span class="string">"string"</span> }
<span class="type">Property</span> { <span class="name">name</span>: <span class="string">"loopsEnum"</span>; <span class="name">type</span>: <span class="string">"Loops"</span> }
<span class="type">Enum</span> {
<span class="name">name</span>: <span class="string">"Loops"</span>
<span class="name">values</span>: {
"Infinite": -<span class="number">2</span>,
"OnceOnly": 1
}
}
<span class="comment">// Signal and Method work the same way. The inner Parameter</span>
<span class="comment">// declarations also support the isReadonly, isPointer and isList</span>
<span class="comment">// attributes which mean the same as for Property</span>
<span class="type">Method</span> { <span class="name">name</span>: <span class="string">"restart"</span> }
<span class="type">Signal</span> { <span class="name">name</span>: <span class="string">"started"</span>; <span class="name">revision</span>: <span class="number">2</span> }
<span class="type">Signal</span> {
<span class="name">name</span>: <span class="string">"runningChanged"</span>
<span class="type">Parameter</span> { <span class="name">type</span>: <span class="string">"bool"</span> }
<span class="type">Parameter</span> { <span class="name">name</span>: <span class="string">"foo"</span>; <span class="name">type</span>: <span class="string">"bool"</span> }
}
}
}</pre>
</div>
<!-- @@@qdeclarativemodules.html -->
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
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.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Digia, Qt and their respective logos are trademarks of Digia Plc
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
