Visual C++ Team Blog

CTaskDialog: an alternative to the simple message box!

Hello everybody,

Let me introduce myself, my name is Lukasz Chodorski and I am a new SDE in the Visual C++ Libraries Team. In this post I would like to present to you the CTaskDialog class which wraps the Windows API* in the MFC library. What actually is the CTaskDialog? It is a class/component which can be easily customized depending on your application’s needs. You can set following elements on the CTaskDialog:

·         Window title

·         Main icon

·         Main instruction

·         Content

·         Progress bar

·         Radio buttons

·         Custom button

·         Expand/collapse button

·         Verification check box

·         Footer icon

·         Footer text

·         Common button

So, as you can see there are many configuration options which can be set. In the simplest configuration, it looks like a standard message box, but in more advanced forms it can have progress bars, custom buttons or radio buttons. It is even possible to define a http link in the control’s text or create a simple wizard. Also, the MFC implementation provides a simple mechanism that allows the developer to handle dialog events.

The CTaskDialog API delivers simple methods to create and initialise controls. For instance:

CTaskDialog dlg(_T("A CTaskDialog presents information in a clear and consistent way."),

                     _T("How much do you like CTaskDialog?"), _T("Sample CTaskDialog"), 0,

                     TDF_ENABLE_HYPERLINKS | TDF_USE_COMMAND_LINKS , _T("I hope you like it!"));

       dlg.AddCommandControl( 10, _T("&Use it!\nIt's the best dialog you can have!"));

       dlg.AddCommandControl( 20, _T("&Maybe?\nDon't you want to try it?"));

       dlg.AddCommandControl( 25, _T("&No way!\nI'm not going to use it!"));

       dlg.AddRadioButton( 3, _T("Lots"));

       dlg.AddRadioButton( 7, _T("A little"));

       dlg.AddRadioButton( 4, _T("Not at all"));

    dlg.SetMainIcon(TD_SHIELD_ICON);

       dlg.SetFooterIcon(TD_INFORMATION_ICON);

       INT_PTR nResult = dlg.DoModal();

It creates the following window:

Or the one line function call:

INT_PTR nResult = CTaskDialog::ShowDialog(

                     _T("Don't spend to much time on code, write only one line and get your CTaskDialog!"),

                     _T("Where do you like to go?"),

                     _T("One line command"), IDS_RADIO_START, IDS_RADIO_START + 3, TDCBF_CANCEL_BUTTON);

This feature was introduced in Windows Vista, thus it is required for the _WIN32_WINNT define to be set to 0x0600 (value for Windows Vista) or higher. Anyway, it is set per default to Windows Vista in targetver.h file. You should be aware that Windows provides two comctl32.dll libraries (version 5.x.x.x and 6.x.x.x). The CTaskDialog requires version 6.x.x.x or higher, that is why the VC10 adds the required information to the application manifest file. When you get the error message: “The ordinal XXX could not be located in the dynamic link library COMCTL32.dll.” it means that your operating system used the incorrect library version for the application. This can be caused by the wrong assemblies’ configuration in manifest file – external or internal one. To force Windows to use the appropriate version of library it is necessary to add the following snippet into the manifest file.

<dependency>

    <dependentAssembly>

      <assemblyIdentity

          type="win32"

          name="Microsoft.Windows.Common-Controls"

          version="6.0.0.0"

          processorArchitecture="x86"

          publicKeyToken="6595b64144ccf1df"

          language="*"

        />

    </dependentAssembly>

  </dependency>

Operating systems below Windows Vista does not support the TaskDialog API. To check the availability of CTaskDialog it is possible to use the CTaskDialog::IsSupported() method. The simple workaround for this problem would be:

if (CTaskDialog::IsSupported()) 

{

       ... //call CTaskDialog

}

else MessageBox();  //call standard message box

The described feature is a part of the Microsoft Pre-release Software Visual Studio 2010 and .NET Framework 4.0 Community Technology Preview (CTP) which can be downloaded from http://www.microsoft.com/downloads/details.aspx?FamilyId=922B4655-93D0-4476-BDA4-94CF5F8D4814 . The sample application, which uses CTaskDialog, is provided with Visual Studio 2010 and is placed in the Samples directory.

I hope that I’ve encouraged you to use CTaskDialog. Feedback is always appreciated J.

Thx!

Lukasz

--

* More information about it you can be found on MSDN page (http://msdn.microsoft.com/en-us/library/bb760441(VS.85).aspx ).