QML is a declarative language designed to describe the user interface of a program: both what it looks like, and how it behaves. In QML, a user interface is specified as a tree of objects with properties.
This introduction is meant for those with little or no programming experience. JavaScript is used as a scripting language in QML, so you may want to learn a bit more about it (see the Javascript Guide ) before diving deeper into QML. It's also helpful to have a basic understanding of other web technologies like HTML and CSS, but it's not required.
QML looks like this:
import QtQuick 1.0 Rectangle { width: 200 height: 200 color: "blue" Image { source: "pics/logo.png" anchors.centerIn: parent } }
Here we create two objects, a Rectangle object and its child Image object. Objects are specified by their type, followed by a pair of braces in between which additional data can be defined for the object, such as its property values and any child objects.
Properties are specified with a
property: value
syntax. In the above example, we can see the
Image
object has a property named
source
, which has been assigned the value
"pics/logo.png"
. The property and its value are separated by a colon.
Properties can be specified one-per-line:
Rectangle { width: 100 height: 100 }
or you can put multiple properties on a single line:
Rectangle { width: 100; height: 100 }
When multiple property/value pairs are specified on a single line, they must be separated by a semicolon.
The
import
statement imports the
QtQuick
模块
, which contains all of the standard
QML 元素
. Without this import statement, the
Rectangle
and
Image
elements would not be available.
Commenting in QML is similar to JavaScript.
Text { text: "Hello world!" //a basic greeting /* We want this text to stand out from the rest so we give it a large size and different font. */ font.family: "Helvetica" font.pointSize: 24 }
Comments are ignored by the engine. They are useful for explaining what you are doing; for referring back to at a later date, or for others reading your QML files.
Comments can also be used to prevent the execution of code, which is sometimes useful for tracking down problems.
Text { text: "Hello world!" //opacity: 0.5 }
在以上范例中， Text object will have normal opacity, since the line opacity: 0.5 has been turned into a comment.
Each object can be given a special id value that allows the object to be identified and referred to by other objects.
For example, below we have two
Text
objects. The first
Text
object has an
id
value of "text1". The second
Text
object can now set its own
text
property value to be the same as that of the first object, by referring to
text1.text
:
import QtQuick 1.0 Row { Text { id: text1 text: "Hello World" } Text { text: text1.text } }
An object can be referred to by its
id
from anywhere within the
component
in which it is declared. Therefore, an
id
value must always be unique within a single component.
The
id
value is a special value for a QML object and should not be thought of as an ordinary object property; for example, it is not possible to access
text1.id
in the above example. Once an object is created, its
id
cannot be changed.
Note that an
id
must begin with a lower-case letter or an underscore, and cannot contain characters other than letters, numbers and underscores.
JavaScript expressions can be used to assign property values. For example:
Item { width: 100 * 3 height: 50 + 22 }
These expressions can include references to other objects and properties, in which case a binding is established: when the value of the expression changes, the property to which the expression is assigned is automatically updated to the new value. For example:
Item { width: 300 height: 300 Rectangle { width: parent.width - 50 height: 100 color: "yellow" } }
在这里，
Rectangle
对象的
width
property is set relative to the width of its parent. Whenever the parent's width changes, the width of the
Rectangle
is automatically updated.
QML supports properties of many types (see
QML 基本类型
). The basic types include
int
,
real
,
bool
,
string
and
color
.
Item { x: 10.5 // a 'real' property state: "details" // a 'string' property focus: true // a 'bool' property // ... }
QML properties are what is known as
type-safe
. That is, they only allow you to assign a value that matches the property type. For example, the
x
property of item is a real, and if you try to assign a string to it you will get an error.
Item {
x: "hello" // illegal!
}
Note that with the exception of 附加特性 , properties always begin with a lowercase letter.
When a property changes value, it can send a signal to notify others of this change.
To receive these signals, simply create a
信号处理程序
named with an
on<Property>Changed
syntax. For example, the
Rectangle
element has
width
and
color
properties. Below, we have a
Rectangle
object that has defined two signal handlers,
onWidthChanged
and
onColorChanged
, which will automaticallly be called whenever these properties are modified:
Rectangle { width: 100; height: 100 onWidthChanged: console.log("Width has changed to:", width) onColorChanged: console.log("Color has changed to:", color) }
Signal handlers are explained further below .
List properties look like this:
Item { children: [ Image {}, Text {} ] }
The list is enclosed in square brackets, with a comma separating the list elements. In cases where you are only assigning a single item to a list, you can omit the square brackets:
Image { children: Rectangle {} }
Items in the list can be accessed by index. See the list type documentation for more details about list properties and their available operations.
Each object type can specify one of its list or object properties as its default property. If a property has been declared as the default property, the property tag can be omitted.
For example this code:
State { changes: [ PropertyChanges {}, PropertyChanges {} ] }
can be simplified to:
State { PropertyChanges {} PropertyChanges {} }
因为
changes
is the default property of the
状态
类型。
In some cases properties form a logical group and use a 'dot' or grouped notation to show this.
Grouped properties can be written like this:
Text { font.pixelSize: 12 font.bold: true }
or like this:
Text { font { pixelSize: 12; bold: true } }
In the element documentation grouped properties are shown using the 'dot' notation.
Some objects attach properties to another object. Attached Properties are of the form Type.property where Type is the type of the element that attaches property .
例如， ListView element attaches the ListView.isCurrentItem property to each delegate it creates:
Component { id: myDelegate Text { text: "Hello" color: ListView.isCurrentItem ? "red" : "blue" } }
ListView { delegate: myDelegate }
Another example of attached properties is the Keys element which attaches properties for handling key presses to any visual Item, for example:
Item { focus: true Keys.onSelectPressed: console.log("Selected") }
Signal handlers allow JavaScript code to be executed in response to an event. For example, the MouseArea element has an onClicked handler that can be used to respond to a mouse click. Below, we use this handler to print a message whenever the mouse is clicked:
Item { width: 100; height: 100 MouseArea { anchors.fill: parent onClicked: { console.log("mouse button clicked") } } }
All signal handlers begin with "on" .
Some signal handlers include an optional parameter. For example the
MouseArea
onPressed
signal handler has a
mouse
parameter that contains information about the mouse press. This parameter can be referred to in the JavaScript code, as below:
MouseArea { acceptedButtons: Qt.LeftButton | Qt.RightButton onPressed: { if (mouse.button == Qt.RightButton) console.log("Right mouse button pressed") } }