← Back to branch summary

~ubuntu-branches/ubuntu/saucy/qtdeclarative-opensource-src/saucy

« back to all changes in this revision

Viewing changes to src/qml/doc/src/modules/topic.qdoc

  • Committer: Package Import Robot
  • Author(s): Timo Jyrinki
  • Date: 2013-02-05 14:17:19 UTC
  • Revision ID: package-import@ubuntu.com-20130205141719-qqeyml8wslpyez52
Tags: upstream-5.0.1
Import upstream version 5.0.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/qml/doc/src/modules/topic.qdoc
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
 
4
** Contact: http://www.qt-project.org/legal
 
5
**
 
6
** This file is part of the documentation of the Qt Toolkit.
 
7
**
 
8
** $QT_BEGIN_LICENSE:FDL$
 
9
** Commercial License Usage
 
10
** Licensees holding valid commercial Qt licenses may use this file in
 
11
** accordance with the commercial license agreement provided with the
 
12
** Software or, alternatively, in accordance with the terms contained in
 
13
** a written agreement between you and Digia.  For licensing terms and
 
14
** conditions see http://qt.digia.com/licensing.  For further information
 
15
** use the contact form at http://qt.digia.com/contact-us.
 
16
**
 
17
** GNU Free Documentation License Usage
 
18
** Alternatively, this file may be used under the terms of the GNU Free
 
19
** Documentation License version 1.3 as published by the Free Software
 
20
** Foundation and appearing in the file included in the packaging of
 
21
** this file.  Please review the following information to ensure
 
22
** the GNU Free Documentation License version 1.3 requirements
 
23
** will be met: http://www.gnu.org/copyleft/fdl.html.
 
24
** $QT_END_LICENSE$
 
25
**
 
26
****************************************************************************/
 
27
 
 
28
/*!
 
29
\page qtqml-modules-topic.html
 
30
\title QML Modules
 
31
\brief Description of how to write modules for QML
 
32
 
 
33
A QML module provides versioned types and JavaScript resources in a type
 
34
namespace which may be used by clients who import the module.  The types which
 
35
a module provides may be defined in C++ within a plugin, or in QML documents.
 
36
Modules make use of the QML versioning system which allows modules to be
 
37
independently updated.
 
38
 
 
39
Defining of a QML module allows:
 
40
\list
 
41
\li The sharing of common QML types within a project - for example, a group of
 
42
    UI components that are used by different windows
 
43
\li The distribution of QML-based libraries
 
44
\li The modularization of distinct features, so that applications only load the
 
45
    libraries necessary for their individual needs
 
46
\li Versioning of types and resources so that the module can be updated safely
 
47
    without breaking client code
 
48
\endlist
 
49
 
 
50
 
 
51
\section1 Defining a QML Module
 
52
 
 
53
A module is defined by a \l{qtqml-modules-qmldir.html}
 
54
{module definition qmldir file}.  Each module has an associated type
 
55
namespace, which is the module's identifier.  A module can provide QML object
 
56
types (defined either by QML documents or via a C++ plugin) and JavaScript
 
57
resources, and may be imported by clients.
 
58
 
 
59
To define a module, a developer should gather together the various QML
 
60
documents, JavaScript resources and C++ plugins which belong in the module
 
61
into a single directory, and write an appropriate \l{qtqml-modules-qmldir.html}
 
62
{module definition qmldir file} which should also be placed into the directory.
 
63
The directory can then be installed into the
 
64
\l{qtqml-syntax-imports.html#qml-import-path}{QML import path} as a module.
 
65
 
 
66
Note that defining a module is not the only way to share common QML types
 
67
within a project - a simple \l{qtqml-syntax-imports.html#directory-import}
 
68
{QML document directory import} may also be used for this purpose.
 
69
 
 
70
\section1 Supported QML Module Types
 
71
 
 
72
There are two different types of modules supported by QML:
 
73
\list
 
74
\li \l{qtqml-modules-identifiedmodules.html}{Identified Modules}
 
75
\li \l{qtqml-modules-legacymodules.html}{Legacy Modules} (deprecated)
 
76
\endlist
 
77
 
 
78
Identified modules explicitly define their identifier and are installed into
 
79
QML import path.  Identified modules are more maintainable (due to type
 
80
versioning) and are provided with type registration guarantees by the QML
 
81
engine which are not provided to legacy modules.  Legacy modules are only
 
82
supported to allow legacy code to continue to work with the latest version of
 
83
QML, and should be avoided by clients if possible.
 
84
 
 
85
Clients may import a QML module from within QML documents or JavaScript files.
 
86
Please see the documentation about
 
87
\l{qtqml-syntax-imports.html#module-namespace-imports}{importing a QML module}
 
88
for more information on the topic.
 
89
 
 
90
\section1 Providing Types and Functionality in a C++ Plugin
 
91
 
 
92
An application which has a lot of logic implemented in C++, or which defines
 
93
types in C++ and exposes them to QML, may wish to implement a QML plugin.  A
 
94
QML extension module developer may wish to implement some types in a C++ plugin
 
95
(as opposed to defining them via QML documents) to achieve better performance
 
96
or for greater flexibility.
 
97
 
 
98
Every C++ plugin for QML has an initialiatization function which is called by
 
99
the QML engine when it loads the plugin.  This initialization function must
 
100
register any types that the plugin provides, but must not do anything else
 
101
(for example, instantiating QObjects is not allowed).
 
102
 
 
103
See \l{qtqml-modules-cppplugins.html}{Creating C++ Plugins For QML} for more information.
 
104
 
 
105
*/