ColorScheme: make QStyleHints::colorScheme writable for applications

Applications can request the color scheme to be either explicitly light
or dark, or to follow the system default by setting the scheme to
Qt::ColorScheme::Unknown.

Setting the color scheme will make the request to the QPlatformTheme
implementation, which can then use the appropriate implementation to
set the application's appearance so that both palette and window
decoration follow the requested color scheme. This should trigger
theme change and palette change events. A change to the effective
scheme should then call back into QStyleHintsPrivate::updateColorScheme,
which will emit the changed signal for the property.

Implement this for macOS (Cocoa), iOS, Android, and Windows.

On macOS, we have to use deprecated AppKit APIs; the replacements for
those APIs are not suitable for this use case. On iOS, the setting is
for each UIWindow, which we can update or initialize based on an
explicitly requested scheme.

On Android we can piggy-back on the logic added when dark theme support
was introduced in b4a9bb1f6a40e6d504c1f48f0d9ea2b70ab1a9f0.

On Windows, we have to fake a dark palette if the dark scheme is
requested on a light system, as there is no API to read a dark palette.
However, we also have to ignore any application preference if a high-
contrast accessibility theme is selected by the user (we report the
color scheme as unknown; there are both light and dark high-contrast
themes), and read the system palette using the GetSysColor API, which
is used for light mode. And we need to initialize windows with the
correct frame if the application explicitly overrides the system color
scheme.

Add an auto-test to the QApplication test, as that gives us the most
coverage to confirm that QStyleHints emits the changed signal, and that
Theme- and PaletteChange events are received by the toplevel widget
when the color scheme actually changes. This test has to be skipped
on platforms where we cannot set the color scheme programmatically.

Add the option to explicitly select the color scheme to the widget
gallery example, and default it to dark mode.

Fixes: QTBUG-124490
Change-Id: I7302993c0121284bf9d3b72e3149c6abbe6bd261
Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io>

4 files changed, 57 insertions, 3 deletions

diff --git a/src/gui/kernel/qplatformtheme.cpp b/src/gui/kernel/qplatformtheme.cpp
index 48978b849a..3d1319615e 100644
--- a/src/gui/kernel/qplatformtheme.cpp
+++ b/src/gui/kernel/qplatformtheme.cpp
@@ -447,6 +447,11 @@ Qt::ColorScheme QPlatformTheme::colorScheme() const
     return Qt::ColorScheme::Unknown;
 }
 
+void QPlatformTheme::requestColorScheme(Qt::ColorScheme scheme)
+{
+    Q_UNUSED(scheme);
+}
+
 const QPalette *QPlatformTheme::palette(Palette type) const
 {
     Q_D(const QPlatformTheme);
diff --git a/src/gui/kernel/qplatformtheme.h b/src/gui/kernel/qplatformtheme.h
index c0193947b9..d007a19675 100644
--- a/src/gui/kernel/qplatformtheme.h
+++ b/src/gui/kernel/qplatformtheme.h
@@ -295,6 +295,7 @@ public:
 #endif
 
     virtual Qt::ColorScheme colorScheme() const;
+    virtual void requestColorScheme(Qt::ColorScheme scheme);
 
     virtual const QPalette *palette(Palette type = SystemPalette) const;
 
diff --git a/src/gui/kernel/qstylehints.cpp b/src/gui/kernel/qstylehints.cpp
index 5029701f24..0d15d114ec 100644
--- a/src/gui/kernel/qstylehints.cpp
+++ b/src/gui/kernel/qstylehints.cpp
@@ -123,8 +123,29 @@ int QStyleHints::touchDoubleTapDistance() const
 
 /*!
     \property QStyleHints::colorScheme
-    \brief the color scheme of the platform theme.
-    \sa Qt::ColorScheme
+    \brief the color scheme used by the application.
+
+    By default, this follows the system's default color scheme (also known as appearance),
+    and changes when the system color scheme changes (e.g. during dusk or dawn).
+    Setting the color scheme to an explicit value will override the system setting and
+    ignore any changes to the system's color scheme. However, doing so is a hint to the
+    system, and overriding the color scheme is not supported on all platforms.
+
+    Resetting this property, or setting it to \l{Qt::ColorScheme::Unknown}, will remove
+    the override and make the application follow the system default again. The property
+    value will change to the color scheme the system currently has.
+
+    When this property changes, Qt will read the system palette and update the default
+    palette, but won't overwrite palette entries that have been explicitly set by the
+    application. When the colorSchemeChange() signal gets emitted, the old palette is
+    still in effect.
+
+    Application-specific colors should be selected to work well with the effective
+    palette, taking the current color scheme into account. To update application-
+    specific colors when the effective palette changes, handle
+    \l{QEvent::}{PaletteChange} or \l{QEvent::}{ApplicationPaletteChange} events.
+
+    \sa Qt::ColorScheme, QGuiApplication::palette(), QEvent::PaletteChange
     \since 6.5
 */
 Qt::ColorScheme QStyleHints::colorScheme() const
@@ -134,6 +155,30 @@ Qt::ColorScheme QStyleHints::colorScheme() const
 }
 
 /*!
+    \since 6.8
+
+    Sets the color scheme used by the application to an explicit \a scheme, or
+    revert to the system's current color scheme if \a scheme is Qt::ColorScheme::Unknown.
+*/
+void QStyleHints::setColorScheme(Qt::ColorScheme scheme)
+{
+    if (!QCoreApplication::instance()) {
+        qWarning("Must construct a QGuiApplication before accessing a platform theme hint.");
+        return;
+    }
+    if (QPlatformTheme *theme = QGuiApplicationPrivate::platformTheme())
+        theme->requestColorScheme(scheme);
+}
+
+/*!
+    \fn void QStyleHints::unsetColorScheme()
+    \since 6.8
+
+    Restores the color scheme to the system's current color scheme.
+*/
+
+
+/*!
     Sets the \a mousePressAndHoldInterval.
     \internal
     \sa mousePressAndHoldInterval()
diff --git a/src/gui/kernel/qstylehints.h b/src/gui/kernel/qstylehints.h
index 969bec4b35..8981383060 100644
--- a/src/gui/kernel/qstylehints.h
+++ b/src/gui/kernel/qstylehints.h
@@ -52,7 +52,8 @@ class Q_GUI_EXPORT QStyleHints : public QObject
     Q_PROPERTY(int mouseDoubleClickDistance READ mouseDoubleClickDistance STORED false CONSTANT
                FINAL)
     Q_PROPERTY(int touchDoubleTapDistance READ touchDoubleTapDistance STORED false CONSTANT FINAL)
-    Q_PROPERTY(Qt::ColorScheme colorScheme READ colorScheme NOTIFY colorSchemeChanged FINAL)
+    Q_PROPERTY(Qt::ColorScheme colorScheme READ colorScheme WRITE setColorScheme
+               RESET unsetColorScheme NOTIFY colorSchemeChanged FINAL)
 
 public:
     void setMouseDoubleClickInterval(int mouseDoubleClickInterval);
@@ -94,6 +95,8 @@ public:
     void setMouseQuickSelectionThreshold(int threshold);
     int mouseQuickSelectionThreshold() const;
     Qt::ColorScheme colorScheme() const;
+    void setColorScheme(Qt::ColorScheme scheme);
+    void unsetColorScheme() { setColorScheme(Qt::ColorScheme::Unknown); }
 
 Q_SIGNALS:
     void cursorFlashTimeChanged(int cursorFlashTime);