TaskDialog for WinForms

KevinGre, 5 Jan 2007

Using Vista Task Dialog from WinForms - here is some code to do it.

Introduction

Vista's new TaskDialog API’s are really cool and should see lame message boxes banished from you application. We've already seen some articles on using them from C++ but they are not trivial to use from managed code, so here is some code that makes using all the features of the new Task Dialogs really easy in WinForms.

The code is C# and is StyleCop, FXCop and PreSharp clean. Usability and discoverability were given preference to performance and size, with plenty of comments that should be really useful in Intellisense as you explore what Task Dialogs can do. You don’t have to use anything with a shouted (all capitals) name and all the features of Task Dialog are exposed including the callback and actions you can perform on an active Task Dialog. If you hate the very idea of wrappers and want the raw interop declarations, they are all there too.

Using the code

The main class is TaskDialog. The simplest usage gets you MessageBox behavior:

TaskDialog taskDialog = new TaskDialog();
taskDialog.WindowTitle = "My Application";
taskDialog.MainInstruction = "Do you want to do this?";
taskDialog.CommonButtons = TaskDialogCommonButtons.Yes | TaskDialogCommonButtons.No;
int result = taskDialog.Show();
if (result == (int)DialogResult.Yes)
{
    // Do it.
}

TaskDialog with Yes No buttons

From there you can add hyperlinks for help, more structure (adding content, extended info and footer to main instruction), a checkbox for "don’t ask me again", custom button names, etc.:

private void SampleUsageComplex()
{
    TaskDialog taskDialog = new TaskDialog();
    taskDialog.WindowTitle = "My Application";
    taskDialog.MainInstruction = "Do you want to do this?";

    taskDialog.EnableHyperlinks = true;
    taskDialog.Content = "If you do this there could be all sorts of consequences. " +
        "If you don't there will be other consequences. " +
        "You can <A HREF=\"Learn\">learn more about those consequences </A> or more " +
        "about <A HREF=\"blah\">blah blah blah</A>.";
    taskDialog.Callback = new TaskDialogCallback(this.MyTaskDialogCallback);

    taskDialog.VerificationText = "Don't ask me this ever again.";
    taskDialog.VerificationFlagChecked = false;

    TaskDialogButton doItButton = new TaskDialogButton();
    doItButton.ButtonId = 101;
    doItButton.ButtonText = "Do It";

    TaskDialogButton dontDoItButton = new TaskDialogButton();
    dontDoItButton.ButtonId = 102;
    dontDoItButton.ButtonText = "Don't Do It";

    taskDialog.Buttons = new TaskDialogButton[] { doItButton, dontDoItButton };

    bool dontShowAgain;
    int result = taskDialog.Show(null, out dontShowAgain);
    if (dontShowAgain)
    {
        // Suppress future asks.
    }
    if (result == doItButton.ButtonId)
    {
        // Do it.
    }
}

private bool MyTaskDialogCallback(
    ActiveTaskDialog taskDialog,
    TaskDialogNotificationArgs args,
    object callbackData)
{
    if (args.Notification == TaskDialogNotification.HyperlinkClicked)
    {
        if (args.Hyperlink.Equals("Learn", StringComparison.Ordinal))
        {
            // Show a help topic.
        }
        else if (args.Hyperlink.Equals("blah", StringComparison.Ordinal))
        {
            // Show a different help topic.
        }
    }
    return false;
}

TaskDialog with hyperlink and verify checkbox

To get a better idea of all the things you can do with a TaskDialog download the demo, extract the TaskDialogTest.exe and TaskDialog.dll to the same directory and run TaskDialogTest.exe. You'll get a rather large dialog which, while not beautiful, will let you try out the TaskDialog and perhaps sample what different uses in your application would look like.

TaskDialog with hyperlink and verify checkbox

To make use of TaskDialog in your own solution, download the source and include the following source files in your project and adapt them as you see fit:

ActiveTaskDialog.cs
TaskDialog.cs
TaskDialogNotificationArgs.cs
UnsafeNativeMethods.cs

Alternatively you could include the TaskDialog project into you solution.

I look forward to seeing a lot fewer Message Boxes in you applications and I hope this makes it easier. Keep in mind good UI design when you're tempted to use all those features in the one dialog.

License

This article, along with any associated source code and files, is licensed under A Public Domain dedication

About the Author

KevinGre

	Software Developer
	United States

No Biography provided

You may also be interested in...

Comments and Discussions

Custom Icon not working

marjaan17-Apr-18 21:03

marjaan

