diff options
Diffstat (limited to 'src/qml/doc/src/qmllanguageref/syntax/signals.qdoc')
| -rw-r--r-- | src/qml/doc/src/qmllanguageref/syntax/signals.qdoc | 53 |
1 files changed, 52 insertions, 1 deletions
diff --git a/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc b/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc index 8cc13e5e9c..4cb438f85d 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc @@ -85,7 +85,9 @@ This type of signal is a \e {property change signal} and signal handlers for these signals are written in the form \e on<Property>Changed, where \e <Property> is the name of the property, with the first letter capitalized. -For example, the \l MouseArea type has a \l {MouseArea::pressed}{pressed} property. To receive a notification whenever this property changes, write a signal handler named \c onPressedChanged: +For example, the \l MouseArea type has a \l {MouseArea::pressed}{pressed} property. +To receive a notification whenever this property changes, write a signal handler +named \c onPressedChanged: \qml import QtQuick @@ -104,6 +106,55 @@ Even though the \l TapHandler documentation does not document a signal handler named \c onPressedChanged, the signal is implicitly provided by the fact that the \c pressed property exists. +\section2 Signal parameters + +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 +\l{Adding signals to custom QML types} for more information about how signals can be added to +QML components). + +\qml +// Status.qml +import QtQuick + +Item { + id: myitem + signal errorOccurred(message: string, line: int, column: int) +} +\endqml + +\qml +Status { + onErrorOccurred: (mgs, line, col) => console.log(`${line}:${col}: ${msg}`) +} +\endqml + +\note 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: +\qml +Status { + onErrorOccurred: function (message) { console.log(message) } +} +\endqml + +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: +\qml +Status { + onErrorOccurred: (_, _, col) => console.log(`Error happened at column ${col}`) +} +\endqml + +\note 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. + \section2 Using the Connections type In some cases it may be desirable to access a signal outside of the object that |