src/qml/doc/src/modules/qmldir.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27 /*!
  28 \page qtqml-modules-qmldir.html
  29 \title Adding Module Metadata with a qmldir File
  30 \brief How to write a qmldir file for a module
  31
  32 A \e qmldir file is a metadata file for a module that maps all type names in the module to
  33 versioned QML files. It is required for \l{qtqml-modules-installedmodules.html}{installed modules},
  34 as well as \l{qtqml-modules-locatedmodules.html}{located modules} that are loaded from a network
  35 source.
  36
  37 This file is defined by a plain text file named "qmldir" within the module. For
  38 \l{qtqml-modules-locatedmodules.html}{located modules}, this file should be in the module's root
  39 directory. For \l{qtqml-modules-installedmodules.html}{installed modules}, the file should be in a
  40 directory within the module according to the named identifier for the module; see the \l{Installed
  41 Modules} documentation for more information.
  42
  43
  44 \section1 Writing a qmldir File
  45
  46 A \c qmldir file contains one or more lines of the following commands:
  47
  48 \table
  49     \header
  50         \li Command Syntax
  51         \li Usage
  52
  53     \row
  54         \li
  55             \code
  56 <TypeName> [<InitialVersion>] <File>
  57             \endcode
  58         \li Declares an \l{qtqml-typesystem-objecttypes.html}{object type} to be made available by
  59             the module.
  60                 \list
  61                 \li \c <TypeName> is the type being made available
  62                 \li \c <InitialVersion> (optional) is the module version for which the type is to be
  63                     made available
  64                 \li \c <File> is the (relative) file name of the QML file that defines the type
  65                 \endlist
  66
  67             Example:
  68             \code
  69 MyCustomType 1.0 MyCustomType.qml
  70             \endcode
  71     \row
  72         \li
  73             \code
  74 internal <TypeName> <File>
  75             \endcode
  76         \li Declares an object type that is in the module but should not be made available to users
  77             of the module.
  78
  79             Example:
  80             \code
  81 internal MyPrivateType MyPrivateType.qml
  82          \endcode
  83
  84             This is necessary if the module may be imported remotely (see \l{Remotely Located
  85             Modules} and \l{Remotely Installed Modules}) because if an exported type depends on an
  86             non-exported type within the module, the engine must also load the non-exported type.
  87
  88     \row
  89         \li
  90             \code
  91 <Namespace> <InitialVersion> <File>
  92             \endcode
  93         \li Declares a JavaScript file to be made available by the module. The file will be made
  94             available through the specified namespace and verison number.
  95
  96             Example:
  97             \code
  98 MyScript 1.0 MyScript.js
  99             \endcode
 100
 101             See \l{qtqml-javascript-imports.html}{Importing JavaScript Files in QML Documents} for
 102             more information.
 103
 104     \row
 105         \li
 106             \code
 107 plugin <Name> [<Path>]
 108             \endcode
 109         \li Declares a plugin to be made available by the module.
 110
 111             \list
 112             \li \c <Name> is the plugin library name. This is usually not the same as the file name
 113                 of the plugin binary, which is platform dependent; e.g. the library \c MyAppTypes
 114                 would produce \c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows.
 115             \li \c <Path> (optional) specifes either:
 116                 \list
 117                 \li an absolute path to the directory containing the plugin file, or
 118                 \li a relative path from the directory containing the \c qmldir file to the
 119                     directory containing the plugin file.
 120                 \endlist
 121
 122                 By default the engine searches for the plugin library in the directory that contains
 123                 the \c qmldir file. (The plugin search path can be queried with
 124                 QQmlEngine::pluginPathList() and modified using QQmlEngine::addPluginPath().)
 125             \endlist
 126
 127             Example:
 128             \code
 129 plugin MyPluginLibrary
 130            \endcode
 131
 132     \row
 133         \li
 134             \code
 135 typeinfo <File>
 136             \endcode
 137         \li Declares a \l{Writing a qmltypes file}{type description file} for the module that can be
 138             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.
 139
 140             Example:
 141             \code
 142 typeinfo mymodule.qmltypes
 143             \endcode
 144
 145             Without such a file, QML tools may be unable to offer features such as code completion
 146             for the types defined in your plugins.
 147
 148     \row
 149         \li
 150             \code
 151 # <Comment>
 152             \endcode
 153         \li Declares a comment. These are ignored by the engine.
 154
 155             Example:
 156             \code
 157 # this is a comment
 158             \endcode
 159 \endtable
 160
 161 For example, suppose a module's \c qmldir file should export a \c MyButton type in version 1.0, a \c
 162 MyWindow type in version 1.1 and a JavaScript file to a \c MyScript namespace in version 1.1.
 163 Providing the relevant files are in the same directory as the \c qmldir file, the contents of the \c
 164 qmldir file would look like this:
 165
 166 \code
 167 MyButton 1.0 MyButton.qml
 168 MyWindow 1.1 MyWindow.qml
 169 MyScript 1.1 myscript.js
 170 \endcode
 171
 172 If these files were part of an \l{qtqml-modules-installedmodules.html}{installed module} named \c
 173 com.mycompany.module then the module could be imported and its exported types used as follows:
 174
 175 \qml
 176 import com.mycompany.module 1.1
 177
 178 MyWindow {
 179     function doStuff() {
 180         MyScript.doSomething();
 181     }
 182
 183     MyButton {
 184         // ...
 185     }
 186 }
 187 \endqml
 188
 189 Types which are exported for a particular version are still made available if a later version is
 190 imported: in the above example, the code imports version 1.1 of the module but still has access to
 191 the \c MyButton type that was exported for version 1.0. However, the reverse is not true: a type
 192 exported for a particular version cannot be used if an earlier version is imported. If the code
 193 above imported version 1.0 of the module, it could not have used the \c MyWindow type and \c
 194 MyScript namespace as these are declared for version 1.1.
 195
 196 A type can be defined by different files in different versions. In this case, later versions (e.g.
 197 1.2) must precede earlier versions (e.g. 1.0) within the \c qmldir file, since the engine loads the
 198 first type it finds with a matching name and version.
 199
 200 The versioning system ensures that a given QML file will work regardless of the version
 201 of installed software, since a versioned import \e only imports types for that version,
 202 leaving other identifiers available, even if the actual installed version might otherwise
 203 provide those identifiers.
 204
 205 See \l{Located Modules} and \l{Installed Modules} for more example \c qmldir file content, and see
 206 \l{examples/qml/cppextensions/plugins} for an example that uses C++ plugins.
 207
 208
 209 \section1 Writing a qmltypes File
 210
 211 QML modules may refer to one or more type information files in their
 212 \c qmldir file. These usually have the \c .qmltypes
 213 extension and are read by external tools to gain information about
 214 types defined in plugins.
 215
 216 As such qmltypes files have no effect on the functionality of a QML module.
 217 Their only use is to allow tools such as Qt Creator to provide code completion,
 218 error checking and other functionality to users of your module.
 219
 220 Any module that uses plugins should also ship a type description file.
 221
 222 The best way to create a qmltypes file for your module is to generate it
 223 using the \c qmlplugindump tool that is provided with Qt.
 224
 225 Example:
 226 If your module is in \c /tmp/imports/My/Module, you could run
 227 \code
 228 qmlplugindump My.Module 1.0 /tmp/imports > /tmp/imports/My/Module/mymodule.qmltypes
 229 \endcode
 230 to generate type information for your module. Afterwards, add the line
 231 \code
 232 typeinfo mymodule.qmltypes
 233 \endcode
 234 to \c /tmp/imports/My/Module/qmldir to register it.
 235
 236 While the qmldump tool covers most cases, it does not work if:
 237 \list
 238 \li The plugin uses a \l{QQmlCustomParser}. The component that uses
 239    the custom parser will not get its members documented.
 240 \li The plugin can not be loaded. In particular if you cross-compiled
 241    the plugin for a different architecture, qmldump will not be able to
 242    load it.
 243 \endlist
 244
 245 In case you have to create a qmltypes file manually or need to adjust
 246 an existing one, this is the file format:
 247
 248 \qml
 249 import QtQuick.tooling 1.1
 250
 251 // There always is a single Module object that contains all
 252 // Component objects.
 253 Module {
 254     // A Component object directly corresponds to a type exported
 255     // in a plugin with a call to qmlRegisterType.
 256     Component {
 257
 258         // The name is a unique identifier used to refer to this type.
 259         // It is recommended you simply use the C++ type name.
 260         name: "QQuickAbstractAnimation"
 261
 262         // The name of the prototype Component.
 263         prototype: "QObject"
 264
 265         // The name of the default property.
 266         defaultProperty: "animations"
 267
 268         // The name of the type containing attached properties
 269         // and methods.
 270         attachedType: "QDeclarativeAnimationAttached"
 271
 272         // The list of exports determines how a type can be imported.
 273         // Each string has the format "URI/Name version" and matches the
 274         // arguments to qmlRegisterType. Usually types are only exported
 275         // once, if at all.
 276         // If the "URI/" part of the string is missing that means the
 277         // type should be put into the package defined by the URI the
 278         // module was imported with.
 279         // For example if this module was imported with 'import Foo 4.8'
 280         // the Animation object would be found in the package Foo and
 281         // QtQuick.
 282         exports: [
 283             "Animation 4.7",
 284             "QtQuick/Animation 1.0"
 285         ]
 286
 287         // The meta object revisions for the exports specified in 'exports'.
 288         // Describes with revisioned properties will be visible in an export.
 289         // The list must have exactly the same length as the 'exports' list.
 290         // For example the 'animations' propery described below will only be
 291         // available through the QtQuick/Animation 1.0 export.
 292         exportMetaObjectRevisions: [0, 1]
 293
 294         Property {
 295             name: "animations";
 296             type: "QQuickAbstractAnimation"
 297             // defaults to false, whether this property is read only
 298             isReadonly: true
 299             // defaults to false, whether the type of this property was a pointer in C++
 300             isPointer: true
 301             // defaults to false: whether the type actually is a QQmlListProperty<type>
 302             isList: true
 303             // defaults to 0: the meta object revision that introduced this property
 304             revision: 1
 305         }
 306         Property { name: "loops"; type: "int" }
 307         Property { name: "name"; type: "string" }
 308         Property { name: "loopsEnum"; type: "Loops" }
 309
 310         Enum {
 311             name: "Loops"
 312             values: {
 313                 "Infinite": -2,
 314                 "OnceOnly": 1
 315             }
 316         }
 317
 318         // Signal and Method work the same way. The inner Parameter
 319         // declarations also support the isReadonly, isPointer and isList
 320         // attributes which mean the same as for Property
 321         Method { name: "restart" }
 322         Signal { name: "started"; revision: 2 }
 323         Signal {
 324             name: "runningChanged"
 325             Parameter { type: "bool" }
 326             Parameter { name: "foo"; type: "bool" }
 327         }
 328     }
 329 }
 330 \endqml
 331
 332 */
 333