PICARD-2300: Add qt's stylehints to theme.py for a consistent exp. across platforms

[knguyen1]

Summary

• This is a…
  • Bug fix
  • Feature addition
  • Refactoring
  • Minor / simple change (like a typo)
  • Other
• Describe this change in 1-2 sentences:
  Added Qt6 style hints support to theme system and made appearance menu consistent across all platforms by enabling DEFAULT, LIGHT, and DARK themes everywhere except Haiku.

Problem

• JIRA ticket (optional): PICARD-2300

The theme system was inconsistent across platforms - Linux only had DEFAULT and SYSTEM themes while Windows/macOS had DEFAULT, LIGHT, and DARK. Qt6's style hints provide a better way to handle dark themes with automatic fallback to manual color application.

Solution

Added new style hints methods to BaseTheme:

• _get_style_hints(): Gets QGuiApplication.styleHints()
• _set_color_scheme(): Sets color scheme using style hints
• _apply_dark_palette_colors(): Manual dark color application
• _apply_dark_theme_to_palette(): Uses Qt color scheme or manual fallback

Updated AVAILABLE_UI_THEMES to include DEFAULT, LIGHT, and DARK on all platforms except Haiku, making the appearance menu consistent.

Enhanced setup logic to use Qt's built-in color scheme when available, with automatic fallback to manual color application.

Action

Additional actions required:

• Update Picard documentation (See PICARD-3103)
• Other (please specify below)

[rdswift]

The code looks fine to me.

It appears that this will change the choices available for the theme setting on Linux systems. As such, the documentation should be updated -- specifically the "User interface color theme" section on the User Interface Options page. I'll add a sub-task ticket so that this isn't forgotten (see PICARD-3103).

[phw]

This is so great! The code looks fine to me overall. Some minor comments, otherwise I'd just like to test this live before merging.

[zas]

@knguyen1 PR looks good to me, please resolve conflicts

[phw]

I tested this on Linux on Gnome. Unfortunately the style hint setColorScheme does not seem to have an effect there. It uses whatever I have set system wide.

That also means the "Light" and "Dark" theme settings in Picard don't have the desired effect.

apply_dark_theme_to_palette is only run, if the setting is on UiTheme.DEFAULT. Also apply_dark_theme_to_palette doesn't change the palette, if style hint support is detected. So setting the style to "Dark" does not run.

On the opposite if the system theme is already dark, but I set the Picard setting to LIGHT we currently have no way to do this. As the style hint again has no effect, but we also have no logic of explicitly setting a light palette, the app stays dark.

Is anyone currently able to test under a different Linux setup, e.g. Plasma desktop?

UPDATE: QtGui.QGuiApplication.styleHints().colorScheme() works fine to report the system scheme. When querying this on start it correctly reports Dark or Light, depening on what system theme is set (and the UI appears in this scheme accordingly). But a call to QtGui.QGuiApplication.styleHints().setColorScheme() has not effect. Even colorScheme() reports the original value still. On Windows changing the style this way works fine.

I found QTBUG-132929. But it claims to be solved in Qt 6.8, while In was testing with 6.9.1.

[knguyen1]

Failing linting step from the GitHub outage. I filed an issue astral-sh/ruff-action#198

[phw]

@knguyen1 @zas How shall we proceed here? In general I think this is looking good, and we definitely should move forward with the new APIs provides by Qt6. We will have even some potential to further simplify the code in the future with less differences between platforms, I think. But this PR is overall a good starting point.

Just my comment above shows that Linux stays complicated. As I wrote it does not work for me on my Gnome setup. I currently don't have my KDE Neon VM available to run, so I haven't checked there. Do you guys have done some better results on Linux?

[knguyen1]

@phw It's working for me on gnome. Here's a screencast: https://1drv.ms/v/c/0e7c7882e6da112b/EZ5VziUuchBGl03_05izHUIB-MWMCV1kZO-YoVgQ5-S1rQ?e=1m00QB I tested various permutations light, dark, default following sys theme, etc.

I suspect you needed to have qt5 \ qt6 installed

apt list --installed | grep -i 'qt5\|qt6'

libqt5core5t64/noble,now 5.15.13+dfsg-1ubuntu1 amd64 [installed,automatic]
libqt5dbus5t64/noble,now 5.15.13+dfsg-1ubuntu1 amd64 [installed,automatic]
...
python3-pyqt5.sip/noble,now 12.13.0-1build3 amd64 [installed,automatic]
python3-pyqt5/noble,now 5.15.10+dfsg-1build6 amd64 [installed,automatic]
qt5-gtk-platformtheme/noble,now 5.15.13+dfsg-1ubuntu1 amd64 [installed,automatic]

Install with sudo apt install qt6-base-dev. On linux, it's a reasonable expectation for people to have; if not it can be installed. I would update the docs and be very clear about this little nuance.

Maybe file a bug with QTBUG as well?

[zas]

On Linux Mint 22 + Cinnamon, if I switch theme to Light, while having a dark theme, save, restart Picard, it stays on dark theme, no way to force it to Light. So it doesn't look to work for me. I'll do more testing later.

Also since it changes option values we need an upgrade hook (I think).

[knguyen1]

