QML Signal and Handler Event System

Signals and Handlers

Signals provide a way to notify other objects when an event has occurred. For example, the MouseArea clicked signal notifies other objects that the mouse has been clicked within the area.

The syntax for defining a new signal is:

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

Attempting to declare two signals or methods with the same name in the same type block generates an error. However, a new signal may reuse the name of an existing signal on the type. (This should be done with caution, as the existing signal may be hidden and become inaccessible.)

Here are various examples of signal declarations:

 Rectangle {
     signal trigger
     signal send (string notice)
     signal perform (string task, variant object)
 }

If the signal has no parameters, the "()" brackets are optional. If parameters are used, the parameter types must be declared, as for the string and variant arguments of the perform signal.

Adding a signal to an item automatically adds a signal handler as well. The signal hander is named on<SignalName>, with the first letter of the signal in uppercase. The previous signals have the following signal handlers:

 onTrigger: console.log("trigger signal emitted")

 onSend: {
     console.log("send signal emitted with notice: " + notice)
 }

 onPerform: console.log("perform signal emitted")

Further, each QML properties have a <property_name>Changed signal and its corresponding on<property_name>Changed signal handler. As a result, property changes may notify other components for any changes.

 Rectangle {
     id: sprite
     width: 25; height: 25
     x: 50; y: 15

     onXChanged: console.log("x property changed, emitted xChanged signal")
     onYChanged: console.log("y property changed, emitted yChanged signal")
 }

To emit a signal, invoke it as a method. The signal handler binding is similar to a property binding and it is invoked when the signal is emitted. Use the defined argument names to access the respective arguments.

 Rectangle {
     id: messenger

     signal send( string person, string notice)

     onSend: {
         console.log("For " + person + ", the notice is: " + notice)
     }

     Component.onCompleted: messenger.send("Tom", "the door is ajar.")
 }

Note that the Component.onCompleted is an attached signal handler; it is invoked when the Component initialization is complete.

 Rectangle {
     id: relay

     signal send( string person, string notice)
     onSend: console.log("Send signal to: " + person + ", " + notice)

     Component.onCompleted: {
         relay.send.connect(sendToPost)
         relay.send.connect(sendToTelegraph)
         relay.send.connect(sendToEmail)
         relay.send("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)
     }
 }

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

     signal send()
     onSend: console.log("Send clicked")

     MouseArea {
         id: mousearea
         anchors.fill: parent
         onClicked: console.log("MouseArea clicked")
     }
     Component.onCompleted: {
         mousearea.clicked.connect(send)
     }
 }

 output:
     MouseArea clicked
     Send clicked