Imagine Style

The Imagine Style is based on configurable image assets. More...

Import Statement: import QtQuick.Controls.Imagine 2.12
Since: Qt 5.10

Attached Properties

Detailed Description

The Imagine style is based on image assets. The style comes with a default set of images, but the images can be easily changed by providing a directory with images using a predefined naming convention.

The Imagine style with the default images

To run an application with the Imagine style, see Using Styles in Qt Quick Controls.

File Names

The image files are named using the following convention:

<control>-<element>-<states>

The <control> and <element> sections are mandatory, but the <states> section is optional. For example, if a single file named "button-background.9.png" is provided for Button, it will be used for every state that Button supports. It is up to the developer to decide the set of states that they will provide images for. However, it is recommended to provide images for the most common control states where possible, such as disabled, pressed, etc. This will ensure that interactive controls visually behave as the end user would expect them to.

Element Reference

The following table lists which elements are supported for each control, along with the possible states for that element, and the file extension that it expects. An element is an image that represents a certain visual part of the control. For example, Button's "background" element represents its background.

ControlElementStatesExtension
ApplicationWindowbackgroundactive.9.png (or .png)
BusyIndicatoranimationdisabled, running, mirrored, hovered.webp
backgroundsame as above.webp
Buttonbackgrounddisabled, pressed, checked, checkable, focused, highlighted, flat, mirrored, hovered.9.png
CheckBoxbackgrounddisabled, pressed, checked, partially-checked, focused, mirrored, hovered.9.png (or .png)
indicatorsame as above.png
CheckDelegatebackgrounddisabled, pressed, checked, partially-checked, focused, highlighted, mirrored, hovered.9.png (or .png)
indicatorsame as above.png
ComboBoxbackgrounddisabled, pressed, editable, open, focused, mirrored, hovered, flat.9.png (or .png)
indicatorsame as above.png
popupsame as above.9.png (or .png)
DelayButtonbackgrounddisabled, pressed, checked, checkable, focused, mirrored, hovered.9.png (or .png)
progresssame as above.9.png (or .png)
masksame as above.9.png (or .png)
Dialbackground1disabled, pressed, focused, mirrored, hovered.9.png (or .png)
handlesame as above.9.png (or .png)
Dialogbackgroundmodal, dim.9.png (or .png)
titlesame as above.9.png (or .png)
overlaymodal.9.png (or .png)
DialogButtonBoxbackgrounddisabled, mirrored.9.png (or .png)
Drawerbackgroundmodal, dim, top, left, right, bottom.9.png (or .png)
overlaymodal.9.png (or .png)
Framebackgrounddisabled, mirrored.9.png (or .png)
GroupBoxbackgrounddisabled, mirrored.9.png (or .png)
titlesame as above.9.png (or .png)
ItemDelegatebackgrounddisabled, pressed, focused, highlighted, mirrored, hovered.9.png (or .png)
Labelbackgrounddisabled, mirrored, hovered.9.png (or .png)
Menubackgroundmodal, dim.9.png (or .png)
overlaymodal.9.png (or .png)
MenuItemarrowdisabled, pressed, checked, focused, highlighted, mirrored, hovered.png
backgroundsame as above.9.png (or .png)
indicatorsame as above.png
MenuSeparatorbackgrounddisabled, mirrored.9.png (or .png)
separatorsame as above.9.png (or .png)
Pagebackgrounddisabled, mirrored.9.png (or .png)
PageIndicatorbackgrounddisabled, mirrored, hovered.9.png (or .png)
delegatedisabled, pressed, current, mirrored, hovered.png
Panebackgrounddisabled, mirrored.9.png (or .png)
Popupbackgroundmodal, dim.9.png (or .png)
overlaymodal.9.png (or .png)
ProgressBaranimationdisabled, mirrored, hovered.png
backgrounddisabled, indeterminate, mirrored, hovered.9.png (or .png)
masksame as above.9.png (or .png)
progresssame as above.9.png (or .png)
RadioButtonbackgrounddisabled, pressed, checked, focused, mirrored, hovered.9.png (or .png)
indicatorsame as above.png
RadioDelegatebackgrounddisabled, pressed, checked, focused, highlighted, mirrored, hovered.9.png (or .png)
indicatorsame as above.png
RangeSliderbackgroundvertical, horizontal, disabled, focused, mirrored, hovered.9.png (or .png)
RangeSliderprogresssame as above.9.png (or .png)
handlefirst, second, vertical, horizontal, disabled, pressed, focused, mirrored, hovered.png
RoundButtonbackgrounddisabled, pressed, checked, checkable, focused, highlighted, flat, mirrored, hovered.9.png (or .png)
ScrollBarbackgroundvertical, horizontal, disabled, interactive, pressed, mirrored, hovered.9.png (or .png)
handlesame as above.9.png (or .png)
ScrollIndicatorbackgroundvertical, horizontal, disabled, mirrored, hovered.9.png (or .png)
handlesame as above.9.png (or .png)
ScrollViewbackgrounddisabled, mirrored.9.png (or .png)
Sliderbackgroundvertical, horizontal, disabled, pressed, focused, mirrored, hovered.9.png (or .png)
handlesame as above.9.png (or .png)
progresssame as above.9.png (or .png)
SpinBoxbackgrounddisabled, editable, focused, mirrored, hovered.9.png (or .png)
editordisabled, focused, mirrored, hovered.9.png (or .png)
indicatorup, down, disabled, editable, pressed, focused, mirrored, hovered.9.png (or .png)
StackViewbackgrounddisabled, mirrored.9.png (or .png)
SwipeDelegatebackgrounddisabled, pressed, focused, highlighted, mirrored, hovered.9.png (or .png)
SwipeViewbackgroundvertical, horizontal, disabled, interactive, focused, mirrored.9.png (or .png)
Switchbackgrounddisabled, pressed, checked, focused, mirrored, hovered.9.png (or .png)
handlesame as above.9.png (or .png)
indicatorsame as above.9.png (or .png)
SwitchDelegatebackgrounddisabled, pressed, checked, focused, highlighted, mirrored, hovered.9.png (or .png)
handlesame as above.9.png (or .png)
indicatorsame as above.9.png (or .png)
TabBarbackgrounddisabled, header, footer, mirrored.9.png (or .png)
TabButtonbackgrounddisabled, pressed, checked, focused, mirrored, hovered.9.png (or .png)
TextAreabackgrounddisabled, focused, mirrored, hovered.9.png (or .png)
TextFieldbackgrounddisabled, focused, mirrored, hovered.9.png (or .png)
ToolBarbackgrounddisabled, header, footer, mirrored.9.png (or .png)
ToolButtonbackgrounddisabled, pressed, checked, checkable, focused, highlighted, flat, mirrored, hovered.9.png (or .png)
ToolSeparatorbackgroundvertical, horizontal, disabled, mirrored.9.png (or .png)
separatorsame as above.9.png (or .png)
ToolTipbackground.9.png (or .png)
Tumblerbackgrounddisabled, focused, mirrored, hovered.9.png (or .png)

