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