src/qml/doc/src/typesystem/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-typesystem-topic.html
  29 \title The QML Type System
  30 \brief Description of the QML type system
  31
  32 The types which may be used in the definition of an object hierarchy in a QML
  33 document can come from various sources.  They may be:
  34
  35 \list
  36 \li provided natively by the QML language
  37 \li registered via C++ by QML modules
  38 \li provided as QML documents by QML modules
  39 \endlist
  40
  41 Furthermore, application developers can provide their own types, either by
  42 registering C++ types directly, or by defining reusable components in QML
  43 documents which can then be imported.
  44
  45 Wherever the type definitions come from, the engine will enforce type-safety
  46 for properties and instances of those types.
  47
  48
  49 \section1 Basic Types
  50
  51 The QML language has built-in support for various primitive types including
  52 integers, double-precision floating point numbers, strings, and boolean values.
  53 Objects may have properties of these types, and values of these types may be
  54 passed as arguments to methods of objects.
  55
  56 See the \l{qtqml-typesystem-basictypes.html}{Basic Types} documentation for
  57 more information about basic types, or the \l{qtqml-documents-properties.html}
  58 {QML Documents - Object Properties} documentation for more information about
  59 other available property types.
  60
  61
  62 \section1 JavaScript Types
  63
  64 JavaScript objects and arrays are supported by the QML engine. Any standard
  65 JavaScript type can be created and stored using the generic \l var type.
  66
  67 For example, the standard \c Date and \c Array types are available, as below:
  68
  69 \qml
  70 import QtQuick 2.0
  71
  72 Item {
  73     property var theArray: new Array()
  74     property var theDate: new Date()
  75
  76     Component.onCompleted: {
  77         for (var i=0; i<10; i++)
  78             theArray.push("Item " + i)
  79         console.log("There are", theArray.length, "items in the array")
  80         console.log("The time is", theDate.toUTCString())
  81     }
  82 }
  83 \endqml
  84
  85 See \l {Using JavaScript Expressions with QML} for more details.
  86
  87
  88 \section1 QML Object Types
  89
  90 A QML object type is a type from which a QML object can be instantiated. QML
  91 object types are derived from \l QtObject, and are provided by QML modules.
  92 Applications can import these modules to use the object types they provide.
  93 The \c QtQuick module provides the most common object types needed to create
  94 user interfaces in QML.
  95
  96 Finally, every QML document implicitly defines a QML object type, which can be
  97 re-used in other QML documents.  See the documentation about
  98 \l{qtqml-typesystem-objecttypes.html}{object types in the QML type system} for
  99 in-depth information about object types.
 100
 101 \section1 Property Modifier Types
 102
 103 A property modifier type is a special kind of QML object type.  A property
 104 modifier type instance affects a property (of a QML object instance) which it
 105 is applied to.  There are two different kinds of property modifier types:
 106 \list
 107 \li property value write interceptors
 108 \li property value sources
 109 \endlist
 110
 111 A property value write interceptor can be used to filter or modify values as
 112 they are written to properties.  Currently, the only supported property
 113 value write interceptor is the \l Behavior type provided by the \c QtQuick
 114 import.
 115
 116 A property value source can be used to automatically update the value of a
 117 property over time.  Clients can define their own property value source types.
 118 The various \l{qtquick-statesanimations-animations.html}{property animation}
 119 types provided by the \c QtQuick import are examples of property value
 120 sources.
 121
 122 Property modifier type instances can be created and applied to a property of
 123 a QML object through the "<ModifierType> on <propertyName>" syntax, as the
 124 following example shows:
 125
 126 \qml
 127 import QtQuick 2.0
 128
 129 Item {
 130     width: 400
 131     height: 50
 132
 133     Rectangle {
 134         width: 50
 135         height: 50
 136         color: "red"
 137
 138         NumberAnimation on x {
 139             from: 0
 140             to: 350
 141             loops: Animation.Infinite
 142             duration: 2000
 143         }
 144     }
 145 }
 146 \endqml
 147
 148 See the documentation on \l QQmlPropertyValueSource for information about how
 149 to define your own property value source types.
 150
 151 */