doc/src/qml/basictypes.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \page qml-basictypes.html
  30     \ingroup qml-features
  31     \title QML Basic Types
  32     \brief basic data types in QML
  33
  34     QML has a set of primitive types, as listed below, that are used throughout
  35     the \l {QML Elements}.
  36
  37     \annotatedlist qmlbasictypes
  38
  39     To create additional types, such as data types created in C++, read the
  40     \l{Creating QML Types} article.
  41 */
  42
  43 /*!
  44     \qmlbasictype int
  45     \ingroup qmlbasictypes
  46
  47     \brief An integer is a whole number, e.g. 0, 10, or -20.
  48
  49     An integer is a whole number, e.g. 0, 10, or -20. The possible \c
  50     int values range from around -2000000000 to around 2000000000,
  51     although most elements will only accept a reduced range (which they
  52     mention in their documentation).
  53
  54     Example:
  55     \qml
  56     Item { width: 100; height: 200 }
  57     \endqml
  58
  59     \sa {QML Basic Types}
  60 */
  61
  62 /*!
  63     \qmlbasictype bool
  64     \ingroup qmlbasictypes
  65
  66     \brief A boolean is a binary true/false value.
  67
  68     A boolean is a binary true/false value.
  69
  70     Example:
  71     \qml
  72     Item { focus: true; clip: false }
  73     \endqml
  74
  75     \sa {QML Basic Types}
  76 */
  77
  78 /*!
  79     \qmlbasictype real
  80     \ingroup qmlbasictypes
  81
  82     \brief A real number has a decimal point, e.g. 1.2 or -29.8.
  83
  84     A real number has a decimal point, e.g. 1.2 or -29.8.
  85
  86     Example:
  87     \qml
  88     Item { width: 100.45; height: 150.82 }
  89     \endqml
  90
  91     \bold{Note:} In QML all reals are stored in double precision, \l
  92     {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point}
  93     format.
  94
  95     \sa {QML Basic Types}
  96 */
  97
  98 /*!
  99     \qmlbasictype double
 100     \ingroup qmlbasictypes
 101
 102     \brief A double number has a decimal point and is stored in double precision.
 103
 104     A double number has a decimal point and is stored in double precision, \l
 105     {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point}
 106     format.
 107
 108     Example:
 109     \qml
 110     Item {
 111         property double number: 32155.2355
 112     }
 113     \endqml
 114
 115     \sa {QML Basic Types}
 116 */
 117
 118 /*!
 119     \qmlbasictype string
 120     \ingroup qmlbasictypes
 121
 122     \brief A string is a free form text in quotes, e.g. "Hello world!".
 123
 124     A string is a free form text in quotes, e.g. "Hello world!".
 125
 126     Example:
 127     \qml
 128     Text { text: "Hello world!" }
 129     \endqml
 130
 131     Strings have a \c length attribute that holds the number of
 132     characters in the string.
 133
 134     \sa {QML Basic Types}
 135 */
 136
 137 /*!
 138     \qmlbasictype url
 139     \ingroup qmlbasictypes
 140
 141     \brief A URL is a resource locator, like a file name.
 142
 143     A URL is a resource locator, like a file name. It can be either
 144     absolute, e.g. "http://qt.nokia.com", or relative, e.g.
 145     "pics/logo.png". A relative URL is resolved relative to the URL of
 146     the component where the URL is converted from a JavaScript string
 147     expression to a url property value.
 148
 149     Example:
 150     \qml
 151     Image { source: "pics/logo.png" }
 152     \endqml
 153
 154     Note that as QML requires URL paths, you should use "qrc:///" instead of ":/" for
 155     referring to files stored with the \l{resources.html}{Qt Resource System}.
 156     Usually you will only have to do this once, because relative URLs resolved from
 157     that file will use the same protocol.
 158
 159     \sa {QML Basic Types}
 160 */
 161
 162 /*!
 163     \qmlbasictype color
 164     \ingroup qmlbasictypes
 165
 166     \brief A color is a standard color name in quotes.
 167
 168     A color is a standard color name in quotes. It is normally specified
 169     as an \l {http://www.w3.org/TR/SVG/types.html#ColorKeywords} {SVG
 170     color name}. These names include colors like "red", "green" and
 171     "lightsteelblue".
 172
 173     If the color you want isn't part of this list, colors can also be
 174     specified in hexidecimal triplets or quads that take the form \c
 175     "#RRGGBB" and \c "#AARRGGBB" respectively. For example, the color
 176     red corresponds to a triplet of \c "#FF0000" and a slightly
 177     transparent blue to a quad of \c "#800000FF".
 178
 179     Example:
 180     \div{float-right}
 181     \inlineimage declarative-colors.png
 182     \enddiv
 183     \snippet doc/src/snippets/qml/colors.qml colors
 184
 185     Or with the \l{QML:Qt::rgba()}{Qt.rgba()}, \l{QML:Qt::hsla()}{Qt.hsla()}, \l{QML:Qt::darker()}{Qt.darker()},
 186     \l{QML:Qt::lighter()}{Qt.lighter()} or \l{QML:Qt::tint()}{Qt.tint()} functions:
 187
 188     \qml
 189     Rectangle { color: Qt.rgba(0.5, 0.5, 0, 1) }
 190     \endqml
 191
 192     \sa {QML Basic Types}
 193 */
 194
 195 /*!
 196     \qmlbasictype point
 197     \ingroup qmlbasictypes
 198
 199     \brief A point type has x and y attributes.
 200
 201     A \c point type has \c x and \c y attributes.
 202
 203     To create a \c point value, specify it as a "x,y" string:
 204
 205     \qml
 206     CustomObject { myPointProperty: "0,20" }
 207     \endqml
 208
 209     Or use the \l{QML:Qt::point()}{Qt.point()} function:
 210
 211     \qml
 212     CustomObject { myPointProperty: Qt.point(0, 20) }
 213     \endqml
 214
 215     \sa {QML Basic Types}
 216 */
 217
 218 /*!
 219     \qmlbasictype size
 220     \ingroup qmlbasictypes
 221
 222     \brief A size type has width and height attributes
 223
 224     A \c size type has \c width and \c height attributes.
 225
 226     For example, to read the \l {Image::sourceSize} \c size property:
 227
 228     \qml
 229     Column {
 230         Image { id: image; source: "logo.png" }
 231         Text { text: image.sourceSize.width + "," + image.sourceSize.height }
 232     }
 233     \endqml
 234
 235     To create a \c size value, specify it as a "width x height" string:
 236
 237     \qml
 238     LayoutItem { preferredSize: "150x50" }
 239     \endqml
 240
 241     Or use the \l{QML:Qt::size()}{Qt.size()} function:
 242
 243     \qml
 244     LayoutItem { preferredSize: Qt.size(150, 50) }
 245     \endqml
 246
 247     \sa {QML Basic Types}
 248 */
 249
 250 /*!
 251     \qmlbasictype rect
 252     \ingroup qmlbasictypes
 253
 254     \brief A rect type has x, y, width and height attributes.
 255
 256     A \c rect type has \c x, \c y, \c width and \c height attributes.
 257
 258     For example, to read the \l {Item::childrenRect.x}{Item::childrenRect} \c rect property:
 259     \qml
 260     Rectangle {
 261         width: childrenRect.width
 262         height: childrenRect.height
 263
 264         Rectangle { width: 100; height: 100 }
 265     }
 266     \endqml
 267
 268     To create a \c rect value, specify it as a "x, y, width x height" string:
 269
 270     \qml
 271     CustomObject { myRectProperty: "50,50,100x100" }
 272     \endqml
 273
 274     Or use the \l{QML:Qt::rect()}{Qt.rect()} function:
 275
 276     \qml
 277     CustomObject { myRectProperty: Qt.rect(50, 50, 100, 100) }
 278     \endqml
 279
 280     \sa {QML Basic Types}
 281 */
 282
 283 /*!
 284     \qmlbasictype date
 285     \ingroup qmlbasictypes
 286
 287     \brief A date is specified as "YYYY-MM-DD".
 288
 289     To create a \c date value, specify it as a "YYYY-MM-DD" string:
 290
 291     Example:
 292     \qml
 293     MyDatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" }
 294     \endqml
 295
 296     To read a date value returned from a C++ extension class, use
 297     \l{QML:Qt::formatDate()}{Qt.formatDate()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.
 298
 299     \sa {QML Basic Types}
 300 */
 301
 302 /*!
 303     \qmlbasictype time
 304     \ingroup qmlbasictypes
 305
 306     \brief A time is specified as "hh:mm:ss".
 307
 308     A time is specified as "hh:mm:ss".
 309
 310     Example:
 311     \qml
 312     MyTimePicker { time: "14:22:15" }
 313     \endqml
 314
 315     To read a time value returned from a C++ extension class, use
 316     \l{QML:Qt::formatTime()}{Qt.formatTime()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.
 317
 318     Note that when converting historical times to and from javascript that QDateTime and the JS Date object
 319     have different methods of calculating historical daylight savings time application. This can lead to variations of one hour
 320     when converting to historical local time.
 321
 322     \sa {QML Basic Types}
 323  */
 324
 325 /*!
 326     \qmlbasictype font
 327     \ingroup qmlbasictypes
 328
 329     \brief A font type has the properties of a QFont.
 330
 331     A font type has the properties of a QFont. The properties are:
 332
 333     \list
 334     \o \c string font.family
 335     \o \c bool font.bold
 336     \o \c bool font.italic
 337     \o \c bool font.underline
 338     \o \c real font.pointSize
 339     \o \c int font.pixelSize
 340     \endlist
 341
 342     Example:
 343     \qml
 344     Text { font.family: "Helvetica"; font.pointSize: 13; font.bold: true }
 345     \endqml
 346
 347     \sa {QML Basic Types}
 348 */
 349
 350 /*!
 351     \qmlbasictype action
 352     \ingroup qmlbasictypes
 353
 354     \brief The action type has all the properties of QAction.
 355
 356     The action type has all the properties of QAction. The properties
 357     are:
 358
 359     \list
 360     \o \c slot action.trigger - invoke the action
 361     \o \c bool action.enabled - true if the action is enabled
 362     \o \c string action.text - the text associated with the action
 363     \endlist
 364
 365     Actions are used like this:
 366
 367     \qml
 368     Item {
 369         MouseArea { onClicked: myaction.trigger() }
 370         State { name: "enabled"; when: myaction.enabled == true }
 371         Text { text: someaction.text }
 372     }
 373     \endqml
 374
 375     \sa {QML Basic Types}
 376 */
 377
 378 /*!
 379     \qmlbasictype list
 380     \ingroup qmlbasictypes
 381
 382     \brief A list of objects.
 383
 384     A list type contains a list of objects. While not technically
 385     a basic type, QML supports lists of object types. When used
 386     from QML, the engine automatically appends each value to the list.
 387     Items in the list can be accessed by index using the usual
 388     \c listName[index] syntax.
 389
 390     For example, the \l Item class contains a list property named
 391     children that can be used like this:
 392
 393     \qml
 394     Item {
 395         children: [
 396             Item { id: child1 },
 397             Rectangle { id: child2; width: 200 },
 398             Text { id: child3 }
 399         ]
 400
 401         Component.onCompleted: {
 402             console.log("Width of child rectangle:", children[1].width)
 403         }
 404     }
 405     \endqml
 406     \c child1, \c child2 and \c child3 will be added to the children list
 407     in the order in which they appear.
 408
 409     List \l {Property Binding}{properties} can be created as a
 410     \c variant type, or as a \c list<Type> type, where \c Type is the
 411     type of the object in the list:
 412
 413     \qml
 414     Item {
 415         property list<Rectangle> rects: [
 416             Rectangle { width: 100; height: 100},
 417             Rectangle { width: 200; height: 200}
 418         ]
 419     }
 420     \endqml
 421
 422     A list property can only contain values that match (or are derived from) the
 423     specified \c Type.
 424
 425     While the \c rects property can be reassigned to a different list value (including
 426     an empty list), its individual values cannot be modified. See the \l variant type
 427     documentation for details.
 428
 429     \sa {QML Basic Types}
 430 */
 431
 432  /*!
 433     \qmlbasictype var
 434     \ingroup qmlbasictypes
 435
 436     \brief A var type is a generic property type.
 437
 438     A var is a generic property type capable of storing any data type.
 439     It is equivalent to a regular JavaScript variable, except that you
 440     cannot assign a JavaScript function to such a property.
 441     For example, var properties can store numbers, strings, objects and
 442     arrays:
 443
 444     \qml
 445     Item {
 446         property var aNumber: 100
 447         property var aBool: false
 448         property var aString: "Hello world!"
 449         property var anotherString: String("#FF008800")
 450         property var aColor: Qt.rgba(0.2, 0.3, 0.4, 0.5)
 451         property var aRect: Qt.rect(10, 10, 10, 10)
 452         property var aPoint: Qt.point(10, 10)
 453         property var aSize: Qt.size(10, 10)
 454         property var aVector3d: Qt.vector3d(100, 100, 100)
 455         property var anArray: [1, 2, 3, "four", "five", (function() { return "six"; })]
 456         property var anObject: { "foo": 10, "bar": 20 }
 457     }
 458     \endqml
 459
 460     Attempting to assign a JavaScript function to a var property will result in
 461     a binding assignment as per other property types.  You can assign a JavaScript
 462     array containing a single function element instead.
 463
 464     It is important to note that changes in regular properties of JavaScript
 465     objects assigned to a var property will \bold{not} trigger updates of bindings
 466     that access them.  The example below will display "The car has 4 wheels" as
 467     the change to the wheels property will not cause the reevaluation of the
 468     binding assigned to the "text" property:
 469
 470     \qml
 471     Item {
 472         property var car: new Object({wheels: 4})
 473
 474         Text {
 475             text: "The car has " + car.wheels + " wheels";
 476         }
 477
 478         Component.onCompleted: {
 479             car.wheels = 6;
 480         }
 481     }
 482     \endqml
 483
 484     A \c var type property can also hold an image or pixmap.
 485     A \c var which contains a QPixmap or QImage is known as a
 486     "scarce resource" and the declarative engine will attempt to
 487     automatically release such resources after evaluation of any JavaScript
 488     expression which requires one to be copied has completed.
 489
 490     Clients may explicitly release such a scarce resource by calling the
 491     "destroy" method on the \c var property from within JavaScript.  They
 492     may also explicitly preserve the scarce resource by calling the
 493     "preserve" method on the \c var property from within JavaScript.
 494     For more information regarding the usage of a scarce resource, please
 495     see \l{Scarce Resources in JavaScript}.
 496
 497     \sa {QML Basic Types}
 498 */
 499
 500
 501 /*!
 502     \obsolete
 503     \qmlbasictype variant
 504     \ingroup qmlbasictypes
 505
 506     \brief A variant type is a generic property type.
 507
 508     A variant is a generic property type. It is obsolete and exists only to
 509     support old applications; new applications should use "var" type
 510     properties instead.
 511
 512     A variant type property can hold any of the \l {QML Basic Types}{basic type}
 513     values:
 514
 515     \qml
 516     Item {
 517         property variant aNumber: 100
 518         property variant aString: "Hello world!"
 519         property variant aBool: false
 520     }
 521     \endqml
 522
 523     A \c variant type property can also hold an image or pixmap.
 524     A \c variant which contains a QPixmap or QImage is known as a
 525     "scarce resource" and the declarative engine will attempt to
 526     automatically release such resources after evaluation of any JavaScript
 527     expression which requires one to be copied has completed.
 528
 529     Clients may explicitly release such a scarce resource by calling the
 530     "destroy" method on the \c variant property from within JavaScript.  They
 531     may also explicitly preserve the scarce resource by calling the
 532     "preserve" method on the \c variant property from within JavaScript.
 533     For more information regarding the usage of a scarce resource, please
 534     see \l{Scarce Resources in JavaScript}.
 535
 536     Finally, the \c variant type can also hold:
 537
 538     \list
 539     \o An array of \l {QML Basic Types}{basic type} values
 540     \o A map of key-value pairs with \l {QML Basic Types}{basic-type} values
 541     \endlist
 542
 543     For example, below is an \c items array and an \c attributes map. Their
 544     contents can be examined using JavaScript \c for loops. Individual array
 545     values are accessible by index, and individual map values are accessible
 546     by key:
 547
 548     \qml
 549     Item {
 550         property variant items: [1, 2, 3, "four", "five"]
 551         property variant attributes: { 'color': 'red', 'width': 100 }
 552
 553         Component.onCompleted: {
 554             for (var i=0; i<items.length; i++)
 555                 console.log(items[i])
 556
 557             for (var prop in attributes)
 558                 console.log(prop, "=", attributes[prop])
 559         }
 560     }
 561     \endqml
 562
 563     While this is a convenient way to store array and map-type values, you
 564     must be aware that the \c items and \c attributes properties above are \i not
 565     QML objects (and certainly not JavaScript object either) and the key-value
 566     pairs in \c attributes are \i not QML properties. Rather, the \c items
 567     property holds an array of values, and \c attributes holds a set of key-value
 568     pairs. Since they are stored as a set of values, instead of as an object,
 569     their contents \i cannot be modified individually:
 570
 571     \qml
 572     Item {
 573         property variant items: [1, 2, 3, "four", "five"]
 574         property variant attributes: { 'color': 'red', 'width': 100 }
 575
 576         Component.onCompleted: {
 577             items[0] = 10
 578             console.log(items[0])     // This will still be '1'!
 579             attributes.color = 'blue'
 580             console.log(attributes.color)     // This will still be 'red'!
 581         }
 582     }
 583     \endqml
 584
 585     Additionally, since \c items and \c attributes are not QML objects, changing
 586     their individual values do not trigger property change notifications. If
 587     the above example had \c onNumberChanged or \c onAnimalChanged signal
 588     handlers, they would not have been called.  If, however, the \c items or
 589     \c attributes properties themselves were reassigned to different values, then
 590     such handlers would be called.
 591
 592     One way to "update" the contents of an array or map is to copy the property
 593     to a JavaScript object, modify the copy as desired, and then reassign the
 594     property to the updated copy. Note, however, that this is not efficient.
 595     In the example below, which reassigns the \c attributes property, the \i entire
 596     set of key-value pairs must be serialized and deserialized every time it is
 597     copied between a JavaScript object and a QML property:
 598
 599     \qml
 600     Item {
 601         property variant attributes: { 'color': 'red', 'width': 100 }
 602
 603         Component.onCompleted: {
 604             // Change the value of attributes.color to 'blue':
 605             var temp = attributes     // copy all values to 'temp'
 606             temp.color = 'blue'
 607             attributes = temp         // copy all values back to 'attributes'
 608         }
 609     }
 610     \endqml
 611
 612     Since this operation is inefficient, if a list or map should be modifiable,
 613     it is better to use alternative approaches. For example, you could implement
 614     a custom C++ list element, or write to a JavaScript object defined from
 615     within a JavaScript file.
 616
 617     JavaScript programmers should also note that when a JavaScript object is
 618     copied to an array or map property, the \i contents of the object (that is,
 619     its key-value properties) are copied, rather than the object itself. The
 620     property does not hold a reference to the original JavaScript object, and
 621     extra data such as the object's JavaScript prototype chain is also lost in
 622     the process.
 623
 624     \sa {QML Basic Types}
 625 */
 626
 627 /*!
 628     \qmlbasictype vector3d
 629     \ingroup qmlbasictypes
 630
 631     \brief A vector3d type has x, y, and z attributes.
 632
 633     A \c vector3d type has \c x, \c y, and \c z attributes.
 634
 635     To create a \c vector3d value, specify it as a "x,y,z" string:
 636
 637     \qml
 638     Rotation { angle: 60; axis: "0,1,0" }
 639     \endqml
 640
 641     or with the \l{QML:Qt::vector3d()}{Qt.vector3d()} function:
 642
 643     \qml
 644     Rotation { angle: 60; axis: Qt.vector3d(0, 1, 0) }
 645     \endqml
 646
 647     or as separate \c x, \c y, and \c z components:
 648
 649     \qml
 650     Rotation { angle: 60; axis.x: 0; axis.y: 1; axis.z: 0 }
 651     \endqml
 652
 653     \sa {QML Basic Types}
 654 */
 655
 656 /*!
 657     \qmlbasictype enumeration
 658     \ingroup qmlbasictypes
 659
 660     \brief An enumeration type consists of a set of named values.
 661
 662     An enumeration type consists of a set of named values.
 663
 664     An enumeration value may be specified as either a string:
 665     \qml
 666     Text { horizontalAlignment: "AlignRight" }
 667     \endqml
 668
 669     or as \c {<Element>.<value>}:
 670     \qml
 671     Text { horizontalAlignment: Text.AlignRight }
 672     \endqml
 673
 674     The second form is preferred.
 675
 676     \sa {QML Basic Types}
 677 */