SplitView: document how to change handle touch area size

Task-number: QTBUG-82678
Pick-to: 6.2
Change-Id: Icf0f43454086a059e8e14a03db985e570233e0a9
Reviewed-by: Igor Bugaev <freedbrt@gmail.com>
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>

2 files changed, 68 insertions, 0 deletions

diff --git a/src/quickcontrols2/doc/snippets/qtquickcontrols2-splitview-handle-containmentmask.qml b/src/quickcontrols2/doc/snippets/qtquickcontrols2-splitview-handle-containmentmask.qml
new file mode 100644
index 00000000..39af8994
--- /dev/null
+++ b/src/quickcontrols2/doc/snippets/qtquickcontrols2-splitview-handle-containmentmask.qml
@@ -0,0 +1,63 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 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$
+**
+****************************************************************************/
+
+import QtQuick
+import QtQuick.Controls
+
+Item {
+    width: 200
+    height: 100
+
+    //! [1]
+    SplitView {
+        id: splitView
+        anchors.fill: parent
+
+        handle: Rectangle {
+            implicitWidth: 4
+            implicitHeight: 4
+            color: SplitHandle.pressed ? "#81e889"
+                : (SplitHandle.hovered ? Qt.lighter("#c2f4c6", 1.1) : "#c2f4c6")
+
+            containmentMask: Item {
+                x: -width / 2
+                width: 64
+                height: splitView.height
+            }
+        }
+
+        Rectangle {
+            implicitWidth: 150
+            color: "#444"
+        }
+        Rectangle {
+            implicitWidth: 50
+            color: "#666"
+        }
+    }
+    //! [1]
+}
diff --git a/src/quicktemplates2/qquicksplitview.cpp b/src/quicktemplates2/qquicksplitview.cpp
index a34a0c17..a6f70b32 100644
--- a/src/quicktemplates2/qquicksplitview.cpp
+++ b/src/quicktemplates2/qquicksplitview.cpp
@@ -1206,6 +1206,11 @@ bool QQuickSplitView::isResizing() const
             \li \c implicitHeight
     \endtable
 
+    To change the size of the handle for mouse and touch events without
+    changing its visual size, use a \l {Item::}{containmentMask}:
+
+    \snippet qtquickcontrols2-splitview-handle-containmentmask.qml 1
+
     \sa {Customizing SplitView}
 */
 QQmlComponent *QQuickSplitView::handle()