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     \sa {QML Basic Types}
 171 */
 172
 173 /*!
 174     \qmlbasictype color
 175     \ingroup qmlbasictypes
 176
 177     \brief A color is a standard color name in quotes.
 178
 179     A color is a standard color name in quotes. It is normally specified
 180     as an \l {http://www.w3.org/TR/SVG/types.html#ColorKeywords} {SVG
 181     color name}. These names include colors like "red", "green" and
 182     "lightsteelblue".
 183
 184     If the color you want isn't part of this list, colors can also be
 185     specified in hexidecimal triplets or quads that take the form \c
 186     "#RRGGBB" and \c "#AARRGGBB" respectively. For example, the color
 187     red corresponds to a triplet of \c "#FF0000" and a slightly
 188     transparent blue to a quad of \c "#800000FF".
 189
 190     Example:
 191     \div{float-right}
 192     \inlineimage declarative-colors.png
 193     \enddiv
 194
 195     \snippet qml/colors.qml colors
 196
 197     Or with the \l{QML:Qt::rgba()}{Qt.rgba()}, \l{QML:Qt::hsla()}{Qt.hsla()}, \l{QML:Qt::darker()}{Qt.darker()},
 198     \l{QML:Qt::lighter()}{Qt.lighter()} or \l{QML:Qt::tint()}{Qt.tint()} functions:
 199
 200     \qml
 201     Rectangle { color: Qt.rgba(0.5, 0.5, 0, 1) }
 202     \endqml
 203
 204     \sa {QML Basic Types}
 205 */
 206
 207 /*!
 208     \qmlbasictype point
 209     \ingroup qmlbasictypes
 210
 211     \brief A point type has x and y attributes.
 212
 213     A \c point type has \c x and \c y attributes.
 214
 215     To create a \c point value, specify it as a "x,y" string:
 216
 217     \qml
 218     CustomObject { myPointProperty: "0,20" }
 219     \endqml
 220
 221     Or use the \l{QML:Qt::point()}{Qt.point()} function:
 222
 223     \qml
 224     CustomObject { myPointProperty: Qt.point(0, 20) }
 225     \endqml
 226
 227     \sa {QML Basic Types}
 228 */
 229
 230 /*!
 231     \qmlbasictype size
 232     \ingroup qmlbasictypes
 233
 234     \brief A size type has width and height attributes
 235
 236     A \c size type has \c width and \c height attributes.
 237
 238     For example, to read the \l {Image::sourceSize} \c size property:
 239
 240     \qml
 241     Column {
 242         Image { id: image; source: "logo.png" }
 243         Text { text: image.sourceSize.width + "," + image.sourceSize.height }
 244     }
 245     \endqml
 246
 247     To create a \c size value, specify it as a "width x height" string:
 248
 249     \qml
 250     LayoutItem { preferredSize: "150x50" }
 251     \endqml
 252
 253     Or use the \l{QML:Qt::size()}{Qt.size()} function:
 254
 255     \qml
 256     LayoutItem { preferredSize: Qt.size(150, 50) }
 257     \endqml
 258
 259     \sa {QML Basic Types}
 260 */
 261
 262 /*!
 263     \qmlbasictype rect
 264     \ingroup qmlbasictypes
 265
 266     \brief A rect type has x, y, width and height attributes.
 267
 268     A \c rect type has \c x, \c y, \c width and \c height attributes.
 269
 270     For example, to read the \l {Item::childrenRect.x}{Item::childrenRect} \c rect property:
 271     \qml
 272     Rectangle {
 273         width: childrenRect.width
 274         height: childrenRect.height
 275
 276         Rectangle { width: 100; height: 100 }
 277     }
 278     \endqml
 279
 280     To create a \c rect value, specify it as a "x, y, width x height" string:
 281
 282     \qml
 283     CustomObject { myRectProperty: "50,50,100x100" }
 284     \endqml
 285
 286     Or use the \l{QML:Qt::rect()}{Qt.rect()} function:
 287
 288     \qml
 289     CustomObject { myRectProperty: Qt.rect(50, 50, 100, 100) }
 290     \endqml
 291
 292     \sa {QML Basic Types}
 293 */
 294
 295 /*!
 296     \qmlbasictype date
 297     \ingroup qmlbasictypes
 298
 299     \brief A date is specified as "YYYY-MM-DD".
 300
 301     To create a \c date value, specify it as a "YYYY-MM-DD" string:
 302
 303     Example:
 304     \qml
 305     MyDatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" }
 306     \endqml
 307
 308     To read a date value returned from a C++ extension class, use
 309     \l{QML:Qt::formatDate()}{Qt.formatDate()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.
 310
 311     \sa {QML Basic Types}
 312 */
 313
 314 /*!
 315     \qmlbasictype time
 316     \ingroup qmlbasictypes
 317
 318     \brief A time is specified as "hh:mm:ss".
 319
 320     A time is specified as "hh:mm:ss".
 321
 322     Example:
 323     \qml
 324     MyTimePicker { time: "14:22:15" }
 325     \endqml
 326
 327     To read a time value returned from a C++ extension class, use
 328     \l{QML:Qt::formatTime()}{Qt.formatTime()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.
 329
 330     Note that when converting historical times to and from javascript that QDateTime and the JS Date object
 331     have different methods of calculating historical daylight savings time application. This can lead to variations of one hour
 332     when converting to historical local time.
 333
 334     \sa {QML Basic Types}
 335  */
 336
 337 /*!
 338     \qmlbasictype font
 339     \ingroup qmlbasictypes
 340
 341     \brief A font type has the properties of a QFont.
 342
 343     A font type has the properties of a QFont. The properties are:
 344
 345     \list
 346     \li \c string font.family
 347     \li \c bool font.bold
 348     \li \c bool font.italic
 349     \li \c bool font.underline
 350     \li \c real font.pointSize
 351     \li \c int font.pixelSize
 352     \endlist
 353
 354     Example:
 355     \qml
 356     Text { font.family: "Helvetica"; font.pointSize: 13; font.bold: true }
 357     \endqml
 358
 359     \sa {QML Basic Types}
 360 */
 361
 362 /*!
 363     \qmlbasictype action
 364     \ingroup qmlbasictypes
 365
 366     \brief The action type has all the properties of QAction.
 367
 368     The action type has all the properties of QAction. The properties
 369     are:
 370
 371     \list
 372     \li \c slot action.trigger - invoke the action
 373     \li \c bool action.enabled - true if the action is enabled
 374     \li \c string action.text - the text associated with the action
 375     \endlist
 376
 377     Actions are used like this:
 378
 379     \qml
 380     Item {
 381         MouseArea { onClicked: myaction.trigger() }
 382         State { name: "enabled"; when: myaction.enabled == true }
 383         Text { text: someaction.text }
 384     }
 385     \endqml
 386
 387     \sa {QML Basic Types}
 388 */
 389
 390 /*!
 391     \qmlbasictype list
 392     \ingroup qmlbasictypes
 393
 394     \brief A list of objects.
 395
 396     A list type contains a list of objects. While not technically
 397     a basic type, QML supports lists of object types. When used
 398     from QML, the engine automatically appends each value to the list.
 399     Items in the list can be accessed by index using the usual
 400     \c listName[index] syntax.
 401
 402     For example, the \l Item class contains a list property named
 403     children that can be used like this:
 404
 405     \qml
 406     Item {
 407         children: [
 408             Item { id: child1 },
 409             Rectangle { id: child2; width: 200 },
 410             Text { id: child3 }
 411         ]
 412
 413         Component.onCompleted: {
 414             console.log("Width of child rectangle:", children[1].width)
 415         }
 416     }
 417     \endqml
 418     \c child1, \c child2 and \c child3 will be added to the children list
 419     in the order in which they appear.
 420
 421     List \l {Property Binding}{properties} can be created as a
 422     \c variant type, or as a \c list<Type> type, where \c Type is the
 423     type of the object in the list:
 424
 425     \qml
 426     Item {
 427         property list<Rectangle> rects: [
 428             Rectangle { width: 100; height: 100},
 429             Rectangle { width: 200; height: 200}
 430         ]
 431     }
 432     \endqml
 433
 434     A list property can only contain values that match (or are derived from) the
 435     specified \c Type.
 436
 437     While the \c rects property can be reassigned to a different list value (including
 438     an empty list), its individual values cannot be modified. See the \l variant type
 439     documentation for details.
 440
 441     \sa {QML Basic Types}
 442 */
 443
 444  /*!
 445     \qmlbasictype var
 446     \ingroup qmlbasictypes
 447
 448     \brief A var type is a generic property type.
 449
 450     A var is a generic property type capable of storing any data type.
 451     It is equivalent to a regular JavaScript variable.
 452     For example, var properties can store numbers, strings, objects,
 453     arrays and functions:
 454
 455     \qml
 456     Item {
 457         property var aNumber: 100
 458         property var aBool: false
 459         property var aString: "Hello world!"
 460         property var anotherString: String("#FF008800")
 461         property var aColor: Qt.rgba(0.2, 0.3, 0.4, 0.5)
 462         property var aRect: Qt.rect(10, 10, 10, 10)
 463         property var aPoint: Qt.point(10, 10)
 464         property var aSize: Qt.size(10, 10)
 465         property var aVector3d: Qt.vector3d(100, 100, 100)
 466         property var anArray: [1, 2, 3, "four", "five", (function() { return "six"; })]
 467         property var anObject: { "foo": 10, "bar": 20 }
 468         property var aFunction: (function() { return "one"; })
 469     }
 470     \endqml
 471
 472     It is important to note that changes in regular properties of JavaScript
 473     objects assigned to a var property will \b{not} trigger updates of bindings
 474     that access them.  The example below will display "The car has 4 wheels" as
 475     the change to the wheels property will not cause the reevaluation of the
 476     binding assigned to the "text" property:
 477
 478     \qml
 479     Item {
 480         property var car: new Object({wheels: 4})
 481
 482         Text {
 483             text: "The car has " + car.wheels + " wheels";
 484         }
 485
 486         Component.onCompleted: {
 487             car.wheels = 6;
 488         }
 489     }
 490     \endqml
 491
 492     If the onCompleted handler instead had \tt{"car = new Object({wheels: 6})"}
 493     then the text would be updated to say "The car has 6 wheels"., since the
 494     car property itself would be changed, which causes a change notification
 495     to be emitted.
 496
 497     A \c var type property can also hold an image or pixmap.
 498     A \c var which contains a QPixmap or QImage is known as a
 499     "scarce resource" and the declarative engine will attempt to
 500     automatically release such resources after evaluation of any JavaScript
 501     expression which requires one to be copied has completed.
 502
 503     Clients may explicitly release such a scarce resource by calling the
 504     "destroy" method on the \c var property from within JavaScript.  They
 505     may also explicitly preserve the scarce resource by calling the
 506     "preserve" method on the \c var property from within JavaScript.
 507     For more information regarding the usage of a scarce resource, please
 508     see \l{Scarce Resources in JavaScript}.
 509
 510     \sa {QML Basic Types}
 511 */
 512
 513
 514 /*!
 515     \obsolete
 516     \qmlbasictype variant
 517     \ingroup qmlbasictypes
 518
 519     \brief A variant type is a generic property type.
 520
 521     A variant is a generic property type. It is obsolete and exists only to
 522     support old applications; new applications should use "var" type
 523     properties instead.
 524
 525     A variant type property can hold any of the \l {QML Basic Types}{basic type}
 526     values:
 527
 528     \qml
 529     Item {
 530         property variant aNumber: 100
 531         property variant aString: "Hello world!"
 532         property variant aBool: false
 533     }
 534     \endqml
 535
 536     A \c variant type property can also hold an image or pixmap.
 537     A \c variant which contains a QPixmap or QImage is known as a
 538     "scarce resource" and the declarative engine will attempt to
 539     automatically release such resources after evaluation of any JavaScript
 540     expression which requires one to be copied has completed.
 541
 542     Clients may explicitly release such a scarce resource by calling the
 543     "destroy" method on the \c variant property from within JavaScript.  They
 544     may also explicitly preserve the scarce resource by calling the
 545     "preserve" method on the \c variant property from within JavaScript.
 546     For more information regarding the usage of a scarce resource, please
 547     see \l{Scarce Resources in JavaScript}.
 548
 549     Finally, the \c variant type can also hold:
 550
 551     \list
 552     \li An array of \l {QML Basic Types}{basic type} values
 553     \li A map of key-value pairs with \l {QML Basic Types}{basic-type} values
 554     \endlist
 555
 556     For example, below is an \c items array and an \c attributes map. Their
 557     contents can be examined using JavaScript \c for loops. Individual array
 558     values are accessible by index, and individual map values are accessible
 559     by key:
 560
 561     \qml
 562     Item {
 563         property variant items: [1, 2, 3, "four", "five"]
 564         property variant attributes: { 'color': 'red', 'width': 100 }
 565
 566         Component.onCompleted: {
 567             for (var i=0; i<items.length; i++)
 568                 console.log(items[i])
 569
 570             for (var prop in attributes)
 571                 console.log(prop, "=", attributes[prop])
 572         }
 573     }
 574     \endqml
 575
 576     While this is a convenient way to store array and map-type values, you
 577     must be aware that the \c items and \c attributes properties above are \e not
 578     QML objects (and certainly not JavaScript object either) and the key-value
 579     pairs in \c attributes are \e not QML properties. Rather, the \c items
 580     property holds an array of values, and \c attributes holds a set of key-value
 581     pairs. Since they are stored as a set of values, instead of as an object,
 582     their contents \e cannot be modified individually:
 583
 584     \qml
 585     Item {
 586         property variant items: [1, 2, 3, "four", "five"]
 587         property variant attributes: { 'color': 'red', 'width': 100 }
 588
 589         Component.onCompleted: {
 590             items[0] = 10
 591             console.log(items[0])     // This will still be '1'!
 592             attributes.color = 'blue'
 593             console.log(attributes.color)     // This will still be 'red'!
 594         }
 595     }
 596     \endqml
 597
 598     Additionally, since \c items and \c attributes are not QML objects, changing
 599     their individual values do not trigger property change notifications. If
 600     the above example had \c onNumberChanged or \c onAnimalChanged signal
 601     handlers, they would not have been called.  If, however, the \c items or
 602     \c attributes properties themselves were reassigned to different values, then
 603     such handlers would be called.
 604
 605     One way to "update" the contents of an array or map is to copy the property
 606     to a JavaScript object, modify the copy as desired, and then reassign the
 607     property to the updated copy. Note, however, that this is not efficient.
 608     In the example below, which reassigns the \c attributes property, the \e entire
 609     set of key-value pairs must be serialized and deserialized every time it is
 610     copied between a JavaScript object and a QML property:
 611
 612     \qml
 613     Item {
 614         property variant attributes: { 'color': 'red', 'width': 100 }
 615
 616         Component.onCompleted: {
 617             // Change the value of attributes.color to 'blue':
 618             var temp = attributes     // copy all values to 'temp'
 619             temp.color = 'blue'
 620             attributes = temp         // copy all values back to 'attributes'
 621         }
 622     }
 623     \endqml
 624
 625     Since this operation is inefficient, if a list or map should be modifiable,
 626     it is better to use alternative approaches. For example, you could implement
 627     a custom C++ list element, or write to a JavaScript object defined from
 628     within a JavaScript file.
 629
 630     JavaScript programmers should also note that when a JavaScript object is
 631     copied to an array or map property, the \e contents of the object (that is,
 632     its key-value properties) are copied, rather than the object itself. The
 633     property does not hold a reference to the original JavaScript object, and
 634     extra data such as the object's JavaScript prototype chain is also lost in
 635     the process.
 636
 637     \sa {QML Basic Types}
 638 */
 639
 640 /*!
 641     \qmlbasictype vector3d
 642     \ingroup qmlbasictypes
 643
 644     \brief A vector3d type has x, y, and z attributes.
 645
 646     A \c vector3d type has \c x, \c y, and \c z attributes.
 647
 648     To create a \c vector3d value, specify it as a "x,y,z" string:
 649
 650     \qml
 651     Rotation { angle: 60; axis: "0,1,0" }
 652     \endqml
 653
 654     or with the \l{QML:Qt::vector3d()}{Qt.vector3d()} function:
 655
 656     \qml
 657     Rotation { angle: 60; axis: Qt.vector3d(0, 1, 0) }
 658     \endqml
 659
 660     or as separate \c x, \c y, and \c z components:
 661
 662     \qml
 663     Rotation { angle: 60; axis.x: 0; axis.y: 1; axis.z: 0 }
 664     \endqml
 665
 666     \sa {QML Basic Types}
 667 */
 668
 669 /*!
 670     \qmlbasictype enumeration
 671     \ingroup qmlbasictypes
 672
 673     \brief An enumeration type consists of a set of named values.
 674
 675     An enumeration type consists of a set of named values.
 676
 677     An enumeration value may be specified as either a string:
 678     \qml
 679     Text { horizontalAlignment: "AlignRight" }
 680     \endqml
 681
 682     or as \c {<Element>.<value>}:
 683     \qml
 684     Text { horizontalAlignment: Text.AlignRight }
 685     \endqml
 686
 687     The second form is preferred.
 688
 689     \sa {QML Basic Types}
 690 */