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