diff options
Diffstat (limited to 'doc/src/qml/basictypes.qdoc')
-rw-r--r-- | doc/src/qml/basictypes.qdoc | 677 |
1 files changed, 677 insertions, 0 deletions
diff --git a/doc/src/qml/basictypes.qdoc b/doc/src/qml/basictypes.qdoc new file mode 100644 index 0000000000..150383fdc2 --- /dev/null +++ b/doc/src/qml/basictypes.qdoc @@ -0,0 +1,677 @@ +/**************************************************************************** +** +** 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 qml-basictypes.html + \ingroup qml-features + \title QML Basic Types + \brief basic data types in QML + + QML has a set of primitive types, as listed below, that are used throughout + the \l {QML Elements}. + + \annotatedlist qmlbasictypes + + To create additional types, such as data types created in C++, read the + \l{Creating QML Types} article. +*/ + +/*! + \qmlbasictype int + \ingroup qmlbasictypes + + \brief An integer is a whole number, e.g. 0, 10, or -20. + + An integer is 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 + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype bool + \ingroup qmlbasictypes + + \brief A boolean is a binary true/false value. + + A boolean is a binary true/false value. + + Example: + \qml + Item { focus: true; clip: false } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype real + \ingroup qmlbasictypes + + \brief A real number has a decimal point, e.g. 1.2 or -29.8. + + A real number has a decimal point, e.g. 1.2 or -29.8. + + Example: + \qml + Item { width: 100.45; height: 150.82 } + \endqml + + \bold{Note:} In QML all reals are stored in single precision, \l + {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} + format. + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype double + \ingroup qmlbasictypes + + \brief A double number has a decimal point and is stored in double precision. + + A double number has 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 + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype string + \ingroup qmlbasictypes + + \brief A string is a free form text in quotes, e.g. "Hello world!". + + A string is a free form text 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. + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype url + \ingroup qmlbasictypes + + \brief A URL is a resource locator, like a file name. + + A URL is a resource locator, like a file name. 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 component where the URL is converted from a JavaScript string + expression to a url property value. + + Example: + \qml + Image { source: "pics/logo.png" } + \endqml + + Note that as QML requires URL paths, you should use "qrc:///" instead of ":/" for + referring to files stored with the \l{resources.html}{Qt Resource System}. + Usually you will only have to do this once, because relative URLs resolved from + that file will use the same protocol. + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype color + \ingroup qmlbasictypes + + \brief A color is a standard color name in quotes. + + A color is a standard color name in quotes. It is normally specified + as an \l {http://www.w3.org/TR/SVG/types.html#ColorKeywords} {SVG + color name}. These names include colors like "red", "green" and + "lightsteelblue". + + If the color you want isn't part of this list, colors can also be + specified in hexidecimal triplets or quads that take 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". + + Example: + \div{float-right} + \inlineimage declarative-colors.png + \enddiv + \snippet doc/src/snippets/declarative/colors.qml colors + + Or with 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: + + \qml + Rectangle { color: Qt.rgba(0.5, 0.5, 0, 1) } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype point + \ingroup qmlbasictypes + + \brief A point type has x and y attributes. + + A \c point type has \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 + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype size + \ingroup qmlbasictypes + + \brief A size type has width and height attributes + + A \c size type has \c width and \c height attributes. + + For example, to read the \l {Image::sourceSize} \c size 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 + LayoutItem { preferredSize: "150x50" } + \endqml + + Or use the \l{QML:Qt::size()}{Qt.size()} function: + + \qml + LayoutItem { preferredSize: Qt.size(150, 50) } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype rect + \ingroup qmlbasictypes + + \brief A rect type has x, y, width and height attributes. + + A \c rect type has \c x, \c y, \c width and \c height attributes. + + For example, to read the \l {Item::childrenRect.x}{Item::childrenRect} \c rect 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 + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype date + \ingroup qmlbasictypes + + \brief A date is specified as "YYYY-MM-DD". + + To create a \c date value, specify it as a "YYYY-MM-DD" string: + + Example: + \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()}. + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype time + \ingroup qmlbasictypes + + \brief A time is specified as "hh:mm:ss". + + A time is specified as "hh:mm:ss". + + Example: + \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. + + \sa {QML Basic Types} + */ + +/*! + \qmlbasictype font + \ingroup qmlbasictypes + + \brief A font type has the properties of a QFont. + + A font type has the properties of a QFont. The properties are: + + \list + \o \c string font.family + \o \c bool font.bold + \o \c bool font.italic + \o \c bool font.underline + \o \c real font.pointSize + \o \c int font.pixelSize + \endlist + + Example: + \qml + Text { font.family: "Helvetica"; font.pointSize: 13; font.bold: true } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype action + \ingroup qmlbasictypes + + \brief The action type has all the properties of QAction. + + The action type has all the properties of QAction. The properties + are: + + \list + \o \c slot action.trigger - invoke the action + \o \c bool action.enabled - true if the action is enabled + \o \c string action.text - the text associated with the action + \endlist + + Actions are used like this: + + \qml + Item { + MouseArea { onClicked: myaction.trigger() } + State { name: "enabled"; when: myaction.enabled == true } + Text { text: someaction.text } + } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype list + \ingroup qmlbasictypes + + \brief A list of objects. + + A list type contains a list of objects. While not technically + a basic type, QML supports lists of object types. When used + from QML, the engine automatically appends each value to the list. + Items in the list can be accessed by index using the usual + \c listName[index] syntax. + + For example, the \l Item class contains a list property named + children that can be used like this: + + \qml + Item { + children: [ + Item { id: child1 }, + Rectangle { id: child2; width: 200 }, + Text { id: child3 } + ] + + Component.onCompleted: { + console.log("Width of child rectangle:", children[1].width) + } + } + \endqml + \c child1, \c child2 and \c child3 will be added to the children list + in the order in which they appear. + + List \l {Property Binding}{properties} can be created as a + \c variant type, or as a \c list<Type> type, where \c Type is the + type of the object in the list: + + \qml + Item { + property list<Rectangle> rects: [ + Rectangle { width: 100; height: 100}, + Rectangle { width: 200; height: 200} + ] + } + \endqml + + A list property can only contain values that match (or are derived from) the + specified \c Type. + + While the \c rects property can be reassigned to a different list value (including + an empty list), its individual values cannot be modified. See the \l variant type + documentation for details. + + \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. 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 { + property variant aNumber: 100 + property variant aString: "Hello world!" + property variant aBool: false + } + \endqml + + 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}. + + Finally, the \c variant type can also hold: + + \list + \o An array of \l {QML Basic Types}{basic type} values + \o 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 \i not + QML objects (and certainly not JavaScript object either) and the key-value + 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 \i 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 + + 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. + + 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 \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: + + \qml + Item { + property variant attributes: { 'color': 'red', 'width': 100 } + + Component.onCompleted: { + // Change the value of attributes.color to 'blue': + var temp = attributes // copy all values to 'temp' + temp.color = 'blue' + attributes = temp // copy all values back to 'attributes' + } + } + \endqml + + Since this operation is inefficient, if a list or map should be modifiable, + it is better to use alternative approaches. For example, you could implement + a custom C++ list element, or write to a JavaScript object defined from + within a JavaScript file. + + JavaScript programmers should also note that when a JavaScript object 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 + the process. + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype vector3d + \ingroup qmlbasictypes + + \brief A vector3d type has x, y, and z attributes. + + A \c vector3d type has \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 + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype enumeration + \ingroup qmlbasictypes + + \brief An enumeration type consists of a set of named values. + + An enumeration type consists of a set of named values. + + An enumeration value may be specified as either a string: + \qml + Text { horizontalAlignment: "AlignRight" } + \endqml + + or as \c {<Element>.<value>}: + \qml + Text { horizontalAlignment: Text.AlignRight } + \endqml + + The second form is preferred. + + \sa {QML Basic Types} +*/ |