Skip to content

Upgrade Theme to a C++ QObject, and unlock customization of default color schemes for custom apps#7076

Merged
kaustuvpokharel merged 15 commits intomasterfrom
themeEngine
Feb 24, 2026
Merged

Upgrade Theme to a C++ QObject, and unlock customization of default color schemes for custom apps#7076
kaustuvpokharel merged 15 commits intomasterfrom
themeEngine

Conversation

@kaustuvpokharel
Copy link
Collaborator

@kaustuvpokharel kaustuvpokharel commented Feb 23, 2026

This PR replaces the legacy Theme.qml singleton with a new C++ Theme singleton that exposes the same theme API to QML (Theme.mainColor, Theme.darkTheme, Theme.applyAppearance(), etc), while loading theme values from a JSON file

The goal was to keep QML usage as unchanged as possible while moving theme logic to a more scalable and maintainable engine

What changed

  • Removed the old QML-based Theme.qml singleton
  • Added a C++ Theme QObject singleton that mirrors the previous QML API
  • Theme colors are now loaded from :/theme/theme.json
  • Introduced support for:
    • darkThemeColors
    • lightThemeColors
    • as many theme can be added or extended to, one change in json reflects through entire application.
  • Implemented dynamic palette application via Qt meta-object system:
    • applyColors(QVariantMap)
    • applyAppearance(extraColors, baseAppearance)

Reason

The old Theme.qml worked well, but to overcome these:

  • theme values were hardcoded in QML
  • scaling to more themes / white-label builds was difficult for customization

The new C++ implementation gives us:

  • JSON-driven theming (easy to customize / brand / extend)
  • centralized theme engine logic
  • better long-term maintainability
  • a cleaner path for white-label and runtime theme customization
  • compatibility with the existing QML codebase (same property names and theme calls)

Compatibility / Migration

This PR is designed to be a drop-in replacement for most existing QML usage.
Existing QML calls like:

  • Theme.mainColor
  • Theme.mainTextColor
  • Theme.darkTheme
  • Theme.applyAppearance()
  • Theme.getThemeIcon(...)
    continue to work through the new C++ singleton.
    Additionally, darkThemeColors and lightThemeColors are exposed for compatibility with QML code that reads the palette maps directly.

Implementation details

  • Switchable colors (dark/light) are applied dynamically via applyColors() using Qt’s meta-object system
  • Fixed colors are loaded once from fixedColors in JSON and assigned directly
  • errorColor remains derived from darkTheme
  • Font helpers and icon path helpers from the previous QML singleton are preserved

Material.theme / Application.styleHints.colorScheme remain QML-side concerns and should be bound to Theme.darkTheme as needed
This PR creates a foundation for future improvements like (if needed or wished):

  • multiple theme packs
  • white-label theme switching
  • runtime theme overrides
  • font configuration from JSON (future extension)

A demo of minor tweak in the json transforming whole qfield, (not intended to disturb branding just a test run):

Screen.Recording.2026-02-22.at.10.55.08.PM.mov

@qfield-fairy
Copy link
Collaborator

qfield-fairy commented Feb 23, 2026

📱 Android builds

Download an Android arm64 build of this PR for testing.
(Built from commit 36f204e)

Other Android architectures

🍎 MacOS DMG universal builds

Download a MacOS DMG universal build of this PR for testing.
(Built from commit 36f204e)

🪟 Windows builds

Download a Windows build of this PR for testing.
(Built from commit 36f204e)

🐧 Linux AppImage builds

Download a Linux AppImage build of this PR for testing.
(Built from commit 36f204e)

Copy link
Contributor

@github-actions github-actions bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

clang-tidy made some suggestions

@nirvn nirvn changed the title Theme engine Upgrade Theme to a C++ QObject, and unlock customization of default color schemes for custom apps Feb 23, 2026
@nirvn nirvn force-pushed the themeEngine branch 2 times, most recently from cfcf9d9 to 36f204e Compare February 24, 2026 04:36
@kaustuvpokharel kaustuvpokharel merged commit 471f7be into master Feb 24, 2026
33 of 53 checks passed
@kaustuvpokharel kaustuvpokharel deleted the themeEngine branch February 24, 2026 06:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants