XTaskDialog v1.09 An emulated version of Vista's Task Dialog APIs

Welcome to XTaskDialog, an emulation of the new Vista Task Dialog APIs for down level operating systems including Windows 98, Windows ME, Windows 2000, Windows XP and Windows 2003. Task Dialogs are designed as the replacement for the venerable MessageBox API call. Some of you may know that I have extended the MessageBox API for MFC clients thro the use of my CMessageBoxX class. You can do quite a few things with the message box API but MS have decided in their wisdom to deprecate the API in preference to the much more extensible Task Dialog API. For a good intro on the usage of Task Dialogs check out Michael Dunn's article at http://www.codeproject.com/vista/VGTaskDialog2.asp. There is also a good article also on CodeProject about developing an emulated version of the API at http://www.codeproject.com/useritems/taskdialogs.asp. XTaskDialog is my own independently developing emulation version of the Task Dialog API. Note that some of the XTaskDialog code which creates the in memory dialog template is based in part on the XMessageBox class by Hans Dietrich at http://www.codeproject.com/dialog/xmessagebox.asp . You should check this article out as a good primer on how you go about creating in memory dialog templates.

Here's an example of what a Task Dialog looks like from the sample app included in the download assuming you want to see what pretty much all the features look like, when it is run on Windows XP with theming enabled:

Please bear in mind that "less is more" when it comes to UI design and a well written application should not try to use all of the features of a TaskDialog in every single dialog which your application puts up!

Here is a list of the Features / Limitations of the code currently:

• Supports most of the Vista native Task Dialog functionality. This includes: Main instruction text, content text standard command buttons, custom command buttons, radio buttons, Verification check box, expanded text (and associated dialog animations), customizing the expando button caption, standard task dialog message box sounds, footer text, main icon and footer icon customization including the Vista UAC shield icon, support for hyperlinks in text, a complete emulation of command link buttons (These are the 3 options in the centre of the screen capture above which include a larger caption and then a smaller more detailed description on them), a progress control, callback timer support and support for a minimized task dialog.
• Having described the main features of task dialogs and what XTaskDialog supports, here is a list of the current limitations of the XTaskDialog emulation of TaskDialogIndirect:
• TDM_SET_PROGRESS_BAR_STATE is only supported on Windows Vista, so in reality you will not be able to use "paused" or "error" progress bars on downlevel OS'es.
• TDM_SET_MARQUEE_PROGRESS_BAR / TDF_SHOW_MARQUEE_PROGRESS_BAR is only supported for apps which are linked with a Common Control v6 manifest and running on Windows XP or later.
• TDM_SET_BUTTON_ELEVATION_REQUIRED_STATE is only supported for command link buttons and not for the standard buttons on the task dialog.
• TDF_ENABLE_HYPERLINKS is only supported for apps which are linked with a Common Control v6 manifest and are running on Windows XP or later. If you try to create a task dialog if either of these conditions are not true, then the task dialog will fail to show because it could not create the required "SysLink" child windows. You have been warned!
• The metrics which XTaskDialog uses for calculating the dialog window width is definitely different that the native Vista implementation. The mechanism which XTaskDialog uses to calculate the width is quite complicated and for those interested (or for those who spot problems with it), this logic is implemented in CXTaskDialog::Layout.
• The expando button and its associated text is currently drawn using a standard button rather than the bitmap button the native Vista version seems to uses. This is something which I may work on improving in a future release.
• The emulated command link buttons do not emulate all the nice UI / animation features which the native Vista version implements. For example the emulation does not do as nice a job as Vista to show a "selected" command link button. That said the emulation is pretty good and unless you are a hard core UI developer who is used to examining every pixel<gg>, you will most likely not notice much difference.
• The native Vista implementation supports stacking of the standard buttons when horizontal space is limited. Currently XTaskDialog does not support this.
• The native Vista implementation aligns the check box and expando buttons vertically with the standard buttons. Currently XTaskDialog displays both of these controls below the button row.
• TDF_RTL_LAYOUT is currently not properly supported by XTaskDialog. If you think support for this would be useful, then I may implement this in a future release.
• TDM_NAVIGATE_PAGE is currently not supported by XTaskDialog. As a consequence, the TDN_NAVIGATED notification message will also never be sent. If you think support for page navigation would be useful, then I may implement this in a future release.
• Quite a few of the various colors and metrics used by XTaskDialog are hard coded. Examples include the colors used for the dialog backgrounds and divider colors, the various colors used by the emulated command link buttons and the color used for the main instruction text. I believe these will have to remain hard-coded because downlevel OS'es simply would not support the required system metrics to get these values even if I knew you could get these system metrics on Vista!.
• The icons shown on the emulated command link buttons are vertically centred. The native Vista implementation seems to use a fixed offset from the top.
• Because the code uses the _TrackMouseEvent function (used to implement the hot look for the emulated command links) and the MultiMon function "MonitorFromWindow", the code requires at least Windows 98 to operate correctly, that is it will not work for Windows 95.
• Finally with all the limitations mentioned above, you can consider all the other features of TaskDialogIndirect as fully emulated by XTaskDialog. For example, all the animation effects which the native TaskDialogIndirect API uses for handling the expando text are pretty faithfully emulated. If you think I have missed something compared to the native Vista implementation, then please drop me an email and I will see about including it in a future release.

The enclosed zip file contains the XTaskDialog source code and a simple MFC 8 test program to exercise the classes provided as well as a VC 6 MFC test program to exercise the MFC client class on this older compiler.

Copyright

• You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
• You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
• If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.

Updates

V1.0 (14 March 2007)

• Initial public release.

V1.01 (16 March 2007)

