Merge remote-tracking branch 'origin/5.7' into dev

Change-Id: If502b986cc8d6729ebea64cedfdf97b9b612e7c0

11 files changed, 169 insertions, 14 deletions

diff --git a/src/imports/controls/doc/src/qtquickcontrols2-buttons.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-buttons.qdoc
index ef084fcf..48b0097d 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-buttons.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-buttons.qdoc
@@ -28,6 +28,8 @@
 /*!
     \page qtquickcontrols2-buttons.html
     \title Button Controls
+    \ingroup qtquickcontrols2-guidelines
+    \brief Guidelines for button controls
 
     Qt Quick Controls 2 offers a selection of button-like controls.
 
@@ -162,4 +164,8 @@
 
     \b {See also} \l ToolButton
 
+    \section1 Related Information
+    \list
+    \li \l {Qt Quick Controls 2 Guidelines}
+    \endlist
 */
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-containers.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-containers.qdoc
index 1786a4f1..c7a68968 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-containers.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-containers.qdoc
@@ -41,7 +41,8 @@
 
     \image qtquickcontrols2-applicationwindow-wireframe.png
 
-    \l ApplicationWindow contains optional header and footer items.
+    \l ApplicationWindow creates the root window of an application, and makes
+    it easy to add an optional header and footer to that window.
 
     \section1 Frame Control
 
@@ -62,19 +63,26 @@
     \image qtquickcontrols2-page-wireframe.png
 
     \l Page provides page-specific header and footer items.
+    It is perfectly possible to use ApplicationWindow for setting the header
+    and the footer, but if you have a header and footer which varies per
+    screen, then it is better to use \l Page.
 
     \section1 Pane Control
 
     \image qtquickcontrols2-pane.png
 
     \l Pane provides a background color that matches with the application
-    style and theme.
+    style and theme. Pane does not provide a layout of its own, but requires
+    you to position its contents, for instance by using a \l RowLayout or
+    a \l ColumnLayout.
 
     \section1 StackView Control
 
     \image qtquickcontrols2-stackview-wireframe.png
 
-    \l StackView organizes content pages into a stack.
+    \l StackView organizes content pages into a stack using a last-in-first-out
+    principle: the last item to be "pushed" onto the stack is the first one to
+    be removed, and the top-most item is always the one that is visible.
 
     \section1 SwipeView Control
 
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-delegates.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-delegates.qdoc
index 3c8d5ea7..0ecfdf42 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-delegates.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-delegates.qdoc
@@ -28,6 +28,8 @@
 /*!
     \page qtquickcontrols2-delegates.html
     \title Delegate Controls
+    \ingroup qtquickcontrols2-guidelines
+    \brief Guidelines for delegate controls
 
     Qt Quick Controls 2 offers a selection of controls that are used as
     delegates in views.
@@ -52,5 +54,20 @@
     \l RadioDelegate presents a checkable control that can be toggled on
     (checked) or off (unchecked). Radio delegates are typically used to select
     one option from a set of options.
+
+    \b {See also} \l {RadioButton Control}.
+
+    \section1 SwitchDelegate Control
+
+    \image qtquickcontrols2-switchdelegate.gif
+
+    \l SwitchDelegate presents a switchable delegate that can be toggled on or off.
+
+    \b {See also} \l {Switch Control}.
+
+    \section1 Related Information
+    \list
+    \li \l {Qt Quick Controls 2 Guidelines}
+    \endlist
 */
 
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-guidelines.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-guidelines.qdoc
new file mode 100644
index 00000000..87ba4cf1
--- /dev/null
+++ b/src/imports/controls/doc/src/qtquickcontrols2-guidelines.qdoc
@@ -0,0 +1,44 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 The Qt Company Ltd.
+** Contact: http://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 http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qtquickcontrols2-guidelines.html
+    \title Qt Quick Controls 2 Guidelines
+
+    Qt Quick Controls 2 offers a selection of controls that can be used to
+    build complete interfaces in Qt Quick.
+
+    Below you will find practical guidelines on how and when to use
+    the controls.
+
+    \annotatedlist qtquickcontrols2-guidelines
+
+    \section1 Related Information
+    \list
+      \li \l{Qt Quick Controls 2 QML Types}{All Qt Quick Controls 2 QML Types}
+    \endlist
+*/
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc
index 3f4467d5..171239ce 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc
@@ -62,6 +62,7 @@
     \section1 Important Concepts in Qt Quick Controls 2
 
     \list
