Rearrange docs: Pointer Handlers -> Input Handlers

At QtCS 2018 we decided to rename Pointer Handlers to Input Handlers
and include the Keys attached property as part of this set (since we
plan to have attached-property pointer handlers too, eventually).
It's no longer a module, it's included in Qt Quick 2.12.  We need to
start promoting Input Handlers and reducing the visibility of legacy
stuff like MouseArea and MultiPointTouchArea (in the hope of being
able to deprecate them eventually).

Task-number: QTBUG-66651
Change-Id: I801351ac2531191cbb1faac9318441c67a109af6
Reviewed-by: Jan Arve Sæther <jan-arve.saether@qt.io>
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>

4 files changed, 45 insertions, 95 deletions

diff --git a/src/quick/doc/src/concepts/input/mouse.qdoc b/src/quick/doc/src/concepts/input/mouse.qdoc
index 422c326898..cb506cb99a 100644
--- a/src/quick/doc/src/concepts/input/mouse.qdoc
+++ b/src/quick/doc/src/concepts/input/mouse.qdoc
@@ -33,6 +33,13 @@
 
 \tableofcontents
 
+A more modern way of handling events from all pointing devices, including
+mouse and touchscreen, is via \l {Qt Quick Input Handlers}{Input Handlers}.
+This page describes the original Qt Quick \l MouseArea type, which was
+initially designed to handle mouse input, and later began handling single-touch
+events (in the form of synthetic mouse events) in simple touch-oriented user
+interfaces.
+
 \section1 Mouse Types
 
 \list
@@ -44,8 +51,8 @@
 
 QML uses \l{qtqml-syntax-signals.html}{signals and handlers} to
 deliver mouse interactions. Specifically, Qt Quick provides the \l MouseArea
-and \l MouseEvent types which allow developers to define signal handlers which
-accept mouse events within a defined area.
+and \l MouseEvent types that allow developers to define JavaScript callbacks
+(also called signal handlers), which accept mouse events within a defined area.
 
 \section1 Defining a Mouse Area
 
@@ -59,8 +66,8 @@ definable.
 
 \section1 Receiving Events
 
-The MouseArea type provides
-\l{qtqml-syntax-signals.html}{signals and handlers} to detect different
+The MouseArea type emits
+\l{qtqml-syntax-signals.html}{signals} in response to different
 mouse events. The \l MouseArea type documentation describes these
 gestures in greater detail:
 
@@ -76,8 +83,8 @@ gestures in greater detail:
 \li released
 \endlist
 
-These signals have signal handlers that are invoked when the signals are emitted.
-\snippet qml/mousearea/mousearea-snippet.qml mouse handlers
+These signals can have callbacks that are invoked when the signals are emitted.
+\snippet qml/mousearea/mousearea-snippet.qml signal handlers
 
 \section1 Enabling Gestures
 Some mouse gestures and button clicks need to be enabled before they send or
@@ -101,9 +108,9 @@ Additionally, to disable the whole mouse area, set the MouseArea
 
 \section1 MouseEvent Object
 
-Signals and their handlers receive a \l MouseEvent object as a parameter. The
-\c mouse object contain information about the mouse event. For example, the
-mouse button that started the event is queried through the
+Signals and their callbacks receive a \l MouseEvent object as a parameter.
+The \c mouse object contains information about the mouse event. For example,
+the mouse button that started the event is queried through the
 \l {MouseEvent::button}{mouse.button} property.
 
 The \c MouseEvent object can also ignore a mouse event using its \c accepted
diff --git a/src/quick/doc/src/concepts/input/topic.qdoc b/src/quick/doc/src/concepts/input/topic.qdoc
index c23654cadb..95f4732f46 100644
--- a/src/quick/doc/src/concepts/input/topic.qdoc
+++ b/src/quick/doc/src/concepts/input/topic.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2017 The Qt Company Ltd.
+** Copyright (C) 2018 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -35,30 +35,20 @@ design.  Depending on the use-case that an application solves, and the
 form-factor of the device that the application runs on, the best way
 to receive user-input may be different.
 
-\section1 Touch
+\section1 Input from Pointing Devices
 
 Allowing users to physically touch a screen to interact with an application is
 a popular user-interface paradigm on portable devices like smartphones and
-tablets.
+tablets. In desktop applications, detecting and reacting to clicks and presses
+according to the mouse cursor position is a fundamental concept in
+user-interface design.
 
-Qt Quick was designed specifically with touch-driven user-interfaces in mind,
-and thus touch events are supported in various visual object types, from
-\l{Flickable} lists to the generic \l{MultiPointTouchArea} type, as well as
-in the \l{MouseArea} type (which will be documented thoroughly in a proceeding
-section).
+Touch-driven and mouse-driven user interfaces are supported by various
+\l{Qt Quick Input Handlers}{input handler} types, and visual object types
+such as \l{Flickable} and \l{MouseArea}.
 
