Signal and Handler Event System

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, where <Property> is the name of the property, with the first letter capitalized.

For example, the MouseArea type has a pressed property. To receive a notification whenever this property changes, write a signal handler named onPressedChanged:

import QtQuick

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.

Signals might have parameters. To access those, you should assign a function to the handler. Both arrow functions and anonymous functions work.

For the following examples, consider a Status component with an errorOccurred signal (see Adding signals to custom QML types for more information about how signals can be added to QML components).

// Status.qml
import QtQuick

Item {
    id: myitem
    signal errorOccurred(message: string, line: int, column: int)
}

Status {
    onErrorOccurred: (mgs, line, col) => console.log(`${line}:${col}: ${msg}`)
}

If you do not need to handle all parameters, it is possible to omit trailing ones:

Status {
    onErrorOccurred: function (message) { console.log(message) }
}

It is not possible to leave out leading parameters you are interested in, however you can use some placeholder name to indicate to readers that they are not important:

Status {
    onErrorOccurred: (_, _, col) => console.log(`Error happened at column ${col}`)
}

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.

For example, the 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
import QtQuick.Controls

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.

For example, 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

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 Component attaching type with a completed signal has automatically been attached to the 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.

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

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

import QtQuick

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