src/qml/doc/src/typesystem/basictypes.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-basictypes.html
  29 \title QML Basic Types
  30 \brief Description of basic types provided by the Qt QML module
  31
  32 QML supports a number of basic types.
  33
  34 A \e{basic type} is one that refers to a simple value, such as an \c int
  35 or a \c string. This contrasts with a \l{qtqml-typesystem-topic.html#qml-object-types}{QML Object Types},
  36 which refers to an object with properties, signals, methods and so on. Unlike an object type,
  37 a basic type cannot be used to declare QML objects: it is not possible, for example, to declare an
  38 \c int{} object or a \c size{} object.
  39
  40 Basic types can be used to refer to:
  41
  42 \list
  43 \li A single value (e.g. \l int refers to a single number, \l var can refer to a single list of items)
  44 \li A value that contains a simple set of property-value pairs (e.g. \l size refers to a value with \c width and \c height attributes)
  45 \endlist
  46
  47 \sa {qtqml-typesystem-topic.html}{The QML Type System}
  48
  49
  50 \section1 Supported Basic Types
  51
  52 Most basic types are supported by the engine by default and do not require an
  53 \l {Import Statements}{Import Statement} to be used, unlike QML object types.
  54 Some basic types which contain multiple property-value pairs (also known as \c{value types})
  55 do require an import, as they are provided by the QtQuick module.
  56 The basic types supported in QML are listed below:
  57
  58 \annotatedlist qmlbasictypes
  59
  60
  61 \section1 Property Change Behavior for Basic Types
  62
  63 Some basic types have properties: for example, the \l font type has
  64 \c pixelSize, \c family and \c bold properties. Unlike properties of
  65 \l{qtqml-typesystem-topic.html#qml-object-types}{object types}, properties of
  66 basic types do not provide their own property change signals. It is only possible
  67 to create a property change signal handler for the basic type property itself:
  68
  69 \code
  70 Text {
  71     // invalid!
  72     onFont.pixelSizeChanged: doSomething()
  73
  74     // also invalid!
  75     font {
  76         onPixelSizeChanged: doSomething()
  77     }
  78
  79     // but this is ok
  80     onFontChanged: doSomething()
  81 }
  82 \endcode
  83
  84 Be aware, however, that a property change signal for a basic type is emitted
  85 whenever \e any of its attributes have changed, as well as when the property itself
  86 changes. Take the following code, for example:
  87
  88 \qml
  89 Text {
  90     onFontChanged: console.log("font changed")
  91
  92     Text { id: otherText }
  93
  94     focus: true
  95
  96     // changing any of the font attributes, or reassigning the property
  97     // to a different font value, will invoke the onFontChanged handler
  98     Keys.onDigit1Pressed: font.pixelSize += 1
  99     Keys.onDigit2Pressed: font.bold = !font.bold
 100     Keys.onDigit3Pressed: font = otherText.font
 101 }
 102 \endqml
 103
 104 In contrast, properties of an \l{qtqml-typesystem-topic.html#qml-object-types}{object type}
 105 emit their own property change signals, and a property change signal handler for an object-type
 106 property is only invoked when the property is reassigned to a different object value.
 107
 108 */
 109
 110 /*!
 111     \qmlbasictype int
 112     \ingroup qmlbasictypes
 113     \brief a whole number, e.g. 0, 10, or -20.
 114
 115     The \c int type refers to a whole number, e.g. 0, 10, or -20.
 116
 117     The possible \c int values range from around -2000000000 to around 2000000000,
 118     although most elements will only accept a reduced range (which they
 119     mention in their documentation).
 120
 121     Example:
 122     \qml
 123     Item { width: 100; height: 200 }
 124     \endqml
 125
 126     This basic type is provided by the QML language.
 127
 128     \sa {QML Basic Types}
 129 */
 130
 131 /*!
 132     \qmlbasictype bool
 133     \ingroup qmlbasictypes
 134     \brief a binary true/false value.
 135
 136     The \c bool type refers to a binary true/false value.
 137
 138     Example:
 139     \qml
 140     Item {
 141         focus: true
 142         clip: false
 143     }
 144     \endqml
 145
 146     This basic type is provided by the QML language.
 147
 148     \sa {QML Basic Types}
 149 */
 150
 151 /*!
 152     \qmlbasictype real
 153     \ingroup qmlbasictypes
 154
 155     \brief a number with a decimal point.
 156
 157     The \c real type refers to a number with decimal point, e.g. 1.2 or -29.8.
 158
 159     Example:
 160     \qml
 161     Item { width: 100.45; height: 150.82 }
 162     \endqml
 163
 164     \b{Note:} In QML all reals are stored in double precision, \l
 165     {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point}
 166     format.
 167
 168     This basic type is provided by the QML language.
 169
 170     \sa {QML Basic Types}
 171 */
 172
 173 /*!
 174     \qmlbasictype double
 175     \ingroup qmlbasictypes
 176
 177     \brief a number with a decimal point, stored in double precision.
 178
 179     The \c double type refers to a number with a decimal point and is stored in double precision, \l
 180     {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} format.
 181
 182     Example:
 183     \qml
 184     Item {
 185         property double number: 32155.2355
 186     }
 187     \endqml
 188
 189     This basic type is provided by the QML language.
 190
 191     \sa {QML Basic Types}
 192 */
 193
 194 /*!
 195     \qmlbasictype string
 196     \ingroup qmlbasictypes
 197     \brief a free form text string.
 198
 199     The \c string type refers to a free form text string in quotes, e.g. "Hello world!".
 200
 201     Example:
 202     \qml
 203     Text { text: "Hello world!" }
 204     \endqml
 205
 206     Strings have a \c length attribute that holds the number of
 207     characters in the string.
 208
 209     QML extends the JavaScript String type with a \l {String::arg}{arg()} function
 210     to support value substitution.
 211
 212     When integrating with C++, note that any QString value
 213     \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 214     converted into a \c string value, and vice-versa.
 215
 216     This basic type is provided by the QML language.
 217
 218     \sa {QML Basic Types}
 219 */
 220
 221 /*!
 222     \qmlbasictype url
 223     \ingroup qmlbasictypes
 224     \brief a resource locator.
 225
 226     The \c url type refers to a resource locator (like a file name, for example). It can be either
 227     absolute, e.g. "http://qt.nokia.com", or relative, e.g.  "pics/logo.png". A relative URL is
 228     resolved relative to the URL of the containing component.
 229
 230     For example, the following assigns a valid URL to the \l {Image::source}
 231     property, which is of type \c url:
 232
 233     \qml
 234     Image { source: "pics/logo.png" }
 235     \endqml
 236
 237     When integrating with C++, note that any QUrl value
 238     \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 239     converted into a \c url value, and vice-versa.
 240
 241
 242     \section1 Using the url type
 243
 244     When a relative URL is written to a \c url type property, it is converted
 245     into a URL object, so \bold {matching the URL value against the input string
 246     value will fail}. Instead, convert the string to a URL using Qt.resolvedUrl()
 247     for means of comparison, and use \c toString() to get the contents of the URL:
 248
 249     \qml
 250     Image {
 251         source: "pics/logo.png"
 252
 253         Component.onCompleted: {
 254             // This prints 'false'. Although "pics/logo.png" was the input string,
 255             // it's been converted from a string to a URL, so these two are not the same.
 256             console.log(source == "pics/logo.png")
 257
 258             // This prints 'true' as Qt.resovledUrl() converts the string into a
 259             // URL with the correctly resolved path
 260             console.log(source == Qt.resolvedUrl("pics/logo.png"))
 261
 262             // This prints the absolute path, e.g. "file:///path/to/pics/logo.png"
 263             console.log(source.toString())
 264         }
 265     }
 266     \endqml
 267
 268     \note When referring to files stored with the \l{resources.html}{Qt Resource System}
 269     from within QML, you should use "qrc:///" instead of ":/" as QML requires URL paths.
 270     Relative URLs resolved from within that file will use the same protocol.
 271
 272     Additionally, URLs may contain encoded characters using the 'percent-encoding' scheme
 273     specified by \l {http://tools.ietf.org/html/rfc3986}{RFC 3986}.  These characters
 274     will be preserved within properties of type \c url, to allow QML code to
 275     construct precise URL values. An exception to this rule is the preemptive
 276     decoding of directory-separator characters (\c '/') - these characters are decoded
 277     to allow the URL to be correctly classified.
 278
 279     For example, a local file containing a '#' character, which would normally be
 280     interpreted as the beginning of the URL 'fragment' element, can be accessed by
 281     encoding the characters of the file name:
 282
 283     \qml
 284     Image { source: encodeURIComponent("/tmp/test#1.png") }
 285     \endqml
 286
 287     This basic type is provided by the QML language.
 288
 289     \sa {QML Basic Types}
 290 */
 291
 292 /*!
 293     \qmlbasictype color
 294     \ingroup qmlbasictypes
 295     \brief an ARGB color value.
 296     \target qmlbasictypecolor
 297
 298     The \c color type refers to an ARGB color value. It can be specified in a number of ways:
 299
 300     \list
 301     \li By a \l{http://www.w3.org/TR/SVG/types.html#ColorKeywords}{SVG color name}, such as
 302         "red", "green" or "lightsteelblue".
 303     \li By a hexadecimal triplet or quad in the form \c "#RRGGBB" and \c "#AARRGGBB"
 304         respectively. For example, the color red corresponds to a triplet of \c "#FF0000"
 305         and a slightly transparent blue to a quad of \c "#800000FF".
 306     \li Using the \l{QML:Qt::rgba()}{Qt.rgba()}, \l{QML:Qt::hsla()}{Qt.hsla()},
 307         \l{QML:Qt::darker()}{Qt.darker()}, \l{QML:Qt::lighter()}{Qt.lighter()} or
 308         \l{QML:Qt::tint()}{Qt.tint()} functions.
 309     \endlist
 310
 311     Example:
 312
 313     \div{float-right}
 314     \inlineimage declarative-colors.png
 315     \enddiv
 316     \snippet qml/colors.qml colors
 317
 318     Additionally, a color type has \c r, \c g, \c b and \c a properties that refer to the
 319     red, green, blue and alpha values of the color, respectively:
 320
 321     \qml
 322     Text {
 323         color: "red"
 324
 325         // prints "1 0 0 1"
 326         Component.onCompleted: console.log(color.r, color.g, color.b, color.a)
 327     }
 328     \endqml
 329
 330     To test color values for equality, use the \l{QML:Qt::colorEqual()}{Qt.colorEqual()}
 331     function.  This allows colors to be accurately compared whether they are in property
 332     form or in any of the acceptable string specification forms.
 333
 334     When integrating with C++, note that any QColor value
 335     \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 336     converted into a \c color value, and vice-versa.
 337
 338     This basic type is provided by the QtQuick import.
 339
 340     \sa {QML Basic Types}
 341 */
 342
 343 /*!
 344     \qmlbasictype point
 345     \ingroup qmlbasictypes
 346     \brief a value with x and y attributes.
 347
 348     The \c point type refers to a value with \c x and \c y attributes.
 349
 350     To create a \c point value, specify it as a "x,y" string:
 351
 352     \qml
 353     CustomObject { myPointProperty: "0,20" }
 354     \endqml
 355
 356     Or use the \l{QML:Qt::point()}{Qt.point()} function:
 357
 358     \qml
 359     CustomObject { myPointProperty: Qt.point(0, 20) }
 360     \endqml
 361
 362     When integrating with C++, note that any QPoint or QPointF value
 363     \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 364     converted into a \c point value. When a \c point value is passed to C++, it
 365     is automatically converted into a QPointF value.
 366
 367     This basic type is provided by the QML language.
 368
 369     \sa {QML Basic Types}
 370 */
 371
 372 /*!
 373     \qmlbasictype size
 374     \ingroup qmlbasictypes
 375     \brief a value with width and height attributes
 376
 377     The \c size type refers to a value with has \c width and \c height attributes.
 378
 379     For example, to read the \c width and \c height values of the
 380     \l {Image::sourceSize} size-type property:
 381
 382     \qml
 383     Column {
 384         Image { id: image; source: "logo.png" }
 385         Text { text: image.sourceSize.width + "," + image.sourceSize.height }
 386     }
 387     \endqml
 388
 389     To create a \c size value, specify it as a "width x height" string:
 390
 391     \qml
 392     Image { sourceSize: "150x50" }
 393     \endqml
 394
 395     Or use the \l{QML:Qt::size()}{Qt.size()} function:
 396
 397     \qml
 398     Image { sourceSize: Qt.size(150, 50) }
 399     \endqml
 400
 401     When integrating with C++, note that any QSize or QSizeF value
 402     \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 403     converted into a \c size value, and vice-versa. When a \c size value is passed to C++, it
 404     is automatically converted into a QSizeF value.
 405
 406     This basic type is provided by the QML language.
 407
 408     \sa {QML Basic Types}
 409 */
 410
 411 /*!
 412     \qmlbasictype rect
 413     \ingroup qmlbasictypes
 414     \brief a value with x, y, width and height attributes.
 415
 416     The \c rect type refers to a value with \c x, \c y, \c width and \c height attributes.
 417
 418     For example, to read the \c width and \c height values of the \l Item
 419     \l {Item::}{childrenRect} rect-type type property:
 420
 421     \qml
 422     Rectangle {
 423         width: childrenRect.width
 424         height: childrenRect.height
 425
 426         Rectangle { width: 100; height: 100 }
 427     }
 428     \endqml
 429
 430     To create a \c rect value, specify it as a "x, y, width x height" string:
 431
 432     \qml
 433     CustomObject { myRectProperty: "50,50,100x100" }
 434     \endqml
 435
 436     Or use the \l{QML:Qt::rect()}{Qt.rect()} function:
 437
 438     \qml
 439     CustomObject { myRectProperty: Qt.rect(50, 50, 100, 100) }
 440     \endqml
 441
 442     When integrating with C++, note that any QRect or QRectF value
 443     \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 444     converted into a \c rect value, and vice-versa. When a \c rect value is passed to C++, it
 445     is automatically converted into a QRectF value.
 446
 447     This basic type is provided by the QML language.
 448
 449     \sa {QML Basic Types}
 450 */
 451
 452 /*!
 453     \qmlbasictype date
 454     \ingroup qmlbasictypes
 455     \brief a date value.
 456
 457     The \c date type refers to a date value.
 458
 459     To create a \c date value, specify it as a "YYYY-MM-DD" string:
 460
 461     \qml
 462     MyDatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" }
 463     \endqml
 464
 465     To read a date value returned from a C++ extension class, use
 466     \l{QML:Qt::formatDate()}{Qt.formatDate()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.
 467
 468     When integrating with C++, note that any QDate value
 469     \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 470     converted into a \c date value, and vice-versa.
 471
 472     Note that the date type has comparison semantics which match
 473     those of the JavaScript Date object.  To compare the value
 474     of two date properties, you should compare their "toString()"
 475     values.
 476
 477     This basic type is provided by the QML language.
 478
 479     \sa {QML Basic Types}
 480 */
 481
 482 /*!
 483     \qmlbasictype time
 484     \ingroup qmlbasictypes
 485     \brief a time value.
 486
 487     The \c time type refers to a time value.
 488
 489     To create a \c time value, specified as "hh:mm:ss":
 490
 491     \qml
 492     MyTimePicker { time: "14:22:15" }
 493     \endqml
 494
 495     To read a time value returned from a C++ extension class, use
 496     \l{QML:Qt::formatTime()}{Qt.formatTime()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.
 497
 498     Note that when converting historical times to and from javascript that QDateTime and the JS Date object
 499     have different methods of calculating historical daylight savings time application. This can lead to variations of one hour
 500     when converting to historical local time.
 501
 502     When integrating with C++, note that any QTime value
 503     \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 504     converted into a \c time value, and vice-versa.
 505
 506     This basic type is provided by the QML language.
 507
 508     \sa {QML Basic Types}
 509  */
 510
 511 /*!
 512     \qmlbasictype font
 513     \ingroup qmlbasictypes
 514     \brief a font value with the properties of QFont.
 515     \target fontbasictypedocs
 516
 517     The \c font type refers to a font value with the properties of QFont.
 518
 519     These properties are:
 520
 521     \list
 522     \li \l string \c font.family
 523     \li \l bool \c font.bold
 524     \li \l bool \c font.italic
 525     \li \l bool \c font.underline
 526     \li \l real \c font.pointSize
 527     \li \l int \c font.pixelSize
 528     \endlist
 529
 530     Example:
 531     \qml
 532     Text { font.family: "Helvetica"; font.pointSize: 13; font.bold: true }
 533     \endqml
 534
 535     When integrating with C++, note that any QFont value
 536     \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 537     converted into a \c font value, and vice-versa.
 538
 539     This basic type is provided by the QtQuick import.
 540
 541     \sa {QML Basic Types}
 542 */
 543
 544 /*!
 545     \qmlbasictype list
 546     \ingroup qmlbasictypes
 547     \brief a list of QML objects.
 548
 549     The \c list type refers to a list of QML objects.
 550
 551     A list value can be accessed in a similar way to a JavaScript array:
 552
 553     \list
 554     \li Values are assigned using the \c[] square bracket syntax with comma-separated values
 555     \li The \c length property provides the number of items in the list
 556     \li Values in the list are accessed using the \c [index] syntax
 557     \endlist
 558
 559     A \c list can only store QML objects, and cannot contain any
 560     \l {QML Basic Types}{basic type} values. (To store basic types within a
 561     list, use the \l var type instead.)
 562
 563     When integrating with C++, note that any QQmlListProperty value
 564     \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 565     converted into a \c list value, and vice-versa.
 566
 567
 568     \section1 Using the list type
 569
 570     For example, the \l Item type has a \l {Item::}{states} list-type property that
 571     can be assigned to and used as follows:
 572
 573     \qml
 574     import QtQuick 2.0
 575
 576     Item {
 577         width: 100; height: 100
 578
 579         states: [
 580             State { name: "activated" },
 581             State { name: "deactivated" }
 582         ]
 583
 584         Component.onCompleted: {
 585             console.log("Name of first state:", states[0].name)
 586             for (var i=0; i<states.length; i++)
 587                 console.log("state", i, states[i].name)
 588         }
 589     }
 590     \endqml
 591
 592     The defined \l State objects will be added to the \c states list
 593     in the order in which they are defined.
 594
 595     If the list only contains one object, the square brackets may be omitted:
 596
 597     \qml
 598     import QtQuick 2.0
 599
 600     Item {
 601         width: 100; height: 100
 602         states: State { name: "activated" }
 603     }
 604     \endqml
 605
 606     Note that objects cannot be individually added to or removed from
 607     the list once created; to modify the contents of a list, it must be
 608     reassigned to a new list.
 609
 610     \note The \c list type is not recommended as a type for custom properties.
 611     The \c var type should be used instead for this purpose as
 612     lists stored by the \c var type can be manipulated with greater
 613     flexibility from within QML.
 614
 615     This basic type is provided by the QML language.
 616
 617     \sa {QML Basic Types}
 618 */
 619
 620  /*!
 621     \qmlbasictype var
 622     \ingroup qmlbasictypes
 623     \brief a generic property type.
 624
 625     The \c var type is a generic property type that can refer to any data type.
 626
 627     It is equivalent to a regular JavaScript variable.
 628     For example, var properties can store numbers, strings, objects,
 629     arrays and functions:
 630
 631     \qml
 632     Item {
 633         property var aNumber: 100
 634         property var aBool: false
 635         property var aString: "Hello world!"
 636         property var anotherString: String("#FF008800")
 637         property var aColor: Qt.rgba(0.2, 0.3, 0.4, 0.5)
 638         property var aRect: Qt.rect(10, 10, 10, 10)
 639         property var aPoint: Qt.point(10, 10)
 640         property var aSize: Qt.size(10, 10)
 641         property var aVector3d: Qt.vector3d(100, 100, 100)
 642         property var anArray: [1, 2, 3, "four", "five", (function() { return "six"; })]
 643         property var anObject: { "foo": 10, "bar": 20 }
 644         property var aFunction: (function() { return "one"; })
 645     }
 646     \endqml
 647
 648     It is important to note that changes in regular properties of JavaScript
 649     objects assigned to a var property will \b{not} trigger updates of bindings
 650     that access them.  The example below will display "The car has 4 wheels" as
 651     the change to the wheels property will not cause the reevaluation of the
 652     binding assigned to the "text" property:
 653
 654     \qml
 655     Item {
 656         property var car: new Object({wheels: 4})
 657
 658         Text {
 659             text: "The car has " + car.wheels + " wheels";
 660         }
 661
 662         Component.onCompleted: {
 663             car.wheels = 6;
 664         }
 665     }
 666     \endqml
 667
 668     If the onCompleted handler instead had \tt{"car = new Object({wheels: 6})"}
 669     then the text would be updated to say "The car has 6 wheels", since the
 670     car property itself would be changed, which causes a change notification
 671     to be emitted.
 672
 673     \section1 Using Scarce Resources with the var Type
 674
 675     A \c var type property can also hold an image or pixmap.
 676     A \c var which contains a QPixmap or QImage is known as a
 677     "scarce resource" and the declarative engine will attempt to
 678     automatically release such resources after evaluation of any JavaScript
 679     expression which requires one to be copied has completed.
 680
 681     Clients may explicitly release such a scarce resource by calling the
 682     "destroy" method on the \c var property from within JavaScript.  They
 683     may also explicitly preserve the scarce resource by calling the
 684     "preserve" method on the \c var property from within JavaScript.
 685     For more information regarding the usage of a scarce resource, please
 686     see \l{Scarce Resources in JavaScript}.
 687
 688     This basic type is provided by the QML language.
 689
 690     \sa {QML Basic Types}
 691 */
 692
 693
 694 /*!
 695     \obsolete
 696     \qmlbasictype variant
 697     \ingroup qmlbasictypes
 698     \brief a generic property type.
 699
 700     The \c variant type is a generic property type. It is obsolete and exists only to
 701     support old applications; new applications should use \l var type
 702     properties instead.
 703
 704     A variant type property can hold any of the \l {QML Basic Types}{basic type}
 705     values:
 706
 707     \qml
 708     Item {
 709         property variant aNumber: 100
 710         property variant aString: "Hello world!"
 711         property variant aBool: false
 712     }
 713     \endqml
 714
 715     When integrating with C++, note that any QVariant value
 716     \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 717     converted into a \c variant value, and vice-versa.
 718
 719
 720     \section1 Using Scarce Resources with the variant Type
 721
 722     A \c variant type property can also hold an image or pixmap.
 723     A \c variant which contains a QPixmap or QImage is known as a
 724     "scarce resource" and the declarative engine will attempt to
 725     automatically release such resources after evaluation of any JavaScript
 726     expression which requires one to be copied has completed.
 727
 728     Clients may explicitly release such a scarce resource by calling the
 729     "destroy" method on the \c variant property from within JavaScript.  They
 730     may also explicitly preserve the scarce resource by calling the
 731     "preserve" method on the \c variant property from within JavaScript.
 732     For more information regarding the usage of a scarce resource, please
 733     see \l{Scarce Resources in JavaScript}.
 734
 735     \section1 Storing Arrays and Objects
 736
 737     The \c variant type can also hold:
 738
 739     \list
 740     \li An array of \l {QML Basic Types}{basic type} values
 741     \li A map of key-value pairs with \l {QML Basic Types}{basic-type} values
 742     \endlist
 743
 744     For example, below is an \c items array and an \c attributes map. Their
 745     contents can be examined using JavaScript \c for loops. Individual array
 746     values are accessible by index, and individual map values are accessible
 747     by key:
 748
 749     \qml
 750     Item {
 751         property variant items: [1, 2, 3, "four", "five"]
 752         property variant attributes: { 'color': 'red', 'width': 100 }
 753
 754         Component.onCompleted: {
 755             for (var i=0; i<items.length; i++)
 756                 console.log(items[i])
 757
 758             for (var prop in attributes)
 759                 console.log(prop, "=", attributes[prop])
 760         }
 761     }
 762     \endqml
 763
 764     While this is a convenient way to store array and map-type values, you
 765     must be aware that the \c items and \c attributes properties above are \e not
 766     QML objects (and certainly not JavaScript object either) and the key-value
 767     pairs in \c attributes are \e not QML properties. Rather, the \c items
 768     property holds an array of values, and \c attributes holds a set of key-value
 769     pairs. Since they are stored as a set of values, instead of as an object,
 770     their contents \e cannot be modified individually:
 771
 772     \qml
 773     Item {
 774         property variant items: [1, 2, 3, "four", "five"]
 775         property variant attributes: { 'color': 'red', 'width': 100 }
 776
 777         Component.onCompleted: {
 778             items[0] = 10
 779             console.log(items[0])     // This will still be '1'!
 780             attributes.color = 'blue'
 781             console.log(attributes.color)     // This will still be 'red'!
 782         }
 783     }
 784     \endqml
 785
 786     Since it is not possible to individually add or remove items from a list or
 787     object stored in a \c variant, the only way to modify its contents is to
 788     reassign a new value. However, this is not efficent, as it causes the value
 789     to be serialized and deserialized.
 790
 791     Additionally, since \c items and \c attributes are not QML objects, changing
 792     their individual values do not trigger property change notifications. If
 793     the above example had \c onNumberChanged or \c onAnimalChanged signal
 794     handlers, they would not have been called.  If, however, the \c items or
 795     \c attributes properties themselves were reassigned to different values, then
 796     such handlers would be called.
 797
 798     JavaScript programmers should also note that when a JavaScript object is
 799     copied to an array or map property, the \e contents of the object (that is,
 800     its key-value properties) are copied, rather than the object itself. The
 801     property does not hold a reference to the original JavaScript object, and
 802     extra data such as the object's JavaScript prototype chain is also lost in
 803     the process.
 804
 805     This basic type is provided by the QML language.
 806
 807     \sa {QML Basic Types}
 808 */
 809
 810 /*!
 811     \qmlbasictype vector2d
 812     \ingroup qmlbasictypes
 813
 814     \brief A vector2d type has x and y attributes.
 815
 816     A \c vector2d type has \c x and \c y attributes, otherwise
 817     it is similar to the \c vector3d type.  Please see the
 818     documentation about the \c vector3d type for more information.
 819
 820     To create a \c vector2d value, specify it as a "x,y" string,
 821     or define the components individually, or compose it with
 822     the Qt.vector2d() function.
 823
 824     This basic type is provided by the QtQuick import.
 825
 826     \sa {QML Basic Types}
 827 */
 828
 829 /*!
 830     \qmlbasictype vector3d
 831     \ingroup qmlbasictypes
 832     \brief a value with x, y, and z attributes.
 833
 834     The \c vector3d type refers to a value with \c x, \c y, and \c z attributes.
 835
 836     To create a \c vector3d value, specify it as a "x,y,z" string:
 837
 838     \qml
 839     Rotation { angle: 60; axis: "0,1,0" }
 840     \endqml
 841
 842     or with the \l{QML:Qt::vector3d()}{Qt.vector3d()} function:
 843
 844     \qml
 845     Rotation { angle: 60; axis: Qt.vector3d(0, 1, 0) }
 846     \endqml
 847
 848     or as separate \c x, \c y, and \c z components:
 849
 850     \qml
 851     Rotation { angle: 60; axis.x: 0; axis.y: 1; axis.z: 0 }
 852     \endqml
 853
 854     When integrating with C++, note that any QVector3D value
 855     \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 856     converted into a \c vector3d value, and vice-versa.
 857
 858     This basic type is provided by the QtQuick import.
 859
 860     \sa {QML Basic Types}
 861 */
 862
 863 /*!
 864     \qmlbasictype vector4d
 865     \ingroup qmlbasictypes
 866
 867     \brief A vector4d type has x, y, z and w attributes.
 868
 869     A \c vector4d type has \c x, \c y, \c z and \c w attributes,
 870     otherwise it is similar to the \c vector3d type.  Please see the
 871     documentation about the \c vector3d type for more information.
 872
 873     To create a \c vector4d value, specify it as a "x,y,z,w" string,
 874     or define the components individually, or compose it with
 875     the Qt.vector4d() function.
 876
 877     This basic type is provided by the QtQuick import.
 878
 879     \sa {QML Basic Types}
 880 */
 881
 882 /*!
 883     \qmlbasictype quaternion
 884     \ingroup qmlbasictypes
 885
 886     \brief A quaternion type has scalar, x, y, and z attributes.
 887
 888     A \c quaternion type has \c scalar, \c x, \c y and \c z attributes,
 889     otherwise it is similar to the \c vector3d type.  Please see the
 890     documentation about the \c vector3d type for more information.
 891
 892     To create a \c quaternion value, specify it as a "scalar,x,y,z" string,
 893     or define the components individually, or compose it with
 894     the Qt.quaternion() function.
 895
 896     This basic type is provided by the QtQuick import.
 897
 898     \sa {QML Basic Types}
 899 */
 900
 901 /*!
 902     \qmlbasictype matrix4x4
 903     \ingroup qmlbasictypes
 904
 905     \brief A matrix4x4 type is a 4-row and 4-column matrix
 906
 907     A \c matrix4x4 type has sixteen values, but these values are
 908     largely opaque to QML.  Values of this type can be composed with
 909     the Qt.matrix4x4() function.
 910
 911     This basic type is provided by the QtQuick import.
 912
 913     \sa {QML Basic Types}
 914 */
 915
 916 /*!
 917     \qmlbasictype enumeration
 918     \ingroup qmlbasictypes
 919     \brief a set of named values.
 920
 921     The \c enumeration type refers to a set of named values.
 922
 923     Each named value can be referred to as \c {<Type>.<value>}. For
 924     example, the \l Text type has an \c AlignRight enumeration value:
 925
 926     \qml
 927     Text { horizontalAlignment: Text.AlignRight }
 928     \endqml
 929
 930     (For backwards compatibility, the enumeration value may also be
 931     specified as a string, e.g. "AlignRight". This form is not
 932     recommended for new code.)
 933
 934     When integrating with C++, note that any enumeration value
 935     \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
 936     converted into an \c enumeration value, and vice-versa.
 937
 938     This basic type is provided by the QML language.  Some enumeration values
 939     are provided by the QtQuick import.
 940
 941     \sa {QML Basic Types}
 942 */
 943