diff options
Diffstat (limited to 'src/quickcontrols/doc/src/qtquickcontrols-universal.qdoc')
| -rw-r--r-- | src/quickcontrols/doc/src/qtquickcontrols-universal.qdoc | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/src/quickcontrols/doc/src/qtquickcontrols-universal.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-universal.qdoc new file mode 100644 index 0000000000..eba367061f --- /dev/null +++ b/src/quickcontrols/doc/src/qtquickcontrols-universal.qdoc @@ -0,0 +1,258 @@ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtquickcontrols-universal.html + \title Universal Style + + The Universal Style is based on the Microsoft Universal Design Guidelines. + \l {detailed-desc-universal}{More...} + + \styleimport {QtQuick.Controls.Universal 2.12} {Qt 5.7} + + \section1 Attached Properties + + \list + \li \l {universal-accent-attached-prop}{\b accent} : color + \li \l {universal-background-attached-prop}{\b background} : color + \li \l {universal-foreground-attached-prop}{\b foreground} : color + \li \l {universal-theme-attached-prop}{\b theme} : enumeration + \endlist + + \section1 Attached Methods + + \list + \li color \l {color-attached-method}{\b color}(enumeration predefined) + \endlist + + \section1 Detailed Description + \target detailed-desc-universal + + The Universal style is a device-agnostic style based on the + \l {https://dev.windows.com/design}{Microsoft Universal Design Guidelines}. + The Universal style has been designed to look good on all devices, from + phones and tablets to PCs. + + \include style-screenshots.qdocinc {file} {Universal} {universal} + + To run an application with the Universal style, see + \l {Using Styles in Qt Quick Controls}. + + \note The Universal style is not a native Windows 10 style. The Universal + style is a 100% cross-platform Qt Quick Controls style implementation that + follows the Microsoft Universal 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 Universal style allows customizing four attributes, \l {universal-theme-attached-prop}{theme}, + \l {universal-accent-attached-prop}{accent}, \l {universal-foreground-attached-prop}{foreground}, and + \l {universal-background-attached-prop}{background}. + + \image qtquickcontrols-universal-attributes.png + + Both 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 violet accent color: + + \table + \row + \li + \qml + import QtQuick 2.12 + import QtQuick.Controls 2.12 + import QtQuick.Controls.Universal 2.12 + + ApplicationWindow { + visible: true + + Universal.theme: Universal.Dark + Universal.accent: Universal.Violet + + Column { + anchors.centerIn: parent + + RadioButton { text: qsTr("Small") } + RadioButton { text: qsTr("Medium"); checked: true } + RadioButton { text: qsTr("Large") } + } + } + \endqml + \li + \image qtquickcontrols-universal-violet.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 qquickuniversalstyle.qdocinc conf + + See \l {Qt Quick Controls Configuration File} for more details about the + configuration file. + + \section3 Environment Variables + + \include qquickuniversalstyle.qdocinc env + + See \l {Supported Environment Variables in Qt Quick Controls} for the full + list of supported environment variables. + + \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 Quick Controls}{file selectors}, + style-specific tweaks can be applied without creating a hard dependency to + a style. + + \section2 Pre-defined Universal Colors + + Available pre-defined colors: + \value Universal.Lime \stylecolor {#A4C400} {} + \value Universal.Green \stylecolor {#60A917} {} + \value Universal.Emerald \stylecolor {#008A00} {} + \value Universal.Teal \stylecolor {#00ABA9} {} + \value Universal.Cyan \stylecolor {#1BA1E2} {} + \value Universal.Cobalt \stylecolor {#3E65FF} {(default accent)} + \value Universal.Indigo \stylecolor {#6A00FF} {} + \value Universal.Violet \stylecolor {#AA00FF} {} + \value Universal.Pink \stylecolor {#F472D0} {} + \value Universal.Magenta \stylecolor {#D80073} {} + \value Universal.Crimson \stylecolor {#A20025} {} + \value Universal.Red \stylecolor {#E51400} {} + \value Universal.Orange \stylecolor {#FA6800} {} + \value Universal.Amber \stylecolor {#F0A30A} {} + \value Universal.Yellow \stylecolor {#E3C800} {} + \value Universal.Brown \stylecolor {#825A2C} {} + \value Universal.Olive \stylecolor {#6D8764} {} + \value Universal.Steel \stylecolor {#647687} {} + \value Universal.Mauve \stylecolor {#76608A} {} + \value Universal.Taupe \stylecolor {#87794E} {} + + \b {See also} \l {Basic Style}, \l {Material Style} + + \section1 Attached Property Documentation + + \styleproperty {Universal.accent} {color} + \target universal-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 Universal.Cobalt. + + In the following example, the accent color of the highlighted button is + changed to \c Universal.Orange: + + \table + \row + \li + \snippet qtquickcontrols-universal-accent.qml 1 + \li + \image qtquickcontrols-universal-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 Universal colors} that have been + designed to work well with the rest of the Universal style palette. + + \endstyleproperty + + \styleproperty {Universal.background} {color} + \target universal-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 pane is changed to + \c Universal.Steel: + + \table + \row + \li + \snippet qtquickcontrols-universal-background.qml 1 + \li + \image qtquickcontrols-universal-background.png + \endtable + + \endstyleproperty + + \styleproperty {Universal.foreground} {color} + \target universal-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 + Universal.Pink: + + \table + \row + \li + \snippet qtquickcontrols-universal-foreground.qml 1 + \li + \image qtquickcontrols-universal-foreground.png + \endtable + + \styleproperty {Universal.theme} {enumeration} + \target universal-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 Universal.Light Light theme (default) + \value Universal.Dark Dark theme + \value Universal.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 Universal.Dark: + + \table + \row + \li + \snippet qtquickcontrols-universal-theme.qml 1 + \li + \image qtquickcontrols-universal-theme.png + \endtable + + \endstyleproperty + + \section1 Attached Method Documentation + + \stylemethod {color} {color} {enumeration} {predefined} + \target color-attached-method + This attached method returns the effective color value of the specified + \l {pre-defined Universal colors}{pre-defined Universal color}. + + \qml + Rectangle { + color: Universal.color(Universal.Red) + } + \endqml + + \endstylemethod + + \section1 Related Information + + \list + \li \l{Styling Qt Quick Controls} + \endlist +*/ |