Docs: promote the icon docs on its own page

- other controls (textfield, combobox, ...) will eventually gain support
  for icons too
- advertise icon support on the index page amongst other important topics
- document the steps for building an icon theme with high-dpi support

Change-Id: I35ed76ef005d7e273beb5f5147ca92849adc0d90
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>

3 files changed, 172 insertions, 52 deletions

diff --git a/src/imports/controls/doc/src/qtquickcontrols2-icons.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-icons.qdoc
new file mode 100644
index 00000000..c35af60c
--- /dev/null
+++ b/src/imports/controls/doc/src/qtquickcontrols2-icons.qdoc
@@ -0,0 +1,169 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \page qtquickcontrols2-icons.html
+    \title Icons in Qt Quick Controls 2
+
+    Qt Quick Controls 2.3 (Qt 5.10) introduced built-in support for icons. Buttons,
+    item delegates, and menu items are now capable of presenting an icon in addition
+    to a text label.
+
+    \section1 Using Icons
+
+    \l {AbstractButton::icon}{AbstractButton} and \l {Action::icon}{Action} provide
+    the following properties through which icons can be set:
+    \list
+        \li \c icon.name
+        \li \c icon.source
+        \li \c icon.width
+        \li \c icon.height
+        \li \c icon.color
+    \endlist
+
+    Theme icons are referenced by a name, and regular icons by a source URL. Both
+    \c icon.name and \c icon.source can be set to ensure that an icon will always
+    be found. If the icon is found in the theme, it will always be used; even if
+    \c icon.source is also set. If the icon is not found in the theme, \c icon.source
+    will be used instead.
+
+    \code
+    Button {
+        icon.name: "edit-cut"
+        icon.source: "images/cut.png"
+    }
+    \endcode
+
+    Each \l {Styling Qt Quick Controls 2}{Qt Quick Controls 2 style} requests a
+    default icon size and color according to their guidelines, but it is possible
+    to override these by setting the \c icon.width, \c icon.height, and \c icon.color
+    properties.
+
+    The image that is loaded by an icon whose \c width and \c height are not set
+    depends on the type of icon in use. For theme icons, the closest available size
+    will be chosen. For regular icons, the behavior is the same as the \l {Image::}
+    {sourceSize} property of \l Image.
+
+    The icon color is specified by default so that it matches the text color in
+    different states. In order to use an icon with the original colors, set the
+    color to \c "transparent".
+
+    \code
+    Button {
+        icon.color: "transparent"
+        icon.source: "images/logo.png"
+    }
+    \endcode
+
+    For buttons, the \l {AbstractButton::}{display} property can be used to control
+    how the icon and text are displayed within the button.
+
+    \section1 Icon Themes
+
+    Compliant icon themes must follow the freedesktop icon theme specification,
+    which can be obtained here: \l {http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html}.
+
+    Traditionally, only Linux and UNIX support icon themes on the platform level,
+    but it is possible to bundle a compliant icon theme in an application to use
+    themed icons on any platform.
+
+    The default \l {QIcon::themeSearchPaths()}{icon theme search paths} depend on
+    the platform. On Linux and UNIX, the search path will use the \c XDG_DATA_DIRS
+    environment variable if available. All platforms have the resource directory
+    \c :/icons as a fallback. Custom icon theme search paths can be set with
+    \l QIcon::setThemeSearchPaths().
+
+    The following example bundles an icon theme called \e mytheme into the application's
+    resources using \l {The Qt Resource System}{Qt's resource system}.
+
+    \badcode
+    <RCC>
+        <qresource prefix="/">
+            <file>icons/mytheme/index.theme</file>
+            <file>icons/mytheme/32x32/myicon.png</file>
+            <file>icons/mytheme/32x32@2/myicon.png</file>
+        </qresource>
+    </RCC>
+    \endcode
+
+    The \c index.theme file describes the general attributes of the icon theme, and
+    lists the available theme icon directories:
+
+    \badcode
+    [Icon Theme]
+    Name=mytheme
+    Comment=My Icon Theme
+
+    Directories=32x32,32x32@2
+
+    [32x32]
+    Size=32
+    Type=Fixed
+
+    [32x32@2]
+    Size=32
+    Scale=2
+    Type=Fixed
+    \endcode
+
+    In order to use the bundled icon theme, an application should call \l QIcon::setThemeName()
+    before loading the main QML file:
+
+    \code
+    #include <QGuiApplication>
+    #include <QQmlApplicationEngine>
+    #include <QIcon>
+
+    int main(int argc, char *argv[])
+    {
+        QGuiApplication app(argc, argv);
+
+        QIcon::setThemeName("mytheme"); // <--
+
+        QQmlApplicationEngine engine;
+        engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
+        return app.exec();
+    }
+    \endcode
+
+    Now it is possible to use named icons from the bundled icon theme without having
+    to specify any fallback source:
+
+    \code
+    Button {
+        icon.name: "myicon"
+    }
+    \endcode
+
+    The \l {Qt Quick Controls 2 - Gallery}{Gallery example} provides a complete runnable
+    application with a bundled icon theme.
+
+    \section1 Related Information
+    \list
+        \li \l {High-DPI Support in Qt Quick Controls 2}
+    \endlist
+*/
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc
index f64901d5..661266aa 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc
@@ -113,6 +113,7 @@
     \list
       \li \l{Qt Quick Controls 2 Guidelines}{Guidelines}
       \li \l{Styling Qt Quick Controls 2}{Styling}
+      \li \l{Icons in Qt Quick Controls 2}{Icons}
       \li \l{Customizing Qt Quick Controls 2}{Customization}
       \li \l{High-DPI Support in Qt Quick Controls 2}{High-DPI Support}
       \li \l{Using File Selectors with Qt Quick Controls 2}{Using File Selectors}
diff --git a/src/quicktemplates2/qquickabstractbutton.cpp b/src/quicktemplates2/qquickabstractbutton.cpp
index 2100dce2..2c77d941 100644
--- a/src/quicktemplates2/qquickabstractbutton.cpp
+++ b/src/quicktemplates2/qquickabstractbutton.cpp
@@ -68,56 +68,6 @@ static const int AUTO_REPEAT_INTERVAL = 100;
     radio buttons and check boxes. As an abstract control, it has no delegate
     implementations, leaving them to the types that derive from it.
 
-    \section2 Button Icons
-
-    AbstractButton provides the following properties through which icons can
-    be set:
-
-    \list
-    \li \l icon.name
-    \li \l icon.source
-    \li \l icon.width
-    \li \l icon.height
-    \li \l icon.color
-    \endlist
-
-    For applications that target platforms that support both
-    \l {QIcon::fromTheme()}{theme icons} and regular icons,
-    both \l icon.name and \l icon.source can be set to ensure that an icon will
-    always be found. If the icon is found in the theme, it will always be used;
-    even if \l icon.source is also set. If the icon is not found,
-    \l icon.source will be used instead.
-
-    \code
-    Button {
-        icon.name: "edit-cut"
-        icon.source: "qrc:/icons/edit-cut.png"
-    }
-    \endcode
-
-    Each \l {Styling Qt Quick Controls 2}{style} sets a default icon size and
-    color according to their guidelines, but it is possible to override these
-    by setting the \l icon.width, \l icon.height, and \l icon.color properties.
-
-    The image that is loaded by an icon whose \c width and \c height are not set
-    depends on the type of icon in use. For theme icons, the closest available
-    size will be chosen. For regular icons, the behavior is the same as the
-    \l {Image::}{sourceSize} property of \l Image.
-
-    The icon color is specified by default so that it matches the text color in
-    different states. In order to use an icon with the original colors, set the
-    color to \c "transparent".
-
-    \code
-    Button {
-        icon.color: "transparent"
-        icon.source: "qrc:/icons/logo.png"
-    }
-    \endcode
-
-    The \l display property can be used to control how the icon and text are
-    displayed within the button.
-
     \sa ButtonGroup, {Button Controls}
 */
 
@@ -441,7 +391,7 @@ QQuickAbstractButton::~QQuickAbstractButton()
     \note The text is used for accessibility purposes, so it makes sense to
           set a textual description even if the content item is an image.
 
-    \sa {Control::contentItem}{contentItem}
+    \sa icon, display, {Control::contentItem}{contentItem}
 */
 QString QQuickAbstractButton::text() const
 {
@@ -686,7 +636,7 @@ void QQuickAbstractButton::setIndicator(QQuickItem *indicator)
 
     \include qquickicon.qdocinc grouped-properties
 
-    \sa {Button Icons}
+    \sa text, display, {Icons in Qt Quick Controls 2}
 */
 
 QQuickIcon QQuickAbstractButton::icon() const