src/qml/doc/src/syntax/basics.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-syntax-basics.html
  29 \title QML Syntax Basics
  30 \brief Description of the basics of QML syntax
  31
  32 QML is a declarative language that enables objects to be defined in terms of their attributes
  33 and how they relate and respond to changes in other objects. In contrast to imperative code, where changes in attributes and behavior are expressed through a series of statements that are processed step by step, the declarative QML syntax integrates attribute and behavioral changes directly into the definitions of individual objects.
  34
  35 QML source code is generally loaded by the engine through QML \e documents, which are
  36 standalone documents of QML code. These can be used to define \l {QML Object Types}{QML object types} that can then be reused throughout an application.
  37
  38
  39 \section1 Import Statements
  40
  41 A QML document may have one or more imports at the top of the file.
  42 An import can be any one of:
  43
  44 \list
  45 \li a versioned namespace into which types have been registered (e.g., by a plugin)
  46 \li a versioned namespace which provides a module API
  47 \li a relative directory which contains type-definitions as QML documents
  48 \li a JavaScript file
  49 \endlist
  50
  51 Module API imports and JavaScript file imports must be qualified when
  52 imported, so that the properties and methods they provide can be accessed.
  53
  54 The generic form of the various imports are as follows:
  55 \list
  56 \li \tt{import Namespace VersionMajor.VersionMinor}
  57 \li \tt{import Namespace VersionMajor.VersionMinor as ModuleApiIdentifier}
  58 \li \tt{import "directory"}
  59 \li \tt{import "file.js" as ScriptIdentifier}
  60 \endlist
  61
  62 Examples:
  63 \list
  64 \li \tt{import QtQuick 2.0}
  65 \li \tt{import QtQuick.LocalStorage 2.0 as Database}
  66 \li \tt{import "../privateComponents"}
  67 \li \tt{import "somefile.js" as Script}
  68 \endlist
  69
  70 Please see the \l{qtqml-syntax-imports.html}{QML Syntax - Import Statements}
  71 documentation for in-depth information about QML imports.
  72
  73
  74 \section1 Object Declarations
  75
  76 Syntactically, a block of QML code defines a tree of QML objects to be created. Objects are
  77 defined using \e {object declarations} that describe the type of object to be created as well
  78 as the attributes that are to be given to the object. Each object may also declare child objects
  79 using nested object declarations.
  80
  81 An object declaration consists of the name of its object type, followed by a set of curly braces. All attributes and child objects are then declared within these braces.
  82
  83 Here is a simple object declaration:
  84
  85 \qml
  86 Rectangle {
  87     width: 200
  88     height: 200
  89     color: "red"
  90 }
  91 \endqml
  92
  93 This declares an object of type \l Rectangle, followed by a set of curly braces that encompasses the attributes defined for that object. The \l Rectangle type is a type made available by the \l QtQuick module, and the attributes defined in this case are the values of the rectangle's \c width, \c height and \c color properties. (These are properties made available by the \l Rectangle type, as described in the \l Rectangle documentation.)
  94
  95 The above object can be loaded by the engine if it is part of a \l{qtqml-documents-topic.html}{QML document}. That is, if the source code is complemented with \e import statement that imports the QtQuick module (to make the \l Rectangle type available), as below:
  96
  97 \qml
  98 import QtQuick 2.0
  99
 100 Rectangle {
 101     width: 200
 102     height: 200
 103     color: "red"
 104 }
 105 \endqml
 106
 107 When placed into a \c .qml file and loaded by the QML engine, the above code creates a \l Rectangle object using the \l Rectangle type supplied by the QtQuick module:
 108
 109 \image qtqml-syntax-basics-object-declaration.png
 110
 111 \note If an object definition only has a small number of properties, it can be written on a single line like this, with the properties separated by semi-colons:
 112
 113 \qml
 114 Rectangle { width: 200; height: 200; color: "red" }
 115 \endqml
 116
 117 Obviously, the \l Rectangle object declared in this example is very simple indeed, as it defines nothing more than a few property values. To create more useful objects, an object declaration may define many other types of attributes: these are discussed in the \l{qtqml-syntax-object-declaration.html}{Object Declarations} documentation. Additionally, an object declaration may define child objects, as discussed below.
 118
 119
 120 \section2 Child Objects
 121
 122 Any object declaration can define child objects through nested object declarations. In this way, \b {any object declaration implicitly declares an object tree that may contain any number of child objects}.
 123
 124 For example, the \l Rectangle object declaration below includes a \l Gradient object declaration,
 125 which in turn contains two \l GradientStop declarations:
 126
 127 \qml
 128 import QtQuick 2.0
 129
 130 Rectangle {
 131     width: 200
 132     height: 200
 133
 134     gradient: Gradient {
 135         GradientStop { position: 0.0; color: "yellow" }
 136         GradientStop { position: 1.0; color: "green" }
 137     }
 138 }
 139 \endqml
 140
 141 When this code is loaded by the engine, it creates an object tree with a \l Rectangle object at the root; this object has a \l Gradient child object, which in turn has two \l GradientStop children.
 142
 143 Note, however, that this is a parent-child relationship in the context of the QML object tree, not
 144 in the context of the visual scene. The concept of a parent-child relationship in a visual scene is provided by the \l Item type from the \l QtQuick module, which is the base type for most QML types, as most QML objects are intended to be visually rendered. For example, \l Rectangle and \l Text are both \l {Item}-based types, and below, a \l Text object has been declared as a visual child of a \l Rectangle object:
 145
 146 \qml
 147 import QtQuick 2.0
 148
 149 Rectangle {
 150     width: 200
 151     height: 200
 152     color: "red"
 153
 154     Text {
 155         anchors.centerIn: parent
 156         text: "Hello, QML!"
 157     }
 158 }
 159 \endqml
 160
 161 When the \l Text object refers to its \l {Item::parent}{parent} value in the above code, it is referring to its \e {visual parent}, not the parent in the object tree. In this case, they are one and the same: the \l Rectangle object is the parent of the \l Text object in both the context of the QML object tree as well as the context of the visual scene. However, while the \l {Item::parent}{parent} property can be modified to change the visual parent, the parent of an object in the context of the object tree cannot be changed from QML.
 162
 163 (Additionally, notice that the \l Text object has been declared without assigning it to a property of the \l Rectangle, unlike the earlier example which assigned a \l Gradient object to the rectangle's \c gradient property. This is because the \l {Item::children}{children} property of \l Item has been set as the type's \l {qtqml-syntax-objectattributes.html#default-properties}{default property} to enable this more convenient syntax.)
 164
 165 See the \l{qtquick-concepts-visual.html#items-and-visual-parenting}{Visual Parent} documentation for more information on the concept of visual parenting with the \l Item type.
 166
 167
 168 \section1 Comments
 169
 170 The syntax for commenting in QML is similar to that of JavaScript:
 171
 172 \list
 173 \li Single line comments start with // and finish at the end of the line.
 174 \li Multiline comments start with /* and finish with *\/
 175 \endlist
 176
 177 \snippet qml/comments.qml 0
 178
 179 Comments are ignored by the engine when processing QML code. They are useful for explaining what a section of code is doing, whether for reference at a later date or for explaining the implementation to others.
 180
 181 Comments can also be used to prevent the execution of code, which is sometimes useful for tracking down problems.
 182
 183 \qml
 184     Text {
 185         text: "Hello world!"
 186         //opacity: 0.5
 187     }
 188 \endqml
 189
 190 In the above example, the \l Text object will have normal opacity, since the line opacity: 0.5 has been turned into a comment.
 191 */