On Linux Mint 22 + Cinnamon, if I switch theme to Light, while having a dark theme, save, restart Picard, it stays on dark theme, no way to force it to Light. So it doesn't look to work for me. I'll do more testing later.

Can you try after installing sudo apt install qt6-base-dev?

[phw]

I have been trying with the PyQt6 / Qt6 from PyPI only. I'm on Ubuntu 24.04, and the Qt6 package provided there is too old (6.4). We have 6.5 defined as minimum, and the ColorScheme support makes this more important again.

Anyway, that might as well be the reason. We had the experience already in the past that the PyPI version did not integrate that well with the platform, while the distribution packages provided a much better experience. On Qt5 e.g. you could install qgnomeplatform for a better integration.

Maybe also the qt6-xdgdesktopportal-platformtheme package has some impact?

Anyway, if it generally works this is already much of an improvement. A lot of Qt6 is still progressing. I'd vote for getting this PR merged and improve as needed.

UPDATE: Weirdly it works fine for me today with PyQt6 from PyPI. I'm not aware that anything changed since my last attempt, but theme overrides in Picard work both when I have the light and dark theme configured in Gnome settings.

[zas]

sudo apt install qt6-base-dev

No change.

Though it seems it sets theme to Light, it doesn't actually switch to light theme.

D: 15:27:36,625 tagger._log_startup:314: Starting Picard from '/home/zas/src/picard/picard/tagger.py'
D: 15:27:36,626 tagger._log_startup:315: Platform: Linux-6.8.0-71-generic-x86_64-with-glibc2.39 CPython 3.12.3
D: 15:27:36,634 tagger._log_startup:317: Versions: Picard 3.0.0.dev6, Python 3.12.3, PyQt 6.9.0, Qt 6.9.0, Mutagen 1.47.0, Discid discid 1.2.0, libdiscid 0.6.4, astrcmp C, SSL OpenSSL 3.0.13 30 Jan 2024
D: 15:27:36,635 tagger._log_startup:318: Configuration file path: '/home/zas/.config/MusicBrainz/Picard.ini'
D: 15:27:36,636 tagger._log_startup:320: User directory: '/home/zas/.config/MusicBrainz/Picard'
D: 15:27:36,636 tagger._log_startup:321: System long path support: True
D: 15:27:36,637 tagger._log_startup:324: Qt Env.: QT_SCALE_FACTOR='1.3' QT_ACCESSIBILITY='1' QT_AUTO_SCREEN_SCALE_FACTOR='0'
D: 15:27:36,652 ui/theme.setup:254: Theme: light (BaseTheme) dark=False accent_color=#ffc5a07c

[phw]

A couple of suggested changes in knguyen1#1

[phw]

@knguyen1 sorry, I pushed my changes from my PR accidentally directly to your branch with my latest commit. Please double check, we can undo stuff if it turns out to be a problem.

[zas]

@knguyen1 sorry, I pushed my changes from my PR accidentally directly to your branch with my latest commit. Please double check, we can undo stuff if it turns out to be a problem.

There's a leftover in the current branch:

picard/ui/options/interface.py:180:            if new_theme_setting == str(UiTheme.SYSTEM):

[knguyen1]

Haha, no problem. I'm about to go to the airport for a trip. But will check when possible...

[knguyen1]

sudo apt install qt6-base-dev

No change.

Though it seems it sets theme to Light, it doesn't actually switch to light theme.

D: 15:27:36,625 tagger._log_startup:314: Starting Picard from '/home/zas/src/picard/picard/tagger.py'

D: 15:27:36,626 tagger._log_startup:315: Platform: Linux-6.8.0-71-generic-x86_64-with-glibc2.39 CPython 3.12.3

D: 15:27:36,634 tagger._log_startup:317: Versions: Picard 3.0.0.dev6, Python 3.12.3, PyQt 6.9.0, Qt 6.9.0, Mutagen 1.47.0, Discid discid 1.2.0, libdiscid 0.6.4, astrcmp C, SSL OpenSSL 3.0.13 30 Jan 2024

D: 15:27:36,635 tagger._log_startup:318: Configuration file path: '/home/zas/.config/MusicBrainz/Picard.ini'

D: 15:27:36,636 tagger._log_startup:320: User directory: '/home/zas/.config/MusicBrainz/Picard'

D: 15:27:36,636 tagger._log_startup:321: System long path support: True

D: 15:27:36,637 tagger._log_startup:324: Qt Env.: QT_SCALE_FACTOR='1.3' QT_ACCESSIBILITY='1' QT_AUTO_SCREEN_SCALE_FACTOR='0'

D: 15:27:36,652 ui/theme.setup:254: Theme: light (BaseTheme) dark=False accent_color=#ffc5a07c

What about qt5-base-dev? I don't know why the diff would be. I have it on Gnome and it works.

In regard to the PR, I'm of the opinion that if the code on our part is technically correct, it's the qt api's fault and we should file a bug with QTBUG.

[phw]

I'm fine with the current state in this PR. I'd appreciate some review of my specific changes, but otherwise this did currently work for me and the usage of the APIs as it is makes sense.

I assume the situation on Linux to stay a bit difficult for a while. We already made the experience that the various Qt 6 versions have different issues, and distributions like e.g. Ubuntu 24.04 unfortunately ship older versions. But yes, if we have specific error case we should report it.

[zas]

LGTM