diff options
Diffstat (limited to 'src/imports/controls/doc/src/qtquickcontrols2-material.qdoc')
| -rw-r--r-- | src/imports/controls/doc/src/qtquickcontrols2-material.qdoc | 367 |
1 files changed, 367 insertions, 0 deletions
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-material.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-material.qdoc new file mode 100644 index 00000000..9842fee6 --- /dev/null +++ b/src/imports/controls/doc/src/qtquickcontrols2-material.qdoc @@ -0,0 +1,367 @@ +/**************************************************************************** +** +** 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-material.html + \title Material Style + + The Material Style is based on the Google Material Design Guidelines. + \l{detailed-desc-material}{More...} + + \styleimport {QtQuick.Controls.Material 2.0} {Qt 5.7} + + \section1 Attached Properties + + \list + \li \l {material-accent-attached-prop}{\b accent} : color + \li \l {material-background-attached-prop}{\b background} : color + \li \l {material-elevation-attached-prop}{\b elevation} : int + \li \l {material-foreground-attached-prop}{\b foreground} : color + \li \l {material-primary-attached-prop}{\b primary} : color + \li \l {material-theme-attached-prop}{\b theme} : enumeration + \endlist + + \section1 Attached Methods + + \list + \li color \l {material-color-attached-method}{\b color}(enumeration predefined, enumeration shade) + \endlist + + \section1 Detailed Description + \target detailed-desc-material + + The Material style is based on the \l {https://www.google.com/design/spec/material-design/introduction.html} + {Google Material Design Guidelines}. It allows for a unified experience + across platforms and device sizes. + + \image qtquickcontrols2-material.png + \caption The Material style in light and dark themes + + To run an application with the Material style, see + \l {Using Styles in Qt Quick Controls 2}. + + \note The Material style is not a native Android style. The Material + style is a 100% cross-platform Qt Quick Controls 2 style implementation that + follows the Google Material Design Guidelines. The style runs on any + platform, and looks more or less identical everywhere. Minor differences + may occur due to differences in available system fonts and font rendering + engines. + + \section2 Customization + + The Material style allows customizing five attributes, \l {material-theme-attached-prop}{theme}, + \l {material-primary-attached-prop}{primary}, \l {material-accent-attached-prop}{accent}, + \l {material-foreground-attached-prop}{foreground}, and \l {material-background-attached-prop}{background}. + + \image qtquickcontrols2-material-attributes.png + + All attributes can be specified for any window or item, and they automatically + propagate to children in the same manner as \l {Control::font}{fonts}. In the + following example, the window and all three radio buttons appear in the dark + theme using a purple accent color: + + \table + \row + \li + \qml + import QtQuick 2.0 + import QtQuick.Controls 2.0 + import QtQuick.Controls.Material 2.0 + + ApplicationWindow { + visible: true + + Material.theme: Material.Dark + Material.accent: Material.Purple + + Column { + anchors.centerIn: parent + + RadioButton { text: qsTr("Small") } + RadioButton { text: qsTr("Medium"); checked: true } + RadioButton { text: qsTr("Large") } + } + } + \endqml + \li + \image qtquickcontrols2-material-dark.png + \endtable + + In addition to specifying the attributes in QML, it is also possible to + specify them via environment variables or in a configuration file. Attributes + specified in QML take precedence over all other methods. + + \section3 Configuration File + + \include qquickmaterialstyle.qdocinc conf + + See \l {Qt Quick Controls 2 Configuration File} for more details about the + configuration file. + + \section3 Environment Variables + + \include qquickmaterialstyle.qdocinc env + + See \l {Supported Environment Variables in Qt Quick Controls 2} for the full + list of supported environment variables. + + \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 Quick Controls 2}{file selectors}, + style-specific tweaks can be applied without creating a hard dependency to + a style. + + \section2 Pre-defined Material Colors + + Even though primary and accent can be any \l {colorbasictypedocs}{color}, it + is recommended to use one of the pre-defined colors that have been designed + to work well with the rest of the Material style palette: + + Available pre-defined colors: + \value Material.Red \stylecolor {#F44336} {} + \value Material.Pink \stylecolor {#E91E63} {(default accent)} + \value Material.Purple \stylecolor {#9C27B0} {} + \value Material.DeepPurple \stylecolor {#673AB7} {} + \value Material.Indigo \stylecolor {#3F51B5} {(default primary)} + \value Material.Blue \stylecolor {#2196F3} {} + \value Material.LightBlue \stylecolor {#03A9F4} {} + \value Material.Cyan \stylecolor {#00BCD4} {} + \value Material.Teal \stylecolor {#009688} {} + \value Material.Green \stylecolor {#4CAF50} {} + \value Material.LightGreen \stylecolor {#8BC34A} {} + \value Material.Lime \stylecolor {#CDDC39} {} + \value Material.Yellow \stylecolor {#FFEB3B} {} + \value Material.Amber \stylecolor {#FFC107} {} + \value Material.Orange \stylecolor {#FF9800} {} + \value Material.DeepOrange \stylecolor {#FF5722} {} + \value Material.Brown \stylecolor {#795548} {} + \value Material.Grey \stylecolor {#9E9E9E} {} + \value Material.BlueGrey \stylecolor {#607D8B} {} + + When the dark theme is in use, different \l {Pre-defined Shades}{shades} of + the pre-defined colors are used by default: + + \value Material.Red \stylecolor {#EF9A9A} {} + \value Material.Pink \stylecolor {#F48FB1} {(default accent)} + \value Material.Purple \stylecolor {#CE93D8} {} + \value Material.DeepPurple \stylecolor {#B39DDB} {} + \value Material.Indigo \stylecolor {#9FA8DA} {(default primary)} + \value Material.Blue \stylecolor {#90CAF9} {} + \value Material.LightBlue \stylecolor {#81D4FA} {} + \value Material.Cyan \stylecolor {#80DEEA} {} + \value Material.Teal \stylecolor {#80CBC4} {} + \value Material.Green \stylecolor {#A5D6A7} {} + \value Material.LightGreen \stylecolor {#C5E1A5} {} + \value Material.Lime \stylecolor {#E6EE9C} {} + \value Material.Yellow \stylecolor {#FFF59D} {} + \value Material.Amber \stylecolor {#FFE082} {} + \value Material.Orange \stylecolor {#FFCC80} {} + \value Material.DeepOrange \stylecolor {#FFAB91} {} + \value Material.Brown \stylecolor {#BCAAA4} {} + \value Material.Grey \stylecolor {#EEEEEE} {} + \value Material.BlueGrey \stylecolor {#B0BEC5} {} + + \section2 Pre-defined Shades + + There are several different + \l {https://material.google.com/style/color.html#color-color-palette}{shades} + of each \l {Pre-defined Material Colors}{pre-defined color} that can be passed + to the \l {material-color-attached-method}{Material.color()} function: + \value Material.Shade50 + \value Material.Shade100 + \value Material.Shade200 + \value Material.Shade300 + \value Material.Shade400 + \value Material.Shade500 + \value Material.Shade600 + \value Material.Shade700 + \value Material.Shade800 + \value Material.Shade900 + \value Material.ShadeA100 + \value Material.ShadeA200 + \value Material.ShadeA400 + \value Material.ShadeA700 + + \b {See also} \l {Default Style}, \l {Universal Style} + + \section1 Attached Property Documentation + + \styleproperty {Material.accent} {color} {material-accent-attached-prop} + \target material-accent-attached-prop + This attached property holds the accent color of the theme. The property + can be attached to any window or item. The value is propagated to children. + + The default value is \c Material.Pink. + + In the following example, the accent color of the highlighted button is + changed to \c Material.Orange: + + \table + \row + \li + \snippet qtquickcontrols2-material-accent.qml 1 + \li + \image qtquickcontrols2-material-accent.png + \endtable + + \note Even though the accent can be any \l {colorbasictypedocs}{color}, it is + recommended to use one of the \l {pre-defined Material colors} that have been + designed to work well with the rest of the Material style palette. + + \endstyleproperty + + \styleproperty {Material.background} {color} {material-background-attached-prop} + \target material-background-attached-prop + This attached property holds the background color of the theme. The property + can be attached to any window or item. The value is propagated to children. + + The default value is theme-specific (light or dark). + + In the following example, the background color of the button is changed to + \c Material.Teal: + + \table + \row + \li + \snippet qtquickcontrols2-material-background.qml 1 + \li + \image qtquickcontrols2-material-background.png + \endtable + + \endstyleproperty + + \styleproperty {Material.elevation} {int} {material-elevation-attached-prop} + \target material-elevation-attached-prop + This attached property holds the elevation of the control. The higher the + elevation, the deeper the shadow. The property can be attached to any control, + but not all controls visualize elevation. + + The default value is control-specific. + + In the following example, the elevation of the pane is set to \c 6 + in order to achieve the look of an + \l {https://material.google.com/components/cards.html}{elevated card}: + + \table + \row + \li + \snippet qtquickcontrols2-material-elevation.qml 1 + \li + \image qtquickcontrols2-material-elevation.png + \endtable + + \endstyleproperty + + \styleproperty {Material.foreground} {color} {material-foreground-attached-prop} + \target material-foreground-attached-prop + This attached property holds the foreground color of the theme. The property + can be attached to any window or item. The value is propagated to children. + + The default value is theme-specific (light or dark). + + In the following example, the foreground color of the button is set to \c + Material.Pink: + + \table + \row + \li + \snippet qtquickcontrols2-material-foreground.qml 1 + \li + \image qtquickcontrols2-material-foreground.png + \endtable + + \endstyleproperty + + \styleproperty {Material.primary} {color} {material-primary-attached-prop} + \target material-primary-attached-prop + This attached property holds the primary color of the theme. The property + can be attached to any window or item. The value is propagated to children. + + The primary color is used as the background color of ToolBar by default. + + The default value is \c Material.Indigo. + + \note Even though the primary can be any \l {colorbasictypedocs}{color}, it is + recommended to use one of the \l {pre-defined Material colors} that have been + designed to work well with the rest of the Material style palette. + + \endstyleproperty + + \styleproperty {Material.theme} {enumeration} {material-theme-attached-prop} + \target material-theme-attached-prop + This attached property holds whether the theme is light or dark. The property + can be attached to any window or item. The value is propagated to children. + + Available themes: + \value Material.Light Light theme (default) + \value Material.Dark Dark theme + + In the following example, the theme for both the pane and the button is set + to \c Material.Dark: + + \table + \row + \li + \snippet qtquickcontrols2-material-theme.qml 1 + \li + \image qtquickcontrols2-material-theme.png + \endtable + + \endstyleproperty + + \section1 Attached Method Documentation + + \stylemethod2 {color} {color} {enumeration} {predefined} {enumeration} {shade} {material-color-attached-method} + \target material-color-attached-method + This attached method returns the effective color value of the specified + \l {pre-defined Material colors}{pre-defined Material color} combined with + the given \l {pre-defined shades}{shade}. If omitted, the shade argument + defaults to \c Material.Shade500. + + \qml + Rectangle { + color: Material.color(Material.Red) + } + \endqml + + \endstylemethod2 + + \section1 Related Information + + \list + \li \l{Styling Qt Quick Controls 2} + \endlist +*/ |