summaryrefslogtreecommitdiffstats
path: root/doc/src/declarative/modules.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/declarative/modules.qdoc')
-rw-r--r--doc/src/declarative/modules.qdoc100
1 files changed, 44 insertions, 56 deletions
diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc
index f1ebd00..dbc8806 100644
--- a/doc/src/declarative/modules.qdoc
+++ b/doc/src/declarative/modules.qdoc
@@ -51,16 +51,14 @@ example, an \c import statement is required to use:
An \c import statement includes the module name, and possibly a version number.
This can be seen in the snippet commonly found at the top of QML files:
-\qml
-import QtQuick 1.0
-\endqml
+\snippet doc/src/snippets/declarative/imports/qtquick-1.0.qml import
This imports version 1.0 of the "QtQuick" module into the global namespace. (The QML
library itself must be imported to use any of the \l {QML Elements}, as they
are not included in the global namespace by default.)
The \c Qt module is an \e installed module; it is found in the
-\l{The QML import path}{import path}. There are two types of QML modules:
+\l{#import-path}{import path}. There are two types of QML modules:
located modules (defined by a URL) and installed modules (defined by a URI).
@@ -94,24 +92,25 @@ MyQMLProject
\endcode
\o
-\code
+\qml
import "../MyComponents"
Window {
- Slider { ... }
- CheckBox { ... }
+ Slider {
+ // ...
+ }
+ CheckBox {
+ // ...
+ }
}
-\endcode
+\endqml
\endtable
Similarly, if the directory resided on a network source, it could
be imported like this:
-\code
- import "http://www.my-server.com/MyQMLProject/MyComponents"
- import "http://www.my-server.com/MyQMLProject/MyComponents" 1.0
-\endcode
+\snippet doc/src/snippets/declarative/imports/network-imports.qml imports
A located module can also be imported as a network resource if it has a
\l{Writing a qmldir file}{qmldir file} in the directory that specifies the QML files
@@ -127,14 +126,18 @@ Window 1.0 Window.qml
If the \c MyComponents directory was then hosted as a network resource, it could
be imported as a module, like this:
-\code
+\qml
import "http://the-server-name.com/MyQMLProject/MyComponents"
Window {
- Slider { ... }
- CheckBox { ... }
+ Slider {
+ // ...
+ }
+ CheckBox {
+ // ...
+ }
}
-\endcode
+\endqml
with an optional "1.0" version specification. Notice the import would fail if
a later version was used, as the \c qmldir file specifies that these elements
@@ -145,7 +148,8 @@ defined in QML files; components defined by C++ \l{QDeclarativeExtensionPlugin}{
are not available.
-\section1 Installed modules
+\target import-path
+\section1 Installed Modules
Installed modules are modules that are made available through the QML import path,
as defined by QDeclarativeEngine::importPathList(), or modules defined within
@@ -156,10 +160,7 @@ path or network resource URL.
When importing an installed module, an un-quoted URI is
used, with a mandatory version number:
-\code
- import QtQuick 1.0
- import com.nokia.qml.mymodule 1.0
-\endcode
+\snippet doc/src/snippets/declarative/imports/installed-module.qml imports
When a module is imported, the QML engine searches the QML import path for a matching
module. The root directory of the module must contain a
@@ -190,7 +191,7 @@ Additional import paths can be added through QDeclarativeEngine::addImportPath()
can also use the \c -I option to add an import path.
-\section2 Creating installed modules
+\section2 Creating Installed Modules
As an example, suppose the \c MyQMLProject directory in the \l{Located Modules}{previous example}
was located on the local filesystem at \c C:\qml\projects\MyQMLProject. The \c MyComponents
@@ -211,8 +212,12 @@ without referring to the module's absolute filesystem location:
import projects.MyQMLProject.MyComponents 1.0
Window {
- Slider { ... }
- CheckBox { ... }
+ Slider {
+ // ...
+ }
+ CheckBox {
+ // ...
+ }
}
\endqml
@@ -225,22 +230,20 @@ defined in QML files; components defined by C++ \l{QDeclarativeExtensionPlugin}{
are not available.
-\section2 Creating installed modules in C++
+\section2 Creating Installed Modules in C++
C++ applications can define installed modules directly within the application using qmlRegisterType().
For example, the \l {Tutorial: Writing QML extensions 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():
-\qml
+\code
qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart");
-\endqml
+\endcode
This allows the application's QML files to use the \c PieChart type by importing the declared
\c Charts module:
-\qml
-import Charts 1.0
-\endqml
+\snippet doc/src/snippets/declarative/imports/chart.qml import
For \l{QDeclarativeExtensionPlugin}{QML plugins}, the
module URI is automatically passed to QDeclarativeExtensionPlugin::registerTypes(). This method
@@ -253,9 +256,7 @@ example:
Once the plugin is built and installed, and includes a \l{Writing a qmldir file}{qmldir file},
the module can be imported from QML, like this:
-\code
-import com.nokia.TimeExample 1.0
-\endcode
+\snippet doc/src/snippets/declarative/imports/timeexample.qml import
Unlike QML types defined by QML files, a QML type defined in a C++ extension plugin cannot be loaded by
a module that is imported as a network resource.
@@ -269,47 +270,34 @@ By default, when a module is imported, its contents are imported into the global
To import a module into a specific namespace, use the \e as keyword:
-\qml
- import QtQuick 1.0 as QtLibrary
- import "../MyComponents" as MyComponents
- import com.nokia.qml.mymodule 1.0 as MyModule
-\endqml
+\snippet doc/src/snippets/declarative/imports/named-imports.qml imports
Types from these modules can then only be used when qualified by the namespace:
-\qml
- QtLibrary.Rectangle { ... }
-
- MyComponents.Slider { ... }
-
- MyModule.SomeComponent { ... }
-\endqml
+\snippet doc/src/snippets/declarative/imports/named-imports.qml imported items
Multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace:
-\qml
- import QtQuick 1.0 as Nokia
- import Ovi 1.0 as Nokia
-\endqml
+\snippet doc/src/snippets/declarative/imports/merged-named-imports.qml imports
-\section2 JavaScript files
+\section2 JavaScript Files
JavaScript files must always be imported with a named import:
\qml
- import "somescript.js" as MyScript
+import "somescript.js" as MyScript
- Item {
- //...
- Component.onCompleted: MyScript.doSomething()
- }
+Item {
+ //...
+ Component.onCompleted: MyScript.doSomething()
+}
\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.
-\section1 Writing a qmldir file
+\section1 Writing a qmldir File
A \c 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 installed modules, and