Imagine Style#

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

Attached Properties#

  • path :ref:` <Imagine-Style>` : string

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.

../_images/qtquickcontrols-imagine.png

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 .

Control

Element

States

Extension

ApplicationWindow

background

active

.9.png (or .png)

BusyIndicator

animation

disabled, running, mirrored, hovered

.webp

background

same as above

.webp

Button

background

disabled, pressed, checked, checkable, focused, highlighted, flat, mirrored, hovered

.9.png

CheckBox

background

disabled, pressed, checked, partially-checked, focused, mirrored, hovered

.9.png (or .png)

indicator

same as above

.png

CheckDelegate

background

disabled, pressed, checked, partially-checked, focused, highlighted, mirrored, hovered

.9.png (or .png)

indicator

same as above

.png

ComboBox

background

disabled, pressed, editable, open, focused, mirrored, hovered, flat

.9.png (or .png)

indicator

same as above

.png

popup

same as above

.9.png (or .png)

DelayButton

background

disabled, pressed, checked, checkable, focused, mirrored, hovered

.9.png (or .png)

progress

same as above

.9.png (or .png)

mask

same as above

.9.png (or .png)

Dial

background 1

disabled, pressed, focused, mirrored, hovered

.9.png (or .png)

handle

same as above

.9.png (or .png)

Dialog

background

modal, dim

.9.png (or .png)

title

same as above

.9.png (or .png)

overlay

modal

.9.png (or .png)

DialogButtonBox

background

disabled, mirrored

.9.png (or .png)

Drawer

background

modal, dim, top, left, right, bottom

.9.png (or .png)

overlay

modal

.9.png (or .png)

Frame

background

disabled, mirrored

.9.png (or .png)

GroupBox

background

disabled, mirrored

.9.png (or .png)

title

same as above

.9.png (or .png)

ItemDelegate

background

disabled, pressed, focused, highlighted, mirrored, hovered

.9.png (or .png)

Label

background

disabled, mirrored, hovered

.9.png (or .png)

Menu

background

modal, dim

.9.png (or .png)

overlay

modal

.9.png (or .png)

MenuItem

arrow

disabled, pressed, checked, focused, highlighted, mirrored, hovered

.png

background

same as above

.9.png (or .png)

indicator

same as above

.png

MenuSeparator

background

disabled, mirrored

.9.png (or .png)

separator

same as above

.9.png (or .png)

Page

background

disabled, mirrored

.9.png (or .png)

PageIndicator

background

disabled, mirrored, hovered

.9.png (or .png)

delegate

disabled, pressed, current, mirrored, hovered

.png

Pane

background

disabled, mirrored

.9.png (or .png)

Popup

background

modal, dim

.9.png (or .png)

overlay

modal

.9.png (or .png)

ProgressBar

animation

disabled, mirrored, hovered

.png

background

disabled, indeterminate, mirrored, hovered

.9.png (or .png)

mask

same as above

.9.png (or .png)

progress

same as above

.9.png (or .png)

RadioButton

background

disabled, pressed, checked, focused, mirrored, hovered

.9.png (or .png)

indicator

same as above

.png

RadioDelegate

background

disabled, pressed, checked, focused, highlighted, mirrored, hovered

.9.png (or .png)

indicator

same as above

.png

RangeSlider

background

vertical, horizontal, disabled, focused, mirrored, hovered

.9.png (or .png)

RangeSlider

progress

same as above

.9.png (or .png)

handle

first, second, vertical, horizontal, disabled, pressed, focused, mirrored, hovered

.png

RoundButton

background

disabled, pressed, checked, checkable, focused, highlighted, flat, mirrored, hovered

.9.png (or .png)

ScrollBar

background

vertical, horizontal, disabled, interactive, pressed, mirrored, hovered

.9.png (or .png)

handle

same as above

.9.png (or .png)

ScrollIndicator

background

vertical, horizontal, disabled, mirrored, hovered

