ColorScheme: clean up code to prepare adding a setter

The current QStyleHintsPrivate::setColorScheme is called when the system
theme changes, handling the change and informing the application. It is
not a setter. When we add a public setter, that setter will have to go
through the QPlatformTheme to request an override for the application.
That will then result in a call back to the QStyleHints to update the
theme with the effective color scheme (or ignore the request for the
override, on some platforms).

Rename it (and similar misleading APIs in platform plugins) to
updateColorScheme, and adjust outdated comments in some of the platform
plugins.

Task-number: QTBUG-124490
Change-Id: I6a852211254993df86acf2e2d42cf345e7401f4f
Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io>
Reviewed-by: Doris Verria <doris.verria@qt.io>

src/gui/kernel/qguiapplication.cpp

@@ -1531,7 +1531,7 @@ void QGuiApplicationPrivate::createPlatformIntegration()
 
     init_platform(QLatin1StringView(platformName), platformPluginPath, platformThemeName, argc, argv);
     if (const QPlatformTheme *theme = platformTheme())
-        QStyleHintsPrivate::get(QGuiApplication::styleHints())->setColorScheme(theme->colorScheme());
+        QStyleHintsPrivate::get(QGuiApplication::styleHints())->updateColorScheme(theme->colorScheme());
 
     if (!icon.isEmpty())
         forcedWindowIcon = QDir::isAbsolutePath(icon) ? QIcon(icon) : QIcon::fromTheme(icon);
@@ -2643,7 +2643,7 @@ void QGuiApplicationPrivate::processThemeChanged(QWindowSystemInterfacePrivate::
 
     QIconPrivate::clearIconCache();
 
-    QStyleHintsPrivate::get(QGuiApplication::styleHints())->setColorScheme(colorScheme());
+    QStyleHintsPrivate::get(QGuiApplication::styleHints())->updateColorScheme(colorScheme());
 
     QEvent themeChangeEvent(QEvent::ThemeChange);
     const QWindowList windows = tce->window ? QWindowList{tce->window} : window_list;

src/gui/kernel/qstylehints.cpp

@@ -595,11 +595,15 @@ int QStyleHints::mouseQuickSelectionThreshold() const
 
 /*!
    \internal
-   QStyleHintsPrivate::setColorScheme - set a new color scheme.
+   QStyleHintsPrivate::updateColorScheme - set a new color scheme.
+
+   This function is called by the QPA plugin when the system theme changes. This in
+   turn might be the result of an explicit request of a color scheme via setColorScheme.
+
    Set \a colorScheme as the new color scheme of the QStyleHints.
    The colorSchemeChanged signal will be emitted if present and new color scheme differ.
  */
-void QStyleHintsPrivate::setColorScheme(Qt::ColorScheme colorScheme)
+void QStyleHintsPrivate::updateColorScheme(Qt::ColorScheme colorScheme)
 {
     if (m_colorScheme == colorScheme)
         return;

src/gui/kernel/qstylehints_p.h

@@ -41,7 +41,7 @@ public:
     int m_touchDoubleTapDistance = -1;
 
     Qt::ColorScheme colorScheme() const { return m_colorScheme; }
-    void setColorScheme(Qt::ColorScheme colorScheme);
+    void updateColorScheme(Qt::ColorScheme colorScheme);
 
     static QStyleHintsPrivate *get(QStyleHints *q);
 

src/gui/platform/unix/qgenericunixthemes.cpp

@@ -957,7 +957,7 @@ Qt::ColorScheme QKdeTheme::colorScheme() const
 
 /*!
    \internal
-   \brief QKdeTheme::setColorScheme - guess and set appearance for unix themes.
+   \brief QKdeTheme::updateColorScheme - guess and set appearance for unix themes.
    KDE themes do not have an appearance property.
    The key words "dark" or "light" should be part of the theme name.
    This is, however, not a mandatory convention.

src/plugins/platforms/android/androidjnimain.cpp

@@ -703,7 +703,7 @@ Q_DECLARE_JNI_NATIVE_METHOD(handleScreenRemoved)
 
 static void handleUiDarkModeChanged(JNIEnv */*env*/, jobject /*thiz*/, jint newUiMode)
 {
-    QAndroidPlatformIntegration::setColorScheme(
+    QAndroidPlatformIntegration::updateColorScheme(
         (newUiMode == 1 ) ? Qt::ColorScheme::Dark : Qt::ColorScheme::Light);
 }
 Q_DECLARE_JNI_NATIVE_METHOD(handleUiDarkModeChanged)

src/plugins/platforms/android/qandroidplatformintegration.cpp

@@ -537,7 +537,7 @@ void QAndroidPlatformIntegration::setScreenSize(int width, int height)
 
 Qt::ColorScheme QAndroidPlatformIntegration::m_colorScheme = Qt::ColorScheme::Light;
 
-void QAndroidPlatformIntegration::setColorScheme(Qt::ColorScheme colorScheme)
+void QAndroidPlatformIntegration::updateColorScheme(Qt::ColorScheme colorScheme)
 {
     if (m_colorScheme == colorScheme)
         return;

src/plugins/platforms/android/qandroidplatformintegration.h

@@ -110,7 +110,7 @@ public:
 
     void flushPendingUpdates();
 
-    static void setColorScheme(Qt::ColorScheme colorScheme);
+    static void updateColorScheme(Qt::ColorScheme colorScheme);
     static Qt::ColorScheme colorScheme() { return m_colorScheme; }
 #if QT_CONFIG(vulkan)
     QPlatformVulkanInstance *createPlatformVulkanInstance(QVulkanInstance *instance) const override;