Dial: add inputMode property

This property adds two new ways of interacting with the dial:
horizontally and vertically. These new input modes use a relative
input system, which means that, unlike the old absolute input system,
changes to the dial's position are "added" to its value. This results
in a dial that is less "jumpy", making it safe for operations that
could be harmful if done incorrectly, like adjusting audio levels.

[ChangeLog][Controls][Dial] Added the inputMode property. This property
controls how the dial is interacted with. The circular input mode
(default, old behavior) operates on an absolute input system, whereas
the horizontal and vertical input modes use a relative input system.

Task-number: QTBUG-56323
Change-Id: Iab4e7f048b4797ab626741326ce709914e67bd31
Reviewed-by: J-P Nurmi <jpnurmi@qt.io>

5 files changed, 24 insertions, 0 deletions

diff --git a/src/imports/controls/doc/images/qtquickcontrols2-dial-inputMode.svgz b/src/imports/controls/doc/images/qtquickcontrols2-dial-inputMode.svgz
new file mode 100644
index 00000000..005ab7b3
--- /dev/null
+++ b/src/imports/controls/doc/images/qtquickcontrols2-dial-inputMode.svgz
diff --git a/src/imports/controls/doc/images/qtquickcontrols2-dial-inputmode.png b/src/imports/controls/doc/images/qtquickcontrols2-dial-inputmode.png
new file mode 100644
index 00000000..27694ee3
--- /dev/null
+++ b/src/imports/controls/doc/images/qtquickcontrols2-dial-inputmode.png
diff --git a/src/imports/controls/doc/src/includes/qquickdial.qdocinc b/src/imports/controls/doc/src/includes/qquickdial.qdocinc
new file mode 100644
index 00000000..3370b3d8
--- /dev/null
+++ b/src/imports/controls/doc/src/includes/qquickdial.qdocinc
@@ -0,0 +1,13 @@
+//! [inputMode]
+Dial supports three \l {inputMode}{input modes}: \c Dial.Circular,
+\c Dial.Horizontal and \c Dial.Vertical. The circular input mode operates on an
+absolute input system, where the position of the cursor within the dial
+directly reflects its value. The horizontal and vertical input modes use a
+relative input system, where changes in the cursor's position are "added" to
+the value of the dial.
+
+The following image illustrates the directions in which the various input modes
+track movement:
+
+\image qtquickcontrols2-dial-inputmode.png
+//! [inputMode]
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc
index 71de6104..60cd586d 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc
@@ -67,6 +67,16 @@
     The dial is rotated by clicking and dragging, with the handle indicating the
     value of the dial.
 
+    For applications where fast input is important, the circular
+    \l {Dial::inputMode}{input mode} is useful, as clicking on the dial will
+    move it directly to that position.
+
+    For applications where precise input is important, the horizontal and
+    vertical input modes are recommended, as these allow small adjustments to
+    be made relative to where the dial is clicked. These modes are also better
+    for dials where large jumps in values could be unsafe, such as a dial that
+    controls audio volume.
+
     \b {See also} \l {Tumbler Control}.
 
     \section1 TextArea Control
diff --git a/src/imports/templates/qtquicktemplates2plugin.cpp b/src/imports/templates/qtquicktemplates2plugin.cpp
index 5b91c234..ef7a646b 100644
--- a/src/imports/templates/qtquicktemplates2plugin.cpp
+++ b/src/imports/templates/qtquicktemplates2plugin.cpp
@@ -328,6 +328,7 @@ void QtQuickTemplates2Plugin::registerTypes(const char *uri)
     qmlRegisterType<QQuickComboBox, 5>(uri, 2, 5, "ComboBox");
     qmlRegisterType<QQuickControl, 5>(uri, 2, 5, "Control");
     qmlRegisterType<QQuickContainer, 5>(uri, 2, 5, "Container");
+    qmlRegisterType<QQuickDial, 5>(uri, 2, 5, "Dial");
     qmlRegisterType<QQuickDialog, 5>(uri, 2, 5, "Dialog");
     qmlRegisterType<QQuickGroupBox, 5>(uri, 2, 5, "GroupBox");
     qmlRegisterType<QQuickLabel, 5>(uri, 2, 5, "Label");