信号和处理程序事件系统

Application and user interface components need to communicate with each other. For example, a button needs to know that the user has clicked on it. The button may change colors to indicate its state or perform some logic. As well, application needs to know whether the user is clicking the button. The application may need to relay this clicking event to other applications.

QML has a signal and handler mechanism, where the signal is the event and the signal is responded to through a 信号处理程序 . When a signal is emitted, the corresponding signal handler is invoked. Placing logic such as a script or other operations in the handler allows the component to respond to the event.

采用信号处理程序接收信号

To receive a notification when a particular signal is emitted for a particular object, the object definition should declare a signal handler named on<Signal> ，其中 <Signal> is the name of the signal, with the first letter capitalized. The signal handler should contain the JavaScript code to be executed when the signal handler is invoked.

例如， Button 类型从 Qt Quick Controls module has a clicked signal, which is emitted whenever the button is clicked. In this case, the signal handler for receiving this signal should be onClicked . In the example below, whenever the button is clicked, the onClicked handler is invoked, applying a random color to the parent Rectangle :

import QtQuick 2.15
import QtQuick.Controls 2.15
Rectangle {
    id: rect
    width: 250; height: 250
    Button {
        anchors.bottom: parent.bottom
        anchors.horizontalCenter: parent.horizontalCenter
        text: "Change color!"
        onClicked: {
            rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1);
        }
    }
}

特性改变信号处理程序

A signal is automatically emitted when the value of a QML property changes. This type of signal is a property change signal and signal handlers for these signals are written in the form on<Property>Changed ，其中 <Property> is the name of the property, with the first letter capitalized.

例如， MouseArea 类型拥有 pressed property. To receive a notification whenever this property changes, write a signal handler named onPressedChanged :

import QtQuick 2.15
Rectangle {
    id: rect
    width: 100; height: 100
    TapHandler {
        onPressedChanged: console.log("taphandler pressed?", pressed)
    }
}

Even though the TapHandler documentation does not document a signal handler named onPressedChanged , the signal is implicitly provided by the fact that the pressed property exists.

使用连接类型

In some cases it may be desirable to access a signal outside of the object that emits it. For these purposes, the QtQuick module provides the Connections type for connecting to signals of arbitrary objects. A Connections object can receive any signal from its specified target .

例如， onClicked handler in the earlier example could have been received by the root Rectangle instead, by placing the onClicked handler in a Connections object that has its target set to the button :

import QtQuick 2.15
import QtQuick.Controls 2.15
Rectangle {
    id: rect
    width: 250; height: 250
    Button {
        id: button
        anchors.bottom: parent.bottom
        anchors.horizontalCenter: parent.horizontalCenter
        text: "Change color!"
    }
    Connections {
        target: button
        function onClicked() {
            rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1);
        }
    }
}

附加信号处理程序

An attached signal handler receives a signal from an attaching type rather than the object within which the handler is declared.

例如， Component.onCompleted is an attached signal handler. It is often used to execute some JavaScript code when its creation process is complete. Here is an example:

import QtQuick 2.15
Rectangle {
    width: 200; height: 200
    color: Qt.rgba(Qt.random(), Qt.random(), Qt.random(), 1)
    Component.onCompleted: {
        console.log("The rectangle's color is", color)
    }
}

The onCompleted handler is not responding to a completed signal from the Rectangle type. Instead, an object of the 组件 attaching type 采用 completed signal has automatically been attached 到 Rectangle object by the QML engine. The engine emits this signal when the Rectangle object is created, thus triggering the Component.onCompleted signal handler.

Attached signal handlers allow objects to be notified of particular signals that are significant to each individual object. If there was no Component.onCompleted attached signal handler, for example, an object could not receive this notification without registering for some special signal from some special object. The attached signal handler mechanism enables objects to receive particular signals without extra code.

见 Attached properties and attached signal handlers for more information on attached signal handlers.

将信号添加到自定义 QML 类型

Signals can be added to custom QML types through the signal 关键词。

The syntax for defining a new signal is:

signal <name>[([<type> <parameter name>[, ...]])]

A signal is emitted by invoking the signal as a method.

For example, the code below is defined in a file named SquareButton.qml . The root Rectangle object has an activated signal, which is emitted whenever the child TapHandler is tapped . In this particular example the activated signal is emitted with the x and y coordinates of the mouse click:

// SquareButton.qml
import QtQuick 2.15
Rectangle {
    id: root
    signal activated(real xPosition, real yPosition)
    property point mouseXY
    property int side: 100
    width: side; height: side
    TapHandler {
        id: handler
        onTapped: root.activated(mouseXY.x, mouseXY.y)
        onPressedChanged: mouseXY = handler.point.position
    }
}

Now any objects of the SquareButton can connect to the activated signal using an onActivated signal handler:

// myapplication.qml
SquareButton {
    onActivated: console.log("Activated at " + xPosition + "," + yPosition)
}

见信号属性 for more details on writing signals for custom QML types.

连接信号到方法和信号

信号对象拥有 connect() method to a connect a signal either to a method or another signal. When a signal is connected to a method, the method is automatically invoked whenever the signal is emitted. This mechanism enables a signal to be received by a method instead of a signal handler.

Below, the messageReceived signal is connected to three methods using the connect() 方法：

import QtQuick 2.15
Rectangle {
    id: relay
    signal messageReceived(string person, string notice)
    Component.onCompleted: {
        relay.messageReceived.connect(sendToPost)
        relay.messageReceived.connect(sendToTelegraph)
        relay.messageReceived.connect(sendToEmail)
        relay.messageReceived("Tom", "Happy Birthday")
    }
    function sendToPost(person, notice) {
        console.log("Sending to post: " + person + ", " + notice)
    }
    function sendToTelegraph(person, notice) {
        console.log("Sending to telegraph: " + person + ", " + notice)
    }
    function sendToEmail(person, notice) {
        console.log("Sending to email: " + person + ", " + notice)
    }
}

In many cases it is sufficient to receive signals through signal handlers rather than using the connect() function. However, using the connect method allows a signal to be received by multiple methods as shown earlier, which would not be possible with signal handlers as they must be uniquely named. Also, the connect method is useful when connecting signals to dynamically created objects .

There is a corresponding disconnect() method for removing connected signals:

Rectangle {
    id: relay
    //...
    function removeTelegraphSignal() {
        relay.messageReceived.disconnect(sendToTelegraph)
    }
}

Signal to signal connect

By connecting signals to other signals, the connect() method can form different signal chains.

import QtQuick 2.15
Rectangle {
    id: forwarder
    width: 100; height: 100
    signal send()
    onSend: console.log("Send clicked")
    TapHandler {
        id: mousearea
        anchors.fill: parent
        onTapped: console.log("Mouse clicked")
    }
    Component.onCompleted: {
        mousearea.tapped.connect(send)
    }
}

Whenever the TapHandler 's tapped signal is emitted, the send signal will automatically be emitted as well.

output:
    MouseArea clicked
    Send clicked