[API Proposal]: Add ability to get modern Windows icons to System.Drawing.SystemIcons.

Background and motivation

The existing SystemIcons come from an older API that has icons that don’t get updated with the OS. The new API SHGetStockIconInfo is the way to get the current version of icons used in dialogs, etc.

Providing a new method in SystemIcons would allow getting updated versions of icons and allow access to a number of additional icons. It additionally allows getting small icon versions, highlighted versions, link versions, etc.

API Proposal

namespace System.Drawing;

public static class SystemIcons
{
    /// <summary>
    ///  Gets the specified stock shell icon.
    /// </summary>
    public static Icon GetStockIcon(StockIcon stockIcon);
    public static Icon GetStockIcon(StockIcon stockIcon, StockIconOptions options);
}

[Flags]
public enum StockIconOptions
{
    SmallIcon = 0x000000001,
    ShellIconSize = 0x000000004,
    LinkOverlay = 0x000008000,
    Selected = 0x000010000,
}

// Matching https://learn.microsoft.com/windows/win32/api/shellapi/ne-shellapi-shstockiconid with
// Pascal casing and no abbreviations ("Assoc" to "Associations"), will still keep acronyms (CD, not CompactDisc).
public enum StockIcon
{
    DocumentNoAssociation = 0,
    DocumentWithAssociation = 1,
    Application = 2,
    Folder = 3,
    OpenFolder = 4,
    Drive525 = 5,
    Drive35 = 6,
    DriveRemovable = 7,
    DriveFixed = 8,
    DriveNetwork = 9,
    DriveNetworkDisabled = 10,
    DriveCD = 11,
    DriveRAM = 12,
    World = 13,
    Server = 15,
    Printer = 16,
    // ...
}

API Usage

using Icon icon = SystemIcons.GetStockIcon(StockIcon.Shield);

Alternative Designs

We could update the existing methods to use the current icons but:

• Some applications will depend on the legacy icon look
• There are over 90 stock icons (and growing)

We could also put the static method in StockIcons, but that would make discoverability more difficult. Could potentially add to ‘Icon’?

Risks

No response

[KalleOlaviNiemitalo]

When documenting this, please make it clear whether the caller should eventually Dispose(). The SystemIcons.Application etc. properties cache the results and return Icon instances that ignore Dispose(). If GetStockIcon works differently, that will cause confusion.

[Amy-Li03]

Verified this on .NET 8.0 latest build: 8.0.100-preview.4.23179.4, saved the generated Icons using Icon.Save(), it behaves as expected.