1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:FDL$
10 ** GNU Free Documentation License
11 ** Alternatively, this file may be used under the terms of the GNU Free
12 ** Documentation License version 1.3 as published by the Free Software
13 ** Foundation and appearing in the file included in the packaging of
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \page qdeclarativebasictypes.html
30 \inqmlmodule QtQuick 2
32 \contentspage QML Features
33 \previouspage {QML Basic Elements}
34 \nextpage Property Binding
35 \title QML Basic Types
37 QML has a set of primitive types, as listed below, that are used throughout
38 the \l {QML Elements}.
40 \annotatedlist qmlbasictypes
42 To create additional types, such as data types created in C++, read the
43 \l{Extending QML Functionalities using C++} article.
48 \ingroup qmlbasictypes
50 \brief An integer is a whole number, e.g. 0, 10, or -20.
52 An integer is a whole number, e.g. 0, 10, or -20. The possible \c
53 int values range from around -2000000000 to around 2000000000,
54 although most elements will only accept a reduced range (which they
55 mention in their documentation).
59 Item { width: 100; height: 200 }
67 \ingroup qmlbasictypes
69 \brief A boolean is a binary true/false value.
71 A boolean is a binary true/false value.
75 Item { focus: true; clip: false }
83 \ingroup qmlbasictypes
85 \brief A real number has a decimal point, e.g. 1.2 or -29.8.
87 A real number has a decimal point, e.g. 1.2 or -29.8.
91 Item { width: 100.45; height: 150.82 }
94 \note In QML all reals are stored in single precision, \l
95 {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point}
103 \ingroup qmlbasictypes
105 \brief A double number has a decimal point and is stored in double precision.
107 A double number has a decimal point and is stored in double precision, \l
108 {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point}
114 property double number: 32155.2355
118 \sa {QML Basic Types}
123 \ingroup qmlbasictypes
125 \brief A string is a free form text in quotes, e.g. "Hello world!".
127 A string is a free form text in quotes, e.g. "Hello world!".
131 Text { text: "Hello world!" }
134 Strings have a \c length attribute that holds the number of
135 characters in the string.
137 \sa {QML Basic Types}
142 \ingroup qmlbasictypes
144 \brief A URL is a resource locator, like a file name.
146 A URL is a resource locator, like a file name. It can be either
147 absolute, e.g. "http://qt.nokia.com", or relative, e.g.
148 "pics/logo.png". A relative URL is resolved relative to the URL of
149 the component where the URL is converted from a JavaScript string
150 expression to a url property value.
154 Image { source: "pics/logo.png" }
157 \sa {QML Basic Types}
162 \ingroup qmlbasictypes
164 \brief A color is a standard color name in quotes.
166 A color is a standard color name in quotes. It is normally specified
167 as an \l {http://www.w3.org/TR/SVG/types.html#ColorKeywords} {SVG
168 color name}. These names include colors like "red", "green" and
171 If the color you want isn't part of this list, colors can also be
172 specified in hexidecimal triplets or quads that take the form \c
173 "#RRGGBB" and \c "#AARRGGBB" respectively. For example, the color
174 red corresponds to a triplet of \c "#FF0000" and a slightly
175 transparent blue to a quad of \c "#800000FF".
179 \inlineimage declarative-colors.png
181 \snippet doc/src/snippets/declarative/colors.qml colors
183 Or with the \l{QML:Qt::rgba()}{Qt.rgba()}, \l{QML:Qt::hsla()}{Qt.hsla()}, \l{QML:Qt::darker()}{Qt.darker()},
184 \l{QML:Qt::lighter()}{Qt.lighter()} or \l{QML:Qt::tint()}{Qt.tint()} functions:
187 Rectangle { color: Qt.rgba(0.5, 0.5, 0, 1) }
190 \sa {QML Basic Types}
195 \ingroup qmlbasictypes
197 \brief A point type has x and y attributes.
199 A \c point type has \c x and \c y attributes.
201 To create a \c point value, specify it as a "x,y" string:
204 CustomObject { myPointProperty: "0,20" }
207 Or use the \l{QML:Qt::point()}{Qt.point()} function:
210 CustomObject { myPointProperty: Qt.point(0, 20) }
213 \sa {QML Basic Types}
218 \ingroup qmlbasictypes
220 \brief A size type has width and height attributes
222 A \c size type has \c width and \c height attributes.
224 For example, to read the \l {Image::sourceSize} \c size property:
228 Image { id: image; source: "logo.png" }
229 Text { text: image.sourceSize.width + "," + image.sourceSize.height }
233 To create a \c size value, specify it as a "width x height" string:
236 LayoutItem { preferredSize: "150x50" }
239 Or use the \l{QML:Qt::size()}{Qt.size()} function:
242 LayoutItem { preferredSize: Qt.size(150, 50) }
245 \sa {QML Basic Types}
250 \ingroup qmlbasictypes
252 \brief A rect type has x, y, width and height attributes.
254 A \c rect type has \c x, \c y, \c width and \c height attributes.
256 For example, to read the \l {Item::childrenRect.x}{Item::childrenRect} \c rect property:
259 width: childrenRect.width
260 height: childrenRect.height
262 Rectangle { width: 100; height: 100 }
266 To create a \c rect value, specify it as a "x, y, width x height" string:
269 CustomObject { myRectProperty: "50,50,100x100" }
272 Or use the \l{QML:Qt::rect()}{Qt.rect()} function:
275 CustomObject { myRectProperty: Qt.rect(50, 50, 100, 100) }
278 \sa {QML Basic Types}
283 \ingroup qmlbasictypes
285 \brief A date is specified as "YYYY-MM-DD".
287 To create a \c date value, specify it as a "YYYY-MM-DD" string:
291 MyDatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" }
294 To read a date value returned from a C++ extension class, use
295 \l{QML:Qt::formatDate()}{Qt.formatDate()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.
297 \sa {QML Basic Types}
302 \ingroup qmlbasictypes
304 \brief A time is specified as "hh:mm:ss".
306 A time is specified as "hh:mm:ss".
310 MyTimePicker { time: "14:22:15" }
313 To read a time value returned from a C++ extension class, use
314 \l{QML:Qt::formatTime()}{Qt.formatTime()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.
316 Note that when converting historical times to and from javascript that QDateTime and the JS Date object
317 have different methods of calculating historical daylight savings time application. This can lead to variations of one hour
318 when converting to historical local time.
320 \sa {QML Basic Types}
325 \ingroup qmlbasictypes
327 \brief A font type has the properties of a QFont.
329 A font type has the properties of a QFont. The properties are:
332 \o \c string font.family
334 \o \c bool font.italic
335 \o \c bool font.underline
336 \o \c real font.pointSize
337 \o \c int font.pixelSize
342 Text { font.family: "Helvetica"; font.pointSize: 13; font.bold: true }
345 \sa {QML Basic Types}
350 \ingroup qmlbasictypes
352 \brief The action type has all the properties of QAction.
354 The action type has all the properties of QAction. The properties
358 \o \c slot action.trigger - invoke the action
359 \o \c bool action.enabled - true if the action is enabled
360 \o \c string action.text - the text associated with the action
363 Actions are used like this:
367 MouseArea { onClicked: myaction.trigger() }
368 State { name: "enabled"; when: myaction.enabled == true }
369 Text { text: someaction.text }
373 \sa {QML Basic Types}
378 \ingroup qmlbasictypes
380 \brief A list of objects.
382 A list type contains a list of objects. While not technically
383 a basic type, QML supports lists of object types. When used
384 from QML, the engine automatically appends each value to the list.
385 Items in the list can be accessed by index using the usual
386 \c listName[index] syntax.
388 For example, the \l Item class contains a list property named
389 children that can be used like this:
395 Rectangle { id: child2; width: 200 },
399 Component.onCompleted: {
400 console.log("Width of child rectangle:", children[1].width)
404 \c child1, \c child2 and \c child3 will be added to the children list
405 in the order in which they appear.
407 List \l {Property Binding}{properties} can be created as a
408 \c variant type, or as a \c list<Type> type, where \c Type is the
409 type of the object in the list:
413 property list<Rectangle> rects: [
414 Rectangle { width: 100; height: 100},
415 Rectangle { width: 200; height: 200}
420 A list property can only contain values that match (or are derived from) the
423 While the \c rects property can be reassigned to a different list value (including
424 an empty list), its individual values cannot be modified. See the \l variant type
425 documentation for details.
427 \sa {QML Basic Types}
432 \ingroup qmlbasictypes
434 \brief A var type is a generic property type.
436 A var is a generic property type capable of storing any data type.
437 It is equivalent to a regular JavaScript variable, except that you
438 cannot assign a JavaScript function to such a property.
439 For example, var properties can store numbers, strings, objects and
444 property var aNumber: 100
445 property var aBool: false
446 property var aString: "Hello world!"
447 property var anotherString: String("#FF008800")
448 property var aColor: Qt.rgba(0.2, 0.3, 0.4, 0.5)
449 property var aRect: Qt.rect(10, 10, 10, 10)
450 property var aPoint: Qt.point(10, 10)
451 property var aSize: Qt.size(10, 10)
452 property var aVector3d: Qt.vector3d(100, 100, 100)
453 property var anArray: [1, 2, 3, "four", "five", (function() { return "six"; })]
454 property var anObject: { "foo": 10, "bar": 20 }
458 Attempting to assign a JavaScript function to a var property will result in
459 a binding assignment as per other property types. You can assign a JavaScript
460 array containing a single function element instead.
462 It is important to note that changes in regular properties of JavaScript
463 objects assigned to a var property will \bold{not} trigger updates of bindings
464 that access them. The example below will display "The car has 4 wheels" as
465 the change to the wheels property will not cause the reevaluation of the
466 binding assigned to the "text" property:
470 property var car: new Object({wheels: 4})
473 text: "The car has " + car.wheels + " wheels";
476 Component.onCompleted: {
482 A \c var type property can also hold an image or pixmap.
483 A \c var which contains a QPixmap or QImage is known as a
484 "scarce resource" and the declarative engine will attempt to
485 automatically release such resources after evaluation of any JavaScript
486 expression which requires one to be copied has completed.
488 Clients may explicitly release such a scarce resource by calling the
489 "destroy" method on the \c var property from within JavaScript. They
490 may also explicitly preserve the scarce resource by calling the
491 "preserve" method on the \c var property from within JavaScript.
492 For more information regarding the usage of a scarce resource, please
493 see \l{Scarce Resources in JavaScript}.
495 \sa {QML Basic Types}
501 \qmlbasictype variant
502 \ingroup qmlbasictypes
504 \brief A variant type is a generic property type.
506 A variant is a generic property type. It is obsolete and exists only to
507 support old applications; new applications should use "var" type
510 A variant type property can hold any of the \l {QML Basic Types}{basic type}
515 property variant aNumber: 100
516 property variant aString: "Hello world!"
517 property variant aBool: false
521 A \c variant type property can also hold an image or pixmap.
522 A \c variant which contains a QPixmap or QImage is known as a
523 "scarce resource" and the declarative engine will attempt to
524 automatically release such resources after evaluation of any JavaScript
525 expression which requires one to be copied has completed.
527 Clients may explicitly release such a scarce resource by calling the
528 "destroy" method on the \c variant property from within JavaScript. They
529 may also explicitly preserve the scarce resource by calling the
530 "preserve" method on the \c variant property from within JavaScript.
531 For more information regarding the usage of a scarce resource, please
532 see \l{Scarce Resources in JavaScript}.
534 Finally, the \c variant type can also hold:
537 \o An array of \l {QML Basic Types}{basic type} values
538 \o A map of key-value pairs with \l {QML Basic Types}{basic-type} values
541 For example, below is an \c items array and an \c attributes map. Their
542 contents can be examined using JavaScript \c for loops. Individual array
543 values are accessible by index, and individual map values are accessible
548 property variant items: [1, 2, 3, "four", "five"]
549 property variant attributes: { 'color': 'red', 'width': 100 }
551 Component.onCompleted: {
552 for (var i=0; i<items.length; i++)
553 console.log(items[i])
555 for (var prop in attributes)
556 console.log(prop, "=", attributes[prop])
561 While this is a convenient way to store array and map-type values, you
562 must be aware that the \c items and \c attributes properties above are \i not
563 QML objects (and certainly not JavaScript object either) and the key-value
564 pairs in \c attributes are \i not QML properties. Rather, the \c items
565 property holds an array of values, and \c attributes holds a set of key-value
566 pairs. Since they are stored as a set of values, instead of as an object,
567 their contents \i cannot be modified individually:
571 property variant items: [1, 2, 3, "four", "five"]
572 property variant attributes: { 'color': 'red', 'width': 100 }
574 Component.onCompleted: {
576 console.log(items[0]) // This will still be '1'!
577 attributes.color = 'blue'
578 console.log(attributes.color) // This will still be 'red'!
583 Additionally, since \c items and \c attributes are not QML objects, changing
584 their individual values do not trigger property change notifications. If
585 the above example had \c onNumberChanged or \c onAnimalChanged signal
586 handlers, they would not have been called. If, however, the \c items or
587 \c attributes properties themselves were reassigned to different values, then
588 such handlers would be called.
590 One way to "update" the contents of an array or map is to copy the property
591 to a JavaScript object, modify the copy as desired, and then reassign the
592 property to the updated copy. Note, however, that this is not efficient.
593 In the example below, which reassigns the \c attributes property, the \i entire
594 set of key-value pairs must be serialized and deserialized every time it is
595 copied between a JavaScript object and a QML property:
599 property variant attributes: { 'color': 'red', 'width': 100 }
601 Component.onCompleted: {
602 // Change the value of attributes.color to 'blue':
603 var temp = attributes // copy all values to 'temp'
605 attributes = temp // copy all values back to 'attributes'
610 Since this operation is inefficient, if a list or map should be modifiable,
611 it is better to use alternative approaches. For example, you could implement
612 a custom C++ list element, or write to a JavaScript object defined from
613 within a JavaScript file.
615 JavaScript programmers should also note that when a JavaScript object is
616 copied to an array or map property, the \i contents of the object (that is,
617 its key-value properties) are copied, rather than the object itself. The
618 property does not hold a reference to the original JavaScript object, and
619 extra data such as the object's JavaScript prototype chain is also lost in
622 \sa {QML Basic Types}
626 \qmlbasictype vector3d
627 \ingroup qmlbasictypes
629 \brief A vector3d type has x, y, and z attributes.
631 A \c vector3d type has \c x, \c y, and \c z attributes.
633 To create a \c vector3d value, specify it as a "x,y,z" string:
636 Rotation { angle: 60; axis: "0,1,0" }
639 or with the \l{QML:Qt::vector3d()}{Qt.vector3d()} function:
642 Rotation { angle: 60; axis: Qt.vector3d(0, 1, 0) }
645 or as separate \c x, \c y, and \c z components:
648 Rotation { angle: 60; axis.x: 0; axis.y: 1; axis.z: 0 }
651 \sa {QML Basic Types}
655 \qmlbasictype enumeration
656 \ingroup qmlbasictypes
658 \brief An enumeration type consists of a set of named values.
660 An enumeration type consists of a set of named values.
662 An enumeration value may be specified as either a string:
664 Text { horizontalAlignment: "AlignRight" }
667 or as \c {<Element>.<value>}:
669 Text { horizontalAlignment: Text.AlignRight }
672 The second form is preferred.
674 \sa {QML Basic Types}