17-Apr-18 21:03

Hi there!
First things first... Bravo, Great Work!! Thumbs Up | :thumbsup:

My concerns are as follows:
1. I came here only in the search of being able to show a customized icon in the message box, e.g. green tick icon for success reporting. But i got everything in TaskDialog except Custom Icon, because when i specify custom icon, it raises error that the specified file is not a valid picture, while the specified file is a perfect .jpg or .png icon opening successfully in any imaging tool.

You haven't included any means of specifying custom icon in your test app as well... you only take pre-defined icons through radio buttons, both for main and footer icons.

2. You have also not included the Question icon in the pre-provided icons, as in standard MessageBox. Kindly include that and, if possible, Success icon as well. Sometimes Information icon doesn't seem appropriate for that purpose.

3. If possible, release a newer version valid for VS2015, (64bit OS) for the ease of future users, because every user of your code has to do those amendments for a working version but after much digging...

Thanks a lot for making life bit easier for others!

~Marjaan~

Unsafe code is not needed

Dialecticus25-Nov-16 3:11

Dialecticus

25-Nov-16 3:11

There are four places in TaskDialog.cs where the code is unsafe (using unsafe keyword). There is no reason for unsafe keyword in none of those places. IntPtr is converted to byte*, and then back to IntPtr with some arithmetic. But this arithmetic works with IntPtr too. Remove the conversions and use the original IntPtr values, and everything still works without unsafe keyword:

Marshal.StructureToPtr(customButtons[i], config.pButtons + (elementSize * i), false);

BugFix: EnableButton() and EnableRadioButton() on ActiveTaskDialog

Alex Essilfie19-Nov-15 18:13

Alex Essilfie

19-Nov-15 18:13

As was noted by Andrew Cushen[^], the behaviour of the ActiveTaskDialog.EnableButton() and the ActiveTaskDialog.EnableRadioButton() methods are reversed. Calling either of these methods with true disables the specified button/radio button and calling the method with false enables it.
Also, contrary to @andrewcushen's observation, referencing the code from C# or VB.NET yields the same behaviour irrespective of the version of the .NET framework it is compiled against.

In order to resolve this, modify the affected methods in ActiveTaskDialog.cs to check for the reverse of the specified enable value as follows:

public class ActiveTaskDialog : IWin32Window
{
    .
    .
    .

    public void EnableButton(int buttonId, bool enable)
    {
        // TDM_ENABLE_BUTTON = WM_USER+111, 
        // lParam = 0 (disable), lParam != 0 (enable), wParam = Button ID
        UnsafeNativeMethods.SendMessage(
            this.handle,
            (uint)UnsafeNativeMethods.TASKDIALOG_MESSAGES.TDM_ENABLE_BUTTON,
            (IntPtr)buttonId,
            (IntPtr)(!enable ? 0 : 1 ));  // <<== Modified line
    }

    .
    .
    .

    public void EnableRadioButton(int buttonId, bool enable)
    {
        // TDM_ENABLE_RADIO_BUTTON = WM_USER+112, 
        // lParam = 0 (disable), lParam != 0 (enable), wParam = Radio Button ID
        UnsafeNativeMethods.SendMessage(
            this.handle,
            (uint)UnsafeNativeMethods.TASKDIALOG_MESSAGES.TDM_ENABLE_RADIO_BUTTON,
            (IntPtr)buttonId,
            (IntPtr)(!enable ? 0 : 1));  // <<== Modified line
    }

    .
    .
    .
}

NOTE:
I cannot not guarantee that it will fix the bug on all systems since I have not tested it on any other computer besides mine. Kindly post replies to this message if this bug is detected on other system configurations as well as if this proposed solution is able to fix the bug.

System Configuration:
Windows 8.1 64-bit
Visual Studio 2013 Community Edition

modified 20-Nov-15 8:05am.

Doesn't work, error message

Axel Steiner13-Aug-15 2:21

Axel Steiner

13-Aug-15 2:21

The demo and if I execute the "Show task dialog" from VS I get an error.
Tested with current OS Windows 10/VS 2015 Community.

