1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
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
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \page qdeclarativeintroduction.html
30 \inqmlmodule QtQuick 1
31 \title Introduction to the QML Language
35 QML is a declarative language designed to describe the user interface of a
36 program: both what it looks like, and how it behaves. In QML, a user
37 interface is specified as a tree of objects with properties.
39 This introduction is meant for those with little or no programming
40 experience. JavaScript is used as a scripting language in QML, so you may want
41 to learn a bit more about it (see the \l{Javascript Guide}) before diving
42 deeper into QML. It's also helpful to have a basic understanding of other web
43 technologies like HTML and CSS, but it's not required.
45 \section1 Basic QML Syntax
58 source: "pics/logo.png"
59 anchors.centerIn: parent
64 Here we create two objects, a \l Rectangle object and its child
65 \l Image object. Objects are specified by their type, followed by a pair of
66 braces in between which additional data can be defined for the object, such as
67 its property values and any child objects.
69 Properties are specified with a \c {property: value} syntax. In the above example, we
70 can see the \l Image object 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.
73 Properties can be specified one-per-line:
82 or you can put multiple properties on a single line:
85 Rectangle { width: 100; height: 100 }
88 When multiple property/value pairs are specified on a single line, they
89 must be separated by a semicolon.
91 The \c import statement imports the \c QtQuick \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.
98 Commenting in QML is similar to JavaScript.
100 \o Single line comments start with // and finish at the end of the line.
101 \o Multiline comments start with /* and finish with *\/
104 \snippet doc/src/snippets/declarative/comments.qml 0
106 Comments are ignored by the engine. They are useful for explaining what you
107 are doing; for referring back to at a later date, or for others reading
110 Comments can also be used to prevent the execution of code, which is
111 sometimes useful for tracking down problems.
120 In the above example, the \l Text object will have normal opacity, since the
121 line opacity: 0.5 has been turned into a comment.
125 \section1 Object Identifiers
127 Each object can be given a special \e id value that allows the object to be identified
128 and referred to by other objects.
130 For example, below we have two \l Text objects. The first \l Text object
131 has an \c id value of "text1". The second \l Text object can now set its own
132 \c text property value to be the same as that of the first object, by referring to
144 Text { text: text1.text }
148 An object can be referred to by its \c id from anywhere within the \l {QML Documents}{component}
149 in which it is declared. Therefore, an \c id value must always be unique within a single component.
151 The \c id value is a special value for a QML object and should not be thought of as an
152 ordinary object property; for example, it is not possible to access \c text1.id in the
153 above example. Once an object is created, its \c id cannot be changed.
155 Note that an \c id must begin with a lower-case letter or an underscore, and cannot contain
156 characters other than letters, numbers and underscores.
160 \section1 Expressions
162 JavaScript expressions can be used to assign property values. For example:
171 These expressions can include references to other objects and properties, in which case
172 a \l{Property Binding}{binding} is established: when the value of the expression changes,
173 the property to which the expression is assigned is automatically updated to the
174 new value. For example:
182 width: parent.width - 50
189 Here, the \l Rectangle object's \c width property is set relative to the width
190 of its parent. Whenever the parent's width changes, the width of the \l Rectangle is
191 automatically updated.
196 \target intro-properties
198 \section2 Basic Property Types
200 QML supports properties of many types (see \l{QML Basic Types}). The basic types include \c int,
201 \c real, \c bool, \c string and \c color.
205 x: 10.5 // a 'real' property
206 state: "details" // a 'string' property
207 focus: true // a 'bool' property
212 QML properties are what is known as \e type-safe. That is, they only allow you to assign a value that
213 matches the property type. For example, the \c x property of item is a real, and if you try to assign
214 a string to it you will get an error.
218 x: "hello" // illegal!
222 Note that with the exception of \l {Attached Properties}, properties always begin with a lowercase
226 \section2 Property Change Notifications
228 When a property changes value, it can send a signal to notify others of this change.
230 To receive these signals, simply create a \e {signal handler} named with an \c on<Property>Changed
231 syntax. For example, the \l Rectangle element has \l {Item::}{width} and \l {Rectangle::}{color}
232 properties. Below, we have a \l Rectangle object that has defined two signal handlers,
233 \c onWidthChanged and \c onColorChanged, which will automaticallly be called whenever these
234 properties are modified:
238 width: 100; height: 100
240 onWidthChanged: console.log("Width has changed to: " + width)
241 onColorChanged: console.log("Color has changed to: " + color)
245 Signal handlers are explained further \l {Signal Handlers}{below}.
248 \section2 List properties
250 List properties look like this:
261 The list is enclosed in square brackets, with a comma separating the
262 list elements. In cases where you are only assigning a single item to a
263 list, you can omit the square brackets:
267 children: Rectangle {}
271 Items in the list can be accessed by index. See the \l{list}{list type} documentation
272 for more details about list properties and their available operations.
275 \section2 Default Properties
277 Each object type can specify one of its list or object properties as its default property.
278 If a property has been declared as the default property, the property tag can be omitted.
280 For example this code:
290 can be simplified to:
299 because \c changes is the default property of the \c State type.
301 \section2 Grouped Properties
302 \target dot properties
304 In some cases properties form a logical group and use a 'dot' or grouped notation
307 Grouped properties can be written like this:
318 font { pixelSize: 12; bold: true }
322 In the element documentation grouped properties are shown using the 'dot' notation.
324 While you can bind the entire group at once, like below, note that setting any of the
325 grouped properties will result in setting the group and thus invalidate the binding.
332 \section2 Attached Properties
333 \target attached-properties
335 Some objects attach properties to another object. Attached Properties
336 are of the form \e {Type.property} where \e Type is the type of the
337 element that attaches \e property.
339 For example, the \l ListView element attaches the \e ListView.isCurrentItem property
340 to each delegate it creates:
347 color: ListView.isCurrentItem ? "red" : "blue"
358 Another example of attached properties is the \l Keys element which
359 attaches properties for handling key presses to
360 any visual Item, for example:
365 Keys.onSelectPressed: console.log("Selected")
369 \section1 Signal Handlers
371 Signal handlers allow JavaScript code to be executed in response to an event. For
372 example, the \l MouseArea element has an \l {MouseArea::}{onClicked} handler that can
373 be used to respond to a mouse click. Below, we use this handler to print a
374 message whenever the mouse is clicked:
378 width: 100; height: 100
383 console.log("mouse button clicked")
389 All signal handlers begin with \e "on".
391 Some signal handlers include an optional parameter. For example
392 the MouseArea \l{MouseArea::}{onPressed} signal handler has a \c mouse parameter
393 that contains information about the mouse press. This parameter can be referred to in
394 the JavaScript code, as below:
398 acceptedButtons: Qt.LeftButton | Qt.RightButton
400 if (mouse.button == Qt.RightButton)
401 console.log("Right mouse button pressed")