+      \li \l{Qt Quick Controls 2 Guidelines}
       \li \l{Styling Qt Quick Controls 2}
       \li \l{Customizing Qt Quick Controls 2}
       \li \l{High-DPI Support in Qt Quick Controls 2}
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-indicators.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-indicators.qdoc
index dcc0ff9e..010ff444 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-indicators.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-indicators.qdoc
@@ -28,6 +28,8 @@
 /*!
     \page qtquickcontrols2-indicators.html
     \title Indicator Controls
+    \ingroup qtquickcontrols2-guidelines
+    \brief Guidelines for indicator controls
 
     Qt Quick Controls 2 offers a selection of indicator-like controls.
 
@@ -47,8 +49,8 @@
 
     \image qtquickcontrols2-pageindicator.png
 
-    \l PageIndicator is used to indicate the currently active page in
-    a container of multiple pages.
+    \l BusyIndicator can be used to show that an operation is in progress,
+    and that the UI has to wait for the operation to complete.
 
     \section1 ScrollBar Control
 
@@ -63,5 +65,11 @@
     \image qtquickcontrols2-scrollindicator.png
 
     \l ScrollIndicator is a non-interactive indicator that indicates the
-    current scroll position in a \l Flickable.
+    current scroll position, and can be used to scroll to a specific position in a
+    \l {Flickable}.
+
+    \section1 Related Information
+    \list
+    \li \l {Qt Quick Controls 2 Guidelines}
+    \endlist
 */
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc
index 60b2250f..681a9d89 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc
@@ -28,6 +28,8 @@
 /*!
     \page qtquickcontrols2-input.html
     \title Input Controls
+    \ingroup qtquickcontrols2-guidelines
+    \brief Guidelines for input controls
 
     Qt Quick Controls 2 offers a variety of input controls for both numeric
     and textual input.
@@ -42,13 +44,30 @@
 
     \image qtquickcontrols2-combobox.png
 
-    \l ComboBox is used to select a value from a drop-down list.
+    \l ComboBox is used to select a value from a static multiple-line drop-down list.
+    It is not possible to add new values, and only one option can be selected.
+
+    Recommendations:
+    \list
+    \li If the number of values is very large, consider applying a filter.
+    \li If the list is very limited, consider using RadioButton. This has the
+    advantage that the user can see all options at the same time.
+    \li Select a default value, the value that will be chosen most often.
+    \endlist
+
+    \b {See also} \l {CheckBox Control}, \l {Tumbler Control}.
 
     \section1 Dial Control
 
     \image qtquickcontrols2-dial.png
 
-    \l Dial is a circular dial that is rotated to set a value.
+    \l Dial is similar to a traditional dial knob that is found on devices such
+    as stereos or industrial equipment.
+
+    The dial is rotated by clicking and dragging, with the handle indicating the
+    value of the dial.
+
+    \b {See also} \l {Tumbler Control}.
 
     \section1 TextArea Control
 
@@ -62,6 +81,8 @@
 
     \l TextField is a single line text editor.
 
+    \b {See also} \l {Tumbler Control}.
+
     \section1 Slider Control
 
     \image qtquickcontrols2-slider.png
@@ -75,9 +96,19 @@
     \l RangeSlider is used to select a range specified by two values,
     by sliding each handle along a track.
 
+
+    \b {See also} \l {Slider Control}.
+
     \section1 Tumbler Control
 
     \image qtquickcontrols2-tumbler.png
 
     \l Tumbler is a spinnable wheel of items that can be selected.
+
+    \b {See also} \l {ComboBox Control}.
+
+    \section1 Related Information
+    \list
+    \li \l {Qt Quick Controls 2 Guidelines}
+    \endlist
 */
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-menus.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-menus.qdoc
index d54b360c..faa8c3bc 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-menus.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-menus.qdoc
@@ -28,6 +28,8 @@
 /*!
     \page qtquickcontrols2-menus.html
     \title Menu Controls
+    \ingroup qtquickcontrols2-guidelines
+    \brief Guidelines for menu controls
 
     \annotatedlist qtquickcontrols2-menus
 
@@ -39,5 +41,15 @@
 
     \image qtquickcontrols2-menu.png
 
-    \l Menu is a traditional menu.
+    \l Menu control can be used for context menus; for example, after
+    right-clicking. It can also be used for popup menus; for example, a
+    menu that is shown after clicking a button.
+
+   \l MenuItem is an item in the Menu control. Each item in a menu:
+   \list
+   \li displays text to the user
+   \li allows checking/unchecking
+   \li is highlighted (for example, on keyboard navigation)
+   \li performs some action on activation
+   \endlist
 */
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-navigation.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-navigation.qdoc
index 8ddc2f3a..a2bd15a6 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-navigation.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-navigation.qdoc
@@ -28,6 +28,8 @@
 /*!
     \page qtquickcontrols2-navigation.html
     \title Navigation Controls
+    \ingroup qtquickcontrols2-guidelines
+    \brief Guidelines for navigation controls
 
     Qt Quick Controls 2 offers a selection of navigation models.
 
@@ -40,17 +42,29 @@
 
     \image qtquickcontrols2-stackview-wireframe.png
 
-    \l StackView provides a stack-based navigation model.
+    \l StackView provides a stack-based navigation model which can be used
+    with a set of interlinked pages. StackView works according to a last-in
+    first-out principle: the page pushed last on the stack is the one visible.
+    Popping a page removes the last page and makes the previous one visible.
 
     \section1 SwipeView Control
 
     \image qtquickcontrols2-swipeview-wireframe.png
 
-    \l SwipeView provides a swipe-based navigation model.
+    \l SwipeView provides a navigation model that simplifies horizontal paged
+    scrolling. The page indicator on the bottom shows which is the presently
+    active page.
 
-    \section1 TabBar and TabButton Controls
+    \section1 TabBar
 
     \image qtquickcontrols2-tabbar-wireframe.png
 
-    \l TabBar and \l TabButton provide a tab-based navigation model.
+    \l TabBar is a bar with icons or text that allows the user to switch
+    between different subtasks, views, or modes.
+
+    \section1 TabButton Control
+
+    \image qtquickcontrols2-tabbutton.png
+
+    \l TabButton is a button with a layout suitable for a TabBar control.
 */
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-popups.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-popups.qdoc
index 2ea21f3f..aa2efb90 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-popups.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-popups.qdoc
@@ -28,6 +28,8 @@
 /*!
     \page qtquickcontrols2-popups.html
     \title Popup Controls
+    \ingroup qtquickcontrols2-guidelines
+    \brief Guidelines for popup controls
 
     \annotatedlist qtquickcontrols2-popups
 
@@ -53,6 +55,8 @@
     The \l Menu control displays a vertical list of items that can be selected. It can
     be used for offering a list of actions that can be taken in a given context.
 
+    \b {See also} \l {Drawer Control}.
+
     \section1 Popup Control
 
     \image qtquickcontrols2-popup-settings.png
@@ -76,7 +80,7 @@
     \image qtquickcontrols2-tooltip.png
 
     \l ToolTip shows a short piece of text that informs the user of a control's
-    function.
+    function. It is typically placed above or below the parent control.
 
     Recommendations:
     \list
@@ -87,4 +91,9 @@
     \li Keep the tooltip text short so that it does not cover other content
     while being displayed.
     \endlist
+
+    \section1 Related Information
+    \list
+    \li \l {Qt Quick Controls 2 Guidelines}
+    \endlist
 */
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-qmltypes.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-qmltypes.qdoc
index 13a7f24e..52da41a7 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-qmltypes.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-qmltypes.qdoc
@@ -48,4 +48,9 @@
 
     For more information on the Qt Quick Controls 2 module, see the
     \l {Qt Quick Controls 2} module documentation.
+
+    \section1 Related Information
+    \list
+    \li \l {Qt Quick Controls 2 Guidelines}
+    \endlist
 */