Proposal: Converged and improved badge APIs

[SetTrend]

Summary

Status

Customer / job-to-be-done: App developers need to keep their users informed about number of new items/etc via badges on the taskbar regardless of whether their app is currently open Problem: Win32 apps have a different API for using badges on taskbar, with completely different functionality than UWP apps. Win32 apps can't simply set a number (they have to use custom icons), and UWP apps can only use preset badge/number options (they can't use custom icons). How does our solution make things easier? All types of apps will benefit from a single, easy-to-use badge API, that supports straightforward numbers and common symbols in addition to custom icons.

❌ Problem validation ❌ Docs ❌ Dev spec ❌ Solution validation ❌ Implementation ❌ Samples

Target customer

Packaging	App types
✅ Packaged apps ✅ Unpackaged apps	✅ WPF ✅ Win32 (C++) ✅ WinForms ✅ Console ✅ UWP ⚠ Cross-plat (Electron, MAUI, React Native, etc) ⚠ PowerShell

While this work should be consumable by cross-platform platforms to improve experiences there, we should have a separate feature specifically for ensuring badges are built in "natively" and developers don't have to do additional custom work to access the Windows native layer.

Customer's job-to-be-done

Developer needs to keep their users informed via badges regardless of whether their app is currently open. They may need advanced functionality like custom icons, or might just need simple functionality like setting a number.

Problems that exist today

Problem	Validated?
TODO: Fill this out	❌ TODO

Summary

Converge badge APIs across Win32 and UWP, and also provide objects for the APIs rather than XML (bring in the Toolkit helpers into Reunion itself).

public class BadgeUpdater
{
  public void Update(byte newValue) {...}
  public void Update(BadgeGlyph newValue) {...}

  //...

  public enum BadgeGlyph
  {
    None,
    Activity,
    Alarm,
    //...
  }

  //...
}

Rationale

Manipulating XML text doesn't seem either compile-time safe nor adequate when programming in a programming language.

XML isn't a programming language, it's a serialization medium, like YAML, JSON or plain text.

Editing plain text in terms of XML doesn't provide compile-time safety nor does it support IntelliSense.

Hence, for API purity I suggest do add these two type-safe overloads to the API, basically implementing the two functions documented in the documentation.

Additional ask for this here: microsoft/microsoft-ui-xaml#1919

[michael-hawker]

🦙 FYI @andrewleader does this fall into your purview as well? Thoughts?

[soumyamahunt]

Personally, I would like the tile and taskbar badges to be separated APIs. This will help multi-instance or multi-window UWP apps to set/update badges on each instance or window. Right now only the primary instance or window in taskbar shows badges which isn't that user friendly.

[andrewleader]

@soumyamahunt do your apps have windows that don't appear "glommed" (grouped) together on Taskbar? Most apps always appear glommed together and thus there's only one badge and no point for badges per window...

I'm trying to find out if you're wanting separate badges even when the windows are glommed (like when you hover over and the window previews appear, each one of those has individual separate badges?) or if your app simply avoids glomming the windows and appears as separate instances on taskbar. Any more context/details behind your scenario would be super helpful!

[soumyamahunt]

@soumyamahunt do your apps have windows that don't appear "glommed" (grouped) together on Taskbar? Most apps always appear glommed together and thus there's only one badge and no point for badges per window...

The way I think about badges is that it prompts user to do some tasks by opening a specific window/instance of app. Even if app's windows are grouped together if there is only one badge displayed on the left most window, then we are passing the burden to user to find out in which window/instance of the app demands their attention which isn't that convenient to user.

I'm trying to find out if you're wanting separate badges even when the windows are glommed (like when you hover over and the window previews appear, each one of those has individual separate badges?) or if your app simply avoids glomming the windows and appears as separate instances on taskbar. Any more context/details behind your scenario would be super helpful!

I think even if app windows are either gloomed or not, each window should be allowed to show their own badge to notify user that specific window needs their attention not pass the burden to user to find out which window needs their attention. The scenarios I can think of are:

1. Suppose you are designing a tabbed editor app that user uses to edit files in separate tabs. You might want to give user the flexibility to have multiple windows/instances of your app and have multiple tabs in them. You might want to notify the number of tabs that have unsaved changes separately for each window via taskbar badges so user knows which window they have to click and save there changes then. Also, the new Windows Terminal, IDEs come in this category.

2. Another scenario can be a social media app that lets user to use multiple accounts simultaneously (since most users normally have to social accounts: one for personal use, and one for official/ commercial use to separate their work from personal opinions or life stuff). You might want to each window to have their separate badges to notify users which account needs their attention.

[andrewleader]

Makes sense, thank you for all those details! That indeed does make sense. We'll discuss this with the taskbar UI team to see if they've heard similar user feedback about this, but I totally agree that the enhanced per-window badges would be useful for those cases!