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 \bold {QML module} is a collection of QML types. They allow you to organize your QML content
into independent units. Modules have an optional versioning mechanism that allows for independent
upgradability of the modules.

There are two types of modules:
location modules (defined by a URL),
and
installed modules (defined by a URI).

Location modules types are defined in QML files and \l{QDeclarativeExtensionPlugin}{QML C++ plugins}
in a directory refered to directly by
the location URL, either on the local filesystem, or as a network resource. The URL that locates them
can be relative, in which case they actual URL is resolved by the QML file containing the import.
When importing a location module, a quoted URL is used:

\code
import "https://qml.nokia.com/qml/example" 1.0
import "https://qml.nokia.com/qml/example" as NokiaExample
import "mymodule" 1.0
import "mymodule"
\endcode

Installed modules can \e only be on the local file system or in application C++ code. Again they
are defined in QML files and \l{QDeclarativeExtensionPlugin}{QML C++ plugins} in a directory,
but the directory is indirectly referred to by the URI. The mapping to actual content is either
by application C++ code registering a C++ type to a module URI (see \l{Extending QML in C++}),
or in the referenced subdirectory of a path on the import path (see below).
When importing a location module, an un-quoted URI is used:

\code
import com.nokia.qml.mymodule 1.0
import com.nokia.qml.mymodule as MyModule
\endcode


For either type of module, a \c qmldir file in the module directory defines the content of the module. This file is
optional for location modules, but only for local filesystem content or a single remote content with a namespace.
The second exception is explained in more detail in the section below on Namespaces.

\section2 The Import Path

Installed modules are searched for on the import path.
The \c -I option to the \l {QML Viewer} adds paths to the import path.

From C++, the path is available via \l QDeclarativeEngine::importPathList() and can be prepended to
using \l QDeclarativeEngine::addImportPath().

\section2 The \c qmldir File

Installed QML modules and remote content without a namespace require a file \c qmldir which
specifies the mapping from all type names to versioned QML files. It is a list of lines of the form:

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

# <Comment> lines are ignored, and can be used for comments.

<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 like \c 4.0; <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: \c 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,
an error results, but if the user imports a version within the range of versions provided,
even if no type is specific to that version, no error results.

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

Installed and remote files without a namespace \e must be referred to by version information described above,
local files \e may have it.

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.

\c 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 MyAppTypes would produce
a libMyAppTypes.so on Linux and MyAppTypes.dll on Windows. 
By default the engine searches for the plugin library in the directory containing the \c qmldir
file.  The \c -P option to the \l {QML Viewer} adds paths to the 
plugin search path. 
From C++, the path is available via \l QDeclarativeEngine::pluginPathList() and can be prepended to
using \l QDeclarativeEngine::addPluginPath().

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


\section2 Namespaces - Named Imports

When importing content it by default imports types 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 namespace:

\code
import Qt 4.7 as TheQtLibrary
\endcode

Types from the Qt 4.7 module may then be used, but only by qualifying them with the namespace:

\code
TheQtLibrary.Rectangle { ... }
\endcode

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

\code
import Qt 4.7 as Nokia
import Ovi 1.0 as Nokia
\endcode

While import statements are needed to make any types available in QML, the directory of the
current file is implicitly loaded. This is the exact same as if you had added 'import "."' to
the start of every QML file. The effect of this is that you can automatically use types defined in C++ plugins
or QML files if they reside in the same directory. This is the last location searched for types - so if you
happen to have a "Text.qml" file, or "text.qml" on case-insensitive file systems, it will not override
the one from Qt if you import Qt.

*/

/*

Original requirement is QT-558.

*/