File: System\Windows\Forms\Dialogs\TaskDialog\TaskDialogIcon.cs
Web Access
Project: src\src\System.Windows.Forms\src\System.Windows.Forms.csproj (System.Windows.Forms)
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
 
using System.Drawing;
 
namespace System.Windows.Forms;
 
/// <summary>
///   Represents an icon that can be shown in the main area of a task dialog
///   (by setting the <see cref="TaskDialogPage.Icon"/> property) or in the
///   footnote of a task dialog (by setting the <see cref="TaskDialogFootnote.Icon"/>
///   property).
/// </summary>
/// <remarks>
/// <para>
///   The task dialog currently supports two icon types: Standard icons that are
///   stored in static fields of class <see cref="TaskDialogIcon"/>, and custom icons
///   created from an <see cref="Icon"/> instance (or an icon handle).
/// </para>
/// <para>
///   Some standard icons play a typical system sound when used as the main icon of
///   the task dialog.
/// </para>
/// <para>
///   Note that while a task dialog is shown, you can only update an icon if the
///   new icon is of the same type (standard icon or custom icon) as the previous
///   one.
/// </para>
/// </remarks>
public class TaskDialogIcon : IDisposable
{
#pragma warning disable IDE1006 // Naming Styles
    /// <summary>
    ///   Gets a standard <see cref="TaskDialogIcon"/> instance where the task dialog
    ///   does not display an icon.
    /// </summary>
    public static readonly TaskDialogIcon None = new(TaskDialogStandardIcon.None);
 
    /// <summary>
    ///   Gets a standard <see cref="TaskDialogIcon"/> instance where the task dialog
    ///   contains a symbol consisting of a lowercase letter i in a circle.
    /// </summary>
    public static readonly TaskDialogIcon Information = new(TaskDialogStandardIcon.Information);
 
    /// <summary>
    ///   Gets a standard <see cref="TaskDialogIcon"/> instance where the task dialog
    ///   contains an icon consisting of an exclamation point in a triangle with a yellow background.
    /// </summary>
    public static readonly TaskDialogIcon Warning = new(TaskDialogStandardIcon.Warning);
 
    /// <summary>
    ///   Gets a standard <see cref="TaskDialogIcon"/> instance where the task dialog
    ///   contains an icon consisting of white X in a circle with a red background.
    /// </summary>
    public static readonly TaskDialogIcon Error = new(TaskDialogStandardIcon.Error);
 
    /// <summary>
    ///   Gets a standard <see cref="TaskDialogIcon"/> instance where the task dialog
    ///   contains an icon consisting of an user account control (UAC) shield.
    /// </summary>
    public static readonly TaskDialogIcon Shield = new(TaskDialogStandardIcon.Shield);
 
    /// <summary>
    ///   Gets a standard <see cref="TaskDialogIcon"/> instance where the task dialog
    ///   contains an icon consisting of an user account control (UAC) shield and shows a blue bar around the icon.
    /// </summary>
    public static readonly TaskDialogIcon ShieldBlueBar = new(TaskDialogStandardIcon.ShieldBlueBar);
 
    /// <summary>
    ///   Gets a standard <see cref="TaskDialogIcon"/> instance where the task dialog
    ///   contains an icon consisting of an user account control (UAC) shield and shows a gray bar around the icon.
    /// </summary>
    public static readonly TaskDialogIcon ShieldGrayBar = new(TaskDialogStandardIcon.ShieldGrayBar);
 
    /// <summary>
    ///   Gets a standard <see cref="TaskDialogIcon"/> instance where the task dialog
    ///   contains an icon consisting of an exclamation point in a yellow shield and shows a yellow bar around the icon.
    /// </summary>
    public static readonly TaskDialogIcon ShieldWarningYellowBar = new(TaskDialogStandardIcon.ShieldWarningYellowBar);
 
    /// <summary>
    ///   Gets a standard <see cref="TaskDialogIcon"/> instance where the task dialog
    ///   contains an icon consisting of white X in a red shield and shows a red bar around the icon.
    /// </summary>
    public static readonly TaskDialogIcon ShieldErrorRedBar = new(TaskDialogStandardIcon.ShieldErrorRedBar);
 
    /// <summary>
    ///   Gets a standard <see cref="TaskDialogIcon"/> instance where the task dialog
    ///   contains an icon consisting of white tick in a green shield and shows a green bar around the icon.
    /// </summary>
    public static readonly TaskDialogIcon ShieldSuccessGreenBar = new(TaskDialogStandardIcon.ShieldSuccessGreenBar);
#pragma warning restore IDE1006
 
    private readonly TaskDialogStandardIcon? _standardIcon;
    private readonly Icon? _ownedIcon;
    private readonly IntPtr? _iconHandle;
 
    /// <summary>
    ///   Initializes a new instance of the <see cref="TaskDialogIcon"/> class from an
    ///   <see cref="Bitmap"/> instance.
    /// </summary>
    /// <param name="image">The <see cref="Bitmap"/> instance.</param>
    /// <exception cref="ArgumentNullException"><paramref name="image"/> is <see langword="null"/>.</exception>
    /// <remarks>
    ///   <para>
    ///     The <see cref="Icon"/> instance from which this <see cref="TaskDialogIcon"/>
    ///     instance is created must not be disposed while the icon is shown in the task
    ///     dialog.
    ///   </para>
    /// </remarks>
    public TaskDialogIcon(Bitmap image)
        : this(BitmapToIcon(image.OrThrowIfNull()), true)
    {
    }
 
    /// <summary>
    ///   Initializes a new instance of the <see cref="TaskDialogIcon"/> class from an
    ///   <see cref="Icon"/> instance.
    /// </summary>
    /// <param name="icon">The <see cref="Icon"/> instance.</param>
    /// <exception cref="ArgumentNullException"><paramref name="icon"/> is <see langword="null"/>.</exception>
    /// <remarks>
    ///   <para>
    ///     The <see cref="Icon"/> instance from which this <see cref="TaskDialogIcon"/>
    ///     instance is created must not be disposed while the icon is shown in the task
    ///     dialog.
    ///   </para>
    /// </remarks>
    public TaskDialogIcon(Icon icon)
        : this(icon.OrThrowIfNull(), false)
    {
    }
 
    /// <summary>
    ///   Initializes a new instance of the <see cref="TaskDialogIcon"/> class from an
    ///   icon handle.
    /// </summary>
    /// <param name="iconHandle">A handle to an instance of an icon, or <see cref="IntPtr.Zero"/> to not show an icon.</param>
    /// <remarks>
    ///   <para>
    ///     The specified icon handle must not be released while the icon is shown in the
    ///     task dialog.
    ///   </para>
    /// </remarks>
    public TaskDialogIcon(IntPtr iconHandle)
    {
        _iconHandle = iconHandle;
    }
 
    private TaskDialogIcon(Icon icon, bool takeOwnership)
        : this(icon.Handle)
    {
        if (takeOwnership)
        {
            _ownedIcon = icon;
        }
    }
 
    private TaskDialogIcon(TaskDialogStandardIcon standardIcon)
    {
        _standardIcon = standardIcon;
    }
 
    /// <summary>
    ///   Releases all resources used by this <see cref="TaskDialogIcon"/>.
    /// </summary>
    public void Dispose()
    {
        _ownedIcon?.Dispose();
    }
 
    /// <summary>
    ///   The icon handle (<c>HICON</c>) that is represented by this
    ///   <see cref="TaskDialogIcon"/> instance.
    /// </summary>
    /// <exception cref="InvalidOperationException">
    ///   This <see cref="TaskDialogIcon"/> instance was not created using a
    ///   constructor that takes an icon or icon handle.
    /// </exception>
    public IntPtr IconHandle => _iconHandle ?? throw new InvalidOperationException();
 
    internal TaskDialogStandardIcon StandardIcon => _standardIcon ?? throw new InvalidOperationException();
 
    internal bool IsStandardIcon => _standardIcon is not null;
 
    internal bool IsHandleIcon => _iconHandle is not null;
 
    private static Icon BitmapToIcon(Bitmap bitmap)
    {
        HICON handle = HICON.Null;
        try
        {
            handle = (HICON)bitmap.GetHicon();
            var icon = Icon.FromHandle(handle);
 
            return (Icon)icon.Clone();
        }
        finally
        {
            if (!handle.IsNull)
            {
                PInvokeCore.DestroyIcon(handle);
            }
        }
    }
}