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