doc/src/qtquick1/qmlsyntax.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 qmlsyntax.html
  30 \inqmlmodule QtQuick 1
  31 \title QML Syntax
  32 \ingroup QML Reference
  33 \contentspage QML Reference
  34
  35 \tableofcontents
  36
  37 QML is a declarative language designed to describe the user interface of a
  38 program: both what it looks like, and how it behaves. In QML, a user
  39 interface is specified as a tree of objects with properties.
  40
  41 JavaScript is used as a scripting language in QML, so you may want
  42 to learn a bit more about it (\l{Javascript Guide}) before diving
  43 deeper into QML.
  44
  45 \section1 Basic QML Syntax
  46
  47 QML looks like this:
  48
  49 \code
  50 import QtQuick 1.0
  51
  52 Rectangle {
  53     width: 200
  54     height: 200
  55     color: "blue"
  56
  57     Image {
  58         source: "pics/logo.png"
  59         anchors.centerIn: parent
  60     }
  61 }
  62 \endcode
  63
  64 Objects are specified by their type, followed by a pair of braces. Object
  65 types always begin with a capital letter. In the above example, there are
  66 two objects, a \l Rectangle, and an \l Image. Between the braces, we can specify
  67 information about the object, such as its properties.
  68
  69 Properties are specified as \c {propertyname: value}. In the above example, we
  70 can see the Image has a property named \c source, which has been assigned the
  71 value \c "pics/logo.png". The property and its value are separated by a colon.
  72
  73 Properties can be specified one-per-line:
  74
  75 \code
  76 Rectangle {
  77     width: 100
  78     height: 100
  79 }
  80 \endcode
  81
  82 or you can put multiple properties on a single line:
  83
  84 \code
  85 Rectangle { width: 100; height: 100 }
  86 \endcode
  87
  88 When multiple property/value pairs are specified on a single line, they
  89 must be separated by a semicolon.
  90
  91 The \c import statement imports the \c Qt \l{QML Modules}{module}, which contains all of the
  92 standard \l {QML Elements}. Without this import statement, the \l Rectangle
  93 and \l Image elements would not be available.
  94
  95 \section1 Expressions
  96
  97 In addition to assigning values to properties, you can also assign
  98 expressions written in JavaScript.
  99
 100 \code
 101 Rotation {
 102     angle: 360 * 3
 103 }
 104 \endcode
 105
 106 These expressions can include references to other objects and properties, in which case
 107 a \e binding is established: when the value of the expression changes, the property the
 108 expression has been assigned to is automatically updated to that value.
 109
 110 \code
 111 Item {
 112     Text {
 113         id: text1
 114         text: "Hello World"
 115     }
 116     Text {
 117         id: text2
 118         text: text1.text
 119     }
 120 }
 121 \endcode
 122
 123 In the example above, the \c text2 object will display the same text as \c text1. If \c text1 is changed,
 124 \c text2 is automatically changed to the same value.
 125
 126 Note that to refer to other objects, we use their \e id values. (See below for more
 127 information on the \e id property.)
 128
 129 \section1 QML Comments
 130
 131 Commenting in QML is similar to JavaScript.
 132 \list
 133 \o Single line comments start with // and finish at the end of the line.
 134 \o Multiline comments start with /* and finish with *\/
 135 \endlist
 136
 137 \snippet doc/src/snippets/declarative/comments.qml 0
 138
 139 Comments are ignored by the engine. They are useful for explaining what you
 140 are doing; for referring back to at a later date, or for others reading
 141 your QML files.
 142
 143 Comments can also be used to prevent the execution of code, which is
 144 sometimes useful for tracking down problems.
 145
 146 \code
 147 Text {
 148     text: "Hello world!"
 149     //opacity: 0.5
 150 }
 151 \endcode
 152
 153 In the above example, the Text object will have normal opacity, since the
 154 line opacity: 0.5 has been turned into a comment.
 155
 156 */