Update remarks on taskbar icon precedence

[Hu Jialun (SuibianP)]

Clarified that existing shell link icons and RelaunchIconResource take precedence over this method.

[John Kennedy (GrantMeStrength)]

LGTM — accurate improvement. Approved.

[John Kennedy (GrantMeStrength)]

Copilot /review

[John Kennedy (GrantMeStrength)]

Reviewed ✅ — Documentation improvement looks good.

[Hu Jialun (SuibianP)]

It would also have been nice if there is some official documentation regarding the icon logic (taskbar, peek, titlebar, jump list, task switcher).

• RT_GROUP_ICON resource in the PE executable
• WM_SETICON (ICON_BIG/ICON_SMALL)
• Window class icon (WNDCLASSEX::hIcon/hIconSm)
• RelaunchIconResource
• Icon of RelaunchCommand
• Existing shell links (implicit/explicit)
• Explorer caching, etc.

From my preliminary testing, it seems that for taskbar,

• TaskbarButtonCreated triggers at the following time,
  • Window shown
  • AUMID set and committed
  • ITaskbarList3::AddTab
• Upon every TaskbarButtonCreated, the taskbar icon refreshes following this priority,
  1. IconLocation in existing links with the same AUMID or pointing to the same executable (white paper icon if not accessible, RT_GROUP_ICON if no IconLocation)
  2. RelaunchIconResource (if AUMID set)
  3. ICON_BIG
  4. ICON_SMALL
  5. hIcon
  6. hIconSm
  7. RT_GROUP_ICON
• Upon creation of shell link, the IconLocation is chosen in the following order,
  1. RelaunchIconResource, if AUMID, RelaunchCommand and RelaunchDisplayNameResource are set
  2. Icon of RelaunchCommand, if AUMID and RelaunchDisplayNameResource are set
  3. None
• On first taskbar right click, if there is a real icon candidate per the last point, an implicit shortcut is created with it, the taskbar item recreated (context menu closes on its own) and TaskbarButtonCreated triggered, even without clicking pinning. In order to change the icon again, it is needed to manually delete it, and either call SHChangeNotify(SHCNE_DELETE) or restart explorer.
• Any %systemdir% in the icon path (as per https://learn.microsoft.com/en-us/windows/win32/properties/props-system-appusermodel-relaunchiconresource) renders properly on set, but does not get expanded in shell links. As such, on right click, it produces a shell link without path expansion and renders a vanilla icon.