-
-\section1 Mouse
-
-Mouse input is another important user input for user interfaces. Detecting
-and reacting to clicks and presses according to the mouse cursor position is a fundamental
-concept in user-interface design.
-
-Qt Quick provides the MouseArea visual object type which automatically receives
-mouse events (including clicks and wheel events) which allows developers to
-create custom user-interface objects to handle mouse input.  Please see the
-documentation about \l{qtquick-input-mouseevents.html}
-{mouse events in Qt Quick} for more information on the topic.
+See also the documentation about
+\l{qtquick-input-mouseevents.html} {mouse events in Qt Quick}.
 
 
 \section1 Keyboard Input and Keyboard Focus
diff --git a/src/quick/doc/src/concepts/pointerhandlers/qtquickhandlers-index.qdoc b/src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc
index fc1fd5fbc1..2ac9860e6f 100644
--- a/src/quick/doc/src/concepts/pointerhandlers/qtquickhandlers-index.qdoc
+++ b/src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2017 The Qt Company Ltd.
+** Copyright (C) 2018 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -27,35 +27,34 @@
 
 /*!
     \page qtquickhandlers-index.html
-    \title Qt Quick Pointer Handlers
-    \brief A module with a set of QML elements that handle events from pointing devices in a user interface.
+    \title Qt Quick Input Handlers
+    \brief A module with a set of QML elements that handle events from input devices in a user interface.
 
-    Qt Quick Pointer Handlers are a set of QML types used to handle events from
-    touch, mouse, and stylus devices in a UI. In contrast to event-handling
-    Items, such as \l MouseArea, Pointer Handlers require less memory and are
-    intended to be used in greater numbers: one handler per type of
-    interaction. Each Pointer Handler handles events on behalf of its \c parent
-    Item. One Item can have multiple Pointer Handlers.
+    Qt Quick Input Handlers are a set of QML types used to handle events from
+    keyboard, touch, mouse, and stylus devices in a UI. In contrast to event-handling
+    items, such as \l MouseArea and \l Flickable, input handlers are explicitly non-visual,
+    require less memory and are intended to be used in greater numbers: one
+    handler instance per aspect of interaction. Each input handler instance
+    handles certain events on behalf of its \c parent Item. Thus the visual and
+    behavioral concerns are better separated, and the behavior is built up by
+    finer-grained composition.
 
-    The module is introduced in Qt 5.10.
+    In Qt 5.10, these handlers were introduced in a separate Qt.labs.handlers module.
+    Now they are included with Qt Quick since 5.12.  The pre-existing
+    \l Keys attached property is similar in concept, so we refer to the
+    pointing-device-oriented handlers plus \c Keys together as the set of Input Handlers.
+    We expect to offer more attached-property use cases in future versions of Qt.
 
-    \section1 Pointer Handlers
+    \section1 Input Handlers
 
-    \annotatedlist pointerhandlers
-
-    \section1 Getting Started
-
-    The QML types can be imported into your application using the following import statement in your \c {.qml} file.
-
-    \code
-     import Qt.labs.handlers 1.0
-    \endcode
+    \annotatedlist qtquick-input-handlers
 
     \section1 Key Features
 
     Some of the key features are:
 
     \list
+        \li Handle keystrokes within the focused Item
         \li Handle gestures such as tapping or dragging regardless which device it comes from
         \li Handle gestures from different classes of devices in different ways
         \li Each Item can have unlimited Handlers
@@ -67,7 +66,5 @@
 
      \list
       \li \l{Qt Quick}
-      \li \l{Qt Quick Pointer Handlers}
-      \li \l{Qt Quick Pointer Handlers QML Types}{Qt Quick Pointer Handlers QML Types}
      \endlist
 */
diff --git a/src/quick/doc/src/concepts/pointerhandlers/qtquickhandlers.qdoc b/src/quick/doc/src/concepts/pointerhandlers/qtquickhandlers.qdoc
deleted file mode 100644
index cf87c75e8c..0000000000
--- a/src/quick/doc/src/concepts/pointerhandlers/qtquickhandlers.qdoc
+++ /dev/null
@@ -1,44 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
-    \qmlmodule Qt.labs.handlers 1.0
-    \title Qt Quick Pointer Handlers QML Types
-    \ingroup qmlmodules
-    \brief Provides QML types for handling events from pointing devices in a user interface.
-
-    The \l{Qt Quick Pointer Handlers} module provides QML types for handling
-    events from pointing devices in a UI. These QML types work in conjunction
-    with \l{Qt Quick}.
-
-    The QML types can be imported into your application using the
-    following import statement in your .qml file.
-
-    \code
-    import Qt.labs.handlers 1.0
-    \endcode
-*/