Qt Quick Controls Configuration File | Qt Quick Controls 6.4.1

- Qt 6.4
- Qt Quick Controls
- Qt Quick Controls Configuration File
- Qt 6.4.1 Reference Documentation

# Qt Quick Controls Configuration File

Qt Quick Controls support a special configuration file, `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 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 Universal style instead, the accent color is red and the appropriate theme is chosen based on the system theme colors.

     [Controls]
     Style=Material

     [Universal]
     Theme=System
     Accent=Red

     [Material]
     Theme=Light
     Accent=Teal
     Primary=BlueGrey

It is possible to specify a custom location for the configuration file with the QT_QUICK_CONTROLS_CONF environment variable.

## Controls Section

The following values can be specified in a `Controls` section of the configuration file:

Variable | Description
--- | ---
`Style` | Specifies the style to run the application with. The value can be the name of one of the built-in styles or a custom style.
`FallbackStyle` | Specifies the style to use for controls that are not implemented. The style must be one of the built-in styles. By default, the Basic style is used.

## Imagine Section

The following table lists values that can be used to configure the Imagine style in an `Imagine` section of the configuration file:

Variable | Description
--- | ---
`Path` | Specifies the path to the directory that contains the Imagine style assets. If not specified, the built-in assets are used. For example, to specify a path to a directory stored in the resource system:
     [Imagine]
     Path=:/imagine-assets
To specify a relative path to a local directory:
     [Imagine]
     Path=imagine-assets
Note: Due to a technical limitation, the path should not be named "imagine" if it is relative to the `qtquickcontrols2.conf` file.

## Material Section

The following table lists values that can be used to configure the Material style in a `Material` section of the configuration file:

Variable | Description
--- | ---
`Theme` | Specifies the default Material theme. The value can be one of the available themes, for example `"Dark"`.
`Variant` | Specifies the Material variant. The Material Design has two variants: a normal variant designed for touch devices, and a dense variant for desktop. The dense variant uses smaller sizes for controls and their fonts. The value can be `"Normal"` or `"Dense"`.
`Accent` | Specifies the default Material accent color. The value can be any color, but it is recommended to use one of the pre-defined Material colors, for example `"Teal"`.
`Primary` | Specifies the default Material primary color. The value can be any color, but it is recommended to use one of the pre-defined Material colors, for example `"BlueGrey"`.
`Foreground` | Specifies the default Material foreground color. The value can be any color, or one of the pre-defined Material colors, for example `"Brown"`.
`Background` | Specifies the default Material background color. The value can be any color, or one of the pre-defined Material colors, for example `"Grey"`.

## Universal Section

The following table lists values that can be used to configure the Universal style in a `Universal` section of the configuration file:

Variable | Description
--- | ---
`Theme` | Specifies the default Universal theme. The value can be one of the available themes, for example `"Dark"`.
`Accent` | Specifies the default Universal accent color. The value can be any color, but it is recommended to use one of the pre-defined Universal colors, for example `"Violet"`.
`Foreground` | Specifies the default Universal foreground color. The value can be any color, or one of the pre-defined Universal colors, for example `"Brown"`.
`Background` | Specifies the default Universal background color. The value can be any color, or one of the pre-defined Universal colors, for example `"Steel"`.

## Font Configuration

The default font can be specified in a `Font` sub-group in each style's section in the configuration file. The `Font` sub-group can be defined in two alternative ways:

     [Basic]
     Font\Family=Open Sans
     Font\PixelSize=20

     [Material\Font]
     Family=Open Sans
     PixelSize=20

Supported font attributes:

Variable | Description
--- | ---
`Family` | The font family.
`PointSize` | The point size.
`PixelSize` | The pixel size.
`StyleHint` | The style hint. Available values: `SansSerif`, `Helvetica`, `Serif`, `Times`, `TypeWriter`, `Courier`, `OldEnglish`, `Decorative`, `Monospace`, `Fantasy`, `Cursive`.
`Weight` | The weight. Qt uses a weighting scale from `1` to `1000` compatible with OpenType. A weight of `1` will be thin, whilst `1000` will be extremely black. Available pre-defined weights: `Thin` (100), `ExtraLight` (200), `Light` (300), `Normal` (400), `Medium` (500), `DemiBold` (600), `Bold` (700), `ExtraBold` (800), `Black` (900).
`Style` | The style. Available values: `StyleNormal`, `StyleItalic`, `StyleOblique`.

## Palette Configuration

The default `palette` can be configured for each style using the `Palette` sub-group in the configuration file. The `Palette` sub-group can be defined in two alternative ways:

     [Fusion]
     Palette\Window=#dedede
     Palette\WindowText=#212121

or:

     [Fusion\Palette]
     Window=#dedede
     WindowText=#212121

See Palette QML type for more information.

## 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 The Qt Resource System. Here's an example `.qrc` file:

     <!DOCTYPE RCC><RCC version="1.0">
     <qresource prefix="/">
         <file>qtquickcontrols2.conf</file>
     </qresource>
     </RCC>

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 QFileSelector documentation for more details.

Finally, the `.qrc` file must be listed in the application's `.pro` file so that the build system knows about it. For example:

     RESOURCES = application.qrc

## Related Information

- Styling Qt Quick Controls
- Supported Environment Variables in Qt Quick Controls