src/qml/doc/src/qmltypereference.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-typereference-topic.html
  29 \title QML Types Provided By The Qt QML Module
  30 \brief List of QML types provided by the Qt QML module
  31
  32 The Qt QML module provides the definition and implementation of the QML
  33 language, and it also provides some elementary QML types which provide the
  34 basis for further extensions to the QML language.
  35
  36
  37
  38 The Qt QML module also provides the \c QtObject and \c Component types which
  39 may be used in QML documents, by default.  These types are non-visual and
  40 provide building-blocks for extensions to QML.
  41
  42
  43
  44 \section1 The QtQml Import
  45
  46 The types provided by the Qt QML module are only available in a QML document
  47 if that document imports the QtQml namespace (or if the document imports the
  48 QtQuick namespace, as noted below).
  49
  50 The current version of the import provided by the Qt QML module is version 2.0,
  51 and thus it may be imported via the following statement:
  52
  53 \tt{import QtQml 2.0}
  54
  55 Most clients will never need to use the QtQml import, as all of the types and
  56 functionality provided by the QtQml namespace are also provided by the QtQuick
  57 namespace which may be imported as follows:
  58
  59 \tt{import QtQuick 2.0}
  60
  61 See the \l{Qt Quick} module documentation for more information about the
  62 QtQuick namespace and what it provides to QML application developers.
  63
  64 The documentation for the types below applies equally to the types of the same
  65 name provided by the Qt Quick module, as they are in fact identical.
  66
  67 \section1 QtObject
  68
  69 The \c QtObject type provides a basic instantiable object which can be used in
  70 QML applications.  It is non-visual, but may have properties, methods, signals
  71 and signal handlers.
  72
  73 For example, the following QtObject has several properties, one of which has
  74 been assigned a \l{Property Binding}
  75 {binding}, and a \l{Signal and Handler Event System}{signal handler} for
  76 the default change signal which exists for one of its properties:
  77
  78 \code
  79     import QtQuick 2.0
  80
  81     QtObject {
  82         property int a: 15
  83         property int b: a + 22
  84         property int changeCount: 0
  85
  86         onAChanged: {
  87             changeCount += 1;
  88         }
  89     }
  90 \endcode
  91
  92 \section1 Component
  93
  94 The \c Component type provides a basic re-usable component which allows
  95 instances of another type to be instantiated on-demand.  It may be given an
  96 \c id and it has a default property which is the object type to instantiate,
  97 but no other properties may be added to it.
  98
  99 For example, the following QtObject has two different Component properties,
 100 and it uses those components to dynamically construct objects at run-time:
 101
 102 \code
 103     import QtQuick 2.0
 104
 105     QtObject {
 106         id: root
 107         property bool which: true
 108
 109         property Component a: Component {
 110             id: firstComponent
 111             QtObject {
 112                 property int answer: 42
 113                 function activate() {
 114                     console.log("The answer is: " + answer);
 115                 }
 116             }
 117         }
 118
 119         property Component b: Component {
 120             id: secondComponent
 121             QtObject {
 122                 property string message: "Hello, World!"
 123                 function activate() {
 124                     console.log(message);
 125                 }
 126             }
 127         }
 128
 129         function activateDynamicObject() {
 130             var o = {};
 131             if (which) {
 132                 which = false;
 133                 o = a.createObject(null); // no parent
 134             } else {
 135                 which = true;
 136                 o = b.createObject(null); // no parent
 137             }
 138             o.activate();
 139         }
 140     }
 141 \endcode
 142
 143 */