Note: 1) The Imagine style Dial does not yet support the startAngle and endAngle properties that were introduced in Qt 6.6, and instead uses a fixed background image.

Asset Examples

The following table lists examples of assets (taken from the default Imagine style assets) for all controls. The list is not exhaustive, as not all elements need assets, but it can be used as a guide when creating your own assets.

The template that these assets were exported from is available as a Sketch project.

ControlElementStatesAssetNotes
ApplicationWindowbackground

See footnote 1
overlay

See footnote 1
overlaymodal

See footnote 1
Buttonbackground

backgrounddisabled

backgroundfocused

backgroundpressed

backgroundchecked

backgroundchecked, disabled

backgroundchecked, focused

backgroundchecked, hovered

backgroundhighlighted

backgroundhighlighted, disabled

backgroundhighlighted, focused

backgroundhighlighted, hovered

backgroundhighlighted, pressed

backgroundhighlighted, checked

backgroundhovered

backgroundflat

backgroundflat, disabled

backgroundflat, hovered

backgroundflat, pressed

backgroundflat, checked

CheckBoxindicator

indicatordisabled

indicatorpressed

indicatorchecked

indicatorchecked, pressed

indicatorchecked, hovered

indicatorchecked, focused

indicatorpartially, checked

indicatorpartially, checked, pressed

