diff options
author | J-P Nurmi <jpnurmi@theqtcompany.com> | 2016-02-23 13:50:07 +0100 |
---|---|---|
committer | J-P Nurmi <jpnurmi@theqtcompany.com> | 2016-02-23 15:11:33 +0000 |
commit | 25ade43fdb9feb68ef8eb756640a6b0a9ece3fec (patch) | |
tree | e8f660c1140c7ec71a9c2f33c716e7524c46e3d5 /src/imports | |
parent | 9d32fd6f446844a713d520fe02aa8c5c2104898d (diff) |
Doc: Using File Selectors with Qt Labs Controls
Change-Id: I55a8fa716540d7ee2bd03018c6fefae3f400ca0d
Reviewed-by: Mitch Curtis <mitch.curtis@theqtcompany.com>
Diffstat (limited to 'src/imports')
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 |