Doc: Using File Selectors with Qt Labs Controls

Change-Id: I55a8fa716540d7ee2bd03018c6fefae3f400ca0d
Reviewed-by: Mitch Curtis <mitch.curtis@theqtcompany.com>

5 files changed, 171 insertions, 14 deletions

diff --git a/src/imports/controls/doc/src/qtlabscontrols-fileselectors.qdoc b/src/imports/controls/doc/src/qtlabscontrols-fileselectors.qdoc
new file mode 100644
index 00000000..4e14c37b
--- /dev/null
+++ b/src/imports/controls/doc/src/qtlabscontrols-fileselectors.qdoc
@@ -0,0 +1,141 @@
+/****************************************************************************
+**
+** 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 qtlabscontrols-fileselectors.html
+    \title Using File Selectors with Qt Labs Controls
+
+    \l {QFileSelector}{File selectors} provide a convenient way of selecting
+    file variants. Qt offers the platform name and the locale as built-in
+    selectors. Qt Labs Controls extends the built-in selectors with the name
+    of the style that an application is running with.
+
+    By using file selectors, style-specific tweaks can be applied without
+    creating a hard dependency to a style. From the available file variants,
+    only the selected QML file is loaded by the QML engine. Each file variant
+    can assume the context, that is, a specific style. This typically leads
+    to some code duplication, but on the other hand, cuts the aforementioned
+    hard dependency to the style, and leads to simpler and more efficient
+    QML code. The same technique is used to implement the \l {Styling Qt
+    Labs Controls}{Qt Labs Controls styles}.
+
+    The following example demonstrates a custom rounded button that has a
+    styled drop shadow in the \l {Material Style}{Material style}, and looks
+    flat in other styles. The files are organized so that the Material version
+    of \c CustomButton.qml is placed into a \c +material sub-directory.
+
+    \code
+    :/main.qml
+    :/CustomButton.qml
+    :/+material/CustomButton.qml
+    \endcode
+
+    By default, \c main.qml will use \c CustomButton.qml for the \c CustomButton
+    type. However, when the application is run with the Material style, the
+    \c material selector will be present and the \c +material/CustomButton.qml
+    version will be used instead.
+
+    \code
+    // main.qml
+    import QtQuick 2.6
+    import Qt.labs.controls 1.0
+
+    ApplicationWindow {
+        id: window
+        visible: true
+
+        CustomButton {
+            text: "Button"
+            anchors.centerIn: parent
+        }
+    }
+    \endcode
+
+    The base implementation of the custom button is a simple rounded
+    flat button.
+
+    \code
+    // CustomButton.qml
+    import QtQuick 2.6
+    import Qt.labs.controls 1.0
+
+    Button {
+        id: control
+
+        background: Rectangle {
+            radius: width / 2
+            implicitWidth: 36
+            implicitHeight: 36
+            color: control.pressed ? "#ccc" : "#eee"
+        }
+    }
+    \endcode
+
+    The Material style's implementation of the custom button imports the
+    Material style, requests a dark theme to get light text, and creates
+    a drop shadow for the background.
+
+    \code
+    // +material/CustomButton.qml
+    import QtQuick 2.6
+    import QtGraphicalEffects 1.0
+    import Qt.labs.controls 1.0
+    import Qt.labs.controls.material 1.0
+
+    Button {
+        id: control
+
+        Material.theme: Material.Dark
+
+        background: Rectangle {
+            implicitWidth: 48
+            implicitHeight: 48
+            color: Material.accentColor
+            radius: width / 2
+
+            layer.enabled: control.enabled
+            layer.effect: DropShadow {
+                verticalOffset: 1
+                color: Material.dropShadowColor
+                samples: control.pressed ? 20 : 10
+                spread: 0.5
+            }
+        }
+    }
+    \endcode
+
+    \note It is recommended to use \l QQmlApplicationEngine, which internally
+    creates a \l QQmlFileSelector instance. This is all that is needed to take
+    QML file selectors in use.
+
+    \section1 Related Information
+    \list
+      \li \l {QFileSelector}
+      \li \l {QQmlFileSelector}
+      \li \l {Styling Qt Labs Controls}
+    \endlist
+*/
diff --git a/src/imports/controls/doc/src/qtlabscontrols-index.qdoc b/src/imports/controls/doc/src/qtlabscontrols-index.qdoc
index 2f554db7..e8fa2303 100644
--- a/src/imports/controls/doc/src/qtlabscontrols-index.qdoc
+++ b/src/imports/controls/doc/src/qtlabscontrols-index.qdoc
@@ -48,6 +48,7 @@
       \li \l{Getting Started with Qt Labs Controls}
       \li \l{Styling Qt Labs Controls}
       \li \l{High-DPI Support in Qt Labs Controls}
