path: root/src/qml/doc/src/modules/todo.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 qmllanguage-modules.html
\title QML Modules
\brief creating and importing QML modules

\section1 Modules

A module is a set of QML content files that can be imported as a unit into a QML
application. Modules can be used to organize QML content into independent units,
and they can use a versioning mechanism that allows for independent
upgradability of the modules.

While QML component files within the same directory are automatically accessible
within the global namespace, components defined elsewhere must be imported
explicitly using the \c import statement to import them as modules. For
example, an \c import statement is required to use:

\list
\li A component defined in another QML file that is not in the same directory
\li A component defined in a QML file located on a remote server
\li A \l{QQmlExtensionPlugin}{QML extension plugin} library (unless the plugin is installed in the same directory)
\li A JavaScript file (note this must be imported using \l {#namespaces}{named imports})
\endlist

An \c import statement includes the module name, and possibly a version number.
This can be seen in the snippet commonly found at the top of QML files:

\snippet qml/imports/qtquick-1.0.qml import

This imports version 1.0 of the "QtQuick" module into the global namespace. (The QML
library itself must be imported to use any of the \l {QML Elements}, as they
are not included in the global namespace by default.)

The \c Qt module is an \e installed module; it is found in the
\l{#import-path}{import path}. There are two types of QML modules:
located modules (defined by a URL) and installed modules (defined by a URI).


\section1 Located Modules

Located modules can reside on the local filesystem or a network resource,
and are referred to by a quoted location URL that specifies the filesystem
or network URL. They allow any directory with QML content to be imported
as a module, whether the directory is on the local filesystem or a remote
server.

For example, a QML project may have a separate directory for a set of
custom UI components. These components can be accessed by importing the
directory using a relative or absolute path, like this:

\table
\row
\li Directory structure
\li Contents of application.qml

\row
\li
\code
MyQMLProject
    |- MyComponents
        |- CheckBox.qml
        |- Slider.qml
        |- Window.qml
    |- Main
        |- application.qml
\endcode

\li
\qml
import "../MyComponents"

Window {
    Slider {
        // ...
    }
    CheckBox {
        // ...
    }
}
\endqml

\endtable

Similarly, if the directory resided on a network source, it could
be imported like this:

\snippet qml/imports/network-imports.qml imports

A located module can also be imported as a network resource if it has a
\l{Syntax of a qmldir file}{qmldir file} in the directory that specifies the QML files
to be made available by the module. For example, if the \c MyComponents directory
contained a \c qmldir file defined like this:

\code
Slider 1.0 Slider.qml
CheckBox 1.0 CheckBox.qml
Window 1.0 Window.qml
\endcode

If the \c MyComponents directory was then hosted as a network resource, it could
be imported as a module, like this:

\qml
import "http://the-server-name.com/MyQMLProject/MyComponents"

Window {
    Slider {
        // ...
    }
    CheckBox {
        // ...
    }
}
\endqml

with an optional "1.0" version specification. Notice the import would fail if
a later version was used, as the \c qmldir file specifies that these elements
are only available in the 1.0 version.

Note that modules imported as a network resource allow only access to components
defined in QML files; components defined by C++ \l{QQmlExtensionPlugin}{QML extension plugins}
are not available.


\target import-path
\section1 Installed Modules

Installed modules are modules that are made available through the QML import path,
as defined by QQmlEngine::importPathList(), or modules defined within
C++ application code. An installed module is referred to by a URI, which allows
the module to be imported from QML code without specifying a complete filesystem
path or network resource URL.

When importing an installed module, an un-quoted URI is
used, with a mandatory version number:

\snippet qml/imports/installed-module.qml imports

When a module is imported, the QML engine searches the QML import path for a matching
module. The root directory of the module must contain a
\l{Syntax of a qmldir file}{qmldir file} that defines the QML files
and/or C++ QML extension plugins that are made available to the module.

Modules that are installed into the import path translate the URI into
directory names. For example, the qmldir file of the module \c com.nokia.qml.mymodule
must be located in the subpath \c com/nokia/qml/mymodule/qmldir somewhere in the
QML import path. In addition it is possible to store different versions of the
module in subdirectories of its own. For example, a version 2.1 of the
module could be located under \c com/nokia/qml/mymodule.2/qmldir or
\c com/nokia/qml/mymodule.2.1/qmldir. The engine will automatically load
the module which matches best.

The import path, as returned by QQmlEngine::importPathList(), defines the default
locations to be searched by the QML engine for a matching module. By default, this list
contains:

\list
\li The directory of the current file
\li The location specified by QLibraryInfo::ImportsPath
\li Paths specified by the \c QML_IMPORT_PATH environment variable
\endlist

Additional import paths can be added through QQmlEngine::addImportPath() or the
\c QML_IMPORT_PATH environment variable. When running the \l {Prototyping with qmlscene}, you
can also use the \c -I option to add an import path.


\section2 Creating Installed Modules

As an example, suppose the \c MyQMLProject directory in the \l{Located Modules}{previous example}
was located on the local filesystem at \c C:\qml\projects\MyQMLProject. The \c MyComponents
subdirectory could be made available as an installed module by adding a
\l{Syntax of a qmldir file}{qmldir file} to the \c MyComponents directory that looked like this:

\code
Slider 1.0 Slider.qml
CheckBox 1.0 CheckBox.qml
Window 1.0 Window.qml
\endcode

Providing the path \c C:\qml is added to the QML import path using any of the methods listed previously,
a QML file located anywhere on the local filesystem can then import the module as shown below,
without referring to the module's absolute filesystem location:

\qml
import projects.MyQMLProject.MyComponents 1.0

Window {
    Slider {
        // ...
    }
    CheckBox {
        // ...
    }
}
\endqml

Installed modules are also accessible as a network resource. If the \c C:\qml directory was hosted
as \c http://www.some-server.com/qml and this URL was added to the QML import path, the above
QML code would work just the same.

Note that modules imported as a network resource allow only access to components
defined in QML files; components defined by C++ \l{QQmlExtensionPlugin}{QML extension plugins}
are not available.


\section2 Creating Installed Modules in C++

C++ applications can define installed modules directly within the application using qmlRegisterType().
For example, the \l {Tutorial: Extending QML with C++}{Writing QML extensions with C++ tutorial}
defines a C++ class named \c PieChart and makes this type available to QML by calling qmlRegisterType():

\code
qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart");
\endcode

This allows the application's QML files to use the \c PieChart type by importing the declared
\c Charts module:

\snippet qml/imports/chart.qml import

For \l{QQmlExtensionPlugin}{QML plugins}, the
module URI is automatically passed to QQmlExtensionPlugin::registerTypes(). This method
can be reimplemented by the developer to register the necessary types for the module. Below is the
\c registerTypes() implementation from the \l{qml/cppextensions/plugins}{QML plugins}
example:

\snippet examples/qml/cppextensions/plugins/plugin.cpp plugin

Once the plugin is built and installed, and includes a \l{Syntax of a qmldir file}{qmldir file},
the module can be imported from QML, like this:

\snippet qml/imports/timeexample.qml import

Unlike QML types defined by QML files, a QML type defined in a C++ extension plugin cannot be loaded by
a module that is imported as a network resource.

*/