.9.png (or .png)

handle

same as above

.9.png (or .png)

ScrollView

background

disabled, mirrored

.9.png (or .png)

Slider

background

vertical, horizontal, disabled, pressed, focused, mirrored, hovered

.9.png (or .png)

handle

same as above

.9.png (or .png)

progress

same as above

.9.png (or .png)

SpinBox

background

disabled, editable, focused, mirrored, hovered

.9.png (or .png)

editor

disabled, focused, mirrored, hovered

.9.png (or .png)

indicator

up, down, disabled, editable, pressed, focused, mirrored, hovered

.9.png (or .png)

StackView

background

disabled, mirrored

.9.png (or .png)

SwipeDelegate

background

disabled, pressed, focused, highlighted, mirrored, hovered

.9.png (or .png)

SwipeView

background

vertical, horizontal, disabled, interactive, focused, mirrored

.9.png (or .png)

Switch

background

disabled, pressed, checked, focused, mirrored, hovered

.9.png (or .png)

handle

same as above

.9.png (or .png)

indicator

same as above

.9.png (or .png)

SwitchDelegate

background

disabled, pressed, checked, focused, highlighted, mirrored, hovered

.9.png (or .png)

handle

same as above

.9.png (or .png)

indicator

same as above

.9.png (or .png)

TabBar

background

disabled, header, footer, mirrored

.9.png (or .png)

TabButton

background

disabled, pressed, checked, focused, mirrored, hovered

.9.png (or .png)

TextArea

background

disabled, focused, mirrored, hovered

.9.png (or .png)

TextField

background

disabled, focused, mirrored, hovered

.9.png (or .png)

ToolBar

background

disabled, header, footer, mirrored

.9.png (or .png)

ToolButton

background

disabled, pressed, checked, checkable, focused, highlighted, flat, mirrored, hovered

.9.png (or .png)

ToolSeparator

background

vertical, horizontal, disabled, mirrored

.9.png (or .png)

separator

same as above

.9.png (or .png)

ToolTip

background

.9.png (or .png)

Tumbler

background

disabled, 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 .

Control

Element

States

Asset

Notes

ApplicationWindow

background

../_images/applicationwindow-background.png

See footnote 1

overlay

../_images/applicationwindow-overlay.png

See footnote 1

overlay

modal

../_images/applicationwindow-overlay-modal.png

See footnote 1

Button

background

../_images/button-background.9.png

background

disabled

../_images/button-background-disabled.9.png

background

focused

../_images/button-background-focused.9.png

background

pressed

../_images/button-background-pressed.9.png

background

checked

../_images/button-background-checked.9.png

background

checked, disabled

../_images/button-background-checked-disabled.9.png

background

checked, focused

../_images/button-background-checked-focused.9.png

background

checked, hovered

../_images/button-background-checked-hovered.9.png

background

highlighted

../_images/button-background-highlighted.9.png

background

highlighted, disabled

../_images/button-background-highlighted-disabled.9.png

background

highlighted, focused

../_images/button-background-highlighted-focused.9.png

background

highlighted, hovered

../_images/button-background-highlighted-hovered.9.png

background

highlighted, pressed

../_images/button-background-highlighted-pressed.9.png

background

highlighted, checked

../_images/button-background-highlighted-checked.9.png

background

hovered

../_images/button-background-hovered.9.png

background

flat

../_images/button-background-flat.9.png

background

flat, disabled

../_images/button-background-flat-disabled.9.png

background

flat, hovered

../_images/button-background-flat-hovered.9.png

background

flat, pressed

../_images/button-background-flat-pressed.9.png

background

flat, checked

../_images/button-background-flat-checked.9.png

CheckBox

indicator

../_images/checkbox-indicator.png

indicator

disabled

../_images/checkbox-indicator-disabled.png

indicator

pressed

../_images/checkbox-indicator-pressed.png

indicator

checked

../_images/checkbox-indicator-checked.png

indicator

checked, pressed

../_images/checkbox-indicator-checked-pressed.png

indicator

checked, hovered

../_images/checkbox-indicator-checked-hovered.png

indicator

checked, focused

../_images/checkbox-indicator-checked-focused.png

indicator

partially, checked

../_images/checkbox-indicator-partially-checked.png

indicator

partially, checked, pressed

../_images/checkbox-indicator-partially-checked-pressed.png

indicator

partially, checked, focused

../_images/checkbox-indicator-partially-checked-focused.png

indicator

partially, checked, hovered

../_images/checkbox-indicator-partially-checked-hovered.png

indicator

focused

../_images/checkbox-indicator-focused.png

indicator

hovered

../_images/checkbox-indicator-hovered.png

CheckDelegate

background

../_images/checkdelegate-background.9.png

background

disabled

../_images/checkdelegate-background-disabled.9.png

background

pressed

../_images/checkdelegate-background-pressed.9.png

background

focused

../_images/checkdelegate-background-focused.9.png

background

hovered

../_images/checkdelegate-background-hovered.9.png

indicator

../_images/checkdelegate-indicator.png

indicator

disabled

../_images/checkdelegate-indicator-disabled.png

indicator

pressed

../_images/checkdelegate-indicator-pressed.png

indicator

checked

../_images/checkdelegate-indicator-checked.png

indicator

checked, pressed

../_images/checkdelegate-indicator-checked-pressed.png

indicator

checked, focused

../_images/checkdelegate-indicator-checked-focused.png

indicator

checked, hovered

../_images/checkdelegate-indicator-checked-hovered.png

indicator

focused

../_images/checkdelegate-indicator-focused.png

indicator

hovered

../_images/checkdelegate-indicator-hovered.png

indicator

partially, checked

../_images/checkdelegate-indicator-partially-checked.png

indicator

partially, checked, pressed

../_images/checkdelegate-indicator-partially-checked-pressed.png

indicator

partially, checked, focused

../_images/checkdelegate-indicator-partially-checked-focused.png

indicator

partially, checked, hovered

../_images/checkdelegate-indicator-partially-checked-hovered.png

indicator

hovered

../_images/checkdelegate-indicator-hovered.png

ComboBox

background

../_images/combobox-background.9.png

background

disabled

../_images/combobox-background-disabled.9.png

background

focused

../_images/combobox-background-focused.9.png

background

hovered

../_images/combobox-background-hovered.9.png

background

pressed

../_images/combobox-background-pressed.9.png

background

open

../_images/combobox-background-open.9.png

background

editable

../_images/combobox-background-editable.9.png

background

editable, focused

../_images/combobox-background-editable-focused.9.png

background

editable, disabled

../_images/combobox-background-editable-disabled.9.png

indicator

../_images/combobox-indicator.png

indicator

disabled

../_images/combobox-indicator-disabled.png

indicator

editable

../_images/combobox-indicator-editable.png

indicator

editable, disabled

../_images/combobox-indicator-editable-disabled.png

indicator

editable, mirrored

../_images/combobox-indicator-editable-mirrored.png

indicator

editable, mirrored, disabled

../_images/combobox-indicator-editable-mirrored-disabled.png

popup

../_images/combobox-popup.9.png

DelayButton

background

../_images/delaybutton-background.9.png

background

disabled

../_images/delaybutton-background-disabled.9.png

background

disabled, checked

../_images/delaybutton-background-disabled-checked.9.png

background

focused

../_images/delaybutton-background-focused.9.png

background

pressed

../_images/delaybutton-background-pressed.9.png

background

checked

../_images/delaybutton-background-checked.9.png

background

checked, focused

../_images/delaybutton-background-checked-focused.9.png

background

checked, hovered

../_images/delaybutton-background-checked-hovered.9.png

background

hovered

../_images/delaybutton-background-hovered.9.png

progress

../_images/delaybutton-progress.9.png

progress

disabled

../_images/delaybutton-progress-disabled.9.png

mask

../_images/delaybutton-mask.9.png

Dial

background

../_images/dial-background.png

background

disabled

../_images/dial-background-disabled.png

background

focused

../_images/dial-background-focused.png

handle

../_images/dial-handle.png

handle

disabled

../_images/dial-handle-disabled.png

handle

focused

../_images/dial-handle-focused.png

handle

focused, pressed

../_images/dial-handle-focused-pressed.png

handle

focused, hovered

../_images/dial-handle-focused-hovered.png

handle

pressed

../_images/dial-handle-pressed.png

handle

hovered

../_images/dial-handle-hovered.png

Dialog

background

../_images/dialog-background.9.png

overlay

../_images/dialog-overlay.png

See footnote 1

overlay

modal

../_images/dialog-overlay-modal.png

See footnote 1

DialogButtonBox

background

../_images/dialogbuttonbox-background.9.png

Drawer

background

left

../_images/drawer-background-left.9.png

background

right

../_images/drawer-background-right.9.png

background

top

../_images/drawer-background-top.9.png

background

bottom

../_images/drawer-background-bottom.9.png

overlay

../_images/drawer-overlay.png

See footnote 1

overlay

modal

../_images/drawer-overlay-modal.png

See footnote 1

Frame

background

../_images/frame-background.9.png

GroupBox

background

../_images/groupbox-background.9.png

title

../_images/groupbox-title.9.png

ItemDelegate

background

../_images/itemdelegate-background.9.png

background

disabled

../_images/itemdelegate-background-disabled.9.png

background

pressed

../_images/itemdelegate-background-pressed.9.png

background

focused

../_images/itemdelegate-background-focused.9.png

background

hovered

../_images/itemdelegate-background-hovered.9.png

background

highlighted

../_images/itemdelegate-background-highlighted.9.png

Menu

background

../_images/menu-background.9.png

MenuItem

background

../_images/menuitem-background.9.png

background

highlighted

../_images/menuitem-background-highlighted.9.png

arrow

../_images/menuitem-arrow.png

arrow

mirrored

../_images/menuitem-arrow-mirrored.png

arrow

disabled

../_images/menuitem-arrow-disabled.png

arrow

mirrored, disabled

../_images/menuitem-arrow-mirrored-disabled.png

indicator

../_images/menuitem-indicator.png

indicator

disabled

../_images/menuitem-indicator-disabled.png

indicator

pressed

../_images/menuitem-indicator-pressed.png

indicator

checked

../_images/menuitem-indicator-checked.png

indicator

checked, pressed

../_images/menuitem-indicator-checked-pressed.png

indicator

checked, focused

../_images/menuitem-indicator-checked-focused.png

indicator

checked, hovered

../_images/menuitem-indicator-checked-hovered.png

indicator

focused

../_images/menuitem-indicator-focused.png

indicator

hovered

../_images/menuitem-indicator-hovered.png

MenuSeparator

separator

../_images/menuseparator-separator.9.png

Page

background

../_images/page-background.png

See footnote 1

PageIndicator

delegate

../_images/pageindicator-delegate.png

delegate

disabled

../_images/pageindicator-delegate-disabled.png

delegate

disabled, current

../_images/pageindicator-delegate-disabled-current.png

delegate

pressed

../_images/pageindicator-delegate-pressed.png

delegate

current

../_images/pageindicator-delegate-current.png

Pane

background

../_images/pane-background.9.png

Popup

background

../_images/popup-background.9.png

See footnote 1

overlay

../_images/popup-overlay.png

See footnote 1

overlay

modal

../_images/popup-overlay-modal.png

ProgressBar

background

../_images/progressbar-background.9.png

progress

../_images/progressbar-progress.png

mask

../_images/progressbar-mask.9.png

RadioButton

indicator

../_images/radiobutton-indicator.png

indicator

disabled

../_images/radiobutton-indicator-disabled.png

indicator

pressed

../_images/radiobutton-indicator-pressed.png

indicator

checked

../_images/radiobutton-indicator-checked.png

indicator

checked, focused

../_images/radiobutton-indicator-checked-focused.png

indicator

checked, hovered

../_images/radiobutton-indicator-checked-hovered.png

indicator

checked, pressed

../_images/radiobutton-indicator-checked-pressed.png

indicator

focused

../_images/radiobutton-indicator-focused.png

indicator

hovered

../_images/radiobutton-indicator-hovered.png

RadioDelegate

background

../_images/radiodelegate-background.9.png

background

disabled

../_images/radiodelegate-background-disabled.9.png

background

pressed

../_images/radiodelegate-background-pressed.9.png

background

focused

../_images/radiodelegate-background-focused.9.png

background

hovered

../_images/radiodelegate-background-hovered.9.png

indicator

../_images/radiodelegate-indicator.png

indicator

disabled

../_images/radiodelegate-indicator-disabled.png

indicator

pressed

../_images/radiodelegate-indicator-pressed.png

indicator

checked

../_images/radiodelegate-indicator-checked.png

indicator

checked, focused

../_images/radiodelegate-indicator-checked-focused.png

indicator

checked, hovered

../_images/radiodelegate-indicator-checked-hovered.png

indicator

checked, pressed

../_images/radiodelegate-indicator-checked-pressed.png

indicator

focused

../_images/radiodelegate-indicator-focused.png

indicator

hovered

../_images/radiodelegate-indicator-hovered.png

RangeSlider

background

vertical

../_images/rangeslider-background-vertical.9.png

background

horizontal

../_images/rangeslider-background-horizontal.9.png

progress

vertical

../_images/rangeslider-progress-vertical.9.png

progress

vertical, disabled

../_images/rangeslider-progress-vertical-disabled.9.png

progress

horizontal

../_images/rangeslider-progress-horizontal.9.png

progress

horizontal, disabled

../_images/rangeslider-progress-horizontal-disabled.9.png

handle

../_images/rangeslider-handle.png

handle

disabled

../_images/rangeslider-handle-disabled.png

handle

focused

../_images/rangeslider-handle-focused.png

handle

focused, hovered

../_images/rangeslider-handle-focused-hovered.png

handle

focused, pressed

../_images/rangeslider-handle-focused-pressed.png

handle

hovered

../_images/rangeslider-handle-hovered.png

handle

pressed

../_images/rangeslider-handle-pressed.png

RoundButton

background

../_images/roundbutton-background.png

background

disabled

../_images/roundbutton-background-disabled.png

background

disabled, checked

../_images/roundbutton-background-disabled-checked.png

background

focused

../_images/roundbutton-background-focused.png

background

pressed

../_images/roundbutton-background-pressed.png

background

checked

../_images/roundbutton-background-checked.png

background

checked, focused

../_images/roundbutton-background-checked-focused.png

background

checked, hovered

../_images/roundbutton-background-checked-hovered.png

background

highlighted

../_images/roundbutton-background-highlighted.png

background

highlighted, pressed

../_images/roundbutton-background-highlighted-pressed.png

background

highlighted, focused

../_images/roundbutton-background-highlighted-focused.png

background

highlighted, hovered

../_images/roundbutton-background-highlighted-hovered.png

background

hovered

../_images/roundbutton-background-hovered.png

ScrollBar

handle

../_images/scrollbar-handle.png

handle

disabled

../_images/scrollbar-handle-disabled.png

handle

interactive

../_images/scrollbar-handle-interactive.png

handle

interactive, disabled

../_images/scrollbar-handle-interactive-disabled.png

handle

interactive, pressed

../_images/scrollbar-handle-interactive-pressed.png

handle

interactive, hovered

../_images/scrollbar-handle-interactive-hovered.png

ScrollIndicator

handle

../_images/scrollindicator-handle.png

Slider

background

vertical

../_images/slider-background-vertical.9.png

background

horizontal

../_images/slider-background-horizontal.9.png

progress

vertical

../_images/slider-progress-vertical.9.png

progress

vertical, disabled

../_images/slider-progress-vertical-disabled.9.png

progress

horizontal

../_images/slider-progress-horizontal.9.png

progress

horizontal, disabled

../_images/slider-progress-horizontal-disabled.9.png

handle

../_images/slider-handle.png

handle

disabled

../_images/slider-handle-disabled.png

handle

focused

../_images/slider-handle-focused.png

handle

focused, hovered

../_images/slider-handle-focused-hovered.png

handle

focused, pressed

../_images/slider-handle-focused-pressed.png

handle

hovered

../_images/slider-handle-hovered.png

handle

pressed

../_images/slider-handle-pressed.png

SpinBox

background

../_images/spinbox-background.9.png

background

disabled

../_images/spinbox-background-disabled.9.png

background

focused

../_images/spinbox-background-focused.9.png

background

editable

../_images/spinbox-background-editable.9.png

indicator

up

../_images/spinbox-indicator-up.9.png

indicator

up, disabled

../_images/spinbox-indicator-up-disabled.9.png

indicator

up, pressed

../_images/spinbox-indicator-up-pressed.9.png

indicator

up, focused

../_images/spinbox-indicator-up-focused.9.png

indicator

up, mirrored

../_images/spinbox-indicator-up-mirrored.9.png

indicator

up, hovered

../_images/spinbox-indicator-up-hovered.9.png

indicator

up, editable

../_images/spinbox-indicator-up-editable.9.png

indicator

up, editable, pressed

../_images/spinbox-indicator-up-editable-pressed.9.png

indicator

up, editable, focused

../_images/spinbox-indicator-up-editable-focused.9.png

indicator

up, editable, mirrored

../_images/spinbox-indicator-up-editable-mirrored.9.png

indicator

up, editable, hovered

../_images/spinbox-indicator-up-editable-hovered.9.png

indicator

down

../_images/spinbox-indicator-down.9.png

indicator

down, disabled

../_images/spinbox-indicator-down-disabled.9.png

indicator

down, pressed

../_images/spinbox-indicator-down-pressed.9.png

indicator

down, focused

../_images/spinbox-indicator-down-focused.9.png

indicator

down, mirrored

../_images/spinbox-indicator-down-mirrored.9.png

indicator

down, hovered

../_images/spinbox-indicator-down-hovered.9.png

indicator

down, editable

../_images/spinbox-indicator-down-editable.9.png

indicator

down, editable, pressed

../_images/spinbox-indicator-down-editable-pressed.9.png

indicator

down, editable, focused

../_images/spinbox-indicator-down-editable-focused.9.png

indicator

down, editable, mirrored

../_images/spinbox-indicator-down-editable-mirrored.9.png

indicator

down, editable, hovered

../_images/spinbox-indicator-down-editable-hovered.9.png

SwipeDelegate

background

../_images/swipedelegate-background.9.png

background

disabled

../_images/swipedelegate-background-disabled.9.png

background

pressed

../_images/swipedelegate-background-pressed.9.png

background

focused

../_images/swipedelegate-background-focused.9.png

background

hovered

../_images/swipedelegate-background-hovered.9.png

Switch

indicator

../_images/switch-indicator.png

indicator

disabled

../_images/switch-indicator-disabled.png

indicator

pressed

../_images/switch-indicator-pressed.png

indicator

checked

../_images/switch-indicator-checked.png

indicator

checked, focused

../_images/switch-indicator-checked-focused.png

indicator

checked, hovered

../_images/switch-indicator-checked-hovered.png

indicator

checked, pressed

../_images/switch-indicator-checked-pressed.png

indicator

focused

../_images/switch-indicator-focused.png

indicator

hovered

../_images/switch-indicator-hovered.png

handle

../_images/switch-handle.png

handle

disabled

../_images/switch-handle-disabled.png

handle

pressed

../_images/switch-handle-pressed.png

SwitchDelegate

background

../_images/switchdelegate-background.9.png

background

disabled

../_images/switchdelegate-background-disabled.9.png

background

pressed

../_images/switchdelegate-background-pressed.9.png

background

focused

../_images/switchdelegate-background-focused.9.png

background

hovered

../_images/switchdelegate-background-hovered.9.png

indicator

../_images/switchdelegate-indicator.png

indicator

disabled

../_images/switchdelegate-indicator-disabled.png

indicator

pressed

../_images/switchdelegate-indicator-pressed.png

indicator

checked

../_images/switchdelegate-indicator-checked.png

indicator

checked, focused

../_images/switchdelegate-indicator-checked-focused.png

indicator

checked, hovered

../_images/switchdelegate-indicator-checked-hovered.png

indicator

checked, pressed

../_images/switchdelegate-indicator-checked-pressed.png

indicator

focused

../_images/switchdelegate-indicator-focused.png

indicator

hovered

../_images/switchdelegate-indicator-hovered.png

handle

../_images/switchdelegate-handle.png

handle

disabled

../_images/switchdelegate-handle-disabled.png

TabBar

background

../_images/tabbar-background.png

TabButton

background

../_images/tabbutton-background.9.png

background

disabled

../_images/tabbutton-background-disabled.9.png

background

pressed

../_images/tabbutton-background-pressed.9.png

background

checked

../_images/tabbutton-background-checked.9.png

background

hovered

../_images/tabbutton-background-hovered.9.png

background

disabled, checked

../_images/tabbutton-background-disabled-checked.9.png

TextArea

background

../_images/textarea-background.9.png

background

disabled

../_images/textarea-background-disabled.9.png

background

focused

../_images/textarea-background-focused.9.png

TextField

background

../_images/textfield-background.9.png

background

disabled

../_images/textfield-background-disabled.9.png

background

focused

../_images/textfield-background-focused.9.png

ToolBar

background

../_images/toolbar-background.png

ToolButton

background

../_images/toolbutton-background.9.png

background

disabled, checked

../_images/toolbutton-background-disabled-checked.9.png

background

focused

../_images/toolbutton-background-focused.9.png

background

pressed

../_images/toolbutton-background-pressed.9.png

background

checked

../_images/toolbutton-background-checked.9.png

background

checked, focused

../_images/toolbutton-background-checked-focused.9.png

background

checked, hovered

../_images/toolbutton-background-checked-hovered.9.png

background

hovered

../_images/toolbutton-background-hovered.9.png

ToolSeparator

separator

horizontal

../_images/toolseparator-separator-horizontal.9.png

separator

vertical

../_images/toolseparator-separator-vertical.9.png

ToolTip

background

../_images/tooltip-background.9.png

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):

../_images/qtquickcontrols-imagine-9-patch-4x.png

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 button-background@2x.9.png must both be one pixel thick.

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

../_images/qtquickcontrols-imagine-9-patch-size.png

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:

../_images/qtquickcontrols-imagine-9-patch-resized-stretchable.png

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.

../_images/qtquickcontrols-imagine-9-patch-resized-padding.png

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:

../_images/qtquickcontrols-imagine-9-patch-inset.png

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:

../_images/qtquickcontrols-imagine-9-patch-inset-boundaries.png

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”).

++——————————————————————–+ || .. image:: images/qtquickcontrols-imagine-customization-dark.png| ++——————————————————————–+

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#

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.

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

Environment Variables#

Variable

Description

QT_QUICK_CONTROLS_IMAGINE_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:

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_SMOOTH

Set 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#

This attached property holds the path to the image assets…

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