Doc: Use input handlers and controls wherever appropriate

In addition, changed the \section titles to sentence case.

Change-Id: If62cc8f2a3f6a99123ccfb4d030d3f58a2fe8dea
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

3 files changed, 199 insertions, 198 deletions

diff --git a/src/qml/doc/snippets/qml/integrating-javascript/connectjs.qml b/src/qml/doc/snippets/qml/integrating-javascript/connectjs.qml
index 8243c34b2e..3f50c67aba 100644
--- a/src/qml/doc/snippets/qml/integrating-javascript/connectjs.qml
+++ b/src/qml/doc/snippets/qml/integrating-javascript/connectjs.qml
@@ -48,20 +48,19 @@
 **
 ****************************************************************************/
 //![0]
-import QtQuick 2.0
+import QtQuick 2.12
 import "script.js" as MyScript
 
 Item {
     id: item
     width: 200; height: 200
 
-    MouseArea {
-        id: mouseArea
-        anchors.fill: parent
+    TapHandler {
+        id: inputHandler
     }
 
     Component.onCompleted: {
-        mouseArea.clicked.connect(MyScript.jsFunction)
+        inputHandler.tapped.connect(MyScript.jsFunction)
     }
 }
 //![0]
diff --git a/src/qml/doc/src/javascript/expressions.qdoc b/src/qml/doc/src/javascript/expressions.qdoc
index e80016cb67..b83127389a 100644
--- a/src/qml/doc/src/javascript/expressions.qdoc
+++ b/src/qml/doc/src/javascript/expressions.qdoc
@@ -32,15 +32,15 @@
 
 The \l{JavaScript Host Environment} provided by QML can run valid standard
 JavaScript constructs such as conditional operators, arrays, variable setting,
-loops. In addition to the standard JavaScript properties, the \l {QML Global
+and loops. In addition to the standard JavaScript properties, the \l {QML Global
 Object} includes a number of helper methods that simplify building UIs and
 interacting with the QML environment.
 
 The JavaScript environment provided by QML is stricter than that in a web
-browser.  For example, in QML you cannot add to, or modify, members of the
-JavaScript global object.  In regular JavaScript, it is possible to do this
+browser. For example, in QML you cannot add to, or modify, members of the
+JavaScript global object. In regular JavaScript, it is possible to do this
 accidentally by using a variable without declaring it. In QML this will throw
-an exception, so all local variables must be explicitly declared.  See
+an exception, so all local variables must be explicitly declared. See
 \l{JavaScript Environment Restrictions} for a complete description of the
 restrictions on JavaScript code executed from QML.
 
@@ -49,7 +49,7 @@ Various parts of \l{QML Documents}{QML documents} can contain JavaScript code:
 \list 1
   \li The body of \l{Property Binding}{property bindings}. These JavaScript
       expressions describe relationships between QML object \l{Property Attributes}
-      {properties}. When any of a property's \e dependencies change, the property
+      {properties}. When \e dependencies of a property change, the property
       is automatically updated too, according to the specified relationship.
   \li The body of \l{Signal Attributes}{Signal handlers}. These JavaScript
       statements are automatically evaluated whenever a QML object emits the
@@ -66,42 +66,41 @@ Various parts of \l{QML Documents}{QML documents} can contain JavaScript code:
 
 
 
-\section1 JavaScript in Property Bindings
+\section1 JavaScript in property bindings
 
-In the following example, the \l Rectangle's \c color depends on the
-\l MouseArea's \c pressed property. This relationship is described using a
+In the following example, the \c color property of \l Rectangle depends on the
+\c pressed property of \l TapHandler. This relationship is described using a
 conditional expression:
 
 \qml
-import QtQuick 2.0
+import QtQuick 2.12
 
 Rectangle {
     id: colorbutton
     width: 200; height: 80;
 
-    color: mousearea.pressed ? "steelblue" : "lightsteelblue"
+    color: inputHandler.pressed ? "steelblue" : "lightsteelblue"
 
-    MouseArea {
-        id: mousearea
-        anchors.fill: parent
+    TapHandler {
+        id: inputHandler
     }
 }
 \endqml
 
 In fact, any JavaScript expression (no matter how complex) may be used in a
 property binding definition, as long as the result of the expression is a
-value whose type can be assigned to the property.  This includes side effects.
+value whose type can be assigned to the property. This includes side effects.
 However, complex bindings and side effects are discouraged because they can
 reduce the performance, readability, and maintainability of the code.
 
-There are two ways to define a property binding: the first (and most common)
-is, as previously shown, in a \l{QML Object Attributes#Value Assignment on Initialization}
-{property initialization}.  The second (and much rarer) way is to assign the
+There are two ways to define a property binding: the most common one
+is shown in the example earlier, in a \l{QML Object Attributes#Value Assignment on Initialization}
+{property initialization}. The second (and much rarer) way is to assign the
 property a function returned from the \l{Qt::binding()}{Qt.binding()} function,
 from within imperative JavaScript code, as shown below:
 
 \qml
-import QtQuick 2.0
+import QtQuick 2.12
 
 Rectangle {
     id: colorbutton
@@ -109,13 +108,12 @@ Rectangle {
 
     color: "red"
 
-    MouseArea {
-        id: mousearea
-        anchors.fill: parent
+    TapHandler {
+        id: inputHandler
     }
 
     Component.onCompleted: {
-        color = Qt.binding(function() { return mousearea.pressed ? "steelblue" : "lightsteelblue" });
+        color = Qt.binding(function() { return inputHandler.pressed ? "steelblue" : "lightsteelblue" });
     }
 }
 \endqml
@@ -126,126 +124,111 @@ about \l{qml-javascript-assignment}
 {Property Assignment versus Property Binding} for information about how
 bindings differ from value assignments.
 
-
-
-\section1 JavaScript in Signal Handlers
+\section1 JavaScript in signal handlers
 
 QML object types can emit signals in reaction to certain events occurring.
 Those signals can be handled by signal handler functions, which can be defined
 by clients to implement custom program logic.
 
-Suppose that a button represented by a Rectangle type has a MouseArea and a
-Text label. The MouseArea will emit its \l{MouseArea::}{pressed} signal when the
-user presses the defined interactive area, which will automatically trigger the
-\c onPressed handler, which can be defined by clients. The QML
-engine will execute the JavaScript expressions defined in the \c onPressed and
-\c onReleased handlers, as required. Typically, a signal handler is bound to
-JavaScript expressions to initiate other events or to simply assign property
+Suppose that a button represented by a Rectangle type has a TapHandler and a
+Text label. The TapHandler emits its \l{TapHandler::}{tapped} signal when the
+user presses the button. The clients can react to the signal in the \c onTapped
+handler using JavaScript expressions. The QML engine executes these JavaScript
+expressions defined in the handler as required. Typically, a signal handler is
+bound to JavaScript expressions to initiate other events or to assign property
 values.
 
 \qml
-import QtQuick 2.0
+import QtQuick 2.12
 
 Rectangle {
     id: button
     width: 200; height: 80; color: "lightsteelblue"
 
-    MouseArea {
-        id: mousearea
-        anchors.fill: parent
-
-        onPressed: {
+    TapHandler {
+        id: inputHandler
+        onTapped: {
             // arbitrary JavaScript expression
-            label.text = "I am Pressed!"
+            console.log("Tapped!")
         }
-        onReleased: {
-            // arbitrary JavaScript expression
-            label.text = "Click Me!"
-        }
-
     }
 
     Text {
         id: label
         anchors.centerIn: parent
-        text: "Press Me!"
+        text: inputHandler.pressed ? "Pressed!" : "Press here!"
     }
 }
 \endqml
 
-Please see the \l{Signal and Handler Event System} documentation for in-depth
-discussion of signals and signal handlers, and see the
-\l{QML Object Attributes} documentation for in-depth discussion of how
-to define the implementation of signal handlers in QML with JavaScript.
-
+For more details about signals and signal handlers, refer to the following
+topics:
 
+\list
+    \li \l{Signal and Handler Event System}
+    \li \l{QML Object Attributes}
+\endlist
 
-\section1 JavaScript in Standalone Functions
+\section1 JavaScript in standalone functions
 
-Program logic can also be defined in JavaScript functions.  These functions can
+Program logic can also be defined in JavaScript functions. These functions can
 be defined inline in QML documents (as custom methods) or externally in
 imported JavaScript files.
 
-
-
-\section2 JavaScript in Custom Object Methods
+\section2 JavaScript in custom methods
 
 Custom methods can be defined in QML documents and may be called from signal
-handlers, property bindings, or functions in other QML objects.  Methods
-defined in this way are often referred to as \e{inline JavaScript functions}
-because their implementation is included in the QML object type definition
-(QML document), as opposed to an external JavaScript file.
+handlers, property bindings, or functions in other QML objects. Such methods
+are often referred to as \e{inline JavaScript functions} because their
+implementation is included in the QML object type definition
+(QML document), instead of in an external JavaScript file.
 
 An example of an inline custom method is as follows:
 
 \qml
-import QtQuick 2.0
+import QtQuick 2.12
 
 Item {
-    function factorial(a) {
-        a = parseInt(a);
-        if (a <= 0)
-            return 1;
-        else
-            return a * factorial(a - 1);
-    }
+    function fibonacci(n){
+        var arr = [0, 1];
+        for (var i = 2; i < n + 1; i++)
+            arr.push(arr[i - 2] + arr[i -1]);
 
-    MouseArea {
-        anchors.fill: parent
-        onClicked: console.log(factorial(10))
+        return arr;
+    }
+    TapHandler {
+        onTapped: console.log(fibonacci(10))
     }
 }
 \endqml
 
-The factorial function will run whenever the MouseArea detects a \c clicked signal.
+The fibonacci function is run whenever the TapHandler emits a \c tapped signal.
 
-Importantly, custom methods defined inline in a QML document are exposed to
+\note The custom methods defined inline in a QML document are exposed to
 other objects, and therefore inline functions on the root object in a QML
-component can be invoked by callers outside the component.  If this is not
+component can be invoked by callers outside the component. If this is not
 desired, the method can be added to a non-root object or, preferably, written
 in an external JavaScript file.
 
-See the \l{QML Object Attributes} documentation for in-depth discussion of how
-to define custom methods in QML with JavaScript code implementations.
-
-
+See the \l{QML Object Attributes} documentation for more information on
+defining custom methods in QML using JavaScript.
 
-\section2 Functions in Imported JavaScript Files
+\section2 Functions defined in a JavaScript file
 
-Non-trivial program logic is best separated into external JavaScript files.
-These files can be imported into QML files using an \c import statement, in
-the same way that \l {QML Modules}{modules} are imported.
+Non-trivial program logic is best separated into a separate JavaScript file.
+This file can be imported into QML using an \c import statement, like the
+QML \l {QML Modules}{modules}.
 
-For example, the \c {factorial()} method in the above example could be moved
-into an external file named \c factorial.js, and accessed like this:
+For example, the \c {fibonacci()} method in the earlier example could be moved
+into an external file named \c fib.js, and accessed like this:
 
 \qml
-import "factorial.js" as MathFunctions
+import QtQuick 2.12
+import "fib.js" as MathFunctions
 
 Item {
-    MouseArea {
-        anchors.fill: parent
-        onClicked: console.log(MathFunctions.factorial(10))
+    TapHandler {
+        onTapped: console.log(MathFunctions.fibonacci(10))
     }
 }
 \endqml
@@ -253,20 +236,18 @@ Item {
 For more information about loading external JavaScript files into QML, read
 the section about \l{Importing JavaScript Resources in QML}.
 
+\section2 Connecting signals to JavaScript functions
 
-
-\section2 Connecting Signals to JavaScript Functions
-
-QML object types which emit signals also provide default signal handlers for
-their signals, as described in a previous section.  Sometimes, however, a
-client will want to cause a signal emitted from one object to trigger a
-function defined in another object; and in that case, a signal connection
-is often preferable.
+QML object types that emit signals also provide default signal handlers for
+their signals, as described in the \l{JavaScript in signal handlers}{previous}
+section. Sometimes, however, a client wants to trigger a function defined in a
+QML object when another QML object emits a signal. Such scenarios can be handled
+by a signal connection.
 
 A signal emitted by a QML object may be connected to a JavaScript function
 by calling the signal's \c connect() method and passing the JavaScript function
-as an argument.  For example, the following code connects the MouseArea
-\c clicked signal to the \c jsFunction() in \c script.js:
+as an argument. For example, the following code connects the TapHandler's
+\c tapped signal to the \c jsFunction() in \c script.js:
 
 \table
 \row
@@ -274,34 +255,30 @@ as an argument.  For example, the following code connects the MouseArea
 \li \snippet qml/integrating-javascript/script.js 0
 \endtable
 
-The \c jsFunction() will now be called whenever MouseArea's \c clicked signal
+The \c jsFunction() is called whenever the TapHandler's \c tapped signal
 is emitted.
 
 See \l{qtqml-syntax-signals.html}
 {Connecting Signals to Methods and Signals} for more information.
 
-
-
-
-
-\section1 JavaScript in Application Startup Code
+\section1 JavaScript in application startup code
 
 It is occasionally necessary to run some imperative code at application (or
-component instance) startup.  While it is tempting to just include the startup
+component instance) startup. While it is tempting to just include the startup
 script as \e {global code} in an external script file, this can have severe
-limitations as the QML environment may not have been fully established.  For
+limitations as the QML environment may not have been fully established. For
 example, some objects might not have been created or some
 \l {Property Binding}{property bindings} may not have been established. See
 \l {JavaScript Environment Restrictions} for the exact limitations of global
 script code.
 
-A QML object will emit the \c{Component.completed} \l{Signal and Handler Event
+A QML object emits the \c{Component.completed} \l{Signal and Handler Event
 System#Attached Signal Handlers}{attached signal} when its instantiation is
-complete.  JavaScript code in the corresponding \c{Component.onCompleted} handler
-runs after the object is instantiated.  Thus, the best place to write application
-startup code is in the \c{Component.onCompleted} handler of the top-level
-object, because this object emits \c{Component.completed} when the QML environment
-is fully established.
+complete. The JavaScript code in the corresponding \c{Component.onCompleted}
+handler runs after the object is instantiated. Thus, the best place to write
+application startup code is in the \c{Component.onCompleted} handler of the
+top-level object, because this object emits \c{Component.completed} when the
+QML environment is fully established.
 
 For example:
 
@@ -318,11 +295,11 @@ Rectangle {
 \endqml
 
 Any object in a QML file - including nested objects and nested QML component
-instances - can use this attached property.  If there is more than one
+instances - can use this attached property. If there is more than one
 \c onCompleted() handler to execute at startup, they are run sequentially in
 an undefined order.
 
-Likewise, every \c Component will emit a \l {Component::destruction}{destruction()}
+Likewise, every \c Component emits a \l {Component::destruction}{destruction()}
 signal just before being destroyed.
 
 */
@@ -341,7 +318,7 @@ signal just before being destroyed.
 \section1 Scarce Resources in JavaScript
 
 As described in the documentation for \l{QML Basic Types}, a \c var type
-property may hold a \e{scarce resource} (image or pixmap).  There are several
+property may hold a \e{scarce resource} (image or pixmap). There are several
 important semantics of scarce resources which should be noted:
 
 \list
@@ -351,7 +328,7 @@ important semantics of scarce resources which should be noted:
 \endlist
 
 In most cases, allowing the engine to automatically release the resource is
-the correct choice.  In some cases, however, this may result in an invalid
+the correct choice. In some cases, however, this may result in an invalid
 variant being returned from a function in JavaScript, and in those cases it
 may be necessary for clients to manually preserve or destroy resources for
 themselves.
@@ -364,9 +341,9 @@ and that we have registered it with the QML type-system as follows:
 
 \snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 0
 
-The AvatarExample class has a property which is a pixmap.  When the property
+The AvatarExample class has a property which is a pixmap. When the property
 is accessed in JavaScript scope, a copy of the resource will be created and
-stored in a JavaScript object which can then be used within JavaScript.  This
+stored in a JavaScript object which can then be used within JavaScript. This
 copy will take up valuable system resources, and so by default the scarce
 resource copy in the JavaScript object will be released automatically by the
 declarative engine once evaluation of the JavaScript expression is complete,
@@ -414,7 +391,7 @@ Run it in C++:
 \section2 Example Four: Explicit Destruction
 
 In the following example, we release (via destroy()) an explicitly preserved
-scarce resource variant.  This example shows how a client may free system
+scarce resource variant. This example shows how a client may free system
 resources by releasing the scarce resource held in a JavaScript object, if
 required, during evaluation of a JavaScript expression.
 
@@ -430,7 +407,7 @@ Run it in C++:
 \section2 Example Five: Explicit Destruction and JavaScript References
 
 One thing to be aware of when using "var" type properties is that they
-hold references to JavaScript objects.  As such, if multiple references
+hold references to JavaScript objects. As such, if multiple references
 to one scarce resource is held, and the client calls destroy() on one
 of those references (to explicitly release the scarce resource), all of
 the references will be affected.
diff --git a/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc b/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc
index 8357492557..f0ad2b7767 100644
--- a/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc
+++ b/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc
@@ -39,99 +39,100 @@ application may need to relay this clicking event to other applications.
 
 QML has a signal and handler mechanism, where the \e signal is the event
 and the signal is responded to through a \e {signal handler}. When a signal
-is emitted, the corresponding signal handler is invoked. Placing logic such as scripts or other
-operations in the handler allows the component to respond to the event.
+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.
 
 \target qml-signals-and-handlers
-\section1 Receiving Signals with Signal Handlers
+\section1 Receiving signals with signal handlers
 
-To receive a notification when a particular signal is emitted for a particular object, the object definition should declare a signal handler named \e on<Signal> where \e <Signal> is the name of the signal, with the first letter capitalized. The signal handler should contain the JavaScript code to be executed when the signal handler is invoked.
+To receive a notification when a particular signal is emitted for a particular
+object, the object definition should declare a signal handler named
+\e on<Signal>, where \e <Signal> is the name of the signal, with the first
+letter capitalized. The signal handler should contain the JavaScript code to be
+executed when the signal handler is invoked.
 
-For example, the \l MouseArea type from the \c QtQuick module has a \c clicked signal that is emitted whenever the mouse is clicked within the area. Since the signal name is \c clicked, the signal handler for receiving this signal should be named \c onClicked. In the example below, whenever the mouse area is clicked, the \c onClicked handler is invoked, applying a random color to the \l Rectangle:
+For example, the \l [QtQuick.Controls2]{Button} type from the
+\l{Qt Quick Controls 2}{Qt Quick Controls} module has a \c clicked signal, which
+is emitted whenever the button is clicked. In this case, the signal handler for
+receiving this signal should be \c onClicked. In the example below, whenever
+the button is clicked, the \c onClicked handler is invoked, applying a random
+color to the parent \l Rectangle:
 
 \qml
-import QtQuick 2.0
+import QtQuick 2.\QtMinorVersion
+import QtQuick.Controls 2.\QtMinorVersion
 
 Rectangle {
     id: rect
-    width: 100; height: 100
-
-    MouseArea {
-        anchors.fill: parent
-        onClicked: {
-            rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1);
-        }
-    }
-}
-\endqml
-
-Looking at the \l MouseArea documentation, you can see the \l {MouseArea::}{clicked} signal is emitted with a parameter named \c mouse which is a \l MouseEvent object that contains further details about the mouse click event. This name can be referred to in our \c onClicked handler to access this parameter. For example, the \l MouseEvent type has \c x and \c y coordinates that allows us to print out the exact location where the mouse was clicked:
-
-\qml
-import QtQuick 2.0
-
-Rectangle {
-    id: rect
-    width: 100; height: 100
+    width: 250; height: 250
 
-    MouseArea {
-        anchors.fill: parent
+    Button {
+        anchors.bottom: parent.bottom
+        anchors.horizontalCenter: parent.horizontalCenter
+        text: "Change color!"
         onClicked: {
             rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1);
-
-            // access 'mouse' parameter
-            console.log("Clicked mouse at", mouse.x, mouse.y)
         }
     }
 }
 \endqml
 
+\section2 Property change signal handlers
 
-\section2 Property Change Signal Handlers
-
-A signal is automatically emitted when the value of a QML property changes. 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.
+A signal is automatically emitted when the value of a QML property changes.
+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:
 
 \qml
-import QtQuick 2.0
+import QtQuick 2.\QtMinorVersion
 
 Rectangle {
     id: rect
     width: 100; height: 100
 
-    MouseArea {
-        anchors.fill: parent
-        onPressedChanged: {
-            console.log("Mouse area is pressed?", pressed)
-        }
+    TapHandler {
+        onPressedChanged: console.log("taphandler pressed?", pressed)
     }
 }
 \endqml
 
-Even though the \l MouseArea documentation does not document a signal handler named \c onPressedChanged, the signal is implicitly provided by the fact that the \c pressed property exists.
-
+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 Using the Connections Type
+\section2 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 \c QtQuick module provides the \l Connections type for connecting to signals of arbitrary objects. A \l Connections object can receive any signal from its specified \l {Connections::target}{target}.
+In some cases it may be desirable to access a signal outside of the object that
+emits it. For these purposes, the \c QtQuick module provides the \l Connections
+type for connecting to signals of arbitrary objects. A \l Connections object
+can receive any signal from its specified \l {Connections::target}{target}.
 
-For example, the \c onClicked handler in the earlier example could have been received by the root \l Rectangle instead, by placing the \c onClicked handler in a \l Connections object that has its \l {Connections::target}{target} set to the \l MouseArea:
+For example, the \c onClicked handler in the earlier example could have been
+received by the root \l Rectangle instead, by placing the \c onClicked handler
+in a \l Connections object that has its \l {Connections::target}{target} set to
+the \c button:
 
 \qml
-import QtQuick 2.0
+import QtQuick 2.\QtMinorVersion
+import QtQuick.Controls 2.\QtMinorVersion
 
 Rectangle {
     id: rect
-    width: 100; height: 100
+    width: 250; height: 250
 
-    MouseArea {
-        id: mouseArea
-        anchors.fill: parent
+    Button {
+        id: button
+        anchors.bottom: parent.bottom
+        anchors.horizontalCenter: parent.horizontalCenter
+        text: "Change color!"
     }
 
     Connections {
-        target: mouseArea
+        target: button
         onClicked: {
             rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1);
         }
@@ -140,16 +141,18 @@ Rectangle {
 \endqml
 
 
-\section2 Attached Signal Handlers
+\section2 Attached signal handlers
 
-An \l {Attached Properties and Attached Signal Handlers}{attached signal handler} is a signal handler that receives a signal from an \e {attaching type} rather than the object within which the handler is declared.
+An \l {Attached Properties and Attached Signal Handlers}{attached signal handler}
+receives a signal from an \e {attaching type} rather than the object within which
+the handler is declared.
 
 For example, \l{Component::completed}{Component.onCompleted} is an attached
-signal handler. This handler is often used to execute some JavaScript code when
-its creation process has been completed, as in the example below:
+signal handler. It is often used to execute some JavaScript code when its
+creation process is complete. Here is an example:
 
 \qml
-import QtQuick 2.0
+import QtQuick 2.\QtMinorVersion
 
 Rectangle {
     width: 200; height: 200
@@ -161,14 +164,23 @@ Rectangle {
 }
 \endqml
 
-The \c onCompleted handler is not responding to some \c completed signal from the \l Rectangle type. Instead, an object of the \c Component \e {attaching type} with a \c completed signal has automatically been \e attached to the \l Rectangle object by the QML engine, and the engine emits this signal when the object is fully created, thus triggering the \c Component.onCompleted signal handler.
+The \c onCompleted handler is not responding to a \c completed signal from
+the \l Rectangle type. Instead, an object of the \c Component \e{attaching type}
+with a \c completed signal has automatically been \e attached to the \l Rectangle
+object by the QML engine. The engine emits this signal when the Rectangle object is
+created, thus triggering the \c 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 \c Component.onCompleted attached signal handler, for example, then an object could not receive this notification without registering for some special signal from some special object. The \e {attached signal handler} mechanism enables objects to receive particular signals without these extra processes.
+Attached signal handlers allow objects to be notified of particular signals that are
+significant to each individual object. If there was no \c 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 \e {attached signal handler} mechanism enables objects to receive particular
+signals without extra code.
 
-See \l {Attached properties and attached signal handlers} for more information on attached signal handlers.
+See \l {Attached properties and attached signal handlers} for more information on
+attached signal handlers.
 
-
-\section1 Adding Signals to Custom QML Types
+\section1 Adding signals to custom QML types
 
 Signals can be added to custom QML types through the \c signal keyword.
 
@@ -178,21 +190,27 @@ The syntax for defining a new signal is:
 
 A signal is emitted by invoking the signal as a method.
 
-For example, say the code below is defined in a file named \c SquareButton.qml. The root \l Rectangle object has an \c activated signal. When the child \l MouseArea is clicked, it emits the parent's \c activated signal with the coordinates of the mouse click:
+For example, the code below is defined in a file named \c SquareButton.qml. The
+root \l Rectangle object has an \c activated signal, which is emitted whenever the
+child \l TapHandler is \c tapped. In this particular example the activated signal
+is emitted with the x and y coordinates of the mouse click:
 
 \qml
 // SquareButton.qml
+import QtQuick 2.\QtMinorVersion
+
 Rectangle {
     id: root
 
     signal activated(real xPosition, real yPosition)
-
+    property point mouseXY
     property int side: 100
     width: side; height: side
 
-    MouseArea {
-        anchors.fill: parent
-        onPressed: root.activated(mouse.x, mouse.y)
+    TapHandler {
+        id: handler
+        onTapped: root.activated(mouseXY.x, mouseXY.y)
+        onPressedChanged: mouseXY = handler.point.position
     }
 }
 \endqml
@@ -210,7 +228,7 @@ See \l {Signal Attributes} for more details on writing signals for custom QML ty
 
 
 \target qml-connect-signals-to-method
-\section1 Connecting Signals to Methods and Signals
+\section1 Connecting signals to methods and signals
 
 Signal objects have a \c 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
@@ -220,6 +238,8 @@ signal to be received by a method instead of a signal handler.
 Below, the \c messageReceived signal is connected to three methods using the \c connect() method:
 
 \qml
+import QtQuick 2.\QtMinorVersion
+
 Rectangle {
     id: relay
 
@@ -244,7 +264,12 @@ Rectangle {
 }
 \endqml
 
-In many cases it is sufficient to receive signals through signal handlers rather than using the connect() function. However, using the \c connect method allows a signal to be received by multiple methods as shown above, which would not be possible with signal handlers as they must be uniquely named. Also, the \c connect method is useful when connecting signals to \l {Dynamic QML Object Creation from JavaScript}{dynamically created objects}.
+In many cases it is sufficient to receive signals through signal handlers
+rather than using the connect() function. However, using the \c 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 \c connect method is useful when connecting signals to
+\l {Dynamic QML Object Creation from JavaScript}{dynamically created objects}.
 
 There is a corresponding \c disconnect() method for removing connected signals:
 
@@ -259,12 +284,14 @@ Rectangle {
 }
 \endqml
 
-\section3 Signal to Signal Connect
+\section3 Signal to signal connect
 
 By connecting signals to other signals, the \c connect() method can form different
 signal chains.
 
 \qml
+import QtQuick 2.\QtMinorVersion
+
 Rectangle {
     id: forwarder
     width: 100; height: 100
@@ -272,20 +299,20 @@ Rectangle {
     signal send()
     onSend: console.log("Send clicked")
 
-    MouseArea {
+    TapHandler {
         id: mousearea
         anchors.fill: parent
-        onClicked: console.log("MouseArea clicked")
+        onTapped: console.log("Mouse clicked")
     }
 
     Component.onCompleted: {
-        mousearea.clicked.connect(send)
+        mousearea.tapped.connect(send)
     }
 }
 \endqml
 
 
-Whenever the \l MouseArea \c clicked signal is emitted, the \c send
+Whenever the \l TapHandler's \c tapped signal is emitted, the \c send
 signal will automatically be emitted as well.
 
 \code
@@ -293,6 +320,4 @@ output:
     MouseArea clicked
     Send clicked
 \endcode
-
-
 */