1 /****************************************************************************
3 ** Copyright (C) 2011 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
31 \contentspage QML Features
32 \previouspage {QML Basic Elements}
33 \nextpage Property Binding
34 \title QML Basic Types
36 QML has a set of primitive types, as listed below, that are used throughout
37 the \l {QML Elements}.
39 \annotatedlist qmlbasictypes
41 To create additional types, such as data types created in C++, read the
42 \l{Extending QML Functionalities using C++} article.
47 \ingroup qmlbasictypes
49 \brief An integer is a whole number, e.g. 0, 10, or -20.
51 An integer is a whole number, e.g. 0, 10, or -20. The possible \c
52 int values range from around -2000000000 to around 2000000000,
53 although most elements will only accept a reduced range (which they
54 mention in their documentation).
58 Item { width: 100; height: 200 }
66 \ingroup qmlbasictypes
68 \brief A boolean is a binary true/false value.
70 A boolean is a binary true/false value.
74 Item { focus: true; clip: false }
82 \ingroup qmlbasictypes
84 \brief A real number has a decimal point, e.g. 1.2 or -29.8.
86 A real number has a decimal point, e.g. 1.2 or -29.8.
90 Item { width: 100.45; height: 150.82 }
93 \note In QML all reals are stored in single precision, \l
94 {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point}
102 \ingroup qmlbasictypes
104 \brief A double number has a decimal point and is stored in double precision.
106 A double number has a decimal point and is stored in double precision, \l
107 {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point}
113 property double number: 32155.2355
117 \sa {QML Basic Types}
122 \ingroup qmlbasictypes
124 \brief A string is a free form text in quotes, e.g. "Hello world!".
126 A string is a free form text in quotes, e.g. "Hello world!".
130 Text { text: "Hello world!" }
133 Strings have a \c length attribute that holds the number of
134 characters in the string.
136 \sa {QML Basic Types}
141 \ingroup qmlbasictypes
143 \brief A URL is a resource locator, like a file name.
145 A URL is a resource locator, like a file name. It can be either
146 absolute, e.g. "http://qt.nokia.com", or relative, e.g.
147 "pics/logo.png". A relative URL is resolved relative to the URL of
148 the component where the URL is converted from a JavaScript string
149 expression to a url property value.
153 Image { source: "pics/logo.png" }
156 \sa {QML Basic Types}
161 \ingroup qmlbasictypes
163 \brief A color is a standard color name in quotes.
165 A color is a standard color name in quotes. It is normally specified
166 as an \l {http://www.w3.org/TR/SVG/types.html#ColorKeywords} {SVG
167 color name}. These names include colors like "red", "green" and
170 If the color you want isn't part of this list, colors can also be
171 specified in hexidecimal triplets or quads that take the form \c
172 "#RRGGBB" and \c "#AARRGGBB" respectively. For example, the color
173 red corresponds to a triplet of \c "#FF0000" and a slightly
174 transparent blue to a quad of \c "#800000FF".
178 \inlineimage declarative-colors.png
180 \snippet doc/src/snippets/declarative/colors.qml colors
182 Or with the \l{QML:Qt::rgba()}{Qt.rgba()}, \l{QML:Qt::hsla()}{Qt.hsla()}, \l{QML:Qt::darker()}{Qt.darker()},
183 \l{QML:Qt::lighter()}{Qt.lighter()} or \l{QML:Qt::tint()}{Qt.tint()} functions:
186 Rectangle { color: Qt.rgba(0.5, 0.5, 0, 1) }
189 \sa {QML Basic Types}
194 \ingroup qmlbasictypes
196 \brief A point type has x and y attributes.
198 A \c point type has \c x and \c y attributes.
200 To create a \c point value, specify it as a "x,y" string:
203 CustomObject { myPointProperty: "0,20" }
206 Or use the \l{QML:Qt::point()}{Qt.point()} function:
209 CustomObject { myPointProperty: Qt.point(0, 20) }
212 \sa {QML Basic Types}
217 \ingroup qmlbasictypes
219 \brief A size type has width and height attributes
221 A \c size type has \c width and \c height attributes.
223 For example, to read the \l {Image::sourceSize} \c size property:
227 Image { id: image; source: "logo.png" }
228 Text { text: image.sourceSize.width + "," + image.sourceSize.height }
232 To create a \c size value, specify it as a "width x height" string:
235 LayoutItem { preferredSize: "150x50" }
238 Or use the \l{QML:Qt::size()}{Qt.size()} function:
241 LayoutItem { preferredSize: Qt.size(150, 50) }
244 \sa {QML Basic Types}
249 \ingroup qmlbasictypes
251 \brief A rect type has x, y, width and height attributes.
253 A \c rect type has \c x, \c y, \c width and \c height attributes.
255 For example, to read the \l {Item::childrenRect.x}{Item::childrenRect} \c rect property:
258 width: childrenRect.width
259 height: childrenRect.height
261 Rectangle { width: 100; height: 100 }
265 To create a \c rect value, specify it as a "x, y, width x height" string:
268 CustomObject { myRectProperty: "50,50,100x100" }
271 Or use the \l{QML:Qt::rect()}{Qt.rect()} function:
274 CustomObject { myRectProperty: Qt.rect(50, 50, 100, 100) }
277 \sa {QML Basic Types}
282 \ingroup qmlbasictypes
284 \brief A date is specified as "YYYY-MM-DD".
286 To create a \c date value, specify it as a "YYYY-MM-DD" string:
290 MyDatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" }
293 To read a date value returned from a C++ extension class, use
294 \l{QML:Qt::formatDate()}{Qt.formatDate()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.
296 \sa {QML Basic Types}
301 \ingroup qmlbasictypes
303 \brief A time is specified as "hh:mm:ss".
305 A time is specified as "hh:mm:ss".
309 MyTimePicker { time: "14:22:15" }
312 To read a time value returned from a C++ extension class, use
313 \l{QML:Qt::formatTime()}{Qt.formatTime()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.
315 \sa {QML Basic Types}
320 \ingroup qmlbasictypes
322 \brief A font type has the properties of a QFont.
324 A font type has the properties of a QFont. The properties are:
327 \o \c string font.family
329 \o \c bool font.italic
330 \o \c bool font.underline
331 \o \c real font.pointSize
332 \o \c int font.pixelSize
337 Text { font.family: "Helvetica"; font.pointSize: 13; font.bold: true }
340 \sa {QML Basic Types}
345 \ingroup qmlbasictypes
347 \brief The action type has all the properties of QAction.
349 The action type has all the properties of QAction. The properties
353 \o \c slot action.trigger - invoke the action
354 \o \c bool action.enabled - true if the action is enabled
355 \o \c string action.text - the text associated with the action
358 Actions are used like this:
362 MouseArea { onClicked: myaction.trigger() }
363 State { name: "enabled"; when: myaction.enabled == true }
364 Text { text: someaction.text }
368 \sa {QML Basic Types}
373 \ingroup qmlbasictypes
375 \brief A list of objects.
377 A list type contains a list of objects. While not technically
378 a basic type, QML supports lists of object types. When used
379 from QML, the engine automatically appends each value to the list.
380 Items in the list can be accessed by index using the usual
381 \c listName[index] syntax.
383 For example, the \l Item class contains a list property named
384 children that can be used like this:
390 Rectangle { id: child2; width: 200 },
394 Component.onCompleted: {
395 console.log("Width of child rectangle:", children[1].width)
399 \c child1, \c child2 and \c child3 will be added to the children list
400 in the order in which they appear.
402 List \l {Property Binding}{properties} can be created as a
403 \c variant type, or as a \c list<Type> type, where \c Type is the
404 type of the object in the list:
408 property list<Rectangle> rects: [
409 Rectangle { width: 100; height: 100},
410 Rectangle { width: 200; height: 200}
415 A list property can only contain values that match (or are derived from) the
418 While the \c rects property can be reassigned to a different list value (including
419 an empty list), its individual values cannot be modified. See the \l variant type
420 documentation for details.
422 \sa {QML Basic Types}
426 \qmlbasictype variant
427 \ingroup qmlbasictypes
429 \brief A variant type is a generic property type.
431 A variant is a generic property type. A variant type property can hold
432 any of the \l {QML Basic Types}{basic type} values:
436 property variant aNumber: 100
437 property variant aString: "Hello world!"
438 property variant aBool: false
442 A \c variant type property can also hold an image or pixmap.
443 A \c variant which contains a QPixmap or QImage is known as a
444 "scarce resource" and the declarative engine will attempt to
445 automatically release such resources after evaluation of any JavaScript
446 expression which requires one to be copied has completed.
448 Clients may explicitly release such a scarce resource by calling the
449 "destroy" method on the \c variant property from within JavaScript. They
450 may also explicitly preserve the scarce resource by calling the
451 "preserve" method on the \c variant property from within JavaScript.
452 For more information regarding the usage of a scarce resource, please
453 see \l{Scarce Resources in JavaScript}.
455 Finally, the \c variant type can also hold:
458 \o An array of \l {QML Basic Types}{basic type} values
459 \o A map of key-value pairs with \l {QML Basic Types}{basic-type} values
462 For example, below is an \c items array and an \c attributes map. Their
463 contents can be examined using JavaScript \c for loops. Individual array
464 values are accessible by index, and individual map values are accessible
469 property variant items: [1, 2, 3, "four", "five"]
470 property variant attributes: { 'color': 'red', 'width': 100 }
472 Component.onCompleted: {
473 for (var i=0; i<items.length; i++)
474 console.log(items[i])
476 for (var prop in attributes)
477 console.log(prop, "=", attributes[prop])
482 While this is a convenient way to store array and map-type values, you
483 must be aware that the \c items and \c attributes properties above are \e not
484 QML objects (and certainly not JavaScript object either) and the key-value
485 pairs in \c attributes are \e not QML properties. Rather, the \c items
486 property holds an array of values, and \c attributes holds a set of key-value
487 pairs. Since they are stored as a set of values, instead of as an object,
488 their contents \e cannot be modified individually:
492 property variant items: [1, 2, 3, "four", "five"]
493 property variant attributes: { 'color': 'red', 'width': 100 }
495 Component.onCompleted: {
497 console.log(items[0]) // This will still be '1'!
498 attributes.color = 'blue'
499 console.log(attributes.color) // This will still be 'red'!
504 Additionally, since \c items and \c attributes are not QML objects, changing
505 their individual values do not trigger property change notifications. If
506 the above example had \c onNumberChanged or \c onAnimalChanged signal
507 handlers, they would not have been called. If, however, the \c items or
508 \c attributes properties themselves were reassigned to different values, then
509 such handlers would be called.
511 One way to "update" the contents of an array or map is to copy the property
512 to a JavaScript object, modify the copy as desired, and then reassign the
513 property to the updated copy. Note, however, that this is not efficient.
514 In the example below, which reassigns the \c attributes property, the \e entire
515 set of key-value pairs must be serialized and deserialized every time it is
516 copied between a JavaScript object and a QML property:
520 property variant attributes: { 'color': 'red', 'width': 100 }
522 Component.onCompleted: {
523 // Change the value of attributes.color to 'blue':
524 var temp = attributes // copy all values to 'temp'
526 attributes = temp // copy all values back to 'attributes'
531 Since this operation is inefficient, if a list or map should be modifiable,
532 it is better to use alternative approaches. For example, you could implement
533 a custom C++ list element, or write to a JavaScript object defined from
534 within a JavaScript file.
536 JavaScript programmers should also note that when a JavaScript object is
537 copied to an array or map property, the \e contents of the object (that is,
538 its key-value properties) are copied, rather than the object itself. The
539 property does not hold a reference to the original JavaScript object, and
540 extra data such as the object's JavaScript prototype chain is also lost in
543 \sa {QML Basic Types}
547 \qmlbasictype vector3d
548 \ingroup qmlbasictypes
550 \brief A vector3d type has x, y, and z attributes.
552 A \c vector3d type has \c x, \c y, and \c z attributes.
554 To create a \c vector3d value, specify it as a "x,y,z" string:
557 Rotation { angle: 60; axis: "0,1,0" }
560 or with the \l{QML:Qt::vector3d()}{Qt.vector3d()} function:
563 Rotation { angle: 60; axis: Qt.vector3d(0, 1, 0) }
566 or as separate \c x, \c y, and \c z components:
569 Rotation { angle: 60; axis.x: 0; axis.y: 1; axis.z: 0 }
572 \sa {QML Basic Types}
576 \qmlbasictype enumeration
577 \ingroup qmlbasictypes
579 \brief An enumeration type consists of a set of named values.
581 An enumeration type consists of a set of named values.
583 An enumeration value may be specified as either a string:
585 Text { horizontalAlignment: "AlignRight" }
588 or as \c {<Element>.<value>}:
590 Text { horizontalAlignment: Text.AlignRight }
593 The second form is preferred.
595 \sa {QML Basic Types}