Improve QtQml module documentation

[profile/ivi/qtdeclarative.git] / src / qml / doc / src / typesystem / basictypes.qdoc

/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtqml-typesystem-basictypes.html
\title QML Basic Types
\brief Description of basic types provided by the Qt QML module

QML supports a number of basic types.

A \e{basic type} is one that refers to a simple value, such as an \c int
or a \c string. This contrasts with a \l{qtqml-typesystem-topic.html#qml-object-types}{QML Object Types},
which refers to an object with properties, signals, methods and so on. Unlike an object type,
a basic type cannot be used to declare QML objects: it is not possible, for example, to declare an
\c int{} object or a \c size{} object.

Basic types can be used to refer to:

\list
\li A single value (e.g. \l int refers to a single number, \l var can refer to a single list of items)
\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)
\endlist

\sa {qtqml-typesystem-topic.html}{The QML Type System}


\section1 Supported Basic Types

Most basic types are supported by the engine by default and do not require an
\l {Import Statements}{Import Statement} to be used, unlike QML object types.
Some basic types which contain multiple property-value pairs (also known as \c{value types})
do require an import, as they are provided by the QtQuick module.
The basic types supported in QML are listed below:

\annotatedlist qmlbasictypes


\section1 Property Change Behavior for Basic Types

Some basic types have properties: for example, the \l font type has
\c pixelSize, \c family and \c bold properties. Unlike properties of
\l{qtqml-typesystem-topic.html#qml-object-types}{object types}, properties of
basic types do not provide their own property change signals. It is only possible
to create a property change signal handler for the basic type property itself:

\code
Text {
    // invalid!
    onFont.pixelSizeChanged: doSomething()

    // also invalid!
    font {
        onPixelSizeChanged: doSomething()
    }

    // but this is ok
    onFontChanged: doSomething()
}
\endcode

Be aware, however, that a property change signal for a basic type is emitted
whenever \e any of its attributes have changed, as well as when the property itself
changes. Take the following code, for example:

\qml
Text {
    onFontChanged: console.log("font changed")

    Text { id: otherText }

    focus: true

    // changing any of the font attributes, or reassigning the property
    // to a different font value, will invoke the onFontChanged handler
    Keys.onDigit1Pressed: font.pixelSize += 1
    Keys.onDigit2Pressed: font.bold = !font.bold
    Keys.onDigit3Pressed: font = otherText.font
}
\endqml

In contrast, properties of an \l{qtqml-typesystem-topic.html#qml-object-types}{object type}
emit their own property change signals, and a property change signal handler for an object-type
property is only invoked when the property is reassigned to a different object value.

*/

/*!
    \qmlbasictype int
    \ingroup qmlbasictypes
    \brief a whole number, e.g. 0, 10, or -20.

    The \c int type refers to a whole number, e.g. 0, 10, or -20.

    The possible \c int values range from around -2000000000 to around 2000000000,
    although most elements will only accept a reduced range (which they
    mention in their documentation).

    Example:
    \qml
    Item { width: 100; height: 200 }
    \endqml

    This basic type is provided by the QML language.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype bool
    \ingroup qmlbasictypes
    \brief a binary true/false value.

    The \c bool type refers to a binary true/false value.

    Example:
    \qml
    Item {
        focus: true
        clip: false
    }
    \endqml

    This basic type is provided by the QML language.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype real
    \ingroup qmlbasictypes

    \brief a number with a decimal point.

    The \c real type refers to a number with decimal point, e.g. 1.2 or -29.8.

    Example:
    \qml
    Item { width: 100.45; height: 150.82 }
    \endqml

    \b{Note:} In QML all reals are stored in double precision, \l
    {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point}
    format.

    This basic type is provided by the QML language.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype double
    \ingroup qmlbasictypes

    \brief a number with a decimal point, stored in double precision.

    The \c double type refers to a number with a decimal point and is stored in double precision, \l
    {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} format.

    Example:
    \qml
    Item {
        property double number: 32155.2355
    }
    \endqml

    This basic type is provided by the QML language.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype string
    \ingroup qmlbasictypes
    \brief a free form text string.

    The \c string type refers to a free form text string in quotes, e.g. "Hello world!".

    Example:
    \qml
    Text { text: "Hello world!" }
    \endqml

    Strings have a \c length attribute that holds the number of
    characters in the string.

    QML extends the JavaScript String type with a \l {String::arg}{arg()} function
    to support value substitution.

    When integrating with C++, note that any QString value
    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
    converted into a \c string value, and vice-versa.

    This basic type is provided by the QML language.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype url
    \ingroup qmlbasictypes
    \brief a resource locator.

    The \c url type refers to a resource locator (like a file name, for example). It can be either
    absolute, e.g. "http://qt.nokia.com", or relative, e.g.  "pics/logo.png". A relative URL is
    resolved relative to the URL of the containing component.

    For example, the following assigns a valid URL to the \l {Image::source}
    property, which is of type \c url:

    \qml
    Image { source: "pics/logo.png" }
    \endqml

    When integrating with C++, note that any QUrl value
    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
    converted into a \c url value, and vice-versa.


    \section1 Using the url type

    When a relative URL is written to a \c url type property, it is converted
    into a URL object, so \bold {matching the URL value against the input string
    value will fail}. Instead, convert the string to a URL using Qt.resolvedUrl()
    for means of comparison, and use \c toString() to get the contents of the URL:

    \qml
    Image {
        source: "pics/logo.png"

        Component.onCompleted: {
            // This prints 'false'. Although "pics/logo.png" was the input string,
            // it's been converted from a string to a URL, so these two are not the same.
            console.log(source == "pics/logo.png")

            // This prints 'true' as Qt.resovledUrl() converts the string into a
            // URL with the correctly resolved path
            console.log(source == Qt.resolvedUrl("pics/logo.png"))

            // This prints the absolute path, e.g. "file:///path/to/pics/logo.png"
            console.log(source.toString())
        }
    }
    \endqml

    \note When referring to files stored with the \l{resources.html}{Qt Resource System}
    from within QML, you should use "qrc:///" instead of ":/" as QML requires URL paths.
    Relative URLs resolved from within that file will use the same protocol.

    Additionally, URLs may contain encoded characters using the 'percent-encoding' scheme
    specified by \l {http://tools.ietf.org/html/rfc3986}{RFC 3986}.  These characters
    will be preserved within properties of type \c url, to allow QML code to
    construct precise URL values. An exception to this rule is the preemptive
    decoding of directory-separator characters (\c '/') - these characters are decoded
    to allow the URL to be correctly classified.

    For example, a local file containing a '#' character, which would normally be
    interpreted as the beginning of the URL 'fragment' element, can be accessed by
    encoding the characters of the file name:

    \qml
    Image { source: encodeURIComponent("/tmp/test#1.png") }
    \endqml

    This basic type is provided by the QML language.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype color
    \ingroup qmlbasictypes
    \brief an ARGB color value.
    \target qmlbasictypecolor

    The \c color type refers to an ARGB color value. It can be specified in a number of ways:

    \list
    \li By a \l{http://www.w3.org/TR/SVG/types.html#ColorKeywords}{SVG color name}, such as
        "red", "green" or "lightsteelblue".
    \li By a hexadecimal triplet or quad in the form \c "#RRGGBB" and \c "#AARRGGBB"
        respectively. For example, the color red corresponds to a triplet of \c "#FF0000"
        and a slightly transparent blue to a quad of \c "#800000FF".
    \li Using the \l{QML:Qt::rgba()}{Qt.rgba()}, \l{QML:Qt::hsla()}{Qt.hsla()},
        \l{QML:Qt::darker()}{Qt.darker()}, \l{QML:Qt::lighter()}{Qt.lighter()} or
        \l{QML:Qt::tint()}{Qt.tint()} functions.
    \endlist

    Example:

    \div{float-right}
    \inlineimage declarative-colors.png
    \enddiv
    \snippet qml/colors.qml colors

    Additionally, a color type has \c r, \c g, \c b and \c a properties that refer to the
    red, green, blue and alpha values of the color, respectively:

    \qml
    Text {
        color: "red"

        // prints "1 0 0 1"
        Component.onCompleted: console.log(color.r, color.g, color.b, color.a)
    }
    \endqml

    To test color values for equality, use the \l{QML:Qt::colorEqual()}{Qt.colorEqual()}
    function.  This allows colors to be accurately compared whether they are in property
    form or in any of the acceptable string specification forms.

    When integrating with C++, note that any QColor value
    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
    converted into a \c color value, and vice-versa.

    This basic type is provided by the QtQuick import.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype point
    \ingroup qmlbasictypes
    \brief a value with x and y attributes.

    The \c point type refers to a value with \c x and \c y attributes.

    To create a \c point value, specify it as a "x,y" string:

    \qml
    CustomObject { myPointProperty: "0,20" }
    \endqml

    Or use the \l{QML:Qt::point()}{Qt.point()} function:

    \qml
    CustomObject { myPointProperty: Qt.point(0, 20) }
    \endqml

    When integrating with C++, note that any QPoint or QPointF value
    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
    converted into a \c point value. When a \c point value is passed to C++, it
    is automatically converted into a QPointF value.

    This basic type is provided by the QML language.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype size
    \ingroup qmlbasictypes
    \brief a value with width and height attributes

    The \c size type refers to a value with has \c width and \c height attributes.

    For example, to read the \c width and \c height values of the
    \l {Image::sourceSize} size-type property:

    \qml
    Column {
        Image { id: image; source: "logo.png" }
        Text { text: image.sourceSize.width + "," + image.sourceSize.height }
    }
    \endqml

    To create a \c size value, specify it as a "width x height" string:

    \qml
    Image { sourceSize: "150x50" }
    \endqml

    Or use the \l{QML:Qt::size()}{Qt.size()} function:

    \qml
    Image { sourceSize: Qt.size(150, 50) }
    \endqml

    When integrating with C++, note that any QSize or QSizeF value
    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
    converted into a \c size value, and vice-versa. When a \c size value is passed to C++, it
    is automatically converted into a QSizeF value.

    This basic type is provided by the QML language.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype rect
    \ingroup qmlbasictypes
    \brief a value with x, y, width and height attributes.

    The \c rect type refers to a value with \c x, \c y, \c width and \c height attributes.

    For example, to read the \c width and \c height values of the \l Item
    \l {Item::}{childrenRect} rect-type type property:

    \qml
    Rectangle {
        width: childrenRect.width
        height: childrenRect.height

        Rectangle { width: 100; height: 100 }
    }
    \endqml

    To create a \c rect value, specify it as a "x, y, width x height" string:

    \qml
    CustomObject { myRectProperty: "50,50,100x100" }
    \endqml

    Or use the \l{QML:Qt::rect()}{Qt.rect()} function:

    \qml
    CustomObject { myRectProperty: Qt.rect(50, 50, 100, 100) }
    \endqml

    When integrating with C++, note that any QRect or QRectF value
    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
    converted into a \c rect value, and vice-versa. When a \c rect value is passed to C++, it
    is automatically converted into a QRectF value.

    This basic type is provided by the QML language.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype date
    \ingroup qmlbasictypes
    \brief a date value.

    The \c date type refers to a date value.

    To create a \c date value, specify it as a "YYYY-MM-DD" string:

    \qml
    MyDatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" }
    \endqml

    To read a date value returned from a C++ extension class, use
    \l{QML:Qt::formatDate()}{Qt.formatDate()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.

    When integrating with C++, note that any QDate value
    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
    converted into a \c date value, and vice-versa.

    Note that the date type has comparison semantics which match
    those of the JavaScript Date object.  To compare the value
    of two date properties, you should compare their "toString()"
    values.

    This basic type is provided by the QML language.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype time
    \ingroup qmlbasictypes
    \brief a time value.

    The \c time type refers to a time value.

    To create a \c time value, specified as "hh:mm:ss":

    \qml
    MyTimePicker { time: "14:22:15" }
    \endqml

    To read a time value returned from a C++ extension class, use
    \l{QML:Qt::formatTime()}{Qt.formatTime()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.

    Note that when converting historical times to and from javascript that QDateTime and the JS Date object
    have different methods of calculating historical daylight savings time application. This can lead to variations of one hour
    when converting to historical local time.

    When integrating with C++, note that any QTime value
    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
    converted into a \c time value, and vice-versa.

    This basic type is provided by the QML language.

    \sa {QML Basic Types}
 */

/*!
    \qmlbasictype font
    \ingroup qmlbasictypes
    \brief a font value with the properties of QFont.
    \target fontbasictypedocs

    The \c font type refers to a font value with the properties of QFont.

    The most commonly used properties are:

    \list
    \li \l string \c font.family
    \li \l bool \c font.bold
    \li \l bool \c font.italic
    \li \l bool \c font.underline
    \li \l real \c font.pointSize
    \li \l int \c font.pixelSize
    \endlist

    If both \c pointSize and a \c pixelSize are specified, \c pixelSize will be used.

    The following properties are also available:

    \list
    \li \l enumeration \c font.weight
    \li \l bool \c font.overline
    \li \l bool \c font.sstrikeout
    \li \l enumeration \c font.capitalization
    \li \l real \c font.letterSpacing
    \li \l real \c font.wordSpacing
    \endlist

    Example:
    \qml
    Text { font.family: "Helvetica"; font.pointSize: 13; font.bold: true }
    \endqml

    When integrating with C++, note that any QFont value
    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
    converted into a \c font value, and vice-versa.

    This basic type is provided by the QtQuick import.

    Font weighting is classified on a scale from 0 to 99, where a weight of 0 is ultralight,
    and 99 is extremely black. The following values are supported:

    \table
    \row
        \li \c Font.Light
        \li 25
    \row
        \li \c Font.Normal
        \li 50
    \row
        \li \c Font.DemiBold
        \li 63
    \row
        \li \c Font.Bold
        \li 75
    \row
        \li \c Font.Black
        \li 87
    \endtable

    Capitalization supports the following values:

    \table
    \row
        \li \c Font.MixedCase
        \li No capitalization change is applied.
    \row
        \li \c Font.AllUppercase
        \li Alters the text to be rendered in all uppercase type.
    \row
        \li \c Font.AllLowercase
        \li Alters the text to be rendered in all lowercase type.
    \row
        \li \c Font.SmallCaps
        \li Alters the text to be rendered in small-caps type.
    \row
        \li \c Font.Capitalize
        \li Alters the text to be rendered with the first character of each word as an uppercase character.
    \endtable

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype list
    \ingroup qmlbasictypes
    \brief a list of QML objects.

    The \c list type refers to a list of QML objects.

    A list value can be accessed in a similar way to a JavaScript array:

    \list
    \li Values are assigned using the \c[] square bracket syntax with comma-separated values
    \li The \c length property provides the number of items in the list
    \li Values in the list are accessed using the \c [index] syntax
    \endlist

    A \c list can only store QML objects, and cannot contain any
    \l {QML Basic Types}{basic type} values. (To store basic types within a
    list, use the \l var type instead.)

    When integrating with C++, note that any QQmlListProperty value
    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
    converted into a \c list value, and vice-versa.


    \section1 Using the list type

    For example, the \l Item type has a \l {Item::}{states} list-type property that
    can be assigned to and used as follows:

    \qml
    import QtQuick 2.0

    Item {
        width: 100; height: 100

        states: [
            State { name: "activated" },
            State { name: "deactivated" }
        ]

        Component.onCompleted: {
            console.log("Name of first state:", states[0].name)
            for (var i=0; i<states.length; i++)
                console.log("state", i, states[i].name)
        }
    }
    \endqml

    The defined \l State objects will be added to the \c states list
    in the order in which they are defined.

    If the list only contains one object, the square brackets may be omitted:

    \qml
    import QtQuick 2.0

    Item {
        width: 100; height: 100
        states: State { name: "activated" }
    }
    \endqml

    Note that objects cannot be individually added to or removed from
    the list once created; to modify the contents of a list, it must be
    reassigned to a new list.

    \note The \c list type is not recommended as a type for custom properties.
    The \c var type should be used instead for this purpose as
    lists stored by the \c var type can be manipulated with greater
    flexibility from within QML.

    This basic type is provided by the QML language.

    \sa {QML Basic Types}
*/

 /*!
    \qmlbasictype var
    \ingroup qmlbasictypes
    \brief a generic property type.

    The \c var type is a generic property type that can refer to any data type.

    It is equivalent to a regular JavaScript variable.
    For example, var properties can store numbers, strings, objects,
    arrays and functions:

    \qml
    Item {
        property var aNumber: 100
        property var aBool: false
        property var aString: "Hello world!"
        property var anotherString: String("#FF008800")
        property var aColor: Qt.rgba(0.2, 0.3, 0.4, 0.5)
        property var aRect: Qt.rect(10, 10, 10, 10)
        property var aPoint: Qt.point(10, 10)
        property var aSize: Qt.size(10, 10)
        property var aVector3d: Qt.vector3d(100, 100, 100)
        property var anArray: [1, 2, 3, "four", "five", (function() { return "six"; })]
        property var anObject: { "foo": 10, "bar": 20 }
        property var aFunction: (function() { return "one"; })
    }
    \endqml

    \section1 Change Notification Semantics

    It is important to note that changes in regular properties of JavaScript
    objects assigned to a var property will \b{not} trigger updates of bindings
    that access them.  The example below will display "The car has 4 wheels" as
    the change to the wheels property will not cause the reevaluation of the
    binding assigned to the "text" property:

    \qml
    Item {
        property var car: new Object({wheels: 4})

        Text {
            text: "The car has " + car.wheels + " wheels";
        }

        Component.onCompleted: {
            car.wheels = 6;
        }
    }
    \endqml

    If the onCompleted handler instead had \tt{"car = new Object({wheels: 6})"}
    then the text would be updated to say "The car has 6 wheels", since the
    car property itself would be changed, which causes a change notification
    to be emitted.

    \section1 Property Value Initialization Semantics

    The QML syntax defines that curly braces on the right-hand-side of a
    property value initialization assignment denote a binding assignment.
    This can be confusing when initializing a \c var property, as empty curly
    braces in JavaScript can denote either an expression block or an empty
    object declaration.  If you wish to initialize a \c var property to an
    empty object value, you should wrap the curly braces in parentheses.

    For example:
    \qml
    Item {
        property var first:  {}   // nothing = undefined
        property var second: {{}} // empty expression block = undefined
        property var third:  ({}) // empty object
    }
    \endqml

    In the previous example, the \c first property is bound to an empty
    expression, whose result is undefined.  The \c second property is bound to
    an expression which contains a single, empty expression block ("{}"), which
    similarly has an undefined result.  The \c third property is bound to an
    expression which is evaluated as an empty object declaration, and thus the
    property will be initialized with that empty object value.

    Similarly, a colon in JavaScript can be either an object property value
    assignment, or a code label.  Thus, initializing a var property with an
    object declaration can also require parentheses:

    \qml
    Item {
        property var first: { example: 'true' }    // example is interpreted as a label
        property var second: ({ example: 'true' }) // example is interpreted as a property
        property var third: { 'example': 'true' }  // example is interpreted as a property
        Component.onCompleted: {
            console.log(first.example) // prints 'undefined', as "first" was assigned a string
            console.log(second.example) // prints 'true'
            console.log(third.example) // prints 'true'
        }
    }
    \endqml

    \section1 Using Scarce Resources with the var Type

    A \c var type property can also hold an image or pixmap.
    A \c var which contains a QPixmap or QImage is known as a
    "scarce resource" and the declarative engine will attempt to
    automatically release such resources after evaluation of any JavaScript
    expression which requires one to be copied has completed.

    Clients may explicitly release such a scarce resource by calling the
    "destroy" method on the \c var property from within JavaScript.  They
    may also explicitly preserve the scarce resource by calling the
    "preserve" method on the \c var property from within JavaScript.
    For more information regarding the usage of a scarce resource, please
    see \l{Scarce Resources in JavaScript}.

    This basic type is provided by the QML language.

    \sa {QML Basic Types}
*/


/*!
    \obsolete
    \qmlbasictype variant
    \ingroup qmlbasictypes
    \brief a generic property type.

    The \c variant type is a generic property type. It is obsolete and exists only to
    support old applications; new applications should use \l var type
    properties instead.

    A variant type property can hold any of the \l {QML Basic Types}{basic type}
    values:

    \qml
    Item {
        property variant aNumber: 100
        property variant aString: "Hello world!"
        property variant aBool: false
    }
    \endqml

    When integrating with C++, note that any QVariant value
    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
    converted into a \c variant value, and vice-versa.


    \section1 Using Scarce Resources with the variant Type

    A \c variant type property can also hold an image or pixmap.
    A \c variant which contains a QPixmap or QImage is known as a
    "scarce resource" and the declarative engine will attempt to
    automatically release such resources after evaluation of any JavaScript
    expression which requires one to be copied has completed.

    Clients may explicitly release such a scarce resource by calling the
    "destroy" method on the \c variant property from within JavaScript.  They
    may also explicitly preserve the scarce resource by calling the
    "preserve" method on the \c variant property from within JavaScript.
    For more information regarding the usage of a scarce resource, please
    see \l{Scarce Resources in JavaScript}.

    \section1 Storing Arrays and Objects

    The \c variant type can also hold:

    \list
    \li An array of \l {QML Basic Types}{basic type} values
    \li A map of key-value pairs with \l {QML Basic Types}{basic-type} values
    \endlist

    For example, below is an \c items array and an \c attributes map. Their
    contents can be examined using JavaScript \c for loops. Individual array
    values are accessible by index, and individual map values are accessible
    by key:

    \qml
    Item {
        property variant items: [1, 2, 3, "four", "five"]
        property variant attributes: { 'color': 'red', 'width': 100 }

        Component.onCompleted: {
            for (var i=0; i<items.length; i++)
                console.log(items[i])

            for (var prop in attributes)
                console.log(prop, "=", attributes[prop])
        }
    }
    \endqml

    While this is a convenient way to store array and map-type values, you
    must be aware that the \c items and \c attributes properties above are \e not
    QML objects (and certainly not JavaScript object either) and the key-value
    pairs in \c attributes are \e not QML properties. Rather, the \c items
    property holds an array of values, and \c attributes holds a set of key-value
    pairs. Since they are stored as a set of values, instead of as an object,
    their contents \e cannot be modified individually:

    \qml
    Item {
        property variant items: [1, 2, 3, "four", "five"]
        property variant attributes: { 'color': 'red', 'width': 100 }

        Component.onCompleted: {
            items[0] = 10
            console.log(items[0])     // This will still be '1'!
            attributes.color = 'blue'
            console.log(attributes.color)     // This will still be 'red'!
        }
    }
    \endqml

    Since it is not possible to individually add or remove items from a list or
    object stored in a \c variant, the only way to modify its contents is to
    reassign a new value. However, this is not efficent, as it causes the value
    to be serialized and deserialized.

    Additionally, since \c items and \c attributes are not QML objects, changing
    their individual values do not trigger property change notifications. If
    the above example had \c onNumberChanged or \c onAnimalChanged signal
    handlers, they would not have been called.  If, however, the \c items or
    \c attributes properties themselves were reassigned to different values, then
    such handlers would be called.

    JavaScript programmers should also note that when a JavaScript object is
    copied to an array or map property, the \e contents of the object (that is,
    its key-value properties) are copied, rather than the object itself. The
    property does not hold a reference to the original JavaScript object, and
    extra data such as the object's JavaScript prototype chain is also lost in
    the process.

    This basic type is provided by the QML language.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype vector2d
    \ingroup qmlbasictypes

    \brief A vector2d type has x and y attributes.

    A \c vector2d type has \c x and \c y attributes, otherwise
    it is similar to the \c vector3d type.  Please see the
    documentation about the \c vector3d type for more information.

    To create a \c vector2d value, specify it as a "x,y" string,
    or define the components individually, or compose it with
    the Qt.vector2d() function.

    This basic type is provided by the QtQuick import.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype vector3d
    \ingroup qmlbasictypes
    \brief a value with x, y, and z attributes.

    The \c vector3d type refers to a value with \c x, \c y, and \c z attributes.

    To create a \c vector3d value, specify it as a "x,y,z" string:

    \qml
    Rotation { angle: 60; axis: "0,1,0" }
    \endqml

    or with the \l{QML:Qt::vector3d()}{Qt.vector3d()} function:

    \qml
    Rotation { angle: 60; axis: Qt.vector3d(0, 1, 0) }
    \endqml

    or as separate \c x, \c y, and \c z components:

    \qml
    Rotation { angle: 60; axis.x: 0; axis.y: 1; axis.z: 0 }
    \endqml

    When integrating with C++, note that any QVector3D value
    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
    converted into a \c vector3d value, and vice-versa.

    This basic type is provided by the QtQuick import.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype vector4d
    \ingroup qmlbasictypes

    \brief A vector4d type has x, y, z and w attributes.

    A \c vector4d type has \c x, \c y, \c z and \c w attributes,
    otherwise it is similar to the \c vector3d type.  Please see the
    documentation about the \c vector3d type for more information.

    To create a \c vector4d value, specify it as a "x,y,z,w" string,
    or define the components individually, or compose it with
    the Qt.vector4d() function.

    This basic type is provided by the QtQuick import.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype quaternion
    \ingroup qmlbasictypes

    \brief A quaternion type has scalar, x, y, and z attributes.

    A \c quaternion type has \c scalar, \c x, \c y and \c z attributes,
    otherwise it is similar to the \c vector3d type.  Please see the
    documentation about the \c vector3d type for more information.

    To create a \c quaternion value, specify it as a "scalar,x,y,z" string,
    or define the components individually, or compose it with
    the Qt.quaternion() function.

    This basic type is provided by the QtQuick import.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype matrix4x4
    \ingroup qmlbasictypes

    \brief A matrix4x4 type is a 4-row and 4-column matrix

    A \c matrix4x4 type has sixteen values, but these values are
    largely opaque to QML.  Values of this type can be composed with
    the Qt.matrix4x4() function.

    This basic type is provided by the QtQuick import.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype enumeration
    \ingroup qmlbasictypes
    \brief a set of named values.

    The \c enumeration type refers to a set of named values.

    Each named value can be referred to as \c {<Type>.<value>}. For
    example, the \l Text type has an \c AlignRight enumeration value:

    \qml
    Text { horizontalAlignment: Text.AlignRight }
    \endqml

    (For backwards compatibility, the enumeration value may also be
    specified as a string, e.g. "AlignRight". This form is not
    recommended for new code.)

    When integrating with C++, note that any enumeration value
    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
    converted into an \c enumeration value, and vice-versa.

    This basic type is provided by the QML language.  Some enumeration values
    are provided by the QtQuick import.

    \sa {QML Basic Types}
*/