TaskDialog Class

Represents a task dialog window that is able to display regular buttons, Vista-like command links, radio buttons and a progress bar. Can work in compatibility mode so the dialog can be used even with Windows XP or when visual styles are not available.

See the online help for examples.

Definition

Namespace: KGySoft.WinForms.Components
Assembly: KGySoft.WinForms (in KGySoft.WinForms.dll) Version: 5.0.1
C#
public sealed class TaskDialog : IWin32Window, 
	IDisposable
Inheritance
Object    TaskDialog
Implements
IDisposable, IWin32Window

Remarks

  Caution

.NET 5 also introduced task dialogs, so when targeting .NET 5 or later, referencing TaskDialog, TaskDialogControl, TaskDialogButton and TaskDialogRadioButton button classes may require to use fully qualified names or aliases like using TaskDialog = KGySoft.WinForms.Components.TaskDialog; to avoid ambiguity with the recently added WinForms classes. Please also note that unlike the KGy SOFT TaskDialog, System.Windows.Forms.TaskDialog cannot be used on Windows XP, on Linux/Mono, or when visual styles are not enabled.

But you might want to choose the KGy SOFT version even when running on Windows Vista or later with visual styles enabled, because it offers additional features like custom images on the buttons and command links. If you set ForceCompatibilityMode to , then always the alternative implementation is used, allowing some small improvements to the native version such as tool tips for regular buttons and radio buttons, more detailed info when copying the content to the clipboard by Ctrl+C, fixing possible color issues in high contrast mode, etc.

Examples

In the simplest case the TaskDialog can offer something similar to a MessageBox. In addition to predefined standard buttons you can add buttons with custom texts, too:

C#
using System.Diagnostics;
using System.Windows.Forms;
using KGySoft.WinForms.Components;

// These aliases are needed if you target .NET 5.0+
using TaskDialog = KGySoft.WinForms.Components.TaskDialog;
using TaskDialogButton = KGySoft.WinForms.Components.TaskDialogButton; // if you use custom buttons
using TaskDialogRadioButton = KGySoft.WinForms.Components.TaskDialogRadioButton; // if you use radio buttons

void ShowSimpleTaskDialog(IWin32Window? owner = null)
{
    using var taskDialog = new TaskDialog
    {
        Caption = "Simple Dialog",
        Message = "Hello TaskDialog",
        StandardButtons = TaskDialogStandardButtons.OK | TaskDialogStandardButtons.Cancel,
        Buttons = { new TaskDialogButton("Custom Button 1"), new TaskDialogButton("Custom Button 2") },
    };

    taskDialog.Show(owner);

    // The selected standard button. Cancel, if you closed the dialog, or Custom if you pressed a custom button.
    Debug.WriteLine($"Dialog Result: {taskDialog.DialogResult}");

    // The selected custom button index. -1, if you closed the dialog or pressed a standard button.
    Debug.WriteLine($"Selected Custom Button: {taskDialog.SelectedButtonIndex}");
}

Application.EnableVisualStyles(); // tip: comment this out to see how it works without visual styles
Application.SetCompatibleTextRenderingDefault(false);
ShowSimpleTaskDialog();

The example above appears like this:

A simple TaskDialog

A task dialog can also offer choices by radio buttons, show a verification text on a checkbox, and the custom buttons can be displayed as command links:

C#
// the updated body of the ShowSimpleTaskDialog method above:
using var taskDialog = new TaskDialog
{
    Caption = "Simple Dialog",
    Message = "Hello TaskDialog",
    StandardButtons = TaskDialogStandardButtons.OK | TaskDialogStandardButtons.Cancel,
    Buttons = { new TaskDialogButton("Custom Button 1"), new TaskDialogButton("Custom Button 2") },

    // update:
    RadioButtons = { new TaskDialogRadioButton("Option 1"), new TaskDialogRadioButton("Option 2") },
    CheckBoxText = "This is a checkbox",
    Options = TaskDialogOptions.UseCommandLinks // affects the appearance of Buttons
};

taskDialog.Show(owner);

