diff options
Diffstat (limited to 'src/qml/doc/src/modules/qmldir.qdoc')
| -rw-r--r-- | src/qml/doc/src/modules/qmldir.qdoc | 250 |
1 files changed, 173 insertions, 77 deletions
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 |