QML
Encyclopedia
QML is a JavaScript
-based, declarative
language for designing user interface–centric applications. It is part of Qt Quick
, the UI creation kit developed by Nokia within the Qt framework. QML is mainly used for mobile applications where touch input, fluid animations (60 ) and user experience are crucial.
QML documents describe an object tree of elements. QML elements shipped with Qt are a sophisticated set of building blocks, graphical (e.g., rectangle, image) and behavioral (e.g., state, transition, animation). These elements can be combined to build components ranging in complexity from simple buttons and sliders, to complete internet-enabled programs.
QML elements can be augmented by standard JavaScript
both inline and via included .js files. Elements can also be seamlessly integrated and extended by C++
components using the Qt framework.
The language name is QML. The runtime name is Qt Declarative.
import QtQuick 1.0
Rectangle {
id: canvas
width: 200
height: 200
color: "blue"
Image {
id: logo
source: "pics/logo.png"
anchors.centerIn: parent
x: canvas.height / 5
}
}
Objects are specified by their type, followed by a pair of braces. Object types always begin with a capital letter. In the above example, there are two objects, a Rectangle; and its child, an Image. Between the braces, one can specify information about the object, such as its properties.
Properties are specified as property: value. In the above example, we can see the Image has a property named source, which has been assigned the value "pics/logo.png". The property and its value are separated by a colon.
The id property
Each object can be given a special unique property called an id. Assigning an id enables the object to be referred to by other objects and scripts.
The first Rectangle element below has an id, "myRect". The second Rectangle element defines its own width by referring to myRect.width, which means it will have the same width value as the first Rectangle element.
Item {
Rectangle {
id: myRect
width: 100
height: 100
}
Rectangle {
width: myRect.width
height: 200
}
}
Note that an id must begin with a lower-case letter or an underscore, and cannot contain characters other than letters, numbers and underscores.
Property bindings are created implicitly in QML whenever a property is assigned a JavaScript expression. The following QML uses two property bindings to connect the size of the rectangle to that of otherItem.
Rectangle {
width: otherItem.width
height: otherItem.height
}
QML extends a standards compliant JavaScript engine, so any valid JavaScript expression can be used as a property binding. Bindings can access object properties, make function calls and even use builtin JavaScript objects like Date and Math.
Example:
Rectangle {
function calculateMyHeight {
return Math.max(otherItem.height, thirdItem.height);
}
anchors.centerIn: parent
width: Math.min(otherItem.width, 10)
height: calculateMyHeight
color: { if (width > 10) "blue"; else "red" }
}
Example:
In the default state myRect is positioned at 0,0. In the "moved" state it is positioned at 50,50. Clicking within the mouse area changes the state from the default state to the "moved" state, thus moving the rectangle.
import QtQuick 1.0
Item {
id: myItem
width: 200; height: 200
Rectangle {
id: myRect
width: 100; height: 100
color: "red"
}
states: [
State {
name: "moved"
PropertyChanges {
target: myRect
x: 50
y: 50
}
}
]
MouseArea {
anchors.fill: parent
onClicked: myItem.state = 'moved'
}
}
State changes can be animated using Transitions.
For example, adding this code to the above Item element animates the transition to the "moved" state:
transitions: [
Transition {
NumberAnimation { properties: "x,y"; duration: 500 }
}
]
QML supports three main forms of animation: basic property animation, transitions, and property behaviors.
The simplest form of animation is a PropertyAnimation, which can animate all of the property types listed above.
A property animation can be specified as a value source using the Animation on property syntax. This is especially useful for repeating animations.
The following example creates a bouncing effect:
Rectangle {
id: rect
width: 120; height: 200
Image {
id: img
source: "pics/qt.png"
x: 60 - img.width/2
y: 0
SequentialAnimation on y {
loops: Animation.Infinite
NumberAnimation { to: 200 - img.height; easing.type: Easing.OutBounce; duration: 2000 }
PauseAnimation { duration: 1000 }
NumberAnimation { to: 0; easing.type: Easing.OutQuad; duration: 1000 }
}
}
}
Familiar concepts
QML provides direct access to the following concepts from Qt:
MouseArea {
onPressed: console.log("mouse button pressed")
}
All signal handlers begin with "on".
IDE 2.1.
JavaScript
JavaScript is a prototype-based scripting language that is dynamic, weakly typed and has first-class functions. It is a multi-paradigm language, supporting object-oriented, imperative, and functional programming styles....
-based, declarative
Declarative programming
In computer science, declarative programming is a programming paradigm that expresses the logic of a computation without describing its control flow. Many languages applying this style attempt to minimize or eliminate side effects by describing what the program should accomplish, rather than...
language for designing user interface–centric applications. It is part of Qt Quick
Qt Quick
Qt Quick is a framework that provides a declarative way of building custom, highly dynamic user interfaces with fluid transitions and effects, which are becoming more and more common especially in mobile devices....
, the UI creation kit developed by Nokia within the Qt framework. QML is mainly used for mobile applications where touch input, fluid animations (60 ) and user experience are crucial.
QML documents describe an object tree of elements. QML elements shipped with Qt are a sophisticated set of building blocks, graphical (e.g., rectangle, image) and behavioral (e.g., state, transition, animation). These elements can be combined to build components ranging in complexity from simple buttons and sliders, to complete internet-enabled programs.
QML elements can be augmented by standard JavaScript
JavaScript
JavaScript is a prototype-based scripting language that is dynamic, weakly typed and has first-class functions. It is a multi-paradigm language, supporting object-oriented, imperative, and functional programming styles....
both inline and via included .js files. Elements can also be seamlessly integrated and extended by C++
C++
C++ is a statically typed, free-form, multi-paradigm, compiled, general-purpose programming language. It is regarded as an intermediate-level language, as it comprises a combination of both high-level and low-level language features. It was developed by Bjarne Stroustrup starting in 1979 at Bell...
components using the Qt framework.
The language name is QML. The runtime name is Qt Declarative.
Basic syntax
Example:import QtQuick 1.0
Rectangle {
id: canvas
width: 200
height: 200
color: "blue"
Image {
id: logo
source: "pics/logo.png"
anchors.centerIn: parent
x: canvas.height / 5
}
}
Objects are specified by their type, followed by a pair of braces. Object types always begin with a capital letter. In the above example, there are two objects, a Rectangle; and its child, an Image. Between the braces, one can specify information about the object, such as its properties.
Properties are specified as property: value. In the above example, we can see the Image has a property named source, which has been assigned the value "pics/logo.png". The property and its value are separated by a colon.
The id property
Each object can be given a special unique property called an id. Assigning an id enables the object to be referred to by other objects and scripts.
The first Rectangle element below has an id, "myRect". The second Rectangle element defines its own width by referring to myRect.width, which means it will have the same width value as the first Rectangle element.
Item {
Rectangle {
id: myRect
width: 100
height: 100
}
Rectangle {
width: myRect.width
height: 200
}
}
Note that an id must begin with a lower-case letter or an underscore, and cannot contain characters other than letters, numbers and underscores.
Property bindings
A property binding specifies the value of a property in a declarative way. The property value is automatically updated if the other properties or data values change.Property bindings are created implicitly in QML whenever a property is assigned a JavaScript expression. The following QML uses two property bindings to connect the size of the rectangle to that of otherItem.
Rectangle {
width: otherItem.width
height: otherItem.height
}
QML extends a standards compliant JavaScript engine, so any valid JavaScript expression can be used as a property binding. Bindings can access object properties, make function calls and even use builtin JavaScript objects like Date and Math.
Example:
Rectangle {
function calculateMyHeight {
return Math.max(otherItem.height, thirdItem.height);
}
anchors.centerIn: parent
width: Math.min(otherItem.width, 10)
height: calculateMyHeight
color: { if (width > 10) "blue"; else "red" }
}
States
States are a mechanism to combine changes to properties in a semantic unit. A button for example has a pressed- and a non-pressed state, an address book application could have a read-only and an edit state for contacts. Every element has an "implicit" base state. Every other state is described by listing the properties and values of those elements which differ from the base state.Example:
In the default state myRect is positioned at 0,0. In the "moved" state it is positioned at 50,50. Clicking within the mouse area changes the state from the default state to the "moved" state, thus moving the rectangle.
import QtQuick 1.0
Item {
id: myItem
width: 200; height: 200
Rectangle {
id: myRect
width: 100; height: 100
color: "red"
}
states: [
State {
name: "moved"
PropertyChanges {
target: myRect
x: 50
y: 50
}
}
]
MouseArea {
anchors.fill: parent
onClicked: myItem.state = 'moved'
}
}
State changes can be animated using Transitions.
For example, adding this code to the above Item element animates the transition to the "moved" state:
transitions: [
Transition {
NumberAnimation { properties: "x,y"; duration: 500 }
}
]
Animation
Animations in QML are done by animating properties of objects. Properties of type real, int, color, rect, point, size, and vector3d can all be animated.QML supports three main forms of animation: basic property animation, transitions, and property behaviors.
The simplest form of animation is a PropertyAnimation, which can animate all of the property types listed above.
A property animation can be specified as a value source using the Animation on property syntax. This is especially useful for repeating animations.
The following example creates a bouncing effect:
Rectangle {
id: rect
width: 120; height: 200
Image {
id: img
source: "pics/qt.png"
x: 60 - img.width/2
y: 0
SequentialAnimation on y {
loops: Animation.Infinite
NumberAnimation { to: 200 - img.height; easing.type: Easing.OutBounce; duration: 2000 }
PauseAnimation { duration: 1000 }
NumberAnimation { to: 0; easing.type: Easing.OutQuad; duration: 1000 }
}
}
}
Qt/C++ integration
QML does not need Qt/C++ knowledge to use, but it can be easily extended via Qt.Familiar concepts
QML provides direct access to the following concepts from Qt:
- QAction – the action type
- QObject signals and slots – available as functions to call in JavaScript
- QObject properties – available as variables in JavaScript
- QWidget – QDeclarativeView is a QML-displaying widget
- Q*Model – used directly in data binding (e.g. QAbstractItemModel)
Qt signal handlers
Signal handlers allow actions to be taken in response to an event. For instance, the MouseArea element has signal handlers to handle mouse press, release and click:MouseArea {
onPressed: console.log("mouse button pressed")
}
All signal handlers begin with "on".
How-tos
- Calling Qt class methods from QML
- Creating a custom QML element with Qt
- Connecting Qt signal to QML function
Development tools
Because QML and JavaScript are very similar almost all code editors supporting JavaScript will do the job. Yet full support for syntax highlighting, code completion, integrated help and also a technical preview of a WYSIWYG editor is available in the free and cross-platform Qt CreatorQt Creator
Qt Creator is a cross-platform C++ integrated development environment which is part of the Qt SDK. It includes a visual debugger and an integrated GUI layout and forms designer. The editor's features includes syntax highlighting and autocompletion, but not tabs. Qt Creator uses the C++ compiler...
IDE 2.1.