src/qml/doc/src/modules/topic.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  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 */