indicatorpartially, checked, focused

indicatorpartially, checked, hovered

indicatorfocused

indicatorhovered

CheckDelegatebackground

backgrounddisabled

backgroundpressed

backgroundfocused

backgroundhovered

indicator

indicatordisabled

indicatorpressed

indicatorchecked

indicatorchecked, pressed

indicatorchecked, focused

indicatorchecked, hovered

indicatorfocused

indicatorhovered

indicatorpartially, checked

indicatorpartially, checked, pressed

indicatorpartially, checked, focused

indicatorpartially, checked, hovered

indicatorhovered

ComboBoxbackground

backgrounddisabled

backgroundfocused

backgroundhovered

backgroundpressed

backgroundopen

backgroundeditable

backgroundeditable, focused

backgroundeditable, disabled

indicator

indicatordisabled

indicatoreditable

indicatoreditable, disabled

indicatoreditable, mirrored

indicatoreditable, mirrored, disabled

popup

DelayButtonbackground

backgrounddisabled

backgrounddisabled, checked

backgroundfocused

backgroundpressed

backgroundchecked

backgroundchecked, focused

backgroundchecked, hovered

backgroundhovered

progress

progressdisabled

mask

Dialbackground

backgrounddisabled

backgroundfocused

handle

handledisabled

handlefocused

handlefocused, pressed

handlefocused, hovered

handlepressed

handlehovered

Dialogbackground

overlay

See footnote 1
overlaymodal

See footnote 1
DialogButtonBoxbackground

Drawerbackgroundleft

backgroundright

backgroundtop

backgroundbottom

overlay

See footnote 1
overlaymodal

See footnote 1
Framebackground

GroupBoxbackground

title

ItemDelegatebackground

backgrounddisabled

backgroundpressed

backgroundfocused

backgroundhovered

backgroundhighlighted

Menubackground

MenuItembackground

backgroundhighlighted

arrow

arrowmirrored

arrowdisabled

arrowmirrored, disabled

indicator

indicatordisabled

indicatorpressed

indicatorchecked

indicatorchecked, pressed

indicatorchecked, focused

indicatorchecked, hovered

indicatorfocused

indicatorhovered

MenuSeparatorseparator

Pagebackground

See footnote 1
PageIndicatordelegate

delegatedisabled

delegatedisabled, current

delegatepressed

delegatecurrent

Panebackground

Popupbackground

See footnote 1
overlay

See footnote 1
overlaymodal

ProgressBarbackground

progress

mask

RadioButtonindicator

indicatordisabled

indicatorpressed

indicatorchecked

indicatorchecked, focused

indicatorchecked, hovered

indicatorchecked, pressed

indicatorfocused

indicatorhovered

RadioDelegatebackground

backgrounddisabled

backgroundpressed

backgroundfocused

backgroundhovered

indicator

indicatordisabled

indicatorpressed

indicatorchecked

indicatorchecked, focused

indicatorchecked, hovered

indicatorchecked, pressed

indicatorfocused

indicatorhovered

RangeSliderbackgroundvertical

backgroundhorizontal

progressvertical

progressvertical, disabled

progresshorizontal

progresshorizontal, disabled

handle

handledisabled

handlefocused

handlefocused, hovered

handlefocused, pressed

handlehovered

handlepressed

RoundButtonbackground

backgrounddisabled

backgrounddisabled, checked

backgroundfocused

backgroundpressed

backgroundchecked

backgroundchecked, focused

backgroundchecked, hovered

backgroundhighlighted

backgroundhighlighted, pressed

backgroundhighlighted, focused

backgroundhighlighted, hovered

backgroundhovered

ScrollBarhandle

handledisabled

handleinteractive

handleinteractive, disabled

handleinteractive, pressed

handleinteractive, hovered

ScrollIndicatorhandle

Sliderbackgroundvertical

