diff options
Diffstat (limited to 'src/quickcontrols/doc/src/qtquickcontrols-material.qdoc')
| -rw-r--r-- | src/quickcontrols/doc/src/qtquickcontrols-material.qdoc | 469 |
1 files changed, 469 insertions, 0 deletions
diff --git a/src/quickcontrols/doc/src/qtquickcontrols-material.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-material.qdoc new file mode 100644 index 0000000000..4052337ef8 --- /dev/null +++ b/src/quickcontrols/doc/src/qtquickcontrols-material.qdoc @@ -0,0 +1,469 @@ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtquickcontrols-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.12} {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 + \li \l {material-roundedScale-attached-prop}{\b roundedScale} : enumeration + \li \l {material-containerStyle-attached-prop}{\b containerStyle} : 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://m3.material.io} + {Google Material Design Guidelines}. It allows for a unified experience + across platforms and device sizes. + + \include style-screenshots.qdocinc {file} {Material} {material} + + To run an application with the Material style, see + \l {Using Styles in Qt Quick Controls}. + + \note The Material style is not a native Android style. The Material + style is a 100% cross-platform Qt Quick Controls 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. + + \note As the Material Design Guidelines change over time, this style may + change certain padding or font values, for example, in order to maintain + consistency with the guidelines. + + \section2 Customization + + The Material style supports several customizable attributes. Some of these + attributes \l {QQuickAttachedPropertyPropagator}{propagate} to children in + the same manner as \l {Control::font}{fonts}: + + \list + \li \l {material-theme-attached-prop}{theme} + \li \l {material-primary-attached-prop}{primary} + \li \l {material-accent-attached-prop}{accent} + \li \l {material-foreground-attached-prop}{foreground} + \li \l {material-background-attached-prop}{background} + \endlist + + \image qtquickcontrols-material-attributes.png + + The remaining attributes do not propagate to children: + \list + \li \l {material-elevation-attached-prop}{elevation} + \li \l {material-roundedScale-attached-prop}{roundedScale} + \li \l {material-containerStyle-attached-prop}{containerStyle} + \endlist + + 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 + import QtQuick.Controls + import QtQuick.Controls.Material + + 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 qtquickcontrols-material-purple.png + \endtable + + In addition to specifying the attributes in QML, it is also possible to + specify some of 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 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} 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}{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 {colorvaluetypedocs}{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 {Basic Style}, \l {Universal Style} + + \section2 Variants + + The Material style also supports a dense variant, where controls like + buttons and delegates are smaller in height and use smaller font sizes. + It is recommended to use the dense variant on desktop platforms, where + a mouse and keyboard allow more precise and flexible user interaction. + + To use the dense variant, either set the + \c QT_QUICK_CONTROLS_MATERIAL_VARIANT environment variable to \c Dense, + or specify \c Variant=Dense in the + \l {Qt Quick Controls Configuration File}{qtquickcontrols2.conf} file. + The default value in both cases is \c Normal. + + The following images illustrate the differences between some of the + controls when using the normal and dense variants: + + \table + \row + \li + \image qtquickcontrols-material-variant-normal.png + \li + \image qtquickcontrols-material-variant-dense.png + \endtable + + Note that the heights shown above may vary based on differences in fonts + across platforms. + + \section2 Control-Specific Notes + + \target material-control-specific-notes-textarea + \section3 TextArea + + TextArea supports two + \l {material-containerStyle-attached-prop}{containerStyles}: \c Filled and + \c Outlined. Outlined TextAreas have floating placeholder text that sits at + the top of the control. This requires the placeholder text to go outside + the bounds of the control, which can cause it to be + clipped when the TextArea or the Flickable it's a child of sets + \l {Item::}{clip} to \c true. To avoid this, \l {Control::}{topInset} is + set to an appropriate value in these cases. + + \include qquickmaterialstyle.qdocinc placeholder-text-multiple-lines + + \section3 TextField + + The same \l {material-control-specific-notes-textarea}{issue with clipping} + explained above for TextArea can also occur with \l TextField. To avoid + this, \l {Control::}{topInset} is set to an appropriate value when the + TextField sets clip to \c true. + + \include qquickmaterialstyle.qdocinc placeholder-text-multiple-lines + + \section1 Attached Property Documentation + + \styleproperty {Material.accent} {color} + \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 qtquickcontrols-material-accent.qml 1 + \li + \image qtquickcontrols-material-accent.png + \endtable + + \note Even though the accent can be any \l {colorvaluetypedocs}{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} + \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 qtquickcontrols-material-background.qml 1 + \li + \image qtquickcontrols-material-background.png + \endtable + + \endstyleproperty + + \styleproperty {Material.elevation} {int} + \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 value is not propagated to + children. + + 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://m3.material.io/components/cards/overview}{elevated card}: + + \table + \row + \li + \snippet qtquickcontrols-material-elevation.qml 1 + \li + \image qtquickcontrols-material-elevation.png + \endtable + + \endstyleproperty + + \styleproperty {Material.foreground} {color} + \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 qtquickcontrols-material-foreground.qml 1 + \li + \image qtquickcontrols-material-foreground.png + \endtable + + \endstyleproperty + + \styleproperty {Material.primary} {color} + \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 {colorvaluetypedocs}{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} + \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 + \value Material.System System theme + + Setting the theme to \c System chooses either the light or dark theme based + on the system theme colors. However, when reading the value of the theme + property, the value is never \c System, but the actual theme. + + In the following example, the theme for both the pane and the button is set + to \c Material.Dark: + + \table + \row + \li + \snippet qtquickcontrols-material-theme.qml 1 + \li + \image qtquickcontrols-material-theme.png + \endtable + + \endstyleproperty + + \styleproperty {Material.roundedScale} {enumeration} + \target material-roundedScale-attached-prop + This attached property holds the radius of rounded corners used on the + target control. The property can be attached to any window or item, but + only some controls support it. The value is not propagated to + children. + + The default value is control-specific. + + Available scales: + \value Material.NotRounded Square corners + \value Material.ExtraSmallScale Extra small rounded corners + \value Material.SmallScale Small rounded corners + \value Material.MediumScale Medium rounded corners + \value Material.LargeScale Large rounded corners + \value Material.ExtraLargeScale Extra large rounded corners + \value Material.FullScale Fully rounded corners + + This property was added in Qt 6.5. + + See also: \l {Material Style: Shape}. + + \endstyleproperty + + \styleproperty {Material.containerStyle} {enumeration} + \target material-containerStyle-attached-prop + This attached property holds the style of the container used by the + target control. The property can be attached to any window or item, but + only TextField and TextArea support it by default. The value is not + propagated to children. + + The default value is control-specific. + + Available styles: + \value Material.Filled Use the filled container variant if available + \value Material.Outlined Use the outlined container variant if available + + This property was added in Qt 6.5. + + See also: \l {Material Style: Text Field Containers}. + + \endstyleproperty + + \section1 Attached Method Documentation + + \stylemethod2 {color} {color} {enumeration} {predefined} {enumeration} {shade} + \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} + \endlist +*/ |