diff options
Diffstat (limited to 'src/quickcontrols/doc/src/qtquickcontrols-material.qdoc')
| -rw-r--r-- | src/quickcontrols/doc/src/qtquickcontrols-material.qdoc | 124 |
1 files changed, 85 insertions, 39 deletions
diff --git a/src/quickcontrols/doc/src/qtquickcontrols-material.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-material.qdoc index 450cbb151c..4052337ef8 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-material.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-material.qdoc @@ -32,17 +32,11 @@ \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} + 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. - \table - \row - \li \image qtquickcontrols-material-light.png - \caption The Material style in light theme - \li \image qtquickcontrols-material-dark.png - \caption The Material style in dark theme - \endtable + \include style-screenshots.qdocinc {file} {Material} {material} To run an application with the Material style, see \l {Using Styles in Qt Quick Controls}. @@ -54,26 +48,43 @@ 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 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}. + 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 - 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: + 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 2.12 - import QtQuick.Controls 2.12 - import QtQuick.Controls.Material 2.12 + import QtQuick + import QtQuick.Controls + import QtQuick.Controls.Material ApplicationWindow { visible: true @@ -84,9 +95,16 @@ Column { anchors.centerIn: parent - RadioButton { text: qsTr("Small") } - RadioButton { text: qsTr("Medium"); checked: true } - RadioButton { text: qsTr("Large") } + RadioButton { + text: qsTr("Small") + } + RadioButton { + text: qsTr("Medium") + checked: true + } + RadioButton { + text: qsTr("Large") + } } } \endqml @@ -95,8 +113,8 @@ \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. + 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 @@ -227,9 +245,34 @@ 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} {material-accent-attached-prop} + \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. @@ -253,7 +296,7 @@ \endstyleproperty - \styleproperty {Material.background} {color} {material-background-attached-prop} + \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. @@ -273,17 +316,18 @@ \endstyleproperty - \styleproperty {Material.elevation} {int} {material-elevation-attached-prop} + \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. + 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://material.google.com/components/cards.html}{elevated card}: + \l {https://m3.material.io/components/cards/overview}{elevated card}: \table \row @@ -295,7 +339,7 @@ \endstyleproperty - \styleproperty {Material.foreground} {color} {material-foreground-attached-prop} + \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. @@ -315,7 +359,7 @@ \endstyleproperty - \styleproperty {Material.primary} {color} {material-primary-attached-prop} + \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. @@ -330,7 +374,7 @@ \endstyleproperty - \styleproperty {Material.theme} {enumeration} {material-theme-attached-prop} + \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. @@ -357,11 +401,12 @@ \endstyleproperty - \styleproperty {Material.roundedScale} {enumeration} {material-roundedScale-attached-prop} + \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. + only some controls support it. The value is not propagated to + children. The default value is control-specific. @@ -380,17 +425,18 @@ \endstyleproperty - \styleproperty {Material.containerStyle} {enumeration} {material-containerStyle-attached-prop} + \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. + only TextField and TextArea support it by default. The value is not + propagated to children. The default value is control-specific. - Available scales: - \value Material.Filled Square corners - \value Material.Outlined Extra small rounded corners + 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. @@ -400,7 +446,7 @@ \section1 Attached Method Documentation - \stylemethod2 {color} {color} {enumeration} {predefined} {enumeration} {shade} {material-color-attached-method} + \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 |