Add QGuiApplication API to set a number-badge in the Dock/task bar

The API is supported on macOS, iOS, and Windows. On Android no official
API exists for badging the application icon, and we don't want to take
on dependencies like ShortcutBadger [1].

The macOS and iOS implementations are trivial. The same goes for
the WinRT based implementation on Windows, but this API is only
available for applications that have a so called "package identity",
and does not seem to be stable for Windows 10.

To cover the cases where this API is not available we fall back to
drawing the badge manually, and set it as an overlay icon on the task
bar using ITaskbarList3. The look of this badge has been tweaked to
match the Windows 11/10 styles, and will pick up the user's choice of
dark/light mode and accent color if available.

[1] https://github.com/leolin310148/ShortcutBadger/

[ChangeLog][QtGui] Added QGuiApplication::setBadgeNumber() to inform
the user about e.g. the number of unread e-mail or queued tasks.
The badge will be overlaid on the application's icon in the Dock
on macOS, the home screen icon on iOS, or the task bar on Windows.

Task-number: QTBUG-94009
Change-Id: I6447d55177f9987b0dfcd93caf63c6167f7224c7
Reviewed-by: Axel Spoerl <axel.spoerl@qt.io>
Reviewed-by: Oliver Wolff <oliver.wolff@qt.io>
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>

4 files changed, 40 insertions, 0 deletions

diff --git a/src/gui/kernel/qguiapplication.cpp b/src/gui/kernel/qguiapplication.cpp
index b45113a665..fd7739b06f 100644
--- a/src/gui/kernel/qguiapplication.cpp
+++ b/src/gui/kernel/qguiapplication.cpp
@@ -740,6 +740,29 @@ QString QGuiApplication::applicationDisplayName()
 }
 
 /*!
+    Sets the application's badge to \a number.
+
+    Useful for providing feedback to the user about the number
+    of unread messages or similar.
+
+    The badge will be overlaid on the application's icon in the Dock
+    on \macos, the home screen icon on iOS, or the task bar on Windows.
+
+    If the number is outside the range supported by the platform, the
+    number will be clamped to the supported range. If the number does
+    not fit within the badge, the number may be visually elided.
+
+    Setting the number to 0 will clear the badge.
+
+    \since 6.5
+    \sa applicationName
+*/
+void QGuiApplication::setBadgeNumber(qint64 number)
+{
+    QGuiApplicationPrivate::platformIntegration()->setApplicationBadge(number);
+}
+
+/*!
     \property QGuiApplication::desktopFileName
     \brief the base name of the desktop entry for this application
     \since 5.7
diff --git a/src/gui/kernel/qguiapplication.h b/src/gui/kernel/qguiapplication.h
index b77984c381..14bce88c62 100644
--- a/src/gui/kernel/qguiapplication.h
+++ b/src/gui/kernel/qguiapplication.h
@@ -58,6 +58,8 @@ public:
     static void setApplicationDisplayName(const QString &name);
     static QString applicationDisplayName();
 
+    Q_SLOT void setBadgeNumber(qint64 number);
+
     static void setDesktopFileName(const QString &name);
     static QString desktopFileName();
 
diff --git a/src/gui/kernel/qplatformintegration.cpp b/src/gui/kernel/qplatformintegration.cpp
index 12f8505255..c95742b34d 100644
--- a/src/gui/kernel/qplatformintegration.cpp
+++ b/src/gui/kernel/qplatformintegration.cpp
@@ -569,6 +569,20 @@ void QPlatformIntegration::setApplicationIcon(const QIcon &icon) const
     Q_UNUSED(icon);
 }
 
+/*!
+    \since 6.5
+
+    Should set the application's badge to \a number.
+
+    If the number is 0 the badge should be cleared.
+
+    \sa QGuiApplication::setBadge()
+*/
+void QPlatformIntegration::setApplicationBadge(qint64 number)
+{
+    Q_UNUSED(number);
+}
+
 #if QT_CONFIG(vulkan) || defined(Q_QDOC)
 
 /*!
diff --git a/src/gui/kernel/qplatformintegration.h b/src/gui/kernel/qplatformintegration.h
index 7c166ee698..3d43395767 100644
--- a/src/gui/kernel/qplatformintegration.h
+++ b/src/gui/kernel/qplatformintegration.h
@@ -188,6 +188,7 @@ public:
     virtual QOpenGLContext::OpenGLModuleType openGLModuleType();
 #endif
     virtual void setApplicationIcon(const QIcon &icon) const;
+    virtual void setApplicationBadge(qint64 number);
 
     virtual void beep() const;
     virtual void quit() const;