Debug.WriteLine($"Dialog Result: {taskDialog.DialogResult}");
Debug.WriteLine($"Selected Custom Button: {taskDialog.SelectedButtonIndex}");
Debug.WriteLine($"Selected Radio Button: {taskDialog.SelectedRadioButtonIndex}");
Debug.WriteLine($"Checkbox is checked: {taskDialog.CheckBoxChecked}");

// Alternative way to get every result in a single line:
TaskDialogResult standardButton = taskDialog.Show(owner, out int customButton, out int radioButton, out bool isChecked);

The updated example is starting to look like a typical task dialog:

A simple TaskDialog with options

And there are quite a few more text elements you can set, as well as a couple of icons. Update the previous example as follows:

C#
// updated initialization:
using var taskDialog = new TaskDialog
{
    Caption = "Simple Dialog",
    Message = "Hello TaskDialog",
    StandardButtons = TaskDialogStandardButtons.OK | TaskDialogStandardButtons.Cancel,
    Buttons = { new TaskDialogButton("Custom Button 1"), new TaskDialogButton("Custom Button 2") },
    RadioButtons = { new TaskDialogRadioButton("Option 1"), new TaskDialogRadioButton("Option 2") },
    CheckBoxText = "This is a checkbox",
    // Options = TaskDialogOptions.UseCommandLinks,

    // update:
    Options = TaskDialogOptions.UseCommandLinks | TaskDialogOptions.DetailsExpanded,
    MainInstruction = "Some highlighted title",
    DetailsText = "An optionally long details text that can be concealed",
    ShowDetailsText = "Show details",
    HideDetailsText = "Hide details",
    FooterText = "Even more text in the footer",
    Icon = TaskDialogStandardIcon.Information,
    FooterIcon = TaskDialogStandardIcon.SecurityShield,
};
taskDialog.Buttons[0].Description = "Oh, and here I can place even more text";

Our not-so-simple-anymore dialog now looks like this:

A TaskDialog with all possible texts and icons

Though it contains a lot of elements, the latest example above is still a simple dialog in terms of the quite static content (not considering the collapsible details text), meaning that the dialog closes as soon as one of the buttons is pressed. Actually you subscribe the Click event of the custom buttons, which prevents the dialog from closing by default (unless you set the Handled property to ), which allows you to dynamically change almost everything while dialog is open, including all texts, the Enabled state of the custom buttons and radio buttons, and even the Options property. Additionally, the task dialog supports displaying a progress bar and using a timer, which enables a sort of further dynamic actions, as illustrated in the following image:

A dynamic TaskDialog with progress bar options in the KGySoft.WinForms.Example application

  Tip

The image above is from the example application, which contains numerous dynamic task dialog examples. At the Releases page of the project repository you can download it as executable binaries as well.

See also the Examples section of the ForceCompatibilityMode property for more image examples.

Constructors

TaskDialog Creates a new instance of TaskDialog class.

Properties

Buttons Gets a TaskDialogControlCollectionT containing TaskDialogButton elements, representing the custom buttons of this TaskDialog.
Caption Gets or sets the caption of the task dialog. If caption is , the filename of the executable program is displayed.
CheckBoxChecked Gets or sets whether the verification check box is checked. This property is ignored when CheckBoxText is empty.
Default value: .
CheckBoxText Gets or sets the text of the verification checkbox of the TaskDialog. The checkbox will be visible when this property is not empty when the dialog is shown.
CustomFooterIcon Gets or sets a custom Icon as the footer icon for this TaskDialog. Setting this property clears FooterIcon and vice versa.
CustomIcon Gets or sets a custom Icon as the main icon for this TaskDialog. Setting this property clears Icon and vice versa.
DefaultStandardButton Gets or sets the default standard button. When Buttons are not empty and one of them is specified as default button by IsDefault, then this property is ignored. If neither standard nor custom buttons are specified as default, the first button will be the default one.
DetailsText Gets or sets the details text. The expando button with ShowDetailsText or HideDetailsText will be visible only when this property is not empty.
DialogResult

When read, gets the last result of a closed TaskDialog (if the dialog was closed by one of the StandardButtons).

When set and there is an opened TaskDialog, forces to close the dialog with the specified result.

