** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
-** No Commercial Usage
-** This file contains pre-release code and may not be distributed.
-** You may use this file in accordance with the terms and conditions
-** contained in the Technology Preview License Agreement accompanying
-** this package.
-**
** 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.
+** 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.
+**
+**
+**
**
-** If you have questions regarding the use of this file, please contact
-** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qdeclarativebasictypes.html
+\inqmlmodule QtQuick 2
\ingroup qml-features
\contentspage QML Features
\previouspage {QML Basic Elements}
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.
+
\sa {QML Basic Types}
*/
\sa {QML Basic Types}
*/
+ /*!
+ \qmlbasictype var
+ \ingroup qmlbasictypes
+
+ \brief A var type is a generic property type.
+
+ A var is a generic property type capable of storing any data type.
+ It is equivalent to a regular JavaScript variable, except that you
+ cannot assign a JavaScript function to such a property.
+ For example, var properties can store numbers, strings, objects and
+ arrays:
+
+ \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 }
+ }
+ \endqml
+
+ Attempting to assign a JavaScript function to a var property will result in
+ a binding assignment as per other property types. You can assign a JavaScript
+ array containing a single function element instead.
+
+ It is important to note that changes in regular properties of JavaScript
+ objects assigned to a var property will \bold{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
+
+ 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}.
+
+ \sa {QML Basic Types}
+*/
+
+
/*!
+ \obsolete
\qmlbasictype variant
\ingroup qmlbasictypes
\brief A variant type is a generic property type.
- A variant is a generic property type. A variant type property can hold
- any of the \l {QML Basic Types}{basic type} values:
+ A variant is a generic property type. It is obsolete and exists only to
+ support old applications; new applications should use "var" type
+ properties instead.
+
+ A variant type property can hold any of the \l {QML Basic Types}{basic type}
+ values:
\qml
Item {
\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
+ must be aware that the \c items and \c attributes properties above are \i 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
+ pairs in \c attributes are \i 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:
+ their contents \i cannot be modified individually:
\qml
Item {
One way to "update" the contents of an array or map is to copy the property
to a JavaScript object, modify the copy as desired, and then reassign the
property to the updated copy. Note, however, that this is not efficient.
- In the example below, which reassigns the \c attributes property, the \e entire
+ In the example below, which reassigns the \c attributes property, the \i entire
set of key-value pairs must be serialized and deserialized every time it is
copied between a JavaScript object and a QML property:
within a JavaScript file.
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,
+ copied to an array or map property, the \i 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