Document handling signals with parameters in QML

Change-Id: I1fb2a6b744ee1bbef2ceceba119bc8d4bc882144
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
(cherry picked from commit a678309dfd132e1b34662c72b8d8d8515e2826d0)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

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