diff options
Diffstat (limited to 'doc/src/declarative/modules.qdoc')
| -rw-r--r-- | doc/src/declarative/modules.qdoc | 69 |
1 files changed, 53 insertions, 16 deletions
diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc index 1491fea..ec36fe7 100644 --- a/doc/src/declarative/modules.qdoc +++ b/doc/src/declarative/modules.qdoc @@ -46,24 +46,51 @@ A \bold module is a collection of QML types. To use types from a module it must be imported using the \c import statement. Successive -import statements override earlier import statements. +import statements override earlier import statements, however, since imports have version +qualifiers, changes in modules do not alter the semantics of imports. -\section1 Importing Built-in Types +\section1 Importing Types Defined in C++ -To use built-in types, you must import the module defining them. -For example, to use types from Qt, import it: +Types \link adding-types defined in C++\endlink can be from types your application defines, standard QML types, +or types defined in plugins. To use any such types, you must import +the module defining them. For example, to use types from Qt, import it: \code import Qt 4.6 \endcode This makes available all types in Qt that were available in Qt 4.6, regardless of the -actual version of Qt executing the QML. +actual version of Qt executing the QML. So even if Qt 4.7 adds a type that would conflict +with a type you defined while using 4.6, that type is not imported, so there is no conflict. -Modules can be compiled-in (such as the Qt module), or they can be -defined in QML files. +Types defined by plugins are made using QmlModulePlugin. -\section1 Importing QML Files + +\section1 Importing Types Defined in QML + +When importing types \link components defined using QML\endlink, the syntax depends +on whether or not the types are installed on the system. + +\section2 Installed QML Files + +To import types defined in QML files that are installed on the system running the +QML, a URI import is used: + +\code +import com.nokia.Example 1.0 +\endcode + +Files imported in this way are found on the paths added by QmlEngine::addImportPath(), +which by default only inludes \c $QTDIR/qml, so the above would make available those types +defined in \c $QTDIR/qml/com/nokia/Example which are specified as being in version 1.0. + +The specification of types to versions is given by a special file, \c qmldir which must +exist in the module directory. The syntax is described below. + +The \c -L option to the \l {qmlviewer}{viewer} application also adds paths to the import path. + + +\section2 Local QML Files To import types defined in QML files in directories relative to the file importing them, a quoted import directory is used: @@ -75,18 +102,27 @@ import "path" This allows all components defined in the directory \c path to be used in the component where this statement appears. -To import types defined in QML files that are installed somewhere on the system, -an unquoted URI is used: +In this case, and only this case, it is not necessary for the module directory to include +a \c qmldir file, nor is it necessary to provide a version qualifier. The basis of this is +that the files in the subdirectory are assumed to be packaged with the importer, and therefore +they form a single versioned unit. + + +\section2 Remote QML Files + +To import types defined in QML file at arbitrary network locations, a quoted absolute URL is used: \code -import com.nokia.CoolStuff 1.0 +import "http://url/.../" 1.0 \endcode -This will access file in the directory \c com/nokia/CoolStuff/, found in some -location determined outside QML. See QmlEngine::addImportPath() and the \c -L option -to the \l {qmlviewer}{viewer} application. +This works the same as for relative directory imports, except that the target location \e must +include a \c qmldir file, and a version qualifier must be given. + -The directory of installed files must include a file \c qmldir which specifies the +\section2 The \c qmldir File + +Directories of installed files and remote content must include a file \c qmldir which specifies the mapping from all type names to versioned QML files. It is a list of lines of the form: \code @@ -105,7 +141,7 @@ since the \e first name-version match is used. Installed files do not need to import the module of which they are a part, as they can refer to the other QML files in the module as relative (local) files. -Installed files \e must be referred to by version information described above, +Installed and remote files \e must be referred to by version information described above, local files \e may have it. The versioning system ensures that a given QML file will work regardless of the version @@ -113,6 +149,7 @@ of installed software, since a versioned import \e only imports types for that v leaving other identifiers available, even if the actual installed version might otherwise use those identifiers. + \section1 Namespaces - Named Imports When importing content it by default imports types into the global namespace. |