Revision control

Copy as Markdown

/*! \internal
\page qq-palette-system Qt Quick Palette System
\image html palette-system-resolution.svg "Qt Quick palette resolution chain — highest priority at top"
This page explains how %Qt determines the final color of a UI control, end
to end. The journey starts at the raw platform color APIs and passes
through several distinct subsystems before arriving at the `color`
property in a QML file. Understanding each layer, and how it hands off to
the next, is the key to debugging color issues or extending the system.
The system is easiest to reason about as a *priority stack*. Every brush
role in a QPalette can be either *resolved* (explicitly set) or *unresolved*
(inherited). When a role is unresolved at one layer, the layer below provides
the value. The diagram above illustrates this stack; the sections below describe
each layer in detail, starting from the lowest priority and working upward.
The Material and Universal styles are a special case — they bypass the
palette system entirely and are described in
\ref material_universal_styles "The Material and Universal styles".
\section palette_data_structure QPalette — the data structure
QPalette is the shared currency of the whole system. It is a table of
\ref QBrush "brushes" indexed by two dimensions:
- **Group** — `Active`, `Inactive`, or `Disabled`. Reflects whether
the widget or item currently has keyboard focus, is visible but
unfocused, or is non-interactive.
- **Role** — WindowText, %Button, Light, Midlight, Dark, Mid, Text,
BrightText, ButtonText, Base, %Window, Shadow, Highlight,
HighlightedText, Link, LinkVisited, AlternateBase, ToolTipBase,
ToolTipText, PlaceholderText, and Accent.
Each brush normally carries a fill color and may carry additional paint
properties. Alongside the brush data every QPalette has a
`resolveMask` — a bitmask with one bit per role. %A **set** bit means
"this role was explicitly assigned and must not be silently overridden".
The key function for combining two palettes is:
\code
QPalette QPalette::resolve(const QPalette &other) const;
\endcode
It returns a new palette that keeps every role whose bit is set in
`this`, and pulls the remaining roles from `other`. This single
function is the merging mechanism used at almost every layer boundary.
\note In %Qt Quick, QPalette is wrapped by QQuickPalette, which works the
same way but restricts each brush to a plain fill color.
\section layer1_platform_theme Layer 1 — QPlatformTheme: the system palette
QPlatformTheme::palette() is the foundation. The platform plugin
implements this virtual function to turn native OS color values into a
QPalette:
- **Windows** —
- **GTK3** —
- Other platforms use equivalent native APIs.
When called with the default argument `QPlatformTheme::SystemPalette`
this is the *system palette* — the one that honors the user's OS theme
and personalization settings. The function can also be called with other
`Palette` enum values to return per-widget-class "role" palettes (e.g.
`ToolButtonPalette`), which QApplication uses to give individual widget
types their own defaults.
\section layer2_application_palette Layer 2 — QGuiApplication / QApplication: the application palette
`QGuiApplicationPrivate::generateApplicationPalette()` builds the *application palette*
by composing the layers below it in four steps:
1. Start with **QStyle::standardPalette()** as the base. This generic
palette works without any platform theme.
2. **Resolve** the system palette over it: roles explicitly provided by
QPlatformTheme::palette() fill in or override the corresponding roles
from the standard palette.
3. Reset `resolveMask` to `0`. This lets the next step — and any
later user-set brushes — distinguish themselves from style-generated
values.
4. Apply **QStyle::polish(QPalette &)** so the active style can adjust
any roles it cares about.
The resulting palette has `resolveMask` `0` and acts as a fallback.
Any roles later set explicitly via **QGuiApplication::setPalette()** take
precedence because those brushes are marked resolved.
In QApplication (%Qt Widgets), per-widget-class palette overrides can
additionally be registered via `QApplication::setPalette(palette, className)`.
\section layer3_item_palette_tree Layer 3 — QQuickPaletteProviderPrivateBase: the item palette tree
%Qt Quick introduces a per-item palette. QQuickWindowPrivate,
QQuickItemPrivate, and QQuickPopupPrivate all inherit from
QQuickPaletteProviderPrivateBase, giving every window, item, and popup
both a `palette` and a `defaultPalette`.
Palettes are **lazily initialized**. On first access:
- The item inherits all unresolved roles from its parent item's palette.
- Inheritance walks the parent chain until QQuickWindow is reached.
- QQuickWindow fills its own unresolved roles from `defaultPalette()`.
The base implementation of `defaultPalette()` returns a default-constructed
QPalette() — a copy of the application palette with `resolveMask` `0` —
so all roles are available for override by higher-priority layers.
When the application palette changes (e.g. after QGuiApplication::setPalette()
or an OS theme switch), a `ApplicationPaletteChange` event is dispatched
to every QQuickWindow, QQuickItem, and QQuickPopup, which then
re-inherit from the updated application palette.
\section layer4_style_palette Layer 4 — QQuickTheme: the style palette
%Qt Quick Controls overrides `defaultPalette()` on virtually every control
type to return **QQuickTheme::palette(scope)** instead of the plain
application palette. This is how styles give controls a distinct look
without modifying the application-wide QPalette.
QQuickStylePlugin::createTheme() constructs the QQuickTheme singleton when
the style plugin loads. At that point two things happen:
1. The plugin calls **initializeTheme(QQuickTheme *)** (and optionally **updateTheme()**)
to populate the theme palettes. What this means in practice depends on the style:
- **Fusion** and **macOS** — set `preferPlatformTheme = true`,
which makes QQuickTheme delegate directly to
QPlatformTheme::palette() so the controls always follow the
system palette.
- **Imagine**, **FluentWinUI3**, and **iOS** — supply fully
custom palettes independent of the platform.
- **Windows** — calls
QWindowsApplication::populateLightSystemPalette() to use the
system light-mode colors regardless of the current OS theme (dark
mode is not supported in this style at the time of writing).
2. If a config file is found at the path given by
`QT_QUICK_CONTROLS_CONF`, or at `:/qtquickcontrols2.conf`, the
parser marks any brushes found there as resolved in the theme palette.
These override everything the style itself provides, making the config
file the highest-priority override short of a direct QML binding.
The **scope** argument to **QQuickTheme::palette(Scope)**
and **QQuickTheme::setPalette(Scope, const QPalette &)** lets a style supply
different palettes for different control types. For example, a style can
use a palette with a distinct accent color for buttons while keeping a
neutral palette for other controls. The default scope is `System`.
\section material_universal_styles The Material and Universal styles
These two styles completely bypass the palette system. Instead of
QQuickPaletteProviderPrivateBase or QQuickTheme, each control's color
bindings look up values directly from an *attached-object singleton* —
QQuickMaterialStyle or QQuickUniversalStyle.
The singleton holds two hard-coded color arrays (one for light mode, one
for dark mode) and derives from QQuickAttachedPropertyPropagator to
cascade style-property changes down the item tree, filling the role that
the palette parent chain fills for other styles.
Some customization is available through the config file and environment
variables:
- [Material style customization](https://doc.qt.io/qt-6/qtquickcontrols-material.html)
- [Universal style customization](https://doc.qt.io/qt-6/qtquickcontrols-universal.html)
\section full_order_of_precedence Full order of precedence
For all styles except Material and Universal, the final color for a given
brush role is determined by the first layer in this list that has it
explicitly set:
1. %A direct `color:` binding in QML.
2. The `palette` property set on the item or an ancestor item in QML or
C++ (roles propagate to descendants; unset roles are inherited from
the parent).
3. The config file (`qtquickcontrols2.conf` / `QT_QUICK_CONTROLS_CONF`).
4. **QGuiApplication::setPalette()** — only brushes with their
`resolveMask` bit set.
5. **QStyle::polish(QPalette &)**.
6. **QPlatformTheme::palette()** — the platform system palette.
7. **QStyle::standardPalette()** — the generic base fallback.
For the Material and Universal styles the stack is simpler:
1. %A direct `color:` binding in QML.
2. The config file or style-specific environment variables.
3. The built-in hard-coded light/dark color arrays.
*/