Introduction to the QML Language

oskycar 2014-06-20

展开全文

Introduction to the QML Language

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.

QML是一个说明性语言，用来描述程序的用户界面：它的外观以及它的行为。在QML中，一个用户界面作为一个带有属性的对象树。

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.

本篇是为有很少或没有编程经验的人准备的。JavaScript是用来作为QML的脚本语言，所以你可能想对它了解多一点（JavaScript：The Definitive Guide），然后再深入QML。另外如HTML与CSS等Web 技术的基础原理也是有帮助的；但它不是必需的。

Basic QML Syntax

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.

在上面的示例中，有两个对象，一个Rectangle［矩形］与一个Image［图像］。对象是指定的类型，紧随其后是一对大括号，在大括号之间是关于该对象特定的信息，例如它们的属性。

Properties are specified with a property: value syntax. In the above example, we can see the Image object has a property namedsource, which has been assigned the value "pics/logo.png". The property and its value are separated by a colon.

属性是以property［属性］: value［值］形式指定的。在上面的示例中，我们可以看到图像有个名为source的属性，它的值被指定为“pics/logo.png ”。该属性与它的值是由冒号来分隔。

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 module, which contains all of the standard QML Elements. Without this import statement, theRectangle and Image elements would not be available.

Import语句导入Qt模块，它包含所有标准的QML元素。如果没有Import语句；那么Rectangle与Image元素将无效。

Comments

Commenting in QML is similar to JavaScript.

在QML中的注释类似于JavaScript。

Single line comments start with // and finish at the end of the line.
单选注释以 // 开始。
Multiline comments start with /* and finish with */
多行注释以 /* 开始，以 */ 结束。

 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
 }

In the above example, the Text object will have normal opacity, since the line opacity: 0.5 has been turned into a comment.

在上面的示例中，这个Text对象将正常显示，一旦opacity: 0.5这行关掉注释，这是以半透明方式显示文本。

Object Identifiers

Each object can be given a special id value that allows the object to be identified and referred to by other objects.

每个对象会有一个指定的id，它允许这个对象被识别和被其他对象引用。

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:

例如，下面我们有两个Text对象，第一个Text对象的id为text1。通过引用text1.text，第二个Text对象能设置它的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.

在component被声明的地方，通过id一个对象能在任何地方被引用。因此，一个id值在单个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.

对于QML对象id值是一个特别值，不能被认识是一个普通的对象属性；例如，在上面的例子中访问text1.id是不可能的。一旦一个对象被创建，它的id就不能被改变。

Note that an id must begin with a lower-case letter or an underscore, and cannot contain characters other than letters, numbers and underscores.

请注意，一个id首字符必须是小写字母或下划线并且不能包含字母，数字和下划线以外的字符。

Expressions

JavaScript expressions can be used to assign property values. For example:

JavaScript表达式可以用来赋值属性的值。

 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:

这些表达式可以包含其它的对象与属性的引用，在这种情况下就会建立binding【约束关联】：当该表达式改变值时；该属性值将自动更新。

 Item {
     width: 300
     height: 300

     Rectangle {
         width: parent.width - 50
         height: 100
         color: "yellow"
     }
 }

Here, the Rectangle object's 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.

在上面的示例中，Rectangle对象的width属性被设置为和它父的width值相关。如果它父的width值改变；那么Rectangle的width也将自动更新为相同的值。

Properties

Basic Property Types

QML supports properties of many types (see QML Basic Types). The basic types include int, real, bool, string and color.

QML支持许多类型的属性。基本类型包括int、real、bool、string和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.

QML属性是有类型安全检测的。也就是说，它们只允许你指定一个与属性类型相匹配的值。例如，项目x属性类型是real，如果你赋值一个string；那么将会得到错误的信息。

[cpp] view plain copy

Item {
x: "hello" // illegal!
}

Note that with the exception of Attached Properties, properties always begin with a lowercase letter.

属性命名以首字母为小字（附加属性除外）。

Property Change Notifications

When a property changes value, it can send a signal to notify others of this change.

当一个属性的值改变了，它会发送信号通知其他属性这个变化。

To receive these signals, simply create a signal handler 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 andonColorChanged, which will automaticallly be called whenever these properties are modified:

为了接收信号，很简单，创建signal handler，命名为on<Property>Changed 。例如，Rectangle元素有width和color属性。下面，Rectangle定义了两个signal handler，onWidthChanged 和onColorChanged，当这些属性被修改时，它们会自动被调用。

 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.

下面会更详细的解释Signal handlers。

List properties

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.

列表里的项可以通过索引来访问。关于列表属性和它们可用的操作可以参考list type文档来获取更多信息。

Default Properties

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 {}
 }

because changes is the default property of the State type.

因为changes是State类型的默认属性。

Grouped Properties

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.

在元素文件分组属性使用'.'符号显示。

Attached Properties

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.

有些对象的属性附加到另一个对象。附加属性的形式为Type.property其中Type是附加property元素的类型。

For example, the ListView element attaches the ListView.isCurrentItem property to each delegate it creates:

ListView元素附加ListView.isCurrentItem属性到每个它创建的代理上。

 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:

另一个附加属性的例子就是Keys元素，它用于处理任意可视项目上的按键，例如：

 Item {
     focus: true
     Keys.onSelectPressed: console.log("Selected")
 }

Signal Handlers

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:

Signal handlers 允许用JavaScript 代码来处理一个事件的响应。例如，MouseArea元素有onClicked信号处理器来处理鼠标单击。下面，我们用这个处理器来打印鼠标单击的信息：

 Item {
     width: 100; height: 100

     MouseArea {
         anchors.fill: parent
         onClicked: {
             console.log("mouse button clicked")
         }
     }
 }

All signal handlers begin with "on".

所有信号处理器都以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 onPressed信号处理程序有mouse 参数，它包含了鼠标按下的信息。这个参数能被引用到JavaScript代码里，如下：

 MouseArea {
     acceptedButtons: Qt.LeftButton | Qt.RightButton
     onPressed: {
         if (mouse.button == Qt.RightButton)
             console.log("Right mouse button pressed")
     }
 }