1 files changed, 117 insertions, 0 deletions
diff --git a/src/quickcontrols/doc/src/qtquickcontrols-fileselectors.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-fileselectors.qdoc
new file mode 100644
index 0000000000..a03970d1d8
--- /dev/null
+++ b/src/quickcontrols/doc/src/qtquickcontrols-fileselectors.qdoc
@@ -0,0 +1,117 @@
+// Copyright (C) 2017 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \page qtquickcontrols-fileselectors.html
+    \title Using File Selectors with Qt Quick 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 Quick Controls extends the built-in selectors with the name
+    (Capitalized) 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 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
+    import QtQuick.Controls
+
+    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
+    import QtQuick.Controls
+
+    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
+    import QtQuick.Effects
+    import QtQuick.Controls
+    import QtQuick.Controls.Material
+
+    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: MultiEffect {
+                shadowEnabled: true
+                shadowHorizontalOffset: 3
+                shadowVerticalOffset: 3
+                shadowColor: Material.dropShadowColor
+                shadowBlur: control.pressed ? 0.8 : 0.4
+            }
+        }
+    }
+    \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 into use.
+
+    \section1 Related Information
+    \list
+      \li \l {QFileSelector}
+      \li \l {QQmlFileSelector}
+      \li \l {Styling Qt Quick Controls}
+    \endlist
+*/