1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page qtquickcontrols-configuration.html
6 \keyword Qt Quick Controls Configuration File
7 \title Qt Quick Controls Configuration File
8 \keyword Qt Quick Controls 2 Configuration File
10 Qt Quick Controls support a special configuration file, \c qtquickcontrols2.conf,
11 which is built into an application's resources.
13 The configuration file can specify the preferred style and certain style-specific
14 attributes. The following example specifies that the preferred style is the \l {Material style}.
15 Furthermore, when the application is run with the Material style, its theme is light and the
16 accent and primary colors are teal and blue grey, respectively. However, if the application
17 is run with the \l {Universal style} instead, the accent color is red and the appropriate theme
18 is chosen based on the system theme colors.
34 It is possible to specify a custom location for the configuration file with
35 the \l {Supported Environment Variables in Qt Quick Controls}
36 {QT_QUICK_CONTROLS_CONF} environment variable.
38 \section1 Controls Section
40 The following values can be specified in a \c Controls section of the
49 \li Specifies the style to run the application with.
50 The value can be the name of one of the \l {Available Styles}{built-in styles}
51 or a \l {Creating a Custom Style}{custom style}.
54 \li Specifies the style to use for controls that are not implemented.
55 The style must be one of the \l {Available Styles}{built-in styles}.
56 By default, the \l {Basic Style}{Basic} style is used.
59 \section1 Imagine Section
61 The following table lists values that can be used to configure the
62 \l {Imagine style} in an \c Imagine section of the configuration file:
64 \include qquickimaginestyle.qdocinc conf
66 \section1 Material Section
68 The following table lists values that can be used to configure the
69 \l {Material style} in a \c Material section of the configuration file:
71 \include qquickmaterialstyle.qdocinc conf
73 \section1 Universal Section
75 The following table lists values that can be used to configure the
76 \l {Universal style} in a \c Universal section of the configuration file:
78 \include qquickuniversalstyle.qdocinc conf
80 \section1 Font Configuration
82 The default \l {Control::font}{font} can be specified in a \c Font sub-group
83 in each style's section in the configuration file:
91 Supported font attributes:
98 \li The \l {QFont::family}{font family}.
101 \li The \l {QFont::pointSizeF}{point size}.
104 \li The \l {QFont::pixelSize}{pixel size}.
107 \li The \l {QFont::styleHint}{style hint}.
108 Available values: \c SansSerif, \c Helvetica, \c Serif, \c Times, \c TypeWriter, \c Courier,
109 \c OldEnglish, \c Decorative, \c Monospace, \c Fantasy, \c Cursive.
112 \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,
113 whilst \c 1000 will be extremely black.
114 Available pre-defined weights: \c Thin (100), \c ExtraLight (200), \c Light (300), \c Normal (400),
115 \c Medium (500), \c DemiBold (600), \c Bold (700), \c ExtraBold (800),
119 \li The \l {QFont::}{style}.
120 Available values: \c StyleNormal, \c StyleItalic, \c StyleOblique.
123 \section1 Palette Configuration
125 The default \c palette can be configured for each style using the
126 \c Palette sub-group in the configuration file. The \c Palette sub-group can be
127 defined in two alternative ways:
131 Palette\Window=#dedede
132 Palette\WindowText=#212121
135 See \l [QtQuick]{Palette} QML type for more information.
137 \section1 Using the Configuration File in a Project
139 In order to make it possible for Qt Quick Controls to find the configuration file,
140 it must be built into application's resources using the \l {The Qt Resource System}.
141 Here's an example \c .qrc file:
144 <!DOCTYPE RCC><RCC version="1.0">
145 <qresource prefix="/">
146 <file>qtquickcontrols2.conf</file>
151 \note Qt Quick Controls uses a file selector to load the configuration file. It
152 is possible to provide a different configuration file for different platforms and
153 locales. See \l QFileSelector documentation for more details.
155 Finally, the \c .qrc file must be listed in the application's build file.
158 \if defined(onlinedocs)
159 \tab {build-qt-app}{tab-cmake}{CMakeLists.txt (CMake)}{checked}
160 \tab {build-qt-app}{tab-qmake}{.pro (qmake)}{}
161 \tabcontent {tab-cmake}
163 \section2 Using CMake
166 set(CMAKE_AUTORCC ON)
167 qt_add_executable(my_app
173 \if defined(onlinedocs)
175 \tabcontent {tab-qmake}
177 \section2 Using qmake
180 RESOURCES = application.qrc
183 \if defined(onlinedocs)
187 See also: \l {Build System Integration}
189 \section1 Related Information
192 \li \l{Styling Qt Quick Controls}
193 \li \l{Supported Environment Variables in Qt Quick Controls}