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 QtQml Module
  30 \brief List of QML types provided by the QtQml module
  31
  32 The \c QtQml module provides the definition and implementation of various
  33 convenience types which can be used with the QML language, including some
  34 elementary QML types which can provide the basis for further extensions to the
  35 QML language.
  36
  37 The \c QtQml module provides the \c QtObject and \c Component object types
  38 which may be used in QML documents.  These types are non-visual and provide
  39 building-blocks for extensions to QML.
  40
  41 \section1 Importing QtQml
  42
  43 The types provided by the \c QtQml module are only available in a QML document
  44 if that document imports the \c QtQml namespace (or if the document imports the
  45 \c QtQuick namespace, as noted below).
  46
  47 The current version of the \c QtQml module is version 2.0, and thus it may be
  48 imported via the following statement:
  49
  50 \qml
  51 import QtQml 2.0
  52 \endqml
  53
  54 Most clients will never need to use the \c QtQml import, as all of the types
  55 and functionality provided by the \c QtQml namespace are also provided by the
  56 \c QtQuick namespace which may be imported as follows:
  57
  58 \qml
  59 import QtQuick 2.0
  60 \endqml
  61
  62 See the \l{QtQuick}{QtQuick} module documentation for more information about the
  63 \c QtQuick namespace and what it provides to QML application developers.
  64
  65 The documentation for the types below applies equally to the types of the same
  66 name provided by the \l{QtQuick}{QtQuick} module, as they are in fact identical.
  67
  68 \section1 Basic Types
  69
  70 The following \l{qtqml-typesystem-basictypes.html}{QML basic types} are
  71 provided:
  72
  73 \annotatedlist qtqmlbasictypes
  74
  75 \section1 Object Types
  76
  77 The following \l{qtqml-typesystem-objecttypes.html}{QML object types} are
  78 provided:
  79
  80 \section2 QtObject
  81
  82 The \c QtObject type provides a basic instantiable object which can be used in
  83 QML applications.  It is non-visual, but may have properties, methods, signals
  84 and signal handlers.
  85
  86 For example, the following QtObject has several properties, one of which has
  87 been assigned a \l{Property Binding}
  88 {binding}, and a \l{Signal and Handler Event System}{signal handler} for
  89 the default change signal which exists for one of its properties:
  90
  91 \code
  92     import QtQuick 2.0
  93
  94     QtObject {
  95         property int a: 15
  96         property int b: a + 22
  97         property int changeCount: 0
  98
  99         onAChanged: {
 100             changeCount += 1;
 101         }
 102     }
 103 \endcode
 104
 105 \section2 Component
 106
 107 The \c Component type provides a basic re-usable component which allows
 108 instances of another type to be instantiated on-demand.  It may be given an
 109 \c id and it has a default property which is the object type to instantiate,
 110 but no other properties may be added to it.
 111
 112 For example, the following QtObject has two different \l Component
 113 properties, and it uses those components to dynamically construct objects at
 114 run-time:
 115
 116 \code
 117     import QtQuick 2.0
 118
 119     QtObject {
 120         id: root
 121         property bool which: true
 122
 123         property Component a: Component {
 124             id: firstComponent
 125             QtObject {
 126                 property int answer: 42
 127                 function activate() {
 128                     console.log("The answer is: " + answer);
 129                 }
 130             }
 131         }
 132
 133         property Component b: Component {
 134             id: secondComponent
 135             QtObject {
 136                 property string message: "Hello, World!"
 137                 function activate() {
 138                     console.log(message);
 139                 }
 140             }
 141         }
 142
 143         function activateDynamicObject() {
 144             var o = {};
 145             if (which) {
 146                 which = false;
 147                 o = a.createObject(null); // no parent
 148             } else {
 149                 which = true;
 150                 o = b.createObject(null); // no parent
 151             }
 152             o.activate();
 153         }
 154     }
 155 \endcode
 156
 157 */
 158
 159 /*!
 160 \qmlbasictype date
 161 \ingroup qtqmlbasictypes
 162 \ingroup qtquickbasictypes
 163 \brief a date value.
 164
 165 The \c date type refers to a date value.
 166
 167 To create a \c date value, specify it as a "YYYY-MM-DD" string:
 168
 169 \qml
 170 MyDatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" }
 171 \endqml
 172
 173 To read a date value returned from a C++ extension class, use
 174 \l{QML:Qt::formatDate()}{Qt.formatDate()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.
 175
 176 When integrating with C++, note that any QDate value
 177 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 178 converted into a \c date value, and vice-versa.
 179
 180 Note that the date type has comparison semantics which match
 181 those of the JavaScript Date object.  To compare the value
 182 of two date properties, you should compare their "toString()"
 183 values.
 184
 185 This basic type is provided by the QML language.
 186
 187 \sa {QML Basic Types}
 188 */
 189
 190 /*!
 191 \qmlbasictype time
 192 \ingroup qtqmlbasictypes
 193 \ingroup qtquickbasictypes
 194 \brief a time value.
 195
 196 The \c time type refers to a time value.
 197
 198 To create a \c time value, specified as "hh:mm:ss":
 199
 200 \qml
 201 MyTimePicker { time: "14:22:15" }
 202 \endqml
 203
 204 To read a time value returned from a C++ extension class, use
 205 \l{QML:Qt::formatTime()}{Qt.formatTime()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.
 206
 207 Note that when converting historical times to and from javascript that QDateTime and the JS Date object
 208 have different methods of calculating historical daylight savings time application. This can lead to variations of one hour
 209 when converting to historical local time.
 210
 211 When integrating with C++, note that any QTime value
 212 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 213 converted into a \c time value, and vice-versa.
 214
 215 This basic type is provided by the QML language.
 216
 217 \sa {QML Basic Types}
 218 */
 219
 220 /*!
 221 \qmlbasictype point
 222 \ingroup qtqmlbasictypes
 223 \ingroup qtquickbasictypes
 224 \brief a value with x and y attributes.
 225
 226 The \c point type refers to a value with \c x and \c y attributes.
 227
 228 To create a \c point value, specify it as a "x,y" string:
 229
 230 \qml
 231 CustomObject { myPointProperty: "0,20" }
 232 \endqml
 233
 234 Or use the \l{QML:Qt::point()}{Qt.point()} function:
 235
 236 \qml
 237 CustomObject { myPointProperty: Qt.point(0, 20) }
 238 \endqml
 239
 240 When integrating with C++, note that any QPoint or QPointF value
 241 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 242 converted into a \c point value. When a \c point value is passed to C++, it
 243 is automatically converted into a QPointF value.
 244
 245 \sa{QML Basic Types}
 246 */
 247
 248 /*!
 249 \qmlbasictype size
 250 \ingroup qtqmlbasictypes
 251 \ingroup qtquickbasictypes
 252 \brief a value with width and height attributes
 253
 254 The \c size type refers to a value with has \c width and \c height attributes.
 255
 256 For example, to read the \c width and \c height values of the
 257 \l {Image::sourceSize} size-type property:
 258
 259 \qml
 260 Column {
 261     Image { id: image; source: "logo.png" }
 262     Text { text: image.sourceSize.width + "," + image.sourceSize.height }
 263 }
 264 \endqml
 265
 266 To create a \c size value, specify it as a "width x height" string:
 267
 268 \qml
 269 Image { sourceSize: "150x50" }
 270 \endqml
 271
 272 Or use the \l{QML:Qt::size()}{Qt.size()} function:
 273
 274 \qml
 275 Image { sourceSize: Qt.size(150, 50) }
 276 \endqml
 277
 278 When integrating with C++, note that any QSize or QSizeF value
 279 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 280 converted into a \c size value, and vice-versa. When a \c size value is passed to C++, it
 281 is automatically converted into a QSizeF value.
 282
 283 \sa{QML Basic Types}
 284 */
 285
 286 /*!
 287 \qmlbasictype rect
 288 \ingroup qtqmlbasictypes
 289 \ingroup qtquickbasictypes
 290 \brief a value with x, y, width and height attributes.
 291
 292 The \c rect type refers to a value with \c x, \c y, \c width and \c height attributes.
 293
 294 For example, to read the \c width and \c height values of the \l Item
 295 \l {Item::childrenRect.x}{childrenRect} rect-type type property:
 296
 297 \qml
 298 Rectangle {
 299     width: childrenRect.width
 300     height: childrenRect.height
 301
 302     Rectangle { width: 100; height: 100 }
 303 }
 304 \endqml
 305
 306 To create a \c rect value, specify it as a "x, y, width x height" string:
 307
 308 \qml
 309 CustomObject { myRectProperty: "50,50,100x100" }
 310 \endqml
 311
 312 Or use the \l{QML:Qt::rect()}{Qt.rect()} function:
 313
 314 \qml
 315 CustomObject { myRectProperty: Qt.rect(50, 50, 100, 100) }
 316 \endqml
 317
 318 When integrating with C++, note that any QRect or QRectF value
 319 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 320 converted into a \c rect value, and vice-versa. When a \c rect value is passed to C++, it
 321 is automatically converted into a QRectF value.
 322
 323 \sa{QML Basic Types}
 324 */
 325
 326