diff options
Diffstat (limited to 'src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc')
| -rw-r--r-- | src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc | 434 |
1 files changed, 434 insertions, 0 deletions
diff --git a/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc new file mode 100644 index 0000000000..57d54e27e0 --- /dev/null +++ b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc @@ -0,0 +1,434 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page qtqml-modules-qmldir.html +\title Module Definition qmldir Files +\brief How to write a qmldir file which defines a QML module + +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 Contents of a Module Definition qmldir File + +A \c qmldir file which defines a module is a plain-text file which consists +of the following commands: + +\table + \header + \li Command + \li Syntax + \li Usage + + \row + \li Module Identifier Directive + \li + \code +module <ModuleIdentifier> + \endcode + \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> 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. + + 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 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 +<ResourceIdentifier> <InitialVersion> <File> + \endcode + \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 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>] + \endcode + \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 <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. + \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().) + \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. + + 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. + + \row + \li Comment + \li + \code +# <Comment> + \endcode + \li Declares a comment. These are ignored by the engine. + + Example: + \code +# this is a comment + \endcode +\endtable + +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 version cannot be imported if no types have been explicitly exported for that +version. If a module provides a \c MyButton type in version 1.0 and a +\c MyWindow type in version 1.1, you cannot import version 1.2 or version 2.0 of +that module. + +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 +MyButton 1.1 MyButton11.qml +MyButton 1.3 MyButton13.qml +MyButton 2.0 MyButton20.qml +MyRectangle 1.2 MyRectangle12.qml +\endcode + +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. + +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. + +See \l{examples/qml/plugins} for an example that uses C++ +plugins. + + +\section1 Example of a qmldir File + +One example of a \c qmldir file follows: + +\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 + +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 + +QML modules may refer to one or more type information files in their +\c qmldir file. These usually have the \c .qmltypes +extension and are read by external tools to gain information about +types defined in plugins. + +As such qmltypes files have no effect on the functionality of a QML module. +Their only use is to allow tools such as Qt Creator to provide code completion, +error checking and other functionality to users of your module. + +Any module that uses plugins should also ship a type description file. + +The best way to create a qmltypes file for your module is to generate it +using the \c qmlplugindump tool that is provided with Qt. + +Example: +If your module is in \c /tmp/imports/My/Module, you could run +\code +qmlplugindump My.Module 1.0 /tmp/imports > /tmp/imports/My/Module/mymodule.qmltypes +\endcode +to generate type information for your module. Afterwards, add the line +\code +typeinfo mymodule.qmltypes +\endcode +to \c /tmp/imports/My/Module/qmldir to register it. + +While the qmldump tool covers most cases, it does not work if: +\list +\li The plugin uses a \c{QQmlCustomParser}. The component that uses + the custom parser will not get its members documented. +\li The plugin can not be loaded. In particular if you cross-compiled + the plugin for a different architecture, qmldump will not be able to + load it. +\endlist + +In case you have to create a qmltypes file manually or need to adjust +an existing one, this is the file format: + +\qml +import QtQuick.tooling 1.1 + +// There always is a single Module object that contains all +// Component objects. +Module { + // A Component object directly corresponds to a type exported + // in a plugin with a call to qmlRegisterType. + Component { + + // The name is a unique identifier used to refer to this type. + // It is recommended you simply use the C++ type name. + name: "QQuickAbstractAnimation" + + // The name of the prototype Component. + prototype: "QObject" + + // The name of the default property. + defaultProperty: "animations" + + // The name of the type containing attached properties + // and methods. + attachedType: "QQuickAnimationAttached" + + // The list of exports determines how a type can be imported. + // Each string has the format "URI/Name version" and matches the + // arguments to qmlRegisterType. Usually types are only exported + // once, if at all. + // If the "URI/" part of the string is missing that means the + // type should be put into the package defined by the URI the + // module was imported with. + // For example if this module was imported with 'import Foo 4.8' + // the Animation object would be found in the package Foo and + // QtQuick. + exports: [ + "Animation 4.7", + "QtQuick/Animation 1.0" + ] + + // The meta object revisions for the exports specified in 'exports'. + // Describes with revisioned properties will be visible in an export. + // The list must have exactly the same length as the 'exports' list. + // For example the 'animations' propery described below will only be + // available through the QtQuick/Animation 1.0 export. + exportMetaObjectRevisions: [0, 1] + + Property { + name: "animations"; + type: "QQuickAbstractAnimation" + // defaults to false, whether this property is read only + isReadonly: true + // defaults to false, whether the type of this property was a pointer in C++ + isPointer: true + // defaults to false: whether the type actually is a QQmlListProperty<type> + isList: true + // defaults to 0: the meta object revision that introduced this property + revision: 1 + } + Property { name: "loops"; type: "int" } + Property { name: "name"; type: "string" } + Property { name: "loopsEnum"; type: "Loops" } + + Enum { + name: "Loops" + values: { + "Infinite": -2, + "OnceOnly": 1 + } + } + + // Signal and Method work the same way. The inner Parameter + // declarations also support the isReadonly, isPointer and isList + // attributes which mean the same as for Property + Method { name: "restart" } + Signal { name: "started"; revision: 2 } + Signal { + name: "runningChanged" + Parameter { type: "bool" } + Parameter { name: "foo"; type: "bool" } + } + } +} +\endqml + +*/ + |