• Updated XTaskDialogDefines.h so that XTaskDialog can be used in VC 6 without the need for the Platform SDK header files to be integrated with VC 6. Thanks to Andre Buenger for reporting this issue.
• I've done some testing of the code on Windows 9x (specifically Windows ME). As well as the restrictions which I have already documented, XTaskDialog will fail to show if you use TD_WARNING_ICON, TD_ERROR_ICON or TD_INFORMATION_ICON for the main icon or the footer icon. The reason why this fails is that the XTaskDialog code expects these icons to reside in user32.dll, but on Windows 9x which is a mixture of 16/32 bit binaries, these icons do not exist. I could fix this issue by adding in my own versions of these icons, but to be honest this is too much effort for such old operating systems. Instead, If you specify your own icons for the main icon or the footer icon, then XTaskDialog will display correctly. Hopefully for those people still supporting Windows 9x apps out there, this will be another reason to use XTaskDialog to spruce up your application. Thanks to Andre Buenger for reporting this issue.

V1.02 (20 March 2007)

• Fixed a bug where the code unnecessarily set the progress bar range to 0-100 in CXTaskDialog::OnInitDialog. This was causing client calls to TDM_SET_PROGRESS_BAR_RANGE in TDN_CREATED notifications to effectively be ignored. Thanks to Demetrios A. Thomakos for reporting this issue.
• For completeness, the DLL version of XTaskDialog now also emulates the TaskDialog API call in addition to the existing TaskDialogIndirect API call. Thanks to Demetrios A. Thomakos for reporting this issue.
• XTaskDialog now ships with its own version of the error, warning and info icons in addition to the existing shield icon. This now allows XTaskDialog to work out of the box on Windows 98 and Windows ME in addition to 2000, XP and 2003 which were already supported. In addition the icons are a closer match for the Vista icons. For example the TD_INFORMATION_ICON icon is a I on a blue background.
• Fixed a typo and a minor code optimization in CXTaskDialogCommandLink::DrawItem.
• CXTaskDialogCommandLink now provides a WM_ERASEBKGND handler to optimize it drawing
• Minor code optimization in CXTaskDialog::CalculateCommandLinkMetrics.
• CXTaskDialog::LoadStringResource method has been renamed to LoadStringResources.
• Fixed a minor vertical layout issue for TDF_EXPAND_FOOTER_AREA footer text in CXTaskDialog::Layout

V1.03 (22 March 2007)

• TaskDialog function exported from XTaskDlg dll now uses the correct definition for the TaskDialog API as described at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/commctls/taskdialogs/taskdialogreference/taskdialogfunctions/taskdialog.asp. It seems that the description of the TaskDialog as provided with the latest Vista SDK (aka Windows SDK) is incorrect and forget to mention the pszContent parameter. Thanks to Demetrios A. Thomakos for reporting this issue.
• Removed an unused "m_bCancelButtonPresent" member variable from the CXTaskDialog class.
• Fixed bug where cancel button would always be ignored when clicked when you did not provide the TDF_ALLOW_DIALOG_CANCELLATION flag.

V1.04 (30 March 2007)

• Fixed a problem where the progress control was not created with the proper width if the end of the button row was to the left of the left of the control text. Thanks to Demetrios A. Thomakos for reporting this bug.
• Fixed a bug where the main instruction text could sometimes appear in a standard sized font instead of the expected larger size. Thanks to Demetrios A. Thomakos for reporting this bug.
• Fixed a bug where all static text controls could sometimes display clipped text. Thanks to Demetrios A. Thomakos for reporting this bug.

V1.05 (31 March 2007)

• Removed use of internal "VerificalTextSpacing" enum value.

V1.06 (5 April 2007)

• Fixed a bug where the code would not correctly set the initial selection state of the radio buttons in CXTaskDialog::OnInitDialog. Thanks to Demetrios A. Thomakos for reporting this bug.

V1.07 (12 October 2008)

• Updated copyright details
• The code has now been updated to support VC 2005 or later only.
• Updated code to compile correctly using _ATL_CSTRING_EXPLICIT_CONSTRUCTORS define
• Updated code to clean compile on VC 2008
• Code now compiles cleanly using Code Analysis (/analyze)

V1.08 (20 January 2009)

• Updated copyright details.
• Fixed the text reported in a number of ATLTRACE calls throughout the code
• Fixed a bug where the dialog would appear with a top horizontal white block, followed by a grey block, then a separator and then a final grey block even when no non command link buttons are displayed on the grey blocks. When this condition now occurs, the whole dialog is now shown in white. This is consistent with how the native TaskDialog API behaves on Vista. Thanks to Jacob Liebeck for reporting this bug.

V1.09 (28 June 2009)

• Updated the sample apps project settings to more modern default values.
• The supplied zip file now inclues a x64 Unicode DLL version of XTaskDialog built with VC 2008.
• Fixed a bug in calling SystemParametersInfo(SPI_GETNONCLIENTMETRICS,... ). The issue is that the NONCLIENTMETRICS structure can be bigger depending on the value of the WINVER preprocessor value. The code now ensures that the original base size of NONCLIENTMETRICS is used to ensure it works on down level operating systems. For more information on this issue, please see the MSDN documentation on the NONCLIENTMETRICS stucture. Also the second parameter to SystemParametersInfo in the code was incorrectly being set to 0, it is now set to the sizeof the structure. Thanks to Dick Smith for reporting this issue.
• Updated the code to be as independent as possible from the standard Windows preprocessor variables (WINVER, _WIN32_WINNT, _WIN32_WINDOWS & _WIN32_IE). Note the code still requires WINVER >= 0x500