aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorChris Adams <christopher.adams@nokia.com>2012-08-06 12:15:32 +1000
committerQt by Nokia <qt-info@nokia.com>2012-08-08 13:50:40 +0200
commit4a8a8953f70197a7ab7a62fcd01b1bc08051689e (patch)
tree037e78c35f675e8d5b7bc00f26d8d984387eda86
parent3b0aa0d8048ffa0bb75bb7b29c903e4499c796a8 (diff)
Update imports and module documentation
Recently, the qmldir syntax was modified to allow a module identifier directive to be specified. This allows us to guarantee that types provided in that namespace are not overridden by other modules. Given this fundamental change, the documentation needed to be updated to reflect the new terminology surrounding imports: - modules - identified vs legacy - directories - local and remote directory imports - JavaScript resources - scripts which can be imported directly Change-Id: I5a3d38de93d0186e79b87f2b3050f2b802088348 Reviewed-by: Bea Lam <bea.lam@nokia.com>
-rw-r--r--examples/tutorials/extending/chapter6-plugins/Charts/qmldir2
-rw-r--r--examples/tutorials/extending/chapter6-plugins/ChartsPlugin/qmldir1
-rw-r--r--examples/tutorials/extending/chapter6-plugins/app.qml2
-rw-r--r--examples/tutorials/extending/chapter6-plugins/chapter6-plugins.pro2
-rw-r--r--src/qml/doc/src/cppintegration/definetypes.qdoc41
-rw-r--r--src/qml/doc/src/cppintegration/extending-tutorial.qdoc30
-rw-r--r--src/qml/doc/src/documents/structure.qdoc7
-rw-r--r--src/qml/doc/src/javascript/imports.qdoc159
-rw-r--r--src/qml/doc/src/javascript/resources.qdoc158
-rw-r--r--src/qml/doc/src/javascript/topic.qdoc21
-rw-r--r--src/qml/doc/src/modules/cppplugins.qdoc7
-rw-r--r--src/qml/doc/src/modules/identifiedmodules.qdoc198
-rw-r--r--src/qml/doc/src/modules/installedmodules.qdoc163
-rw-r--r--src/qml/doc/src/modules/legacymodules.qdoc83
-rw-r--r--src/qml/doc/src/modules/locatedmodules.qdoc148
-rw-r--r--src/qml/doc/src/modules/qmldir.qdoc250
-rw-r--r--src/qml/doc/src/modules/topic.qdoc85
-rw-r--r--src/qml/doc/src/qmlfunctions.qdoc14
-rw-r--r--src/qml/doc/src/qtqml.qdoc12
-rw-r--r--src/qml/doc/src/syntax/directoryimports.qdoc203
-rw-r--r--src/qml/doc/src/syntax/imports.qdoc237
21 files changed, 1179 insertions, 644 deletions
diff --git a/examples/tutorials/extending/chapter6-plugins/Charts/qmldir b/examples/tutorials/extending/chapter6-plugins/Charts/qmldir
new file mode 100644
index 0000000000..d9e8471b3c
--- /dev/null
+++ b/examples/tutorials/extending/chapter6-plugins/Charts/qmldir
@@ -0,0 +1,2 @@
+module Charts
+plugin chartsplugin
diff --git a/examples/tutorials/extending/chapter6-plugins/ChartsPlugin/qmldir b/examples/tutorials/extending/chapter6-plugins/ChartsPlugin/qmldir
deleted file mode 100644
index 72650d8243..0000000000
--- a/examples/tutorials/extending/chapter6-plugins/ChartsPlugin/qmldir
+++ /dev/null
@@ -1 +0,0 @@
-plugin chartsplugin \ No newline at end of file
diff --git a/examples/tutorials/extending/chapter6-plugins/app.qml b/examples/tutorials/extending/chapter6-plugins/app.qml
index b6eac44e27..09931e02b5 100644
--- a/examples/tutorials/extending/chapter6-plugins/app.qml
+++ b/examples/tutorials/extending/chapter6-plugins/app.qml
@@ -38,7 +38,7 @@
**
****************************************************************************/
import QtQuick 2.0
-import "ChartsPlugin" 1.0
+import Charts 1.0
Item {
width: 300; height: 200
diff --git a/examples/tutorials/extending/chapter6-plugins/chapter6-plugins.pro b/examples/tutorials/extending/chapter6-plugins/chapter6-plugins.pro
index 75f88b2eaa..c84b6fe7ff 100644
--- a/examples/tutorials/extending/chapter6-plugins/chapter6-plugins.pro
+++ b/examples/tutorials/extending/chapter6-plugins/chapter6-plugins.pro
@@ -2,7 +2,7 @@ TEMPLATE = lib
CONFIG += qt plugin
QT += qml quick
-DESTDIR = ChartsPlugin
+DESTDIR = Charts
TARGET = chartsplugin
OBJECTS_DIR = tmp
diff --git a/src/qml/doc/src/cppintegration/definetypes.qdoc b/src/qml/doc/src/cppintegration/definetypes.qdoc
index fd03cfc758..12da901e4c 100644
--- a/src/qml/doc/src/cppintegration/definetypes.qdoc
+++ b/src/qml/doc/src/cppintegration/definetypes.qdoc
@@ -78,8 +78,9 @@ class instance can be manipulated from QML; as
Types to QML} explains, the properties, methods and signals of any
QObject-derived class are accessible from QML code.
-To register a QObject-derived class as an instantiable QML object type, call the
-qmlRegisterType() function with the appropriate class and module URI.
+To register a QObject-derived class as an instantiable QML object type, call
+qmlRegisterType() to register the class as QML type into a particular type
+namespace. Clients can then import that namespace in order to use the type.
For example, suppose there is a \c Message class with \c author and
\c creationDate properties:
@@ -96,16 +97,16 @@ public:
\endcode
This type can be registered by calling qmlRegisterType() with an appropriate
-module URI and version number. For example, to make the type available in a
-module \c com.mycompany.messaging with version 1.0:
+type namespace and version number. For example, to make the type available in
+the \c com.mycompany.messaging namespace with version 1.0:
\code
qmlRegisterType<Message>("com.mycompany.messaging", 1, 0, "Message");
\endcode
-The type can be used in an \l{qtqml-syntax-basics.html#object-declarations}{object declaration}
-from QML, and its properties can be read and written to, as per the example
-below:
+The type can be used in an \l{qtqml-syntax-basics.html#object-declarations}
+{object declaration} from QML, and its properties can be read and written to,
+as per the example below:
\qml
import com.mycompany.messaging 1.0
@@ -215,7 +216,7 @@ Item {
\code
// MyType.qml
-import MyModule 1.0
+import MyTypes 1.0
CppType {
value: root.x
@@ -225,14 +226,14 @@ CppType {
where \c CppType maps to the C++ class \c CppType.
If the author of CppType adds a \c root property to CppType in a new
-version of the module, \c root.x now resolves to a different value because
-\c root is also the \c id of the top level component. The author could
+version of their type definition, \c root.x now resolves to a different value
+because \c root is also the \c id of the top level component. The author could
specify that the new \c root property is available from a specific minor
version. This permits new properties and features to be added to existing
elements without breaking existing programs.
The REVISION tag is used to mark the \c root property as added in revision 1
-of the class. Methods such as Q_INVOKABLE's, signals and slots can also be
+of the type. Methods such as Q_INVOKABLE's, signals and slots can also be
tagged for a revision using the \c Q_REVISION(x) macro:
\code
@@ -254,13 +255,13 @@ template<typename T, int metaObjectRevision>
int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
\endcode
-To register \c CppType version 1 for \c {MyModule 1.1}:
+To register \c CppType version 1 for \c {MyTypes 1.1}:
\code
-qmlRegisterType<CppType,1>("MyModule", 1, 1, "CppType")
+qmlRegisterType<CppType,1>("MyTypes", 1, 1, "CppType")
\endcode
-\c root is only available when MyModule 1.1 is imported.
+\c root is only available when \c MyTypes version 1.1 is imported.
For the same reason, new elements introduced in later versions should use
the minor version argument of qmlRegisterType.
@@ -271,8 +272,8 @@ should always remember to document what changed between minor versions, and
QML module users should check that their application still runs correctly
before deploying an updated import statement.
-You may also register the revision of a base class that your module depends upon
-using the qmlRegisterRevision() function:
+You may also register the revision of a base class that your type depends
+upon using the qmlRegisterRevision() function:
\code
template<typename T, int metaObjectRevision>
@@ -283,14 +284,14 @@ int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMin
\endcode
For example, if \c BaseType is changed and now has a revision 1, you can
-specify that your module uses the new revision:
+specify that your type uses the new revision:
\code
-qmlRegisterRevision<BaseType,1>("MyModule", 1, 1);
+qmlRegisterRevision<BaseType,1>("MyTypes", 1, 1);
\endcode
-This is useful when deriving from base classes not declared as part of your
-module, e.g. when extending classes from the QtQuick library.
+This is useful when deriving from base classes provided by other authors,
+e.g. when extending classes from the QtQuick library.
\section1 Defining QML-Specific Types and Attributes
diff --git a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc
index 3a9c5d1579..28c310e495 100644
--- a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc
+++ b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc
@@ -78,8 +78,8 @@ several custom QML types connected together through QML features like bindings a
signals, and made available to the QML runtime through a plugin.
To begin with, let's create a new QML type called "PieChart" that has two properties: a name
-and a color. We will make it available in a \l {Modules}{module} called "Charts", with
-a module version of 1.0.
+and a color. We will make it available in an importable type namespace called "Charts", with
+a version of 1.0.
We want this \c PieChart type to be usable from QML like this:
@@ -144,8 +144,8 @@ Here is the application \c main.cpp:
\snippet examples/tutorials/extending/chapter1-basics/main.cpp 0
-This call to qmlRegisterType() registers the \c PieChart type as a type called "PieChart", in a module named "Charts",
-with a module version of 1.0.
+This call to qmlRegisterType() registers the \c PieChart type as a type called "PieChart",
+in a type namespace called "Charts", with a version of 1.0.
Lastly, we write a \c .pro project file that includes the files and the \c declarative library:
@@ -327,7 +327,7 @@ item when its contents are drawn:
Like the \c PieChart type, the \c PieSlice type has to be registered
using qmlRegisterType() to be used from QML. As with \c PieChart, we'll add the
-type to the "Charts" module, version 1.0:
+type to the "Charts" type namespace, version 1.0:
\snippet examples/tutorials/extending/chapter4-customPropertyTypes/main.cpp 0
\dots
@@ -398,8 +398,8 @@ Currently the \c PieChart and \c PieSlice types are used by \c app.qml,
which is displayed using a QQuickView in a C++ application. An alternative
way to use our QML extension is to create a plugin library to make it available
to the QML engine. This would allow the \c PieChart and \c PieSlice types to be
-imported as part of a module by any QML application, instead of restricting these
-types to be only used by the one application.
+registered into a type namespace which could be imported by any QML application,
+instead of restricting these types to be only used by the one application.
The setps for creating a plugin are described in \l {Creating C++ Plugins for QML}.
To start with, we create a plugin class named \c ChartsPlugin. It subclasses QQmlExtensionPlugin
@@ -418,23 +418,23 @@ and specifies with DESTDIR that library files should be built into a "lib" subdi
\quotefile examples/tutorials/extending/chapter6-plugins/chapter6-plugins.pro
-Finally, we add a \l{Adding Module Metadata with a qmldir file}{qmldir} file that is
-automatically parsed by the QML engine. In this file, we specify that a plugin named
+Finally, we add a \l{qtqml-modules-qmldir.html}{qmldir} file that is
+parsed by the QML engine. In this file, we specify that a plugin named
"chapter6-plugin" (the name of the example project) can be found in the "lib" subdirectory:
\quotefile examples/tutorials/extending/chapter6-plugins/ChartsPlugin/qmldir
Now we have a plugin, and instead of having a main.cpp and an executable, we can build
-the project and then load the QML file using the \l{Prototyping with qmlscene}{qmlscene tool}:
+the project and then load the QML file using the \l{Prototyping with qmlscene}{qmlscene tool},
+setting the import path to the current directory so that it finds the \c qmldir file:
\code
- qmlscene app.qml
+ qmlscene -I . app.qml
\endcode
-Notice the "import Charts 1.0" statement has disappeared from \c app.qml. This is
-because the \c qmldir file is in the same directory as \c app.qml: this is equivalent to
-having PieChart.qml and PieSlice.qml files inside the project directory, which could both
-be used by \c app.qml without import statements.
+The module "Charts" will be loaded by the QML engine, and the types provided by that
+module will be available for use in any QML document which imports it.
+
*/
diff --git a/src/qml/doc/src/documents/structure.qdoc b/src/qml/doc/src/documents/structure.qdoc
index 85d028688d..e268a4a7ae 100644
--- a/src/qml/doc/src/documents/structure.qdoc
+++ b/src/qml/doc/src/documents/structure.qdoc
@@ -45,7 +45,12 @@ QML documents are always encoded in UTF-8 format.
\section1 Imports
-A document must import the necessary modules to enable the engine to load the QML object types referenced within the document. By default, a document can access any QML object types that have been defined through \c .qml files in the same directory; if a document needs to refer to any other object types, it must import the module that exports those types.
+A document must import the necessary modules or type namespaces to enable the
+engine to load the QML object types referenced within the document. By default,
+a document can access any QML object types that have been defined through
+\c .qml files in the same directory; if a document needs to refer to any other
+object types, it must import the type namespace into which those types have
+been registered.
QML does \e not have a preprocessor that modifies the document prior to
presentation to the \l{QQmlEngine}{QML engine}, unlike C or C++.
diff --git a/src/qml/doc/src/javascript/imports.qdoc b/src/qml/doc/src/javascript/imports.qdoc
index 08acccbe21..fb3fc2570f 100644
--- a/src/qml/doc/src/javascript/imports.qdoc
+++ b/src/qml/doc/src/javascript/imports.qdoc
@@ -26,62 +26,62 @@
****************************************************************************/
/*!
\page qtqml-javascript-imports.html
-\title Importing JavaScript Files in QML Documents
-\brief Description of how to import and use JavaScript files in QML documents
-
-Both relative and absolute JavaScript URLs can be imported in QML documents.
-In the case of a relative URL, the location is resolved relative to the
-location of the \l {QML Document} that contains the import. If the script
-file is not accessible, an error will occur. If the JavaScript needs to be
-fetched from a network resource, the component's
+\title Importing JavaScript Resources in QML
+\brief Description of how to import and use JavaScript resources in QML documents
+
+\l{qtqml-javascript-resources.html}{JavaScript resources} may be imported by
+QML documents and other JavaScript resources. JavaScript resources may be
+imported via either relative or absolute URLs. In the case of a relative URL,
+the location is resolved relative to the location of the \l {QML Document} or
+\l{qtqml-javascript-resources.html}{JavaScript Resource} that contains the
+import. If the script file is not accessible, an error will occur. If the
+JavaScript needs to be fetched from a network resource, the component's
\l {QQmlComponent::status()}{status} is set to "Loading" until the script has
been downloaded.
-Imported JavaScript files are always qualified using the "as" keyword. The
-qualifier for JavaScript files must be unique, so there is always a one-to-one
-mapping between qualifiers and JavaScript files. (This also means qualifiers
-cannot be named the same as built-in JavaScript objects such as \c Date and
-\c Math).
+JavaScript resources may also import QML modules and other JavaScript
+resources. The syntax of an import statement within a JavaScript resource
+differs slightly from an import statement within a QML document, which is
+documented thoroughly below.
-The functions defined in an imported JavaScript file are available to objects
-defined in the importing QML document, via the \c{"Qualifier.functionName()"}
-syntax.
-
-\section1 Importing a JavaScript File from Another
-
-In QtQuick 2.0, support has been added to allow JavaScript files to import
-other JavaScript files and also QML type namespaces using a variation of the
-standard QML import syntax (where all of the previously described rules and
-qualifications apply).
+\section1 Importing a JavaScript Resource from a QML Document
-A JavaScript file may import another in the following fashion:
+A QML document may import a JavaScript resource with the following syntax:
\code
-.import "filename.js" as Qualifier
+import "ResourceURL" as Qualifier
\endcode
For example:
\code
-.import "factorial.js" as MathFunctions
+import "jsfile.js" as Logic
\endcode
-A JavaScript file may import a QML type namespace in the following fashion:
-\code
-.import TypeNamespace MajorVersion.MinorVersion as Qualifier
-\endcode
+Imported JavaScript resources are always qualified using the "as" keyword. The
+qualifier for JavaScript resources must be unique, so there is always a
+one-to-one mapping between qualifiers and JavaScript files. (This also means
+qualifiers cannot be named the same as built-in JavaScript objects such as
+\c Date and \c Math).
-For example:
-\code
-.import Qt.test 1.0 as JsQtTest
-\endcode
-
-In particular, this may be useful in order to access functionality provided
-via a singleton type; see qmlRegisterSingletonType() for more information.
+The functions defined in an imported JavaScript file are available to objects
+defined in the importing QML document, via the
+\c{"Qualifier.functionName(params)"} syntax. Functions in JavaScript resources
+may take parameters whose type can be any of the supported QML basic types or
+object types, as well as normal JavaScript types. The normal
+\l{qtqml-cppintegration-data.html}{data type conversion rules} will apply to
+parameters and return values when calling such functions from QML.
+
+\section1 Imports Within JavaScript Resources
+
+In QtQuick 2.0, support has been added to allow JavaScript resources to import
+other JavaScript resources and also QML type namespaces using a variation of
+the standard QML import syntax (where all of the previously described rules and
+qualifications apply).
-Due to the ability of a JavaScript file to import another script or QML module
-in this fashion in QtQuick 2.0, some extra semantics are defined:
+Due to the ability of a JavaScript resource to import another script or QML
+module in this fashion in QtQuick 2.0, some extra semantics are defined:
\list
-\li a script with imports will not inherit imports from the QML file which imported it (so accessing Component.error will fail, for example)
-\li a script without imports will inherit imports from the QML file which imported it (so accessing Component.error will succeed, for example)
-\li a shared script (i.e., defined as .pragma library) does not inherit imports from any QML file even if it imports no other scripts
+\li a script with imports will not inherit imports from the QML document which imported it (so accessing Component.errorString will fail, for example)
+\li a script without imports will inherit imports from the QML document which imported it (so accessing Component.errorString will succeed, for example)
+\li a shared script (i.e., defined as .pragma library) does not inherit imports from any QML document even if it imports no other scripts or modules
\endlist
The first semantic is conceptually correct, given that a particular script
@@ -91,71 +91,34 @@ unchanged from the current semantics for shared scripts, but is clarified here
in respect to the newly possible case (where the script imports other scripts
or modules).
+\section2 Importing a JavaScript Resource from Another JavaScript Resource
-\section2 Code-Behind Implementation Files
-
-Most JavaScript files imported into a QML file are stateful implementations
-for the QML file importing them. In these cases, for QML component instances
-to behave correctly each instance requires a separate copy of the JavaScript
-objects and state.
-
-The default behavior when importing JavaScript files is to provide a unique,
-isolated copy for each QML component instance. If that JavaScript file does
-not import any other JavaScript files or QML type namespaces, its code will run
-in the same scope as the QML component instance and consequently can can access
-and manipulate the objects and properties declared in that QML component.
-Otherwise, it will have its own unique scope, and objects and properties of the
-QML component should be passed to the functions of the JavaScript file as
-parameters if they are required.
-
-\section2 Shared JavaScript Files (Libraries)
-
-Some JavaScript files act more like libraries - they provide a set of helper
-functions that take input and compute output, but never manipulate QML
-component instances directly.
-
-As it would be wasteful for each QML component instance to have a unique copy of
-these libraries, the JavaScript programmer can indicate a particular file is a
-shared library through the use of a pragma, as shown in the following example.
-
+A JavaScript resource may import another in the following fashion:
\code
-// factorial.js
-.pragma library
-
-var factorialCount = 0;
-
-function factorial(a) {
- a = parseInt(a);
-
- // factorial recursion
- if (a > 0)
- return a * factorial(a - 1);
-
- // shared state
- factorialCount += 1;
+.import "filename.js" as Qualifier
+\endcode
+For example:
+\code
+.import "factorial.js" as MathFunctions
+\endcode
- // recursion base-case.
- return 1;
-}
+\section2 Importing a QML Module from a JavaScript Resource
-function factorialCallCount() {
- return factorialCount;
-}
+A JavaScript resource may import a QML module in the following fashion:
+\code
+.import TypeNamespace MajorVersion.MinorVersion as Qualifier
\endcode
-The pragma declaration must appear before any JavaScript code excluding comments.
+For example:
+\code
+.import Qt.test 1.0 as JsQtTest
+\endcode
-Note that multiple QML documents can import \c{"factorial.js"} and call the
-factorial and factorialCallCount functions that it provides. The state of the
-JavaScript import is shared across the QML documents which import it, and thus
-the return value of the factorialCallCount function may be non-zero when called
-within a QML document which never calls the factorial function.
+In particular, this may be useful in order to access functionality provided
+via a singleton type; see qmlRegisterSingletonType() for more information.
-As they are shared, .pragma library files cannot access QML component instance
-objects or properties directly, although QML values can be passed as function
-parameters.
-\section1 Including a JavaScript File from Another
+\section1 Including a JavaScript Resource from Another JavaScript Resource
When a JavaScript file is imported, it must be imported with a qualifier. The
functions in that file are then accessible from the importing script via the
diff --git a/src/qml/doc/src/javascript/resources.qdoc b/src/qml/doc/src/javascript/resources.qdoc
new file mode 100644
index 0000000000..b2299d7a0d
--- /dev/null
+++ b/src/qml/doc/src/javascript/resources.qdoc
@@ -0,0 +1,158 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\page qtqml-javascript-resources.html
+\title Defining JavaScript Resources In QML
+\brief Description of how JavaScript files may be defined for use in QML
+
+The program logic for a QML application may be defined in JavaScript. The
+JavaScript code may either be defined in-line in QML documents, or separated
+into JavaScript files (known as \c {JavaScript Resources} in QML).
+
+There are two different kinds of JavaScript resources which are supported in
+QML: code-behind implementation files, and shared (library) files. Both kinds
+of JavaScript resource may be \l{qtqml-javascript-imports.html}{imported} by
+other JavaScript resources, or included in \l{qtqml-modules-topic.html}
+{QML modules}.
+
+\section1 Code-Behind Implementation Resource
+
+Most JavaScript files imported into a QML document are stateful implementations
+for the QML document importing them. In these cases, each instance of the QML
+object type defined in the document requires a separate copy of the JavaScript
+objects and state in order to behave correctly.
+
+The default behavior when importing JavaScript files is to provide a unique,
+isolated copy for each QML component instance. If that JavaScript file does
+not import any resources or modules with a \c{.import} statement, its code will
+run in the same scope as the QML component instance and consequently can access
+and manipulate the objects and properties declared in that QML component.
+Otherwise, it will have its own unique scope, and objects and properties of the
+QML component should be passed to the functions of the JavaScript file as
+parameters if they are required.
+
+An example of a code-behind implementation resource follows:
+
+\qml
+// MyButton.qml
+import QtQuick 2.0
+import "my_button_impl.js" as Logic // a new instance of this JavaScript resource is loaded for each instance of Button.qml
+
+Rectangle {
+ id: rect
+ width: 200
+ height: 100
+ color: "red"
+
+ MouseArea {
+ id: mousearea
+ anchors.fill: parent
+ onClicked: Logic.onClicked(rect)
+ }
+}
+\endqml
+
+\qml
+// my_button_impl.js
+var clickCount = 0; // this state is separate for each instance of MyButton
+function onClicked(btn) {
+ clickCount += 1;
+ if ((clickCount % 5) == 0) {
+ obj.color = Qt.rgba(1,0,0,1);
+ } else {
+ obj.color = Qt.rgba(0,1,0,1);
+ }
+}
+\endqml
+
+In general, simple logic should be defined in-line in the QML file, but more
+complex logic should be separated into code-behind implementation resources
+for maintainability and readability.
+
+\section1 Shared JavaScript Resources (Libraries)
+
+Some JavaScript files act more like libraries - they provide a set of helper
+functions that take input and compute output, but never manipulate QML
+component instances directly.
+
+As it would be wasteful for each QML component instance to have a unique copy of
+these libraries, the JavaScript programmer can indicate a particular file is a
+shared library through the use of a pragma, as shown in the following example.
+
+\code
+// factorial.js
+.pragma library
+
+var factorialCount = 0;
+
+function factorial(a) {
+ a = parseInt(a);
+
+ // factorial recursion
+ if (a > 0)
+ return a * factorial(a - 1);
+
+ // shared state
+ factorialCount += 1;
+
+ // recursion base-case.
+ return 1;
+}
+
+function factorialCallCount() {
+ return factorialCount;
+}
+\endcode
+
+The pragma declaration must appear before any JavaScript code excluding comments.
+
+Note that multiple QML documents can import \c{"factorial.js"} and call the
+factorial and factorialCallCount functions that it provides. The state of the
+JavaScript import is shared across the QML documents which import it, and thus
+the return value of the factorialCallCount function may be non-zero when called
+within a QML document which never calls the factorial function.
+
+For example:
+
+\qml
+// Calculator.qml
+import QtQuick 2.0
+import "factorial.js" as FactorialCalculator // this JavaScript resource is only ever loaded once by the engine, even if multiple instances of Calculator.qml are created
+
+Text {
+ width: 500
+ height: 100
+ property int input: 17
+ text: "The factorial of " + input + " is: " + FactorialCalculator.factorial(input)
+}
+\endqml
+
+As they are shared, .pragma library files cannot access QML component instance
+objects or properties directly, although QML values can be passed as function
+parameters.
+
+*/
diff --git a/src/qml/doc/src/javascript/topic.qdoc b/src/qml/doc/src/javascript/topic.qdoc
index 19019f0817..2c3006ef60 100644
--- a/src/qml/doc/src/javascript/topic.qdoc
+++ b/src/qml/doc/src/javascript/topic.qdoc
@@ -51,13 +51,26 @@ See the documentation page titled
\l{qtqml-javascript-expressions.html}{JavaScript Expressions in QML Documents}
for more information about using JavaScript expressions in QML.
+\section1 JavaScript Resources
+
+Application logic defined in JavaScript functions may be separated into
+separate JavaScript files known as JavaScript resources. There are several
+different kinds of JavaScript resources, with different semantics.
+
+See the documentation page titled \l{qtqml-javascript-resources.html}
+{Defining JavaScript Resources In QML} for more information about defining JavaScript
+resources for QML.
+
\section1 JavaScript Imports
-A QML document may import JavaScript files. This allows an application
-developer to provide application logic in modular, self-contained files.
+A QML document may import JavaScript resources, and JavaScript resources may
+import other JavaScript resources as well as QML modules. This allows an
+application developer to provide application logic in modular, self-contained
+files.
+
See the documentation page titled
-\l{qtqml-javascript-imports.html}{Importing JavaScript Files in QML Documents}
-for more information on how to import JavaScript files and how to use the
+\l{qtqml-javascript-imports.html}{Importing JavaScript Resources}
+for more information on how to import JavaScript resources and how to use the
functionality they provide.
\section1 JavaScript Host Environment
diff --git a/src/qml/doc/src/modules/cppplugins.qdoc b/src/qml/doc/src/modules/cppplugins.qdoc
index d96b3a8e56..df4156d67a 100644
--- a/src/qml/doc/src/modules/cppplugins.qdoc
+++ b/src/qml/doc/src/modules/cppplugins.qdoc
@@ -81,14 +81,15 @@
\snippet examples/qml/cppextensions/plugins/plugin.cpp plugin
The \c TimeModel class receives a \c{1.0} version of this plugin library, as
- a QML type called \c Time. The Q_ASSERT() macro can ensure the module is
+ a QML type called \c Time. The Q_ASSERT() macro can ensure the type namespace is
imported correctly by any QML components that use this plugin. The
\l{Defining QML Types from C++} article has more information about registering C++
types into the runtime.
For this example, the TimeExample source directory is in
- \c{com/nokia/TimeExample}. The plugin's module import statement will follow
- this structure, so the module is registered as "com.nokia.TimeExample".
+ \c{com/nokia/TimeExample}. The plugin's type namespace will mirror
+ this structure, so the types are registered into the namespace
+ "com.nokia.TimeExample".
Additionally, the project file, in a \c .pro file, defines the project as a plugin library,
specifies it should be built into the \c com/nokia/TimeExample directory, and registers
diff --git a/src/qml/doc/src/modules/identifiedmodules.qdoc b/src/qml/doc/src/modules/identifiedmodules.qdoc
new file mode 100644
index 0000000000..fd7a339db9
--- /dev/null
+++ b/src/qml/doc/src/modules/identifiedmodules.qdoc
@@ -0,0 +1,198 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\page qtqml-modules-identifiedmodules.html
+\title Identified Modules
+\brief Creating and importing identified modules
+
+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 \c qmldir 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.
+
+When importing an identified module, an unquoted identifier is used, with a
+mandatory version number:
+
+\snippet qml/imports/installed-module.qml imports
+
+Identified modules must be installed into the
+\l{qtqml-syntax-imports.html#qml-import-path}{import path} in order to be found
+by the QML engine.
+
+\section1 Locally Installed Identified Modules
+
+A directory of QML and/or C++ files can be shared as an identified module if it
+contains a \l{qtqml-modules-qmldir.html}{qmldir file} 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
+\l{qtqml-syntax-imports.html}{import} statement that refers to the module's
+URI, enabling the file to use the \l{qtqml-typesystem-objecttypes.html}
+{QML object types} and \l{qtqml-javascript-resources.html}
+{JavaScript resources} defined by the module.
+
+The module's \c qmldir file must reside in a directory structure within the
+\l{qtqml-syntax-imports.html#qml-import-path}{import path} that reflects the
+URI dotted identifier string, where each dot (".") in the identifier reflects
+a sub-level in the directory tree. For example, the \c qmldir file of the
+module \c com.mycompany.mymodule must be located in the sub-path
+\c com/mycompany/mymodule/qmldir somewhere in the
+\l{qtqml-syntax-imports.html#qml-import-path}{import path}.
+
+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
+\c com/mycompany/mymodule.2/qmldir or \c com/mycompany/mymodule.2.1/qmldir.
+The engine will automatically load the module which matches best.
+
+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
+\c qmldir file merge must take place as part of the update procedure).
+
+
+\section2 An Example
+
+Consider the following QML project directory structure. Under the top level
+directory \c myapp, there are a set of common UI components in a sub-directory
+named \c mycomponents, and the main application code in a sub-directory named
+\c main, like this:
+
+\code
+myapp
+ |- mycomponents
+ |- CheckBox.qml
+ |- DialogBox.qml
+ |- Slider.qml
+ |- main
+ |- application.qml
+\endcode
+
+To make the \c mycomponents directory available as an identified module, the
+directory must include a \l{qtqml-modules-qmldir.html}{qmldir file} that
+defines the module identifier, and describes the object types made available by
+the module. For example, to make the \c CheckBox, \c DialogBox and \c Slider
+types available for version 1.0 of the module, the \c qmldir file would contain
+the following:
+
+\code
+module myapp.mycomponents
+CheckBox 1.0 CheckBox.qml
+DialogBox 1.0 DialogBox.qml
+Slider 1.0 Slider.qml
+\endcode
+
+Additionally, the location of the \c qmldir file in the
+\l{qtqml-syntax-imports.html#qml-import-path}{import path} must match the
+module's dotted identifier string. So, say the top level \c myapp directory is
+located in \c C:\qml\projects, and say the module should be identified as
+"myapp.mycomponents". In this case:
+
+\list
+\li The path \c C:\qml\projects should be added to the
+ \l{qtqml-syntax-imports.html#qml-import-path}{import path}
+\li The qmldir file should be located under \c C:\qml\projects\myapp\mycomponents\qmldir
+\endlist
+
+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:
+
+\qml
+import myapp.mycomponents 1.0
+
+DialogBox {
+ CheckBox {
+ // ...
+ }
+ Slider {
+ // ...
+ }
+}
+\endqml
+
+\section1 Remotely Installed Identified Modules
+
+Identified modules are also accessible as a network resource. In the previous
+example, if the \c C:\qml\projects directory was hosted as
+\c http://www.some-server.com/qml/projects and this URL was added to the QML
+import path, the module could be imported in exactly the same way.
+
+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.
+
+
+\section1 Semantics of Identified Modules
+
+An identified module is provided with the following guarantees by the QML
+engine:
+\list
+\li other modules are unable to modify or override types in the module's
+ namespace
+\li other modules are unable to register new types into the module's
+ namespace
+\li usage of type names by clients will resolve deterministically to a given
+ type definition depending on the versioning specified and the import order
+\endlist
+
+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.
+
+An identified module has several restrictions upon it:
+\list
+\li an identified module must must be installed into the
+ \l{qtqml-syntax-imports.html#qml-import-path}{QML import path}
+\li the module identifier specified in the \l{qtqml-modules-qmldir.html}
+ {module identifier directive} must match the install path of the module
+ (relative to the QML import path, where directory separators are replaced
+ with period characters)
+\li the module must register its types into the module identifier type
+ namespace
+\li the module may not register types into any other module's namespace
+\li clients must specify a version when importing the module
+\endlist
+
+For example, if an identified module is installed into
+\c{$QML_IMPORT_PATH/ExampleModule}, the module identifier directive must be:
+\code
+module ExampleModule
+\endcode
+
+If the strict module is installed into
+\c{$QML_IMPORT_PATH/com/example/CustomUi}, the module identifier directive
+must be:
+\code
+module com.example.CustomUi
+\endcode
+
+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):
+\qml
+import com.example.CustomUi 1.0
+\endqml
+
+*/
+
diff --git a/src/qml/doc/src/modules/installedmodules.qdoc b/src/qml/doc/src/modules/installedmodules.qdoc
deleted file mode 100644
index 4440f1bb80..0000000000
--- a/src/qml/doc/src/modules/installedmodules.qdoc
+++ /dev/null
@@ -1,163 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
-** Contact: http://www.qt-project.org/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** GNU Free Documentation License
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file.
-**
-** Other Usage
-** Alternatively, this file may be used in accordance with the terms
-** and conditions contained in a signed written agreement between you
-** and Nokia.
-**
-**
-**
-**
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-/*!
-\page qtqml-modules-installedmodules.html
-\title Installed Modules
-\brief Creating and importing installed modules
-
-Installed modules are modules that are identifiable to the QML engine by a URI in the form of a
-dotted identifier string. 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. This contrasts with
-\l{qtqml-modules-locatedmodules.html}{located modules}, which are imported according to their
-location on the file system.
-
-When importing an installed module, an unquoted URI is used, with a mandatory version number:
-
-\snippet qml/imports/installed-module.qml imports
-
-Installed modules must be made available in the \l{qtqml-syntax-imports.html#qml-import-path}{import
-path} in order to be found by the QML engine.
-
-
-\section1 Locally Installed Modules
-
-A directory of QML and/or C++ files can be shared as an installed module if it contains a
-\l{qtqml-modules-qmldir.html}{qmldir file} with the module metadata. Any QML file on the local file
-system can import this directory as a module by using an \l{qtqml-syntax-imports.html}{import}
-statement that refers to the module's URI, enabling the file to use the
-\l{qtqml-typesystem-objecttypes.html}{QML object types} defined within that directory.
-
-The module's \c qmldir file must reside in a directory structure within the
-\l{qtqml-syntax-imports.html#qml-import-path}{import path} that reflects the URI dotted identifier
-string, where each dot (".") in the identifier reflects a sub-level in the directory tree. For
-example, the \c qmldir file of the module \c com.mycompany.mymodule must be located in the sub-path
-\c com/mycompany/mymodule/qmldir somewhere in the
-\l{qtqml-syntax-imports.html#qml-import-path}{import path}.
-
-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 \c com/mycompany/mymodule.2/qmldir or \c
-com/mycompany/mymodule.2.1/qmldir. The engine will automatically load the module which matches best.
-
-
-\section2 An Example
-
-Consider the following QML project directory structure. Under the top level directory \c myapp,
-there are a set of common UI components in a sub-directory named \c mycomponents, and the main
-application code in a sub-directory named \c main, like this:
-
-\code
-myapp
- |- mycomponents
- |- CheckBox.qml
- |- DialogBox.qml
- |- Slider.qml
- |- main
- |- application.qml
-\endcode
-
-To make the \c mycomponents directory available as an installed module, the directory must include a
-\l{qtqml-modules-qmldir.html}{qmldir file} that describes the object types made available by the
-module. For example, to make the \c CheckBox, \c DialogBox and \c Slider types available for version
-1.0 of the module, the \c qmldir file would contain the following:
-
-\code
-CheckBox 1.0 CheckBox.qml
-DialogBox 1.0 DialogBox.qml
-Slider 1.0 Slider.qml
-\endcode
-
-Additionally, the location of the \c qmldir file in the
-\l{qtqml-syntax-imports.html#qml-import-path}{import path} must match the module's dotted identifier
-string. So, say the top level \c myapp directory is located in \c C:\qml\projects, and say the
-module should be identified as "myapp.mycomponents". In this case:
-
-\list
-\li The path \c C:\qml\projects should be added to the
-\l{qtqml-syntax-imports.html#qml-import-path}{import path}
-\li The qmldir file should be located under \c C:\qml\projects\myapp\mycomponents\qmldir
-\endlist
-
-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:
-
-\qml
-import myapp.mycomponents 1.0
-
-DialogBox {
- CheckBox {
- // ...
- }
- Slider {
- // ...
- }
-}
-\endqml
-
-
-\section1 Remotely Installed Modules
-
-Installed modules are also accessible as a network resource. In the previous example, if the \c
-C:\qml\projects directory was hosted as \c http://www.some-server.com/qml/projects and this URL was
-added to the QML import path, the module could be imported in exactly the same way.
-
-Note that when a file imports a module over a network, it can only access QML and JavaScript files
-provided by the module; it cannot access any types defined by C++ plugins in the module.
-
-
-\section1 In-application Modules
-
-C++ applications can define installed modules directly within the application using
-qmlRegisterType().
-
-For example, the \l {Tutorial: Extending QML with C++}{Writing QML extensions with C++ tutorial}
-defines a C++ class named \c PieChart and makes this type available to QML by calling
-qmlRegisterType():
-
-\code
-qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart");
-\endcode
-
-This allows the application's QML files to use the \c PieChart type by importing the declared
-\c Charts module:
-
-\snippet qml/imports/chart.qml import
-
-For \l{QQmlExtensionPlugin}{QML plugins}, the
-module URI is automatically passed to QQmlExtensionPlugin::registerTypes(). This method
-can be reimplemented by the developer to register the necessary types for the module. Below is the
-\c registerTypes() implementation from the \l{qml/cppextensions/plugins}{QML plugins}
-example:
-
-\snippet examples/qml/cppextensions/plugins/plugin.cpp plugin
-
-Once the plugin is built and installed, and includes a \l{Adding Module Metadata with a qmldir file}{qmldir file},
-the module can be imported from QML, like this:
-
-\snippet qml/imports/timeexample.qml import
-
-*/
-
diff --git a/src/qml/doc/src/modules/legacymodules.qdoc b/src/qml/doc/src/modules/legacymodules.qdoc
new file mode 100644
index 0000000000..40b9f953e4
--- /dev/null
+++ b/src/qml/doc/src/modules/legacymodules.qdoc
@@ -0,0 +1,83 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qtqml-modules-legacymodules.html
+\title Legacy Modules
+\brief Description of legacy QML modules
+
+Legacy modules are modules whose specification \c qmldir file does not contain
+a module identifier directive. A legacy module may be either installed into
+the QML import path (as an installed legacy module) or imported by clients with
+a relative import (as a located legacy module). Clients are advised to avoid
+using legacy modules if possible. Module developers should ensure they create
+identified modules and not legacy modules.
+
+\section1 Installed Legacy Modules
+
+An installed, non-identified module is automatically given an identifier by the
+QML engine. This implicitly defined identifier is equal to the install path of
+the module (relative to the QML import path) where directory-separator
+characters are replaced with period characters.
+
+A non-identified module which is installed into the QML import path has the
+following semantics:
+\list
+\li it may be imported by clients via the implicit module identifier
+\li clients must specify a version when importing the module
+\li conflicting type names are resolved arbitrarily by the QML engine, and the
+ way in which conflicts are resolved is not guaranteed to stay the same
+ between different versions of QML
+\li other legacy modules may modify or override type definitions provided by
+ the installed legacy module
+\endlist
+
+\section1 Located Legacy Modules
+
+A non-identified module which is imported via a relative directory path
+import statement is loaded by the engine as a located legacy module. The
+following semantics apply to located legacy modules:
+\list
+\li it may be imported by clients via a relative import path
+\li it is not mandatory for clients to specify a version when importing the
+ module
+\li if no import version is supplied by the client in the import statement,
+ no guarantees are given by the QML engine about which version of the
+ definition of a given type name will be imported
+\li conflicting type names are resolved arbitrarily by the QML engine, and the
+ way in which conflicts are resolved is not guaranteed to stay the same
+ between different versions of QML
+\li other legacy modules may modify or override type definitions provided by
+ the located legacy module
+\endlist
+
+A located legacy module may reside on the the local file system or on the
+network and can be referred to by a URL that specifies the file system path or
+network URL.
+
+*/
+
diff --git a/src/qml/doc/src/modules/locatedmodules.qdoc b/src/qml/doc/src/modules/locatedmodules.qdoc
deleted file mode 100644
index b42b1a2c42..0000000000
--- a/src/qml/doc/src/modules/locatedmodules.qdoc
+++ /dev/null
@@ -1,148 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
-** Contact: http://www.qt-project.org/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** GNU Free Documentation License
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file.
-**
-** Other Usage
-** Alternatively, this file may be used in accordance with the terms
-** and conditions contained in a signed written agreement between you
-** and Nokia.
-**
-**
-**
-**
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-/*!
-\page qtqml-modules-locatedmodules.html
-\title Located Modules
-\brief Creating and importing located modules
-
-Located modules are modules that reside on the the local file system or a
-network resource and can be referred to by a URL that specifies the file system
-path or network URL. This allows any directory with QML content to be
-\l{qtqml-syntax-imports.html}{imported} as a module, regardless of whether the
-directory is on the local file system or a remote server.
-
-
-\section1 Locally Located Modules
-
-A directory of QML files can immediately be shared as a module without any additional setup or
-configuration.
-
-Any QML file on the local file system can import this directory as a module by using an
-\l{qtqml-syntax-imports.html}{import} statement that refers to the directory's absolute or relative
-file system path, enabling the file to use the \l{qtqml-typesystem-objecttypes.html}{object types}
-defined within that directory.
-
-\section2 An Example
-
-Consider the following QML project directory structure. Under the top level directory \c myapp,
-there are a set of common UI components in a sub-directory named \c mycomponents, and the main
-application code in a sub-directory named \c main, like this:
-
-\code
-myapp
- |- mycomponents
- |- CheckBox.qml
- |- DialogBox.qml
- |- Slider.qml
- |- main
- |- application.qml
-\endcode
-
-The \c main/application.qml file can import the \c mycomponents directory as a module using the
-relative path to that directory, allowing it to use the QML object types defined within that
-directory:
-
-\qml
-import "../mycomponents"
-
-DialogBox {
- CheckBox {
- // ...
- }
- Slider {
- // ...
- }
-}
-\endqml
-
-It is not necessary to pass a version number to the \c import statement when importing a locally
-located module. Additionally, the module could be imported with a
-\l{qtqml-syntax-imports.html#namespaced-import}{namespaced import} to qualify any references to the
-types in the module:
-
-\qml
-import "../mycomponents" as MyComponents
-
-MyComponents.DialogBox {
- // ...
-}
-\endqml
-
-A local file system module may optionally include a \l{qtqml-modules-qmldir.html}{qmldir file}. This
-allows the module to only expose certain QML types to external parties. Additionally, JavaScript
-files in the module directory are not exposed to external parties unless they are declared in a
-qmldir file.
-
-The ability to import a local module using its file system path is convenient for cases such as
-in-application modules and application prototyping, though any code that imports such modules must
-must update their relevant \c import statements if the module directory moves to another location.
-This can be avoided if \l{qtqml-modules-installedmodules.html}{installed modules} are used instead,
-as an installed module is imported with a unique identifier string rather than a file system path.
-
-
-\section1 Remotely Located Modules
-
-A directory of QML files can also be imported from a remote location if the directory contains a
-\l{qtqml-modules-qmldir.html}{qmldir file}.
-
-For example, if the \c myapp directory in the previous example was hosted at
-"http://www.my-example-server.com", and the \c mycomponents directory contained a \c qmldir file
-defined as follows:
-
-\code
-CheckBox 1.0 CheckBox.qml
-DialogBox 1.0 DialogBox.qml
-Slider 1.0 Slider.qml
-\endcode
-
-Then, the module could be imported using the URL to the remote \c mycomponents directory:
-
-\qml
-import "http://www.my-example-server.com/myapp/mycomponents"
-
-DialogBox {
- CheckBox {
- // ...
- }
- Slider {
- // ...
- }
-}
-\endqml
-
-In this case the module could optionally be imported with a "1.0" version specification as that is
-the version specified in the \c qmldir file. The import would fail if any later version was used as
-the \c qmldir file specifies that these elements are only available in version 1.0.
-
-Note that when a file imports a module over a network, it can only access QML and JavaScript files
-provided by the module; it cannot access any types defined by C++ plugins in the module.
-
-\warning When importing modules from a remote server, developers should always be careful to only
-load modules from trusted sources to avoid loading malicious code.
-
-*/
-
diff --git a/src/qml/doc/src/modules/qmldir.qdoc b/src/qml/doc/src/modules/qmldir.qdoc
index 7e9b8c59b4..9802cd744e 100644
--- a/src/qml/doc/src/modules/qmldir.qdoc
+++ b/src/qml/doc/src/modules/qmldir.qdoc
@@ -26,82 +26,123 @@
****************************************************************************/
/*!
\page qtqml-modules-qmldir.html
-\title Adding Module Metadata with a qmldir File
-\brief How to write a qmldir file for a module
+\title Module Definition qmldir Files
+\brief How to write a qmldir file which defines a QML module
-A \e qmldir file is a metadata file for a module that maps all type names in the module to
-versioned QML files. It is required for \l{qtqml-modules-installedmodules.html}{installed modules},
-as well as \l{qtqml-modules-locatedmodules.html}{located modules} that are loaded from a network
-source.
-
-This file is defined by a plain text file named "qmldir" within the module. For
-\l{qtqml-modules-locatedmodules.html}{located modules}, this file should be in the module's root
-directory. For \l{qtqml-modules-installedmodules.html}{installed modules}, the file should be in a
-directory within the module according to the named identifier for the module; see the \l{Installed
-Modules} documentation for more information.
+There are two distinct types of \c qmldir files:
+\list
+\li QML document directory listing files
+\li QML module definition files
+\endlist
+This documentation covers only the second form of \c qmldir file. For more
+information about the first form of \c qmldir file, please see the
+documentation about
+\l{qtqml-syntax-directoryimports.html#directory-listing-qmldir-files}
+{directory listing qmldir files}.
-\section1 Writing a qmldir File
+\section1 Contents of a Module Definition qmldir File
-A \c qmldir file contains one or more lines of the following commands:
+A \c qmldir file which defines a module is a plain-text file which consists
+of the following commands:
\table
\header
- \li Command Syntax
+ \li Command
+ \li Syntax
\li Usage
\row
+ \li Module Identifier Directive
\li
\code
-<TypeName> [<InitialVersion>] <File>
+module <ModuleIdentifier>
\endcode
- \li Declares an \l{qtqml-typesystem-objecttypes.html}{object type} to be made available by
- the module.
+ \li Declares the module identifier of the module.
+ The <ModuleIdentifier> is the (dotted URI notation) identifier
+ for the module, which must match the module's install path.
+
+ The \l{qtqml-modules-topic.html#the-module-identifier-directive}
+ {module identifier directive} must be the first line of the file.
+ Exactly one module identifier directive may exist in the \c qmldir
+ file.
+
+ Example:
+ \code
+module ExampleModule
+ \endcode
+
+ \row
+ \li Object Type Declaration
+ \li
+ \code
+<TypeName> <InitialVersion> <File>
+ \endcode
+ \li Declares a \l{qtqml-typesystem-objecttypes.html}{QML object type}
+ to be made available by the module.
\list
\li \c <TypeName> is the type being made available
- \li \c <InitialVersion> (optional) is the module version for which the type is to be
- made available
+ \li \c <InitialVersion> is the module version for which the type is to be made available
\li \c <File> is the (relative) file name of the QML file that defines the type
\endlist
+ Zero or more object type declarations may exist in the \c qmldir
+ file, however each object type must have a unique type name within
+ any particular version of the module.
+
Example:
\code
MyCustomType 1.0 MyCustomType.qml
\endcode
+
\row
+ \li Internal Object Type Declaration
\li
\code
internal <TypeName> <File>
\endcode
- \li Declares an object type that is in the module but should not be made available to users
- of the module.
+ \li Declares an object type that is in the module but should not be
+ made available to users of the module.
+
+ Zero or more internal object type declarations may exist in the
+ \c qmldir file.
Example:
\code
internal MyPrivateType MyPrivateType.qml
\endcode
- This is necessary if the module may be imported remotely (see \l{Remotely Located
- Modules} and \l{Remotely Installed Modules}) because if an exported type depends on an
- non-exported type within the module, the engine must also load the non-exported type.
+ This is necessary if the module may be imported remotely (see
+ \l{Remotely Installed Modules}) because if an exported type depends
+ on an non-exported type within the module, the engine must also
+ load the non-exported type.
\row
+ \li JavaScript Resource Declaration
\li
\code
-<Namespace> <InitialVersion> <File>
+<ResourceIdentifier> <InitialVersion> <File>
\endcode
- \li Declares a JavaScript file to be made available by the module. The file will be made
- available through the specified namespace and verison number.
+ \li Declares a JavaScript file to be made available by the module.
+ The resource will be made available via the specified identifier
+ with the specified version number.
+
+ Zero or more JavaScript resource declarations may exist in the
+ \c qmldir file, however each JavaScript resource must have a unique
+ identifier within any particular version of the module.
Example:
\code
MyScript 1.0 MyScript.js
\endcode
- See \l{qtqml-javascript-imports.html}{Importing JavaScript Files in QML Documents} for
- more information.
+ See the documentation about \l{qtqml-javascript-resources.html}
+ {defining JavaScript resources} and
+ \l{qtqml-javascript-imports.html}
+ {Importing JavaScript Resources In QML} for more information.
\row
+ \li C++ Plugin Declaration
\li
\code
plugin <Name> [<Path>]
@@ -109,43 +150,54 @@ plugin <Name> [<Path>]
\li Declares a plugin to be made available by the module.
\list
- \li \c <Name> is the plugin library name. This is usually not the same as the file name
- of the plugin binary, which is platform dependent; e.g. the library \c MyAppTypes
- would produce \c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows.
+ \li \c <Name> is the plugin library name. This is usually not the
+ same as the file name of the plugin binary, which is platform
+ dependent; e.g. the library \c MyAppTypes would produce
+ \c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows.
\li \c <Path> (optional) specifes either:
\list
- \li an absolute path to the directory containing the plugin file, or
- \li a relative path from the directory containing the \c qmldir file to the
- directory containing the plugin file.
+ \li an absolute path to the directory containing the plugin
+ file, or
+ \li a relative path from the directory containing the \c qmldir
+ file to the directory containing the plugin file.
\endlist
- By default the engine searches for the plugin library in the directory that contains
- the \c qmldir file. (The plugin search path can be queried with
- QQmlEngine::pluginPathList() and modified using QQmlEngine::addPluginPath().)
+ By default the engine searches for the plugin library in the
+ directory that contains the \c qmldir file. (The plugin search
+ path can be queried with QQmlEngine::pluginPathList() and
+ modified using QQmlEngine::addPluginPath().)
\endlist
+ Zero or more C++ plugin declarations may exist in the \c qmldir
+ file, however since plugin loading is a relatively expensive
+ operation, clients are advised to specify at most a single plugin.
+
Example:
\code
plugin MyPluginLibrary
\endcode
\row
+ \li Type Information Description File Declaration
\li
\code
typeinfo <File>
\endcode
- \li Declares a \l{Writing a qmltypes file}{type description file} for the module that can be
- read by QML tools such as Qt Creator to access information about the types defined by the module's plugins. \c <File> is the (relative) file name of a \c .qmltypes file.
+ \li Declares a \l{Writing a qmltypes file}{type description file} for
+ the module that can be read by QML tools such as Qt Creator to
+ access information about the types defined by the module's plugins.
+ \c <File> is the (relative) file name of a \c .qmltypes file.
Example:
\code
typeinfo mymodule.qmltypes
\endcode
- Without such a file, QML tools may be unable to offer features such as code completion
- for the types defined in your plugins.
+ Without such a file, QML tools may be unable to offer features such
+ as code completion for the types defined in your plugins.
\row
+ \li Comment
\li
\code
# <Comment>
@@ -158,52 +210,96 @@ typeinfo mymodule.qmltypes
\endcode
\endtable
-For example, suppose a module's \c qmldir file should export a \c MyButton type in version 1.0, a \c
-MyWindow type in version 1.1 and a JavaScript file to a \c MyScript namespace in version 1.1.
-Providing the relevant files are in the same directory as the \c qmldir file, the contents of the \c
-qmldir file would look like this:
+Each command in a \c qmldir file must be on a separate line.
+
+\section1 Versioning Semantics
+
+Types which are exported for a particular version are still made available if a
+later version is imported. If a module provides a \c MyButton type in version
+1.0 and a \c MyWindow type in version 1.1, clients which import version 1.1 of
+the module will be able to use the \c MyButton type and the \c MyWindow type.
+However, the reverse is not true: a type exported for a particular version
+cannot be used if an earlier version is imported. If the client had imported
+version 1.0 of the module, they can use the \c MyButton type but \b not the
+\c MyWindow type.
+
+A type can be defined by different files in different versions. In this case,
+the most closely matching version will be used when imported by clients.
+For example, if a module had specified the following types via its \c qmldir
+file:
\code
+module ExampleModule
MyButton 1.0 MyButton.qml
-MyWindow 1.1 MyWindow.qml
-MyScript 1.1 myscript.js
+MyButton 1.1 MyButton11.qml
+MyButton 1.3 MyButton13.qml
+MyButton 2.0 MyButton20.qml
+MyRectangle 1.2 MyRectangle12.qml
\endcode
-If these files were part of an \l{qtqml-modules-installedmodules.html}{installed module} named \c
-com.mycompany.module then the module could be imported and its exported types used as follows:
+a client who imports version 1.2 of ExampleModule will get the \c MyButton
+type definition provided by \c MyButton11.qml as it is the most closely
+matching (i.e., latest while not being greater than the import) version of the
+type, and the \c MyRectangle type definition provided by \c MyRectangle12.qml.
-\qml
-import com.mycompany.module 1.1
+The versioning system ensures that a given QML file will work regardless of the
+version of installed software, since a versioned import \e only imports types
+for that version, leaving other identifiers available, even if the actual
+installed version might otherwise provide those identifiers.
-MyWindow {
- function doStuff() {
- MyScript.doSomething();
- }
+See \l{examples/qml/cppextensions/plugins} for an example that uses C++
+plugins.
- MyButton {
- // ...
- }
-}
-\endqml
-Types which are exported for a particular version are still made available if a later version is
-imported: in the above example, the code imports version 1.1 of the module but still has access to
-the \c MyButton type that was exported for version 1.0. However, the reverse is not true: a type
-exported for a particular version cannot be used if an earlier version is imported. If the code
-above imported version 1.0 of the module, it could not have used the \c MyWindow type and \c
-MyScript namespace as these are declared for version 1.1.
+\section1 Example of a qmldir File
-A type can be defined by different files in different versions. In this case, later versions (e.g.
-1.2) must precede earlier versions (e.g. 1.0) within the \c qmldir file, since the engine loads the
-first type it finds with a matching name and version.
+One example of a \c qmldir file follows:
-The versioning system ensures that a given QML file will work regardless of the version
-of installed software, since a versioned import \e only imports types for that version,
-leaving other identifiers available, even if the actual installed version might otherwise
-provide those identifiers.
+\code
+module ExampleModule
+CustomButton 1.0 CustomButton.qml
+CustomButton 2.0 CustomButton20.qml
+CustomButton 2.1 CustomButton21.qml
+plugin examplemodule
+MathFunctions 2.0 mathfuncs.js
+\endcode
+
+The above \c qmldir file defines a module called "ExampleModule". It defines
+the \c CustomButton QML object type in versions 1.1, 2.0 and 2.1 of the
+module, with different implementations in each version. It specifies a plugin
+which must be loaded by the engine when the module is imported by clients, and
+that plugin may register various C++-defined types with the QML type system.
+On Unix-like systems the QML engine will attempt to load \c libexamplemodule.so
+as a QQmlExtensionPlugin, and on Windows it will attempt to load
+\c examplemodule.dll as a QQmlExtensionPlugin. Finally, the \c qmldir file
+specifies a \l{qtqml-javascript-resources.html}{JavaScript resource} which is
+only available if version 2.0 or greater of the module is imported, accessible
+via the \c MathFunctions identifier.
+
+If the module is \l{qtqml-modules-identifiedmodules.html}{installed} into the
+QML import path, clients could import and use the module in the following
+manner:
+
+\qml
+import QtQuick 2.0
+import ExampleModule 2.1
+
+Rectangle {
+ width: 400
+ height: 400
+ color: "lightsteelblue"
+
+ CustomButton {
+ color: "gray"
+ text: "Click Me!"
+ onClicked: MathFunctions.generateRandom() > 10 ? color = "red" : color = "gray";
+ }
+}
+\endqml
-See \l{Located Modules} and \l{Installed Modules} for more example \c qmldir file content, and see
-\l{examples/qml/cppextensions/plugins} for an example that uses C++ plugins.
+The \c CustomButton type used above would come from the definition specified in
+the \c CustomButton21.qml file, and the JavaScript resource identified by the
+\c MathFunctions identifier would be defined in the \c mathfuncs.js file.
\section1 Writing a qmltypes File
diff --git a/src/qml/doc/src/modules/topic.qdoc b/src/qml/doc/src/modules/topic.qdoc
index dd3e4de661..6aa4bacbde 100644
--- a/src/qml/doc/src/modules/topic.qdoc
+++ b/src/qml/doc/src/modules/topic.qdoc
@@ -24,63 +24,68 @@
** $QT_END_LICENSE$
**
****************************************************************************/
+
/*!
\page qtqml-modules-topic.html
\title QML Modules
\brief Description of how to write modules for QML
-A module is a collection of content files that can be imported as a unit into a QML
-application. Modules can be used to organize QML content into independent groups,
-and they use a versioning mechanism that allows modules to be independently upgraded.
-
-Modules may contain QML files, JavaScript files and/or QML plugins written in C++. Grouping files
-into modules enables:
+A QML module provides versioned types and JavaScript resources in a type
+namespace which may be used by clients who import the module. The types which
+a module provides may be defined in C++ within a plugin, or in QML documents.
+Modules make use of the QML versioning system which allows modules to be
+independently updated.
+Defining of a QML module allows:
\list
-\li The sharing of common QML types within a project - for example, a group of UI components that
- are used by different windows
+\li The sharing of common QML types within a project - for example, a group of
+ UI components that are used by different windows
\li The distribution of QML-based libraries
-\li The modularization of distinct features, so that applications only load the libraries necessary
- for their individual needs
+\li The modularization of distinct features, so that applications only load the
+ libraries necessary for their individual needs
+\li Versioning of types and resources so that the module can be updated safely
+ without breaking client code
\endlist
-A module may contain QML, JavaScript and/or C++ files. To access the types and functionality within
-a module, the module must be imported with an \l{Import Statements}{import} statement.
-
-\section1 Located Modules
-
-A located module is one that is imported by a quoted URL string that refers to the
-local file system path of the module or the network URL location of the module.
-
-Using this mechanism, any directory of QML files can easily be shared as a module without any
-configuration or installation. Additionally, such modules can be loaded remotely as a network
-resource if it includes a qmldir file with the necessary metadata.
-
-See \l{qtqml-modules-locatedmodules.html}{Located Modules} for more information.
+\section1 Defining a QML Module
-\section1 Installed Modules
+A module is defined by a \l{qtqml-modules-qmldir.html}
+{module definition qmldir file}. Each module has an associated type
+namespace, which is the module's identifier. A module can provide QML object
+types (defined either by QML documents or via a C++ plugin) and JavaScript
+resources, and may be imported by clients.
-An installed module is one that is imported by a URI in the form of a dotted identifier string - for
-example, "com.mycompany.mymodule" - that uniquely identifies the module to the QML engine. This
-allows a module to be imported by an identifier rather than a file system path.
+To define a module, a developer should gather together the various QML
+documents, JavaScript resources and C++ plugins which belong in the module
+into a single directory, and write an appropriate \l{qtqml-modules-qmldir.html}
+{module definition qmldir file} which should also be placed into the directory.
+The directory can then be installed into the
+\l{qtqml-syntax-imports.html#qml-import-path}{QML import path} as a module.
-To enable the engine to find an installed module, the module should be available in the
-\l{qtqml-syntax-imports.html#qml-import-path}{import path}.
+Note that defining a module is not the only way to share common QML types
+within a project - a simple \l{qtqml-syntax-imports.html#directory-import}
+{QML document directory import} may also be used for this purpose.
-See \l{qtqml-modules-installedmodules.html}{Installed Modules} for more information.
+\section1 Supported QML Module Types
+There are two different types of modules supported by QML:
+\list
+\li \l{qtqml-modules-identifiedmodules.html}{Identified Modules}
+\li \l{qtqml-modules-legacymodules.html}{Legacy Modules} (deprecated)
+\endlist
-\section1 Adding Module Metadata with a qmldir File
-
-A qmldir file is a plain text file that describes a module's metadata and contents. This file and
-the associated module contents (QML documents, JavaScript files, and C++ plugins) must be placed
-somewhere into the \l{qtqml-syntax-imports.html#qml-import-path}{QML import path}.
-
-This is required for a module if it is to be imported by URI or as a network resource. It is also
-necessary for exporting JavaScript files and object types defined in C++.
-
-See \l{qtqml-modules-qmldir.html}{Adding Module Metadata with a qmldir File} for more information.
+Identified modules explicitly define their identifier and are installed into
+QML import path. Identified modules are more maintainable (due to type
+versioning) and are provided with type registration guarantees by the QML
+engine which are not provided to legacy modules. Legacy modules are only
+supported to allow legacy code to continue to work with the latest version of
+QML, and should be avoided by clients if possible.
+
+Clients may import a QML module from within QML documents or JavaScript files.
+Please see the documentation about
+\l{qtqml-syntax-imports.html#module-namespace-imports}{importing a QML module}
+for more information on the topic.
\section1 Providing Types and Functionality in a C++ Plugin
diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc
index 790ef5d371..21d2386827 100644
--- a/src/qml/doc/src/qmlfunctions.qdoc
+++ b/src/qml/doc/src/qmlfunctions.qdoc
@@ -74,7 +74,7 @@
For example, this registers a C++ class \c MySliderItem as a QML type
- named \c Slider for version 1.0 of a \l{QML Modules}{module} called
+ named \c Slider for version 1.0 of a type namespace called
"com.mycompany.qmlcomponents":
\code
@@ -86,7 +86,7 @@
\endcode
Once this is registered, the type can be used in QML by importing the
- specified module name and version number:
+ specified type namespace and version number:
\qml
import com.mycompany.qmlcomponents 1.0
@@ -118,7 +118,7 @@
\endcode
This function is typically used to register the revision of a base class to
- use for the specified module version (see \l {Type Revisions and Versions}).
+ use for the specified version of the type (see \l {Type Revisions and Versions}).
*/
/*!
@@ -145,12 +145,12 @@
\fn int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message)
\relates QQmlEngine
- This function registers a type in the QML system with the name \a qmlName, in the library imported from \a uri having the
+ This function registers a type in the QML system with the name \a qmlName, in the type namespace imported from \a uri having the
version number composed from \a versionMajor and \a versionMinor, but any attempt to instantiate the type
will produce the given error \a message.
- Normally, the types exported by a module should be fixed. However, if a C++ type is not available, you should
- at least "reserve" the QML type name, and give the user of your module a meaningful error message.
+ Normally, the types exported by a plugin should be fixed. However, if a C++ type is not available, you should
+ at least "reserve" the QML type name, and give the user of the unavailable type a meaningful error message.
Returns the QML type id.
@@ -164,7 +164,7 @@
#endif
\endcode
- This will cause any QML which uses this module and attempts to use the type to produce an error message:
+ This will cause any QML which imports the "MinehuntCore" type namespace and attempts to use the type to produce an error message:
\code
fun.qml: Get back to work, slacker!
Game {
diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc
index 715b866b47..efd969c7a9 100644
--- a/src/qml/doc/src/qtqml.qdoc
+++ b/src/qml/doc/src/qtqml.qdoc
@@ -92,9 +92,12 @@ types, animation classes, and canvas integration) for the QML language.
\li \l{qtqml-modules-topic.html}{QML Modules}
\list
- \li \l{qtqml-modules-locatedmodules.html}{Located Modules}
- \li \l{qtqml-modules-installedmodules.html}{Installed Modules}
- \li \l{qtqml-modules-qmldir.html}{Adding Module Metadata with a qmldir file}
+ \li \l{qtqml-modules-qmldir.html}{Specifying A QML Module}
+ \li \l{qtqml-modules-topic.html#supported-qml-module-types}{Supported QML Module Types}
+ \list
+ \li \l{qtqml-modules-identifiedmodules.html}{Identified Modules}
+ \li \l{qtqml-modules-legacymodules.html}{Legacy Modules}
+ \endlist
\li \l{qtqml-modules-cppplugins.html}{Providing Types and Functionality in a C++ Plugin}
\endlist
@@ -125,7 +128,8 @@ types, animation classes, and canvas integration) for the QML language.
\li \l{qtqml-javascript-topic.html}{Integrating QML and JavaScript}
\list
\li \l{qtqml-javascript-expressions.html}{Using JavaScript Expressions with QML}
- \li \l{qtqml-javascript-imports.html}{Importing JavaScript Files in QML Documents}
+ \li \l{qtqml-javascript-resources.html}{Defining JavaScript Resources In QML}
+ \li \l{qtqml-javascript-imports.html}{Importing JavaScript Resources In QML}
\li \l{qtqml-javascript-hostenvironment.html}{JavaScript Host Environment}
\list
\li \l{qtqml-javascript-qmlglobalobject.html}{QML Global Object}
diff --git a/src/qml/doc/src/syntax/directoryimports.qdoc b/src/qml/doc/src/syntax/directoryimports.qdoc
new file mode 100644
index 0000000000..eb100c60f0
--- /dev/null
+++ b/src/qml/doc/src/syntax/directoryimports.qdoc
@@ -0,0 +1,203 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\page qtqml-syntax-directoryimports.html
+\title Importing QML Document Directories
+\brief 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 \c qmldir file to exist. A local directory may
+optionally contain a directory listing \c qmldir file in order to define the
+type names which should be provided to clients which import the directory, and
+to specify JavaScript resources which should be made available to importers.
+
+
+\section1 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 \l{qtqml-typesystem-objecttypes.html}
+{object types} defined within that directory.
+
+If the local directory contains a directory listing \c qmldir file, the types
+will be made available with the type names specified in the \c 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 \c qmldir file
+is specified in the directory.
+
+\section2 An Example
+
+Consider the following QML project directory structure. Under the top level directory \c myapp,
+there are a set of common UI components in a sub-directory named \c mycomponents, and the main
+application code in a sub-directory named \c main, like this:
+
+\code
+myapp
+ |- mycomponents
+ |- CheckBox.qml
+ |- DialogBox.qml
+ |- Slider.qml
+ |- main
+ |- application.qml
+\endcode
+
+The \c main/application.qml file can import the \c mycomponents directory using
+the relative path to that directory, allowing it to use the QML object types
+defined within that directory:
+
+\qml
+import "../mycomponents"
+
+DialogBox {
+ CheckBox {
+ // ...
+ }
+ Slider {
+ // ...
+ }
+}
+\endqml
+
+The directory may be imported into a qualified local namespace, in which case
+uses of any types provided in the directory must be qualified:
+
+\qml
+import "../mycomponents" as MyComponents
+
+MyComponents.DialogBox {
+ // ...
+}
+\endqml
+
+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 must update their relevant \c import statements
+if the module directory moves to another location. This can be avoided if
+\l{qtqml-modules-identifiedmodules.html}{QML modules} are used instead,
+as an installed module is imported with a unique identifier string rather than
+a file system path.
+
+
+\section1 Remotely Located Directories
+
+A directory of QML files can also be imported from a remote location if the
+directory contains a directory listing \c qmldir file.
+
+For example, if the \c myapp directory in the previous example was hosted at
+"http://www.my-example-server.com", and the \c mycomponents directory
+contained a \c qmldir file defined as follows:
+
+\code
+CheckBox CheckBox.qml
+DialogBox DialogBox.qml
+Slider Slider.qml
+\endcode
+
+Then, the directory could be imported using the URL to the remote
+\c mycomponents directory:
+
+\qml
+import "http://www.my-example-server.com/myapp/mycomponents"
+
+DialogBox {
+ CheckBox {
+ // ...
+ }
+ Slider {
+ // ...
+ }
+}
+\endqml
+
+Note that when a file imports a directory over a network, it can only access QML
+and JavaScript files specified in the \c qmldir file located in the directory.
+
+\warning When importing directories from a remote server, developers should
+always be careful to only load directories from trusted sources to avoid
+loading malicious code.
+
+
+\section1 Directory Listing qmldir Files
+
+A directory listing \c qmldir file distinctly different from a
+\l{qtqml-modules-qmldir.html}{module definition qmldir file}. A directory
+listing \c 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 \c qmldir file is as follows:
+\table
+ \header
+ \li Command
+ \li Syntax
+ \li Description
+
+ \row
+ \li Object Type Declaration
+ \li <TypeName> <FileName>
+ \li An object type declaration allows a QML document to be exposed with
+ the given \c <TypeName>.
+
+ Example:
+ \code
+RoundedButton RoundedBtn.qml
+ \endcode
+
+ \row
+ \li Internal Object Type Declaration
+ \li internal <TypeName> <FileName>
+ \li 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:
+ \code
+internal HighlightedButton HighlightedBtn.qml
+ \endcode
+
+ \li JavaScript Resource Declaration
+ \li <Identifier> <FileName>
+ \li A JavaScript resource declaration allows a JavaScript file to be
+ exposed via the given identifier.
+
+ Example:
+ \code
+MathFunctions mathfuncs.js
+ \endcode
+\endtable
+
+A local file system directory may optionally include a \c qmldir file. This
+allows the engine to only expose certain QML types to clients who import the
+directory. Additionally, JavaScript resources in the directory are not exposed
+to clients unless they are declared in a \c qmldir file.
+
+*/
+
diff --git a/src/qml/doc/src/syntax/imports.qdoc b/src/qml/doc/src/syntax/imports.qdoc
index 3519b3cc2f..51c80ea6c8 100644
--- a/src/qml/doc/src/syntax/imports.qdoc
+++ b/src/qml/doc/src/syntax/imports.qdoc
@@ -31,71 +31,122 @@
\section1 Syntax of an Import Statement
+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.
-The \c import statement is used to provide the QML engine with access to the modules that define the types that are referred to from within the QML file.
+\section2 Import Types
-The syntax for the \c import statement is:
+There are three different types of imports. Each import type has a slightly
+different syntax, and different semantics apply to different import types.
-\code
-import <module> <major version>.<minor version> [as <namespace>]
-\endcode
+\section3 Module (Namespace) Imports
-When a QML file is loaded by the engine, the only QML types that are automatically made available to that file are those that are \l{Defining Object Types through QML Documents}{defined by .qml files} within the same directory. Any types defined elsewhere are not accessible unless an \c import statement has imported the module that contains the required type. For example, the \c QtQuick module must be imported in order to use any of its QML types:
+The most common type of import is a module import. Clients can import
+\l{qtqml-modules-identifiedmodules.html}{QML modules} which register QML object
+types and JavaScript resources into a given namespace.
+The generic form of a module import is as follows:
\qml
-import QtQuick 2.0
-
-Rectangle {} // won't work if import line is missing, engine will refuse to load the file
+import <ModuleIdentifier> <Version.Number> [as <Qualifier>]
\endqml
-The \c <module> can be either a filesystem path to the module, or an identifier for the module if it is accessible to the import path. For example:
-
-\code
-import "../relative/path/to/module"
-import "/absolute/path/to/module"
-import com.company.module
-\endcode
+\list
+ \li The \c <ModuleIdentifier> is an identifier specified in dotted URI
+ notation, which uniquely identifies the type namespace provided by the
+ module.
+ \li The \c <Version.Number> is a version of the form
+ \c {MajorVersion.MinorVersion} which specifies which definitions of
+ various object types and JavaScript resources will be made available due
+ to the import.
+ \li The \c <Qualifier> 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.
+\endlist
-(See \l {QML Modules} for more information on defining and importing located and installed modules.)
+An example of an unqualified module import is as follows:
+\qml
+import QtQuick 2.0
+\endqml
+This import allows the use of all of the types provided by the \c QtQuick
+module without needing to specify a qualifier. For example, the client code to
+create a rectangle is as follows:
-\note 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 \l{qtqml-documents-networktransparency.html}{Network Transparency} in QML documents.
+\qml
+import QtQuick 2.0
+Rectangle {
+ width: 200
+ height: 100
+ color: "red"
+}
+\endqml
-\section1 Debugging
+An example of a qualified module import is as follows:
+\qml
+import QtQuick 2.0 as Quick
+\endqml
-The \c QML_IMPORT_TRACE environment variable can be useful for debugging
-when there are problems with finding and loading modules. See
-\l{Debugging module imports} for more information.
+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.
+An example of client code which creates a rectangle after using a qualified
+module import is as follows:
-\section1 QML Import Path
+\qml
+import QtQuick 2.0 as Quick
-When an \l{qtqml-modules-installedmodules.html}{installed module} is imported, the QML engine
-searches the \e{import path} for a matching module.
+Quick.Rectangle {
+ width: 200
+ height: 100
+ color: "red"
+}
+\endqml
-This import path, as returned by QQmlEngine::importPathList(), defines the default
-locations to be searched by the engine. By default, this list contains:
+For more information about qualified imports, see the upcoming section on
+\l{Importing Into A Qualified Local Namespace}.
-\list
-\li The directory of the current file
-\li The location specified by QLibraryInfo::ImportsPath
-\li Paths specified by the \c QML_IMPORT_PATH environment variable
-\endlist
+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 \c QtQuick and thus attempting to use the \c Rectangle type will fail:
-Additional import paths can be added through QQmlEngine::addImportPath() or the
-\c QML_IMPORT_PATH environment variable. When running the \l {Prototyping with qmlscene}{qmlscene}
-tool, you can also use the \c -I option to add an import path.
+\qml
+Rectangle {
+ width: 200
+ height: 100
+ color: "red"
+}
+\endqml
+In this case, the engine will emit an error and refuse to load the file.
+\section4 Non-module Namespace Imports
-\section1 Namespaced Imports
+Types can also be registered into namespaces directly via the various
+registration functions in C++ (such as qmlRegisterType()). 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.
+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.
+\section4 Importing into a Qualified Local Namespace
-The \c import statement may optionally use the \c as keyword to specify that the module should be imported into a particular namespace. If a namespace is specified, then any references to the types made available by the module must be prefixed by the namespace qualifier.
+The \c import statement may optionally use the \c as 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.
-Below, the QtQuick module is imported into the namespace "CoreItems". Now, any references to types from the \c QtQuick module must be prefixed with the \c CoreItems name:
+Below, the QtQuick module is imported into the namespace "CoreItems". Now, any
+references to types from the \c QtQuick module must be prefixed with the
+\c CoreItems name:
\qml
import QtQuick 2.0 as CoreItems
@@ -110,9 +161,14 @@ CoreItems.Rectangle {
}
\endqml
-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.
+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.
-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:
+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:
\qml
import QtQuick 2.0 as CoreItems
@@ -126,58 +182,86 @@ CoreItems.Rectangle {
}
\endqml
-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:
+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:
\snippet qml/imports/merged-named-imports.qml imports
+\section3 Directory Imports
+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.
+
+The generic form of a directory import is as follows:
+\qml
+import "<DirectoryPath>" [as <Qualifier>]
+\endqml
+\note 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 \l{qtqml-documents-networktransparency.html}
+{Network Transparency} in QML documents. If the directory is remote, it must
+contain a \l{qtqml-syntax-directoryimports.html#directory-listing-qmldir-files}
+{directory import listing qmldir file} as the QML engine cannot determine
+the contents of a remote directory if that \c qmldir file does not exist.
-\section1 Relative Directory Imports
+Similar semantics for the \c <Qualifier> apply to directory imports as for
+module imports; for more information on the topic, please see the previous
+section about \l{Importing into a Qualified Local Namespace}.
-\section1 JavaScript File Imports
+For more information about directory imports, please see the in-depth
+documentation about \l{qtqml-syntax-directoryimports.html}{directory imports}.
+\section3 JavaScript Resource Imports
-JavaScript files must always be imported with a named import:
+JavaScript resources may be imported directly in a QML document. Every
+JavaScript resource must have an identifier by which it is accessed.
+The generic form of a JavaScript resource import is as follows:
\qml
-import "somescript.js" as MyScript
-
-Item {
- //...
- Component.onCompleted: MyScript.doSomething()
-}
+import "<JavaScriptFile>" as <Identifier>
\endqml
-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.
+Note that the \c <Identifier> must be unique within a QML document, unlike the
+local namespace qualifier which can be applied to module imports.
-Javascript files can be provided by modules, by adding Namespace definitions to the
-\l{Adding Module Metadata with a qmldir file}{qmldir file} for the module. For example:
+\section4 JavaScript Resources from Modules
+Javascript files can be provided by modules, by adding identifier
+definitions to the \c qmldir file which specifies the module.
+
+For example, if the \c projects.MyQMLProject.MyFunctions module is specified
+with the following \c qmldir file, and installed into the QML import path:
\code
+module projects.MyQMLProject.MyFunctions
SystemFunctions 1.0 SystemFunctions.js
UserFunctions 1.0 UserFunctions.js
\endcode
-Javascript can be imported from a module, where they will have the namespace defined
-for them in the module's \c qmldir file:
+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:
\qml
+import QtQuick 2.0
import projects.MyQMLProject.MyFunctions 1.0
-Window {
+Item {
Component.onCompleted: { SystemFunctions.cleanUp(); }
}
\endqml
-Javascript provided by modules can also be imported into namespaces:
+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:
\qml
+import QtQuick 2.0
import projects.MyQMLProject.MyFunctions 1.0 as MyFuncs
import org.example.Functions 1.0 as TheirFuncs
-Window {
+Item {
Component.onCompleted: {
MyFuncs.SystemFunctions.cleanUp();
TheirFuncs.SystemFunctions.shutdown();
@@ -185,9 +269,40 @@ Window {
}
\endqml
+\section4 Further Information
+
+For more information about JavaScript resources, please see the documentation
+about \l{qtqml-javascript-resources.html}
+{defining JavaScript resources in QML}, 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
+\l{qtqml-javascript-imports.html}{importing JavaScript resources in QML}.
+
+
+\section1 QML Import Path
+
+When an \l{qtqml-modules-installedmodules.html}{installed module} is imported,
+the QML engine searches the \e{import path} for a matching module.
+
+This import path, as returned by QQmlEngine::importPathList(), defines the
+default locations to be searched by the engine. By default, this list contains:
+
+\list
+\li The directory of the current file
+\li The location specified by QLibraryInfo::ImportsPath
+\li Paths specified by the \c QML_IMPORT_PATH environment variable
+\endlist
+
+Additional import paths can be added through QQmlEngine::addImportPath() or the
+\c QML_IMPORT_PATH environment variable. When running the
+\l{Prototyping with qmlscene}{qmlscene} tool, you can also use the \c -I option
+to add an import path.
+
-\section1 Version Specification
+\section1 Debugging
-\section1 Import Qualifier
+The \c QML_IMPORT_TRACE environment variable can be useful for debugging
+when there are problems with finding and loading modules. See
+\l{Debugging module imports} for more information.
*/