Signal and Handler Event System¶
the event system in QML
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 signal handler. 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.
Receiving signals with signal handlers¶
For example, the Button type from the 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 :
Property change signal handlers¶
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
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).
The names of the formal parameters in the function do not have to match those in the signal.
If you do not need to handle all parameters, it is possible to omit trailing ones:
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:
Instead of using a function, it is possible, but discouraged, to use a plain code block. In that case all signal parameters get injected into the scope of the block. However, this can make code difficult to read as it’s unclear where the parameters come from, and results in slower lookups in the QML engine. Injecting parameters in this way is deprecated, and will cause runtime warnings if the parameter is actually used.
Using the Connections type¶
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
Attached signal handlers¶
An attached signal handler receives a signal from an attaching type rather than the object within which the handler is declared.
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.
Adding signals to custom QML types¶
Signals can be added to custom QML types through the
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:
Now any objects of the
SquareButton can connect to the
activated signal using an
onActivated signal handler:
See Signal Attributes for more details on writing signals for custom QML types.
Connecting signals to methods and signals¶
Signal objects have a
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.
messageReceived signal is connected to three methods using the
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:
Signal to signal connect¶
By connecting signals to other signals, the
connect() method can form different signal chains.
Whenever the TapHandler ‘s
tapped signal is emitted, the
send signal will automatically be emitted as well.
output: MouseArea clicked Send clicked
© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.