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