diff options
Diffstat (limited to 'doc/src/declarative/modules.qdoc')
| -rw-r--r-- | doc/src/declarative/modules.qdoc | 100 |
1 files changed, 44 insertions, 56 deletions
diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc index 6c87263d32..f2e24f2fa7 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 |