<pre>See the end of this message for details on invoking <br />
just-in-time (JIT) debugging instead of this dialog box.<br />
<br />
************** Exception Text **************<br />
System.ArgumentException: Value does not fall within the expected range.<br />
   at Microsoft.Samples.UnsafeNativeMethods.TaskDialogIndirect(TASKDIALOGCONFIG& pTaskConfig, Int32& pnButton, Int32& pnRadioButton, Boolean& pfVerificationFlagChecked)<br />
   at Microsoft.Samples.TaskDialog.PrivateShow(IntPtr hwndOwner, Boolean& verificationFlagChecked, Int32& radioButtonResult)<br />
   at Microsoft.Samples.TaskDialog.Show(IWin32Window owner, Boolean& verificationFlagChecked, Int32& radioButtonResult)<br />
   at FormPlay.Form1.TaskDialogButton_Click(Object sender, EventArgs e)<br />
   at System.Windows.Forms.Control.OnClick(EventArgs e)<br />
   at System.Windows.Forms.Button.OnMouseUp(MouseEventArgs mevent)<br />
   at System.Windows.Forms.Control.WmMouseUp(Message& m, MouseButtons button, Int32 clicks)<br />
   at System.Windows.Forms.Control.WndProc(Message& m)<br />
   at System.Windows.Forms.ButtonBase.WndProc(Message& m)<br />
   at System.Windows.Forms.Button.WndProc(Message& m)<br />
   at System.Windows.Forms.Control.ControlNativeWindow.WndProc(Message& m)<br />
   at System.Windows.Forms.NativeWindow.Callback(IntPtr hWnd, Int32 msg, IntPtr wparam, IntPtr lparam)<br />
<br />
<br />
************** Loaded Assemblies **************<br />
mscorlib<br />
    Assembly Version: 2.0.0.0<br />
    Win32 Version: 2.0.50727.8662 (QFE.050727-8600)<br />
    CodeBase: file:///C:/Windows/Microsoft.NET/Framework64/v2.0.50727/mscorlib.dll<br />
----------------------------------------<br />
TaskDialogTest<br />
    Assembly Version: 1.0.0.0<br />
    Win32 Version: 1.0.0.0<br />
    CodeBase: file:///C:/TaskDialogForWinForms_demo/TaskDialogTest.exe<br />
----------------------------------------<br />
System.Windows.Forms<br />
    Assembly Version: 2.0.0.0<br />
    Win32 Version: 2.0.50727.8662 (QFE.050727-8600)<br />
    CodeBase: file:///C:/Windows/assembly/GAC_MSIL/System.Windows.Forms/2.0.0.0__b77a5c561934e089/System.Windows.Forms.dll<br />
----------------------------------------<br />
System<br />
    Assembly Version: 2.0.0.0<br />
    Win32 Version: 2.0.50727.8662 (QFE.050727-8600)<br />
    CodeBase: file:///C:/Windows/assembly/GAC_MSIL/System/2.0.0.0__b77a5c561934e089/System.dll<br />
----------------------------------------<br />
System.Drawing<br />
    Assembly Version: 2.0.0.0<br />
    Win32 Version: 2.0.50727.8662 (QFE.050727-8600)<br />
    CodeBase: file:///C:/Windows/assembly/GAC_MSIL/System.Drawing/2.0.0.0__b03f5f7f11d50a3a/System.Drawing.dll<br />
----------------------------------------<br />
TaskDialog<br />
    Assembly Version: 1.0.0.0<br />
    Win32 Version: 1.0.0.0<br />
    CodeBase: file:///C:/TaskDialogForWinForms_demo/TaskDialog.DLL<br />
----------------------------------------<br />
<br />
************** JIT Debugging **************<br />
To enable just-in-time (JIT) debugging, the .config file for this<br />
application or computer (machine.config) must have the<br />
jitDebugging value set in the system.windows.forms section.<br />
The application must also be compiled with debugging<br />
enabled.<br />
<br />
For example:<br />
<br />
<configuration><br />
    <system.windows.forms jitDebugging="true" /><br />
</configuration><br />
<br />
When JIT debugging is enabled, any unhandled exception<br />
will be sent to the JIT debugger registered on the computer<br />
rather than be handled by this dialog box.<br />
<br />
</pre>

modified 13-Aug-15 8:01am.

Re: Doesn't work, error message

Alex Essilfie19-Nov-15 15:01

Alex Essilfie

19-Nov-15 15:01

I believe this error arises due to the way the data structures are stored in memory on 64-bit operating systems.

You'll have to edit a couple of files as stated by the author here[^].

In UnsafeNativeMethods.cs change line 309 to be:

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode, Pack = 1)]
internal struct TASKDIALOGCONFIG

In TaskDialog.cs change line 212 to be:

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode, Pack = 1)]
public struct TaskDialogButton

What I fail to understand is why the author has not integrated this into the code over 5 years down the line though. Sigh | :sigh:

Re: Doesn't work, error message