+      \li \l{Using File Selectors with Qt Labs Controls}
       \li \l{Differences between Qt Quick Controls}
     \endlist
 
diff --git a/src/imports/controls/doc/src/qtlabscontrols-material.qdoc b/src/imports/controls/doc/src/qtlabscontrols-material.qdoc
index e2cadbda..d5a3bd00 100644
--- a/src/imports/controls/doc/src/qtlabscontrols-material.qdoc
+++ b/src/imports/controls/doc/src/qtlabscontrols-material.qdoc
@@ -116,13 +116,20 @@
                 \image qtlabscontrols-material-dark.png
     \endtable
 
-    \note The Material style must be separately imported to gain access to
-    these style-specific attributes. It should be noted that regardless of the
-    references to the Material style, the same application code runs with any
-    other style. The Material style-specific attributes only have an effect
-    when the application is run with the Material style. Furthermore, in case
-    of explicit Material style-specific references, the Material style must
-    be deployed with the application.
+    \section2 Dependency
+
+    The Material style must be separately imported to gain access to the
+    attributes that are specific to the Material style. It should be noted
+    that regardless of the references to the Material style, the same
+    application code runs with any other style. Material-specific attributes
+    only have an effect when the application is run with the Material style.
+
+    If the Material style is imported in a QML file that is always loaded, the
+    Material style must be deployed with the application in order to be able
+    to run the application regardless of which style the application is run with.
+    By using \l {Using File Selectors with Qt Labs Controls}{file selectors},
+    style-specific tweaks can be applied without creating a hard dependency to
+    a style.
 
     \section2 Pre-defined Colors
 
diff --git a/src/imports/controls/doc/src/qtlabscontrols-styles.qdoc b/src/imports/controls/doc/src/qtlabscontrols-styles.qdoc
index 858a9105..46939712 100644
--- a/src/imports/controls/doc/src/qtlabscontrols-styles.qdoc
+++ b/src/imports/controls/doc/src/qtlabscontrols-styles.qdoc
@@ -115,5 +115,6 @@
     \li \l {Default Style}
     \li \l {Material Style}
     \li \l {Universal Style}
+    \li \l{Using File Selectors with Qt Labs Controls}
     \endlist
 */
diff --git a/src/imports/controls/doc/src/qtlabscontrols-universal.qdoc b/src/imports/controls/doc/src/qtlabscontrols-universal.qdoc
index bf3dcfdc..3c09bdd0 100644
--- a/src/imports/controls/doc/src/qtlabscontrols-universal.qdoc
+++ b/src/imports/controls/doc/src/qtlabscontrols-universal.qdoc
@@ -116,13 +116,20 @@
                 \image qtlabscontrols-universal-dark.png
     \endtable
 
-    \note The Universal style must be separately imported to gain access to
-    these style-specific attributes. It should be noted that regardless of the
-    references to the Universal style, the same application code runs with any
-    other style. The Universal style-specific attributes only have an effect
-    when the application is run with the Universal style. Furthermore, in case
-    of explicit Universal style-specific references, the Universal style must
-    be deployed with the application.
+    \section2 Dependency
+
+    The Universal style must be separately imported to gain access to the
+    attributes that are specific to the Universal style. It should be noted
+    that regardless of the references to the Universal style, the same
+    application code runs with any other style. Universal-specific attributes
+    only have an effect when the application is run with the Universal style.
+
+    If the Universal style is imported in a QML file that is always loaded, the
+    Universal style must be deployed with the application in order to be able
+    to run the application regardless of which style the application is run with.
+    By using \l {Using File Selectors with Qt Labs Controls}{file selectors},
+    style-specific tweaks can be applied without creating a hard dependency to
+    a style.
 
     \labs