FooterIcon Gets or sets one of the standard icons as the footer icon for this TaskDialog. Setting this property clears CustomFooterIcon and vice versa.
Default value: None.
FooterText Gets or sets the footer text.
ForceCompatibilityMode Gets or sets whether the TaskDialog is to be forced to operate in compatibility mode even if the current operating system supports native task dialogs.

See the online help for image examples.
Handle Gets the native Win32 handle of the dialog.
HideDetailsText Gets or sets the text of the expando button in expanded state. The expando button is visible only when DetailsText is not empty.
Icon Gets or sets one of the standard icons as the main icon for this TaskDialog. Setting this property clears CustomIcon and vice versa.
Default value: None.
IsInCompatibilityMode Gets whether the TaskDialog is displayed in compatibility mode. When the dialog is not displayed, returns .
MainInstruction Gets or sets the main instruction text.
Message Gets or sets the message text.
Options Gets or sets the options of the TaskDialog.
ProgressBarMarqueeAnimationSpeed Gets or sets the current animation speed value of the progress bar. This property is used only when ProgressBarStyle is Marquee. Zero value stops the animation.
Default value: 20.
ProgressBarMaximum Gets or sets the maximum value of the progress bar. This property is used only when ProgressBarStyle is Regular.
Default value: 100.
ProgressBarMinimum Gets or sets the minimum value of the progress bar. This property is used only when ProgressBarStyle is Regular.
Default value: 0.
ProgressBarState Gets or sets the state of the progress bar.
Default value: Normal.
ProgressBarStyle Gets or sets the style of the progress bar.
Default value: None.
ProgressBarValue Gets or sets the current value of the progress bar. This property is used only when ProgressBarStyle is Regular.
Default value: 0.
RadioButtons Gets a TaskDialogControlCollectionT containing TaskDialogRadioButton elements, representing the radio buttons of this TaskDialog.
SelectedButtonIndex After the dialog is closed, gets the index of the clicked custom button defined in the Buttons collection that closed the TaskDialog. If the TaskDialog has been closed either programmatically or by a standard button, or is not closed yet, this property returns -1.
SelectedRadioButtonIndex After the dialog is closed, gets the index of the selected radio button defined in the RadioButtons collection. If no radio button was selected, this property returns -1.
ShowDetailsText Gets or sets the text of the expando button is collapsed state. The expando button is visible only when DetailsText is not empty.
StandardButtons Gets or sets the standard buttons of this TaskDialog. If neither standard nor custom buttons (see Buttons) are specified, the task dialog will have an OK button by default.
Width Gets or sets the width of the TaskDialog in dialog units (1 DLU is about 2 pixels, but may vary based on the default dialog font). The dialog is always at least 100 DLU wide. Zero value means that size is auto-calculated. Re-assigning zero value adjusts the automatic width of the dialog on demand.
Default value: 0.

Methods

Close Forces to close the TaskDialog. This causes that DialogResult will be Close even if there was no Close button on the dialog.
DisposePerforms application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
FinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.
(Overrides ObjectFinalize)
Show Shows the TaskDialog as a non-modal window, using the current configuration.
Show(IntPtr) Shows the TaskDialog using the current configuration.
Show(IWin32Window) Shows the TaskDialog using the current configuration.
Show(IntPtr, Int32, Int32, Boolean) Shows the TaskDialog using the current configuration.
Show(IWin32Window, Int32, Int32, Boolean) Shows the TaskDialog using the current configuration.

Events

CheckBoxCheckedChanged Occurs when the CheckBoxChecked property changes.
Closed Occurs when the TaskDialog has been closed.
Closing Occurs when the TaskDialog about to be closed.
Created Occurs when the TaskDialog has been created and is about to be displayed.
DetailsVisibleChanged Occurs when the visibility of the details text (the state of the expando button) changes.
HelpRequested Occurs when the user presses F1 on the TaskDialog.
HyperlinkClicked Occurs when HyperlinksEnabled is set in Options, and the user clicks a hyperlink. If this event is not subscribed or Handled is set to in HyperlinkClickedEventArgs, then the system tries to resolve the hyperlink.
Tick Occurs in approximately every 200 milliseconds. Can be used to update progress information.

See Also