Balázs Lengyel2-Nov-17 6:55

Balázs Lengyel

2-Nov-17 6:55

Doesnt work so for me.
Error: Mad | :mad:

Quote:
Severity Code Description Project File Line Suppression State
Error CS0103 The name '__b__' does not exist in the current context TaskDialog G:\_Balu\Visual Basic 2010-2015\Projects\TaskDialogForWinForms_src\TaskDialog\TaskDialog.cs 212 Active

Still System.ArgumentException!

Knorx Thieus11-Aug-15 2:29

Knorx Thieus

11-Aug-15 2:29

Anywhen I click on Show TaskDialog, I get this ArgumentException! Frown | :(

(Using Win 8 x64)
Could you please fix it so I can try?

Vote of 5

Fatman13CC15-Jun-12 12:51

Fatman13CC

15-Jun-12 12:51

Great article!!! Thumbs Up | :thumbsup:

My vote of 5

eaviles30-Mar-12 9:06

eaviles

30-Mar-12 9:06

Very helpful!

Font Changing... And A Question

Saeed Masoomi7-Dec-11 11:39

Saeed Masoomi

7-Dec-11 11:39

Hi,
I Want Change This Great TaskDialogs Fonts And Use For Example Tahoma,
Can Anyone Help Me?

And a question that is this work in windows XP?

tnx

Re: Font Changing... And A Question

marjaan4-Jun-18 21:21

marjaan

4-Jun-18 21:21

I too want the option to change the font name & size for different elements of text (e.g. Title, Main Instruction etc.) in TaskDialog to make them in accordance to my application but it seems there is no such option... A huge flaw, because Message dialogs appear totally different from whole application.

~Marjaan~

License

user303425-Feb-11 1:31

user3034

25-Feb-11 1:31

Excellent article this one !!

I am planning to use this source code in one of my commercial application for my company. Can I use it ? Do I need to mention your name or anything like that ?

I went through The Public Domain dedication. But it's quite confusing.

Please let me know what all should I do in order to use this source code.

Thanks and really appreciate your article.

Citrix and expanded info

esteka17-Jul-09 1:57

esteka

17-Jul-09 1:57

First of all, thanks for this great work!

But I have got one problem with it:
The dialog does not seem to appear on Citrix systems when it contains expanded info.

Anyone who has got the same problem? What can I do?

Thanks!

How change the MainInstruction text

melnac9-Jan-09 12:57

melnac

9-Jan-09 12:57

Hi,
how can change the MainInstruction text from within the CallBack function ?

I call the taskDialog.UpdateMainInstruction method as i use the taskDialog.SetProgressBarPosition to change the position value for the progress bar.

I saw that in the EmulateTaskDialog class i need to extend the WndProc to catch the message, but the MainInstruction remains always the same.

Can you help ?
Can you explain how to use the Callback function ?

Thanks in advance,
Giuseppe.

Issue in parameter to EnableButton() and EnableRadioButton() when calling from VB.NET

AndrewCushen18-Dec-08 17:58

AndrewCushen

18-Dec-08 17:58

This is great work, and is much appreciated; I started to do this myself in VB.NET, but ran out of time and kept hitting walls with the unsafe code.

You may, however, wish to document that there's a minor issue in the EnableButton() and EnableRadioButton() functions in ActiveTaskDialog.CS, when you call the code from VB.NET:

The True/False test appears to be reversed when calling these two functions from VB.NET, so that when you pass in the button id and False, the button is enabled. This is contrary to your documentation, which states that passing in False should disable the button, and is also contrary to the behavior when calling your code from C#, where it exhibits the proper behavior.

I can only guess that this has to do with the differing way in which the C-based languages treat 0/1 as true/false.

With that in mind, there are two approaches a VB.NET user can take to work around the issue.

The first, and simplest, is to just remember to reverse True/False when calling the 2 functions from VB.NET.

The second is to actually change the code in the C# source to match the documentation. This approach is probably preferable for the VB.NET programmer if and only if they are 100% certain the code will never be called from C#.

For those who choose the second option, the following line in both functions:
(IntPtr)(enable ? 0 : 1 ));

should be changed to read:
(IntPtr)(enable ? 1 : 0 ));

It is extremely important that the user document whichever approach they choose; the "enable" parameter in the XML comment above the function in the source code file should be changed to indicate either that VB.NET users should reverse the Boolean logic, or that C# users should.

-AndrewC

Shield Icon on CommandButton

BYoung@OSIsoft.com13-Mar-08 14:04