backgroundhorizontal

progressvertical

progressvertical, disabled

progresshorizontal

progresshorizontal, disabled

handle

handledisabled

handlefocused

handlefocused, hovered

handlefocused, pressed

handlehovered

handlepressed

SpinBoxbackground

backgrounddisabled

backgroundfocused

backgroundeditable

indicatorup

indicatorup, disabled

indicatorup, pressed

indicatorup, focused

indicatorup, mirrored

indicatorup, hovered

indicatorup, editable

indicatorup, editable, pressed

indicatorup, editable, focused

indicatorup, editable, mirrored

indicatorup, editable, hovered

indicatordown

indicatordown, disabled

indicatordown, pressed

indicatordown, focused

indicatordown, mirrored

indicatordown, hovered

indicatordown, editable

indicatordown, editable, pressed

indicatordown, editable, focused

indicatordown, editable, mirrored

indicatordown, editable, hovered

SwipeDelegatebackground

backgrounddisabled

backgroundpressed

backgroundfocused

backgroundhovered

Switchindicator

indicatordisabled

indicatorpressed

indicatorchecked

indicatorchecked, focused

indicatorchecked, hovered

indicatorchecked, pressed

indicatorfocused

indicatorhovered

handle

handledisabled

handlepressed

SwitchDelegatebackground

backgrounddisabled

backgroundpressed

backgroundfocused

backgroundhovered

indicator

indicatordisabled

indicatorpressed

indicatorchecked

indicatorchecked, focused

indicatorchecked, hovered

indicatorchecked, pressed

indicatorfocused

indicatorhovered

handle

handledisabled

TabBarbackground

TabButtonbackground

backgrounddisabled

backgroundpressed

backgroundchecked

backgroundhovered

backgrounddisabled, checked

TextAreabackground

backgrounddisabled

backgroundfocused

TextFieldbackground

backgrounddisabled

backgroundfocused

ToolBarbackground

ToolButtonbackground

backgrounddisabled, checked

backgroundfocused

backgroundpressed

backgroundchecked

backgroundchecked, focused

backgroundchecked, hovered

backgroundhovered

ToolSeparatorseparatorhorizontal

separatorvertical

ToolTipbackground

1 A 1x1 image containing one color, stretched to fill the control.

9-Patch Images

The Imagine style uses 9-patch images in order to give designers control over how a particular element responds to being resized. Here is an example of a 9-patch image that represents a Button's background, alongside a magnified version (to make it easier to see the 9-patch lines):

The content of the image is 44 pixels wide by 32 pixels high. Every 9-patch image needs a one pixel thick line (collectively referred to as "9-patch lines") around every side, so the actual size of the image becomes 46 pixels wide by 34 pixels high. Note that the 9-patch lines must be one pixel thick regardless of the target DPI of the image. For example, the 9-patch lines for button-background.9.png and [email protected] must both be one pixel thick.

The 9-patch lines must be black, and the remaining areas must be transparent or white:

Stretchable Areas

The 9-patch lines on the top and left edges determine which parts of the image are stretched when it is resized.

Below are examples of the 9-patch image being resized to one and a half times its original size in various dimensions:

Notice how the the rounded corners keep their original size, as they are outside the range of the lines.

Padding Areas

The 9-patch lines on the right and bottom edges determine how much space is available for the control's contentItem, which means it can also be thought of as controlling the padding. For a diagram that illustrates padding, see Control Layout.

Below are more examples of the 9-patch image being resized, but this time demonstrating how the padding 9-patch lines work.

The contentItem can take up as much space as it needs within the shaded areas. If the padding lines are left out, the contentItem will take as much space as it needs without exceeding the stretchable areas.

Inset Areas

In some cases it is necessary for a control to have a drop shadow, for example. However, if we were to add a drop shadow to the button above, it would affect its size, which presents problems for both layouting and mouse/touch input boundaries.

Inset areas accounts for this by telling the control that a certain area of the 9-patch image should go outside of the control:

In the image below, the dashed line represents the button's clickable area, as well as the space that it will take up in a layout. The shadow is marked by the striped area behind it:

