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 ** No Commercial Usage
11 ** This file contains pre-release code and may not be distributed.
12 ** You may use this file in accordance with the terms and conditions
13 ** contained in the Technology Preview License Agreement accompanying
16 ** GNU Free Documentation License
17 ** Alternatively, this file may be used under the terms of the GNU Free
18 ** Documentation License version 1.3 as published by the Free Software
19 ** Foundation and appearing in the file included in the packaging of this
22 ** If you have questions regarding the use of this file, please contact
23 ** Nokia at qt-info@nokia.com.
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 The \c variant type can also hold:
445 \o An array of \l {QML Basic Types}{basic type} values
446 \o A map of key-value pairs with \l {QML Basic Types}{basic-type} values
449 For example, below is an \c items array and an \c attributes map. Their
450 contents can be examined using JavaScript \c for loops. Individual array
451 values are accessible by index, and individual map values are accessible
456 property variant items: [1, 2, 3, "four", "five"]
457 property variant attributes: { 'color': 'red', 'width': 100 }
459 Component.onCompleted: {
460 for (var i=0; i<items.length; i++)
461 console.log(items[i])
463 for (var prop in attributes)
464 console.log(prop, "=", attributes[prop])
469 While this is a convenient way to store array and map-type values, you
470 must be aware that the \c items and \c attributes properties above are \e not
471 QML objects (and certainly not JavaScript object either) and the key-value
472 pairs in \c attributes are \e not QML properties. Rather, the \c items
473 property holds an array of values, and \c attributes holds a set of key-value
474 pairs. Since they are stored as a set of values, instead of as an object,
475 their contents \e cannot be modified individually:
479 property variant items: [1, 2, 3, "four", "five"]
480 property variant attributes: { 'color': 'red', 'width': 100 }
482 Component.onCompleted: {
484 console.log(items[0]) // This will still be '1'!
485 attributes.color = 'blue'
486 console.log(attributes.color) // This will still be 'red'!
491 Additionally, since \c items and \c attributes are not QML objects, changing
492 their individual values do not trigger property change notifications. If
493 the above example had \c onNumberChanged or \c onAnimalChanged signal
494 handlers, they would not have been called. If, however, the \c items or
495 \c attributes properties themselves were reassigned to different values, then
496 such handlers would be called.
498 One way to "update" the contents of an array or map is to copy the property
499 to a JavaScript object, modify the copy as desired, and then reassign the
500 property to the updated copy. Note, however, that this is not efficient.
501 In the example below, which reassigns the \c attributes property, the \e entire
502 set of key-value pairs must be serialized and deserialized every time it is
503 copied between a JavaScript object and a QML property:
507 property variant attributes: { 'color': 'red', 'width': 100 }
509 Component.onCompleted: {
510 // Change the value of attributes.color to 'blue':
511 var temp = attributes // copy all values to 'temp'
513 attributes = temp // copy all values back to 'attributes'
518 Since this operation is inefficient, if a list or map should be modifiable,
519 it is better to use alternative approaches. For example, you could implement
520 a custom C++ list element, or write to a JavaScript object defined from
521 within a JavaScript file.
523 JavaScript programmers should also note that when a JavaScript object is
524 copied to an array or map property, the \e contents of the object (that is,
525 its key-value properties) are copied, rather than the object itself. The
526 property does not hold a reference to the original JavaScript object, and
527 extra data such as the object's JavaScript prototype chain is also lost in
530 \sa {QML Basic Types}
534 \qmlbasictype vector3d
535 \ingroup qmlbasictypes
537 \brief A vector3d type has x, y, and z attributes.
539 A \c vector3d type has \c x, \c y, and \c z attributes.
541 To create a \c vector3d value, specify it as a "x,y,z" string:
544 Rotation { angle: 60; axis: "0,1,0" }
547 or with the \l{QML:Qt::vector3d()}{Qt.vector3d()} function:
550 Rotation { angle: 60; axis: Qt.vector3d(0, 1, 0) }
553 or as separate \c x, \c y, and \c z components:
556 Rotation { angle: 60; axis.x: 0; axis.y: 1; axis.z: 0 }
559 \sa {QML Basic Types}
563 \qmlbasictype enumeration
564 \ingroup qmlbasictypes
566 \brief An enumeration type consists of a set of named values.
568 An enumeration type consists of a set of named values.
570 An enumeration value may be specified as either a string:
572 Text { horizontalAlignment: "AlignRight" }
575 or as \c {<Element>.<value>}:
577 Text { horizontalAlignment: Text.AlignRight }
580 The second form is preferred.
582 \sa {QML Basic Types}