Doc: add a "Focus Management in Qt Quick Controls 2" page

This will list each control that is a focus scope, and have
some relevant information about focus in Qt Quick Controls 2.

Change-Id: I3126452bf73f7d7730d0522d616d61ad0da0dd74
Reviewed-by: J-P Nurmi <jpnurmi@qt.io>

13 files changed, 78 insertions, 10 deletions

diff --git a/src/imports/controls/doc/src/qtquickcontrols2-focus.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-focus.qdoc
new file mode 100644
index 00000000..7883db71
--- /dev/null
+++ b/src/imports/controls/doc/src/qtquickcontrols2-focus.qdoc
@@ -0,0 +1,47 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 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$
+**
+****************************************************************************/
+
+/*!
+    \page qtquickcontrols2-focus.html
+    \title Focus Management in Qt Quick Controls 2
+    \brief Overview of focus handling with Qt Quick Controls 2
+
+    Qt Quick Controls 2 follows the standard
+    \l {Keyboard Focus in Qt Quick}{Qt Quick focus system}, while also
+    providing some added convenience. For example, the
+    \l {Control::}{focusPolicy} property can be used to control the ways in
+    which a control receives focus.
+
+    \section1 Focus Scope Controls
+
+    Qt Quick Controls 2 offers a selection of controls that act as
+    \l {Acquiring Focus and Focus Scopes}{focus scopes}:
+
+    \annotatedlist qtquickcontrols2-focusscopes
+
+    \sa {Keyboard Focus in Qt Quick}
+*/
diff --git a/src/quicktemplates2/qquickapplicationwindow.cpp b/src/quicktemplates2/qquickapplicationwindow.cpp
index 687b4233..77cf5465 100644
--- a/src/quicktemplates2/qquickapplicationwindow.cpp
+++ b/src/quicktemplates2/qquickapplicationwindow.cpp
@@ -59,6 +59,7 @@ QT_BEGIN_NAMESPACE
     \inqmlmodule QtQuick.Controls
     \since 5.7
     \ingroup qtquickcontrols2-containers
+    \ingroup qtquickcontrols2-focusscopes
     \brief Styled top-level window with support for a header and footer.
 
     ApplicationWindow is a \l Window which makes it convenient to add
@@ -110,7 +111,8 @@ QT_BEGIN_NAMESPACE
     certain window \c id. A QML component that uses the ApplicationWindow
     attached properties works in any window regardless of its \c id.
 
-    \sa {Customizing ApplicationWindow}, Overlay, Page, {Container Controls}
+    \sa {Customizing ApplicationWindow}, Overlay, Page, {Container Controls},
+        {Focus Management in Qt Quick Controls 2}
 */
 
 static const QQuickItemPrivate::ChangeTypes ItemChanges = QQuickItemPrivate::Visibility
diff --git a/src/quicktemplates2/qquickcombobox.cpp b/src/quicktemplates2/qquickcombobox.cpp
index b4d9bead..74efb6bb 100644
--- a/src/quicktemplates2/qquickcombobox.cpp
+++ b/src/quicktemplates2/qquickcombobox.cpp
@@ -63,6 +63,7 @@ QT_BEGIN_NAMESPACE
     \inqmlmodule QtQuick.Controls
     \since 5.7
     \ingroup qtquickcontrols2-input
+    \ingroup qtquickcontrols2-focusscopes
     \brief Combined button and popup list for selecting options.
 
     \image qtquickcontrols2-combobox.gif
@@ -133,7 +134,7 @@ QT_BEGIN_NAMESPACE
     \l textRole is not defined, ComboBox is unable to visualize it and throws a
     \c {ReferenceError: modelData is not defined}.
 
-    \sa {Customizing ComboBox}, {Input Controls}
+    \sa {Customizing ComboBox}, {Input Controls}, {Focus Management in Qt Quick Controls 2}
 */
 
 /*!
diff --git a/src/quicktemplates2/qquickmenubar.cpp b/src/quicktemplates2/qquickmenubar.cpp
index de3cc9a7..8398633c 100644
--- a/src/quicktemplates2/qquickmenubar.cpp
+++ b/src/quicktemplates2/qquickmenubar.cpp
@@ -53,6 +53,7 @@ QT_BEGIN_NAMESPACE
     \inqmlmodule QtQuick.Controls
     \since 5.10
     \ingroup qtquickcontrols2-menus
+    \ingroup qtquickcontrols2-focusscopes
     \brief Provides a window menu bar.
 
     \image qtquickcontrols2-menubar.png
@@ -71,7 +72,8 @@ QT_BEGIN_NAMESPACE
     \l {removeMenu}{remove}, and \l {takeMenu}{take} menus dynamically. The
     menus in a menu bar can be accessed using \l menuAt().
 
-    \sa {Customizing MenuBar}, Menu, MenuBarItem, {Menu Controls}
+    \sa {Customizing MenuBar}, Menu, MenuBarItem, {Menu Controls},
+        {Focus Management in Qt Quick Controls 2}
 */
 
 QQuickMenuBarPrivate::QQuickMenuBarPrivate()