Exporting 9-Patch Images

Various vector and bitmap editors can be used to create 9-patch images suitable for use with the Imagine style. The following sections briefly explain the export process for each editor, and the last section explains how to ensure the exported images are 9-patch-conformant.

Affinity Designer

See Affinity's Export Settings documentation.

Adobe Illustrator

See Adobe's Asset Export panel documentation.

Adobe Photoshop

See Adobe's Generate image assets from layers documentation.

Inkscape

The Inkscape 9-Patch Export Extension can be used to export assets with Inkscape.

Sketch

See Sketch's Exporting documentation.

Qt Quick Controls also provides a plugin for Sketch that automatically fixes the thickness of the 9-patch lines after the assets are exported. To install this file, double-click on it. Once Sketch has confirmed that the 9-patch export plugin has been installed, the plugin will automatically process images when they are exported.

Fixing 9-Patch Lines

When exporting 9-patch images in several DPI variants (@2x, @3x, etc.), the 9-patch lines will typically be scaled up along with the image. There are several ways to fix this, but perhaps the simplest approach is to use ImageMagick's mogrify tool. The tool has a -shave feature that can be used to crop the image to reduce the thickness of the 9-patch lines:

mogrify -shave 1x1 -path path/to/images *@2x.9.png
mogrify -shave 2x2 -path path/to/images *@3x.9.png
mogrify -shave 3x3 -path path/to/images *@4x.9.png

Regular DPI images (those without the @Nx prefix) are not affected, so it is only necessary to run the command on images intended for high DPI displays.

Animated Images

The WebP and GIF animated image formats are supported by the Imagine style.

Customization

Path

The Imagine style allows customizing the path that is used to do the image asset selection. The path can be specified for any window or item, and it automatically propagates to children in the same manner as fonts. In the following example, the window and all three radio buttons appear with dark image assets (files that are located in "qrc:/themes/dark").

import QtQuick 2.12
import QtQuick.Controls 2.12
import QtQuick.Controls.Imagine 2.12

ApplicationWindow {
    visible: true

    Imagine.path: "qrc:/themes/dark"

    Column {
        anchors.centerIn: parent

        RadioButton { text: qsTr("Small") }
        RadioButton { text: qsTr("Medium"); checked: true }
        RadioButton { text: qsTr("Large") }
    }
}

In addition to specifying the path in QML, it is also possible to specify it via an environment variable or in a configuration file. Attributes specified in QML take precedence over all other methods.

Configuration File
VariableDescription
PathSpecifies 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.

See Qt Quick Controls Configuration File for more details about the configuration file.

Environment Variables
VariableDescription
QT_QUICK_CONTROLS_IMAGINE_PATHSpecifies 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:

QT_QUICK_CONTROLS_IMAGINE_PATH=:/imagine-assets

To specify a relative path to a local directory:

QT_QUICK_CONTROLS_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.

QT_QUICK_CONTROLS_IMAGINE_SMOOTHSet to 1 to enable smooth scaling for 9-patch images. This environment variable was added in Qt 6.5.

See Supported Environment Variables in Qt Quick Controls for the full list of supported environment variables.

Palette

The Imagine style supports palette customization via the palette property and the qtquickcontrols2.conf file. As with other styles, the exact palette roles that the Imagine style uses are style-dependent. However, as most of the visual appearance of controls (for example: backgrounds) are managed through image assets, only the roles that are typically used for text will have an effect.

Font

Custom fonts can be set via the font property and the configuration file.

Dependency

The Imagine style must be separately imported to gain access to the attributes that are specific to the Imagine style. It should be noted that regardless of the references to the Imagine style, the same application code runs with any other style. Imagine-specific attributes only have an effect when the application is run with the Imagine style.

If the Imagine style is imported in a QML file that is always loaded, the Imagine 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 file selectors, style-specific tweaks can be applied without creating a hard dependency to a style.

See also Styling Qt Quick Controls

Attached Property Documentation

Imagine.path : string

This attached property holds the path to the image assets...

Button {
    Imagine.path: "qrc:/themes/dark"
}

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.