diff options
Diffstat (limited to 'src/quickcontrols/doc/src/qtquickcontrols-configuration.qdoc')
| -rw-r--r-- | src/quickcontrols/doc/src/qtquickcontrols-configuration.qdoc | 195 |
1 files changed, 195 insertions, 0 deletions
diff --git a/src/quickcontrols/doc/src/qtquickcontrols-configuration.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-configuration.qdoc new file mode 100644 index 0000000000..7cc61b5701 --- /dev/null +++ b/src/quickcontrols/doc/src/qtquickcontrols-configuration.qdoc @@ -0,0 +1,195 @@ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtquickcontrols-configuration.html + \keyword Qt Quick Controls Configuration File + \title Qt Quick Controls Configuration File + \keyword Qt Quick Controls 2 Configuration File + + Qt Quick Controls support a special configuration file, \c qtquickcontrols2.conf, + which is built into an application's resources. + + The configuration file can specify the preferred style and certain style-specific + attributes. The following example specifies that the preferred style is the \l {Material style}. + Furthermore, when the application is run with the Material style, its theme is light and the + accent and primary colors are teal and blue grey, respectively. However, if the application + is run with the \l {Universal style} instead, the accent color is red and the appropriate theme + is chosen based on the system theme colors. + + \code + [Controls] + Style=Material + + [Universal] + Theme=System + Accent=Red + + [Material] + Theme=Light + Accent=Teal + Primary=BlueGrey + \endcode + + It is possible to specify a custom location for the configuration file with + the \l {Supported Environment Variables in Qt Quick Controls} + {QT_QUICK_CONTROLS_CONF} environment variable. + + \section1 Controls Section + + The following values can be specified in a \c Controls section of the + configuration file: + + \table + \header + \li Variable + \li Description + \row + \li \c Style + \li Specifies the style to run the application with. + The value can be the name of one of the \l {Available Styles}{built-in styles} + or a \l {Creating a Custom Style}{custom style}. + \row + \li \c FallbackStyle + \li Specifies the style to use for controls that are not implemented. + The style must be one of the \l {Available Styles}{built-in styles}. + By default, the \l {Basic Style}{Basic} style is used. + \endtable + + \section1 Imagine Section + + The following table lists values that can be used to configure the + \l {Imagine style} in an \c Imagine section of the configuration file: + + \include qquickimaginestyle.qdocinc conf + + \section1 Material Section + + The following table lists values that can be used to configure the + \l {Material style} in a \c Material section of the configuration file: + + \include qquickmaterialstyle.qdocinc conf + + \section1 Universal Section + + The following table lists values that can be used to configure the + \l {Universal style} in a \c Universal section of the configuration file: + + \include qquickuniversalstyle.qdocinc conf + + \section1 Font Configuration + + The default \l {Control::font}{font} can be specified in a \c Font sub-group + in each style's section in the configuration file: + + \code + [Basic] + Font\Family=Open Sans + Font\PixelSize=20 + \endcode + + Supported font attributes: + \table + \header + \li Variable + \li Description + \row + \li \c Family + \li The \l {QFont::family}{font family}. + \row + \li \c PointSize + \li The \l {QFont::pointSizeF}{point size}. + \row + \li \c PixelSize + \li The \l {QFont::pixelSize}{pixel size}. + \row + \li \c StyleHint + \li The \l {QFont::styleHint}{style hint}. + Available values: \c SansSerif, \c Helvetica, \c Serif, \c Times, \c TypeWriter, \c Courier, + \c OldEnglish, \c Decorative, \c Monospace, \c Fantasy, \c Cursive. + \row + \li \c Weight + \li The \l {QFont::}{weight}. Qt uses a weighting scale from \c 1 to \c 1000 compatible with OpenType. A weight of \c 1 will be thin, + whilst \c 1000 will be extremely black. + Available pre-defined weights: \c Thin (100), \c ExtraLight (200), \c Light (300), \c Normal (400), + \c Medium (500), \c DemiBold (600), \c Bold (700), \c ExtraBold (800), + \c Black (900). + \row + \li \c Style + \li The \l {QFont::}{style}. + Available values: \c StyleNormal, \c StyleItalic, \c StyleOblique. + \endtable + + \section1 Palette Configuration + + The default \c palette can be configured for each style using the + \c Palette sub-group in the configuration file. The \c Palette sub-group can be + defined in two alternative ways: + + \code + [Fusion] + Palette\Window=#dedede + Palette\WindowText=#212121 + \endcode + + See \l [QtQuick]{Palette} QML type for more information. + + \section1 Using the Configuration File in a Project + + In order to make it possible for Qt Quick Controls to find the configuration file, + it must be built into application's resources using the \l {The Qt Resource System}. + Here's an example \c .qrc file: + + \code + <!DOCTYPE RCC><RCC version="1.0"> + <qresource prefix="/"> + <file>qtquickcontrols2.conf</file> + </qresource> + </RCC> + \endcode + + \note Qt Quick Controls uses a file selector to load the configuration file. It + is possible to provide a different configuration file for different platforms and + locales. See \l QFileSelector documentation for more details. + + Finally, the \c .qrc file must be listed in the application's build file. + For example: + + \if defined(onlinedocs) + \tab {build-qt-app}{tab-cmake}{CMakeLists.txt (CMake)}{checked} + \tab {build-qt-app}{tab-qmake}{.pro (qmake)}{} + \tabcontent {tab-cmake} + \else + \section2 Using CMake + \endif + \badcode + set(CMAKE_AUTORCC ON) + qt_add_executable(my_app + application.qrc + main.cpp + ... + ) + \endcode + \if defined(onlinedocs) + \endtabcontent + \tabcontent {tab-qmake} + \else + \section2 Using qmake + \endif + \badcode + RESOURCES = application.qrc + ... + \endcode + \if defined(onlinedocs) + \endtabcontent + \endif + + See also: \l {Build System Integration} + + \section1 Related Information + + \list + \li \l{Styling Qt Quick Controls} + \li \l{Supported Environment Variables in Qt Quick Controls} + \endlist +*/ |