Система событий сигналов и обработчиков

Компоненты приложения и пользовательского интерфейса должны взаимодействовать друг с другом. Например, кнопка должна знать, что пользователь нажал на неё. Кнопка может изменить цвет, чтобы указать своё состояние, или выполнить какой-либо логический оператор. Также приложение должно знать, нажимает ли пользователь на кнопку. Приложение может передать это событие нажатия на другие приложения.

QML имеет механизм сигналов и обработчиков, где сигнал — это событие, а на сигнал реагируют через обработчик сигнала. Когда испускается сигнал, вызывается соответствующий обработчик сигнала. Размещение логики, такой как скрипт или другие операции, в обработчике позволяет компоненту реагировать на событие.

Получение сигналов с помощью обработчиков сигналов

Чтобы получить уведомление при испускании определённого сигнала для определённого объекта, определение объекта должно объявлять обработчик сигнала с именем on<Signal>, где <Signal> — это имя сигнала с заглавной первой буквой. Обработчик сигнала должен содержать код JavaScript, который будет выполняться при вызове обработчика сигнала.

Например, тип Button из модуля Qt Quick Controls имеет clicked сигнал, который испускается всякий раз, когда кнопка нажимается. В этом случае обработчик сигнала для получения этого сигнала должен быть onClicked. В примере ниже, всякий раз, когда нажимается кнопка, вызывается обработчик onClicked, применяющий случайный цвет к родительскому Rectangle:

import QtQuick 2.14
import QtQuick.Controls 2.14

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);
        }
    }
}

Обработчики сигналов изменения свойств

Сигнал автоматически испускается при изменении значения свойства QML. Этот тип сигнала — сигнал изменения свойства, а обработчики сигналов для этих сигналов записываются в форме on<Property>Changed, где <Property> — это имя свойства с заглавной первой буквой.

Например, тип MouseArea имеет свойство pressed. Чтобы получать уведомления всякий раз, когда это свойство изменяется, напишите обработчик сигнала с именем onPressedChanged:

import QtQuick 2.14

Rectangle {
    id: rect
    width: 100; height: 100

    TapHandler {
        onPressedChanged: console.log("taphandler pressed?", pressed)
    }
}

Несмотря на то, что документация TapHandler не документирует обработчик сигнала с именем onPressedChanged, сигнал неявно предоставляется тем, что существует свойство pressed.

Использование типа Connections

В некоторых случаях может быть желательно получить доступ к сигналу за пределами объекта, который его испускает. Для этих целей модуль QtQuick предоставляет тип Connections для подключения к сигналам произвольных объектов. Объект Connections может получать любой сигнал от своего указанного target.

Например, обработчик onClicked в предыдущем примере мог быть получен корневым Rectangle вместо этого, поместив обработчик onClicked в объект Connections, у которого свойство target установлено на button:

import QtQuick 2.14
import QtQuick.Controls 2.14

Rectangle {
    id: rect
    width: 250; height: 250

    Button {
        id: button
        anchors.bottom: parent.bottom
        anchors.horizontalCenter: parent.horizontalCenter
        text: "Change color!"
    }

    Connections {
        target: button
        onClicked: {
            rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1);
        }
    }
}

Прикрепленные обработчики сигналов

Прикрепленный обработчик сигнала получает сигнал от типа прикрепления, а не от объекта, в котором объявлен обработчик.

Например, Component.onCompleted — это прикреплённый обработчик сигнала. Он часто используется для выполнения некоторого кода JavaScript, когда процесс его создания завершён. Вот пример:

import QtQuick 2.14

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

Обработчик onCompleted не реагирует на сигнал completed типа Rectangle. Вместо этого объект типа Component прикрепляемого типа со сигналом completed был автоматически прикреплён к объекту Rectangle движком QML. Движок испускает этот сигнал при создании объекта Rectangle, тем самым вызывая обработчик сигнала Component.onCompleted.

Прикрепленные обработчики сигналов позволяют уведомлять объекты о конкретных сигналах, которые важны для каждого отдельного объекта. Если бы не было Component.onCompleted прикреплённого обработчика сигнала, например, объект не мог бы получить это уведомление без регистрации на какой-то специальный сигнал от какого-то специального объекта. Механизм прикреплённого обработчика сигнала позволяет объектам получать конкретные сигналы без дополнительного кода.

См. Прикреплённые свойства и прикреплённые обработчики сигналов для получения дополнительной информации о прикреплённых обработчиках сигналов.

Добавление сигналов к пользовательским типам QML

Сигналы могут быть добавлены к пользовательским типам QML через ключевое слово signal.

Синтаксис определения нового сигнала:

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

Сигнал испускается путём вызова сигнала как метода.

Например, код ниже определён в файле с именем SquareButton.qml. Корневой объект Rectangle имеет сигнал activated, который испускается всякий раз, когда дочерний TapHandler tapped. В этом примере сигнал activated испускается с координатами x и y нажатия мыши:

// SquareButton.qml
import QtQuick 2.14

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

Теперь любые объекты типа SquareButton могут подключиться к сигналу activated с помощью обработчика сигнала onActivated:

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

См. Атрибуты сигнала для получения дополнительной информации о написании сигналов для пользовательских типов QML.

Подключение сигналов к методам и сигналам

Объекты сигналов имеют метод connect() для подключения сигнала либо к методу, либо к другому сигналу. Когда сигнал подключён к методу, метод автоматически вызывается всякий раз, когда испускается сигнал. Этот механизм позволяет сигналу получать метод вместо обработчика сигнала.

Ниже, сигнал messageReceived подключён к трём методам с использованием метода connect():

import QtQuick 2.14

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

Во многих случаях достаточно получать сигналы через обработчики сигналов, а не использовать функцию connect(). Однако использование метода connect позволяет сигналу получать несколько методов, как показано ранее, что невозможно с обработчиками сигналов, так как они должны иметь уникальные имена. Кроме того, метод connect полезен при подключении сигналов к динамически созданным объектам.

Существует соответствующий метод disconnect() для удаления подключенных сигналов:

Rectangle {
    id: relay
    //...

    function removeTelegraphSignal() {
        relay.messageReceived.disconnect(sendToTelegraph)
    }
}

Подключение сигнала к сигналу

Подключая сигналы к другим сигналам, метод connect() может формировать различные цепочки сигналов.

import QtQuick 2.14

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

Всякий раз, когда сигнал tapped TapHandler испускается, сигнал send также автоматически испускается.

output:
    MouseArea clicked
    Send clicked