diff --git a/src/quicktemplates2/qquickpage.cpp b/src/quicktemplates2/qquickpage.cpp
index 907b01e9..8f34dca9 100644
--- a/src/quicktemplates2/qquickpage.cpp
+++ b/src/quicktemplates2/qquickpage.cpp
@@ -47,6 +47,7 @@ QT_BEGIN_NAMESPACE
     \inqmlmodule QtQuick.Controls
     \since 5.7
     \ingroup qtquickcontrols2-containers
+    \ingroup qtquickcontrols2-focusscopes
     \brief Styled page control with support for a header and footer.
 
     Page is a container control which makes it convenient to add
@@ -79,7 +80,8 @@ QT_BEGIN_NAMESPACE
     }
     \endqml
 
-    \sa ApplicationWindow, {Container Controls}
+    \sa ApplicationWindow, {Container Controls},
+        {Focus Management in Qt Quick Controls 2}
 */
 
 class QQuickPagePrivate : public QQuickControlPrivate
diff --git a/src/quicktemplates2/qquickpane.cpp b/src/quicktemplates2/qquickpane.cpp
index 4c3e1422..8038f1b1 100644
--- a/src/quicktemplates2/qquickpane.cpp
+++ b/src/quicktemplates2/qquickpane.cpp
@@ -46,6 +46,7 @@ QT_BEGIN_NAMESPACE
     \inqmlmodule QtQuick.Controls
     \since 5.7
     \ingroup qtquickcontrols2-containers
+    \ingroup qtquickcontrols2-focusscopes
     \brief Provides a background matching with the application style and theme.
 
     Pane provides a background color that matches with the application style
@@ -101,7 +102,8 @@ QT_BEGIN_NAMESPACE
      }
     \endcode
 
-    \sa {Customizing Pane}, {Container Controls}
+    \sa {Customizing Pane}, {Container Controls},
+        {Focus Management in Qt Quick Controls 2}
 */
 
 QQuickPanePrivate::QQuickPanePrivate()
diff --git a/src/quicktemplates2/qquickpopup.cpp b/src/quicktemplates2/qquickpopup.cpp
index 03328b43..e3ab952d 100644
--- a/src/quicktemplates2/qquickpopup.cpp
+++ b/src/quicktemplates2/qquickpopup.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \inqmlmodule QtQuick.Controls
     \since 5.7
     \ingroup qtquickcontrols2-popups
+    \ingroup qtquickcontrols2-focusscopes
     \brief Base type of popup-like user interface controls.
 
     Popup is the base type of popup-like user interface controls. It can be
diff --git a/src/quicktemplates2/qquickrangeslider.cpp b/src/quicktemplates2/qquickrangeslider.cpp
index 075306cf..7205f26b 100644
--- a/src/quicktemplates2/qquickrangeslider.cpp
+++ b/src/quicktemplates2/qquickrangeslider.cpp
@@ -50,6 +50,7 @@ QT_BEGIN_NAMESPACE
     \inqmlmodule QtQuick.Controls
     \since 5.7
     \ingroup qtquickcontrols2-input
+    \ingroup qtquickcontrols2-focusscopes
     \brief Used to select a range of values by sliding two handles along a track.
 
     \image qtquickcontrols2-rangeslider.gif
@@ -85,7 +86,8 @@ QT_BEGIN_NAMESPACE
     RangeSlider. In the example above, \l {first.visualPosition} will be \c 0.24
     in a left-to-right application, and \c 0.76 in a right-to-left application.
 
-    \sa {Customizing RangeSlider}, {Input Controls}
+    \sa {Customizing RangeSlider}, {Input Controls},
+        {Focus Management in Qt Quick Controls 2}
 */
 
 class QQuickRangeSliderNodePrivate : public QObjectPrivate
diff --git a/src/quicktemplates2/qquickscrollview.cpp b/src/quicktemplates2/qquickscrollview.cpp
index 254a90d7..30750aa8 100644
--- a/src/quicktemplates2/qquickscrollview.cpp
+++ b/src/quicktemplates2/qquickscrollview.cpp
@@ -49,6 +49,7 @@ QT_BEGIN_NAMESPACE
     \inqmlmodule QtQuick.Controls
     \since 5.9
     \ingroup qtquickcontrols2-containers
+    \ingroup qtquickcontrols2-focusscopes
     \brief Scrollable view.
 
     ScrollView provides scrolling for user-defined content. It can be used to
@@ -97,6 +98,7 @@ QT_BEGIN_NAMESPACE
     \snippet qtquickcontrols2-scrollview-interactive.qml file
 
     \sa ScrollBar, ScrollIndicator, {Customizing ScrollView}, {Container Controls},
+        {Focus Management in Qt Quick Controls 2}
 */
 
 class QQuickScrollViewPrivate : public QQuickControlPrivate
diff --git a/src/quicktemplates2/qquickspinbox.cpp b/src/quicktemplates2/qquickspinbox.cpp
index 525de945..04bdec43 100644
--- a/src/quicktemplates2/qquickspinbox.cpp
+++ b/src/quicktemplates2/qquickspinbox.cpp
@@ -59,6 +59,7 @@ static const int AUTO_REPEAT_INTERVAL = 100;
     \inqmlmodule QtQuick.Controls
     \since 5.7
     \ingroup input
+    \ingroup qtquickcontrols2-focusscopes
     \brief Allows the user to select from a set of preset values.
 
     \image qtquickcontrols2-spinbox.png
@@ -91,7 +92,7 @@ static const int AUTO_REPEAT_INTERVAL = 100;
 
     \snippet qtquickcontrols2-spinbox-double.qml 1
 
-    \sa Tumbler, {Customizing SpinBox}
+    \sa Tumbler, {Customizing SpinBox}, {Focus Management in Qt Quick Controls 2}
 */
 
 /*!
diff --git a/src/quicktemplates2/qquickstackview.cpp b/src/quicktemplates2/qquickstackview.cpp
index 090a6d74..1abc506b 100644
--- a/src/quicktemplates2/qquickstackview.cpp
+++ b/src/quicktemplates2/qquickstackview.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \since 5.7
     \ingroup qtquickcontrols2-navigation
     \ingroup qtquickcontrols2-containers
+    \ingroup qtquickcontrols2-focusscopes
     \brief Provides a stack-based navigation model.
 
     \image qtquickcontrols2-stackview-wireframe.png
@@ -342,7 +343,8 @@ QT_BEGIN_NAMESPACE
     }
     \endqml
 
-    \sa {Customizing StackView}, {Navigation Controls}, {Container Controls}
+    \sa {Customizing StackView}, {Navigation Controls}, {Container Controls},
+        {Focus Management in Qt Quick Controls 2}
 */
 
 QQuickStackView::QQuickStackView(QQuickItem *parent)
diff --git a/src/quicktemplates2/qquickswipeview.cpp b/src/quicktemplates2/qquickswipeview.cpp
index 5f84f93e..60bc9477 100644
--- a/src/quicktemplates2/qquickswipeview.cpp
+++ b/src/quicktemplates2/qquickswipeview.cpp
@@ -49,6 +49,7 @@ QT_BEGIN_NAMESPACE
     \since 5.7
     \ingroup qtquickcontrols2-navigation
     \ingroup qtquickcontrols2-containers
+    \ingroup qtquickcontrols2-focusscopes
     \brief Enables the user to navigate pages by swiping sideways.
 
     SwipeView provides a swipe-based navigation model.
@@ -98,7 +99,8 @@ QT_BEGIN_NAMESPACE
           this only applies to the root of the item. Specifying width and height,
           or using anchors for its children works as expected.
 
-    \sa TabBar, PageIndicator, {Customizing SwipeView}, {Navigation Controls}, {Container Controls}
+    \sa TabBar, PageIndicator, {Customizing SwipeView}, {Navigation Controls}, {Container Controls},
+        {Focus Management in Qt Quick Controls 2}
 */
 
 class QQuickSwipeViewPrivate : public QQuickContainerPrivate
diff --git a/src/quicktemplates2/qquicktabbar.cpp b/src/quicktemplates2/qquicktabbar.cpp
index 814d14ea..cd0c5c45 100644
--- a/src/quicktemplates2/qquicktabbar.cpp
+++ b/src/quicktemplates2/qquicktabbar.cpp
@@ -48,6 +48,7 @@ QT_BEGIN_NAMESPACE
     \since 5.7
     \ingroup qtquickcontrols2-navigation
     \ingroup qtquickcontrols2-containers
+    \ingroup qtquickcontrols2-focusscopes
     \brief Allows the user to switch between different views or subtasks.
 
     TabBar provides a tab-based navigation model.
@@ -90,7 +91,8 @@ QT_BEGIN_NAMESPACE
 
     \snippet qtquickcontrols2-tabbar-flickable.qml 1
 
-    \sa TabButton, {Customizing TabBar}, {Navigation Controls}, {Container Controls}
+    \sa TabButton, {Customizing TabBar}, {Navigation Controls}, {Container Controls},
+        {Focus Management in Qt Quick Controls 2}
 */
 
 class QQuickTabBarPrivate : public QQuickContainerPrivate