BYoung@OSIsoft.com

13-Mar-08 14:04

I'm using the TaskDialog for asking the user of my app if they want to restart the application to do the requested task because it requires elevated access, similiar to how VS 2008 asks when you try to do something that requires elevated access.

For the CommandButton that is for saying "Yes, elevate me", I would like to show the shield icon instead of just the standard green arrow. But I've yet to figure out how. I'm pretty sure it's possible because VS2008 does this, but who knows what VS is doing underneath the hood.

Have you tried to do this?

Licensing Question

Thorsten Dittmar15-Nov-07 2:52

Thorsten Dittmar

15-Nov-07 2:52

Hi,

I'd like to use Vista TaskDialog Wrapper and Emulator (by Hedley Muscroft) in commercial applications and asked him for permission to use his code.

While he allowed me to use his code, he also pointed out that his code uses part of your code and suggested that I should double check with you for licensing questions.

So: Is there a special license agreement I have to obey when using your code or am I allowed to use and/or modify your code as I need in both free and commercial applications?

Thanks for information,
Thorsten

Wrapper and Emulator for pre-Vista

Hedley Muscroft12-Nov-07 12:49

Hedley Muscroft

12-Nov-07 12:49

Hi Kevin,

Just to let you know, I recently posted an article which builds on your superb project by including an 'emulator' so that the TaskDialog can be used pre-Vista too. I've given you full credit for this excellent article though, and included links to it from my article. I hope that's ok.

Thanks again.

http://www.codeproject.com/useritems/Vista_TaskDialog_Wrapper.asp

Hedley Muscroft

How to change the Button-Text

Rekire31-Oct-07 14:43

Rekire

31-Oct-07 14:43

Hi,
how can I change the text of a button in the callback function?
Maybe it is possible to work with the handle, but I've got no idea how to do it.

Re: How to change the Button-Text

KevinGre31-Oct-07 15:02

KevinGre

31-Oct-07 15:02

You can't. If you look at the MSDN documentation for TaskDialog (link below) you can see that TaskDialog does not support updating the text of buttons (which is often a poor experience for your users anyway). You might consider having two buttons and using enable and disable, or if you want complete control creating your own dialog. Remember, TaskDialog is designed to meet a lot of requirements and save you creating custom dialogs for most common tasks but it is not the answer to all needs. Technically you could use the window handle of the active TaskDialog to get the window handle of buttons and change their text but that would be pretty evil and probably technically unsupported which means it might break on future versions (adjust layout correctly etc).

http://msdn2.microsoft.com/en-us/library/bb762715.aspx[^]

error [modified]

pravin parmar27-Oct-07 5:35

pravin parmar

27-Oct-07 5:35

i m getting error like: "Unable to find an entry point named 'TaskDialogIndirect' in DLL 'ComCtl32'.".

application shows me this message: "Requires OS Version 6.0.5243 or later" near the "Show Task Dialog" button.

pls help.thanks.

-- modified at 10:46 Saturday 27th October, 2007

Pravin Parmar,
PravinParmar.ce@gmail.com

Thanks for the effort

rykk..15-Feb-07 18:42

rykk..

15-Feb-07 18:42

Very good - code was very helpful

.net 3.0 support for task dialogs, custom Windows XP SP2 support ?

Chris Richner9-Feb-07 1:59

Chris Richner

9-Feb-07 1:59

Hi,

I'm wondering why .net 3.0 framework has no managed way to use task dialogs. When does MS extend .net to provide managed support for vista platform features?

Anybody tought about an legacy implementation of ITaskDialog for task dialogs in .net 2.0 running on windows xp sp2. Maybe there could be something like a migration path for code running currently on xp using custom task dialog implementations today but will run with slightly changes on a future .net framework for vista system.

myMsg.BehindDaKeys = "Chris Richner";

Re: .net 3.0 support for task dialogs, custom Windows XP SP2 support ?

Jonas Nordlund2-Sep-07 23:42

Jonas Nordlund

2-Sep-07 23:42

Agreed; I would love to have a pretty and functional fallback using a custom form for Windows XP. I simply cannot use the new TaskDialog if the dialogs on the OS with the currently still major user base will have reduced functionality. A legacy implementation, using the "real" API under Vista, would be most welcome here, although I understand if there is some effort involved in achieving that...

Re: .net 3.0 support for task dialogs, custom Windows XP SP2 support ? [modified]

Chris Richner3-Sep-07 7:43

Chris Richner

3-Sep-07 7:43

Seems like we have to find someone to write that Wink | ;)