path: root/doc/src/declarative/modules.qdoc

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page qdeclarativemodules.html
\title Modules
\section1 QML 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
\o A component defined in another QML file that is not in the same directory
\o A component defined in a QML file located on a remote server
\o A \l{QDeclarativeExtensionPlugin}{QML C++ plugin} library (unless the plugin is installed in the same directory)
\o 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:

\qml
    import Qt 4.7
\endqml
    
This imports version 4.7 of the "Qt" 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{The QML import path}{import path}. There are two types of QML modules: 
location modules (defined by a URL) and installed modules (defined by a URI).


\section1 Location Modules

Location 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
\o Directory structure
\o Contents of application.qml

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

\o
\code
import "../MyComponents"

Slider { ... }
CheckBox { ... }
\endcode

\endtable

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

\code
    import "https://qml.nokia.com/qml/qmlcomponents"
    import "https://qml.nokia.com/qml/qmlcomponents" 1.0
\endcode

Remote location modules must have a \l{Writing a qmldir file}{qmldir file} in the
same directory to specify which QML files should be made available. See the
\l {#qmldirexample}{example} below. The qmldir file is optional for modules on 
the local filesystem.



\section1 Installed modules


Installed modules are modules that are installed on the
local filesystem within the QML import path, or modules defined in C++ 
application code. When importing an installed module, an un-quoted URI is 
used, with a mandatory version number:

\code
    import Qt 4.7
    import com.nokia.qml.mymodule 1.0
\endcode

Installed modules that are installed into the import path or created
as a \l{QDeclarativeExtensionPlugin}{QML C++ plugin} must define a 
\l{Writing a qmldir file}{qmldir file}.


\section2 The QML import path

The QML engine will search the import path for a requested installed module.
The default import path includes:

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

The import path can be queried using QDeclarativeEngine::importPathList() and modified using QDeclarativeEngine::addImportPath().

When running the \l {QML Viewer}, use the \c -I option to add paths to the import path.


\section2 Creating installed modules in C++

C++ applications can dynamically define installed modules using 
qmlRegisterType(). 

For \l{QDeclarativeExtensionPlugin}{QML C++ plugins}, the 
module URI is automatically passed to QDeclarativeExtensionPlugin::registerTypes().
The QDeclarativeExtensionPlugin documentation shows how to use this URI
to call qmlRegisterType() to enable the plugin library to be built as
an installed module. Once the plugin is built and installed, the module is importable
in QML, like this:

\code
import com.nokia.TimeExample 1.0
\endcode

A \l{QDeclarativeExtensionPlugin}{QML C++ plugin} also requires a 
\l{Writing a qmldir file}{qmldir file} to make it available to the
QML engine.



\target namespaces
\section1 Namespaces: Using Named Imports

By default, when a module is imported, its contents are imported into the global namespace. You may choose to import the module into another namespace, either to allow identically-named types to be referenced, or purely for readability.

To import a module into a specific namespace, use the \e as keyword:

\qml
    import Qt 4.7 as QtLibrary
    import "../MyComponents" as MyComponents
    import com.nokia.qml.mymodule 1.0 as MyModule
\endqml

Types from these modules can then only be used when qualified by the namespace:

\qml
    QtLibrary.Rectangle { ... }
    
    MyComponents.Slider { ... }
    
    MyModule.SomeComponent { ... }
\endqml

Multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace:

\qml
    import Qt 4.7 as Nokia
    import Ovi 1.0 as Nokia
\endqml

\section2 JavaScript files

JavaScript files must always be imported with a named import:

\qml
    import "somescript.js" as MyScript
    
    Item {
        //...
        Component.onCompleted: MyScript.doSomething()
    }
\endqml



\section1 Writing a qmldir file

A \c 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 installed modules, and 
location modules that are loaded from a network source.

It is defined by a plain text file named "qmldir" that contains one or more lines of the form:

\code
# <Comment>
<TypeName> [<InitialVersion>] <File>
internal <TypeName> <File>
plugin <Name> [<Path>]
\endcode

\bold {# <Commment>} lines are used for comments. They are ignored by the QML engine.

\bold {<TypeName> [<InitialVersion>] <File>} lines are used to add QML files as types.
<TypeName> is the type being made available, the optional <InitialVersion> is a version
number, and <File> is the (relative) file name of the QML file defining the type. 

Installed files do not need to import the module of which they are a part, as they can refer
to the other QML files in the module as relative (local) files, but
if the module is imported from a remote location, those files must nevertheless be listed in
the \c qmldir file. Types which you do not wish to export to users of your module
may be marked with the \c internal keyword: \bold {internal <TypeName> <File>}.

The same type can be provided by different files in different versions, in which
case later versions (eg. 1.2) must precede earlier versions (eg. 1.0),
since the \e first name-version match is used and a request for a version of a type
can be fulfilled by one defined in an earlier version of the module. If a user attempts
to import a version earlier than the earliest provided or later than the latest provided,
the import produces a runtime error, but if the user imports a version within the range of versions provided,
even if no type is specific to that version, no error will occur.

A single module, in all versions, may only be provided in a single directory (and a single \c qmldir file).
If multiple are provided, only the first in the search path will be used (regardless of whether other versions
are provided by directories later in the search path).

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.

\bold {plugin <Name> [<Path>]} lines are used to add \l{QDeclarativeExtensionPlugin}{QML C++ plugins} to the module. <Name> is the name of the library.  It 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. 

<Path> is an optional argument specifying either an absolute path to the directory containing the
plugin file, or a relative path from the directory containing the \c qmldir file to the directory 
containing the plugin file. 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 QDeclarativeEngine::pluginPathList() and modified using QDeclarativeEngine::addPluginPath(). When running the \l {QML Viewer}, use the \c -P option to add paths to the plugin search path.


\target qmldirexample
\section2 Example

If the components in the \c MyComponents directory from the 
\l{Location Modules}{earlier example} were to be made available as a network resource,
the directory would need to contain a \c qmldir file similar to this:

\code
ComponentA 1.0 ComponentA.qml
ComponentB 1.0 ComponentB.qml
\endcode

The \c MyComponents directory could then be imported as a module using: 

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

Slider { ... }
CheckBox { ... }
\endcode

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


For examples of \c qmldir files for plugins, see the 
\l {declarative/cppextensions/plugins}{Plugins} example and 
\l {Tutorial: Writing QML extensions with C++}.


\section1 Debugging

The \c QML_IMPORT_TRACE environment variable can be useful for debugging
when there are problems with finding and loading modules. See 
\l{Debugging module imports} for more information.


*/
/