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 \page qtqml-modules-topic.html
  29 \title QML Modules
  30 \brief Description of how to write modules for QML
  31
  32 A module is a collection of content files that can be imported as a unit into a QML
  33 application. Modules can be used to organize QML content into independent groups,
  34 and they use a versioning mechanism that allows modules to be independently upgraded.
  35
  36 Modules may contain QML files, JavaScript files and/or QML plugins written in C++. Grouping files
  37 into modules enables:
  38
  39 \list
  40 \li The sharing of common QML types within a project - for example, a group of UI components that
  41     are used by different windows
  42 \li The distribution of QML-based libraries
  43 \li The modularization of distinct features, so that applications only load the libraries necessary
  44     for their individual needs
  45 \endlist
  46
  47 A module may contain QML, JavaScript and/or C++ files. To access the types and functionality within
  48 a module, the module must be imported with an \l{Import Statements}{import} statement.
  49
  50 \section1 Located Modules
  51
  52 A located module is one that is imported by a quoted URL string that refers to the
  53 local file system path of the module or the network URL location of the module.
  54
  55 Using this mechanism, any directory of QML files can easily be shared as a module without any
  56 configuration or installation. Additionally, such modules can be loaded remotely as a network
  57 resource if it includes a qmldir file with the necessary metadata.
  58
  59 See \l{qtqml-modules-locatedmodules.html}{Located Modules} for more information.
  60
  61
  62 \section1 Installed Modules
  63
  64 An installed module is one that is imported by a URI in the form of a dotted identifier string - for
  65 example, "com.mycompany.mymodule" - that uniquely identifies the module to the QML engine. This
  66 allows a module to be imported by an identifier rather than a file system path.
  67
  68 To enable the engine to find an installed module, the module should be available in the
  69 \l{qtqml-syntax-imports.html#qml-import-path}{import path}.
  70
  71 See \l{qtqml-modules-installedmodules.html}{Installed Modules} for more information.
  72
  73
  74 \section1 Adding Module Metadata with a qmldir File
  75
  76 A qmldir file is a plain text file that describes a module's metadata and contents. This file and
  77 the associated module contents (QML documents, JavaScript files, and C++ plugins) must be placed
  78 somewhere into the \l{qtqml-syntax-imports.html#qml-import-path}{QML import path}.
  79
  80 This is required for a module if it is to be imported by URI or as a network resource. It is also
  81 necessary for exporting JavaScript files and object types defined in C++.
  82
  83 See \l{qtqml-modules-qmldir.html}{Adding Module Metadata with a qmldir File} for more information.
  84
  85 \section1 Providing Types And Functionality In A C++ Plugin
  86
  87 An application which has a lot of logic implemented in C++, or which defines
  88 types in C++ and exposes them to QML, may wish to implement a QML plugin.  A
  89 QML extension module developer may wish to implement some types in a C++ plugin
  90 (as opposed to defining them via QML documents) to achieve better performance
  91 or for greater flexibility.
  92
  93 Every C++ plugin for QML has an initialiatization function which is called by
  94 the QML engine when it loads the plugin.  This initialization function must
  95 register any types that the plugin provides, but must not do anything else
  96 (for example, instantiating QObjects is not allowed).
  97
  98 See \l{qtqml-modules-cppplugins.html}{Creating C++ Plugins For QML} for more information.
  99
 100 */