path: root/src/qml/doc/src/modules/qmldir.qdoc

/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtqml-modules-qmldir.html
\title Adding Module Metadata with a qmldir File
\brief How to write a qmldir file for a 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.


\section1 Writing a qmldir File

A \c qmldir file contains one or more lines of the following commands:

\table
    \header
        \li Command Syntax
        \li Usage

    \row
        \li
            \code
<TypeName> [<InitialVersion>] <File>
            \endcode
        \li Declares an \l{qtqml-typesystem-objecttypes.html}{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 <File> is the (relative) file name of the QML file that defines the type
                \endlist

            Example:
            \code
MyCustomType 1.0 MyCustomType.qml
            \endcode
    \row
        \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.

            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.

    \row
        \li
            \code
<Namespace> <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.

            Example:
            \code
MyScript 1.0 MyScript.js
            \endcode

            See \l{qtqml-javascript-imports.html}{Importing JavaScript Files in QML Documents} for
            more information.

    \row
        \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

            Example:
            \code
plugin MyPluginLibrary
           \endcode

    \row
        \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
            \code
# <Comment>
            \endcode
        \li Declares a comment. These are ignored by the engine.

            Example:
            \code
# this is a comment
            \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:

\code
MyButton 1.0 MyButton.qml
MyWindow 1.1 MyWindow.qml
MyScript 1.1 myscript.js
\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:

\qml
import com.mycompany.module 1.1

MyWindow {
    function doStuff() {
        MyScript.doSomething();
    }

    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.

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.

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{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.


\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: "QDeclarativeAnimationAttached"

        // 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

*/