Walkthrough: Adding a CTaskDialog to an Application

Članek
08/03/2021

This walkthrough introduces the CTaskDialog Class and shows you how to add one to your application.

The CTaskDialog is a task dialog box that replaces the Windows message box in Windows Vista or later. The CTaskDialog improves the original message box and adds functionality. The Windows message box is still supported in Visual Studio.

Note

Versions of Windows earlier than Windows Vista do not support the CTaskDialog. You must program an alternative dialog box option if you want to show a message to a user who runs your application on an earlier version of Windows. You can use the static method CTaskDialog::IsSupported to determine at run time whether a user's computer can display a CTaskDialog. In addition, the CTaskDialog is only available when your application is built with the Unicode library.

The CTaskDialog supports several optional elements to gather and display information. For example, a CTaskDialog can display command links, customized buttons, customized icons, and a footer. The CTaskDialog also has several methods that enable you to query the state of the task dialog box to determine what optional elements the user selected.

Prerequisites

You need the following components to complete this walkthrough:

Visual Studio 2010 or later
Windows Vista or later

Replacing a Windows Message Box with a CTaskDialog

The following procedure demonstrates the most basic use of the CTaskDialog, which is to replace the Windows message box. This example also changes the icon associated with the task dialog box. Changing the icon makes the CTaskDialog appear same to the Windows message box.

To Replace a Windows Message Box with a CTaskDialog

Use the MFC Application Wizard to create an MFC application with all the default settings. See Walkthrough: Using the New MFC Shell Controls for instructions on how to open the wizard for your version of Visual Studio.
Call it MyProject.
Use the Solution Explorer to open the file MyProject.cpp.
Add #include "afxtaskdialog.h" after the list of includes.
Find the method CMyProjectApp::InitInstance. Insert the following lines of code before the return TRUE; statement. This code creates the strings that we use in either the Windows message box or in the CTaskDialog.
```
CString message("My message to the user");
CString dialogTitle("My Task Dialog title");
CString emptyString;
```
Add the following code after the code from step 4. This code guarantees that the user's computer supports the CTaskDialog. If the dialog isn't supported, the application displays a Windows message box instead.
```
if (CTaskDialog::IsSupported())
{

}
else
{
    AfxMessageBox(message);
}
```
Insert the following code between the brackets after the if statement from step 5. This code creates the CTaskDialog.
```
CTaskDialog taskDialog(message, emptyString, dialogTitle, TDCBF_OK_BUTTON);
```
On the next line, add the following code. This code sets the warning icon.
```
taskDialog.SetMainIcon(TD_WARNING_ICON);
```
On the next line, add the following code. This code displays the task dialog box.
```
taskDialog.DoModal();
```

You can avoid step 7 if you don't want the CTaskDialog to display the same icon as the Windows message box. If you avoid that step, the CTaskDialog has no icon when the application displays it.

Compile and run the application. The application displays the task dialog box after it starts.

Adding Functionality to the CTaskDialog

The following procedure shows you how to add functionality to the CTaskDialog that you created in the previous procedure. The example code shows you how to execute specific instructions based on the user's selections.

To Add Functionality to the CTaskDialog

Navigate to the Resource View. If you can't see the Resource View, you can open it from the View menu.
Expand the Resource View until you can select the String Table folder. Expand it and double-click the String Table entry.
Scroll to the bottom of the string table and add a new entry. Change the ID to TEMP_LINE1. Set the caption to Command Line 1.
Add another new entry. Change the ID to TEMP_LINE2. Set the caption to Command Line 2.
Navigate back to MyProject.cpp.

After CString emptyString;, add the following code:

CString expandedLabel("Hide extra information");
CString collapsedLabel("Show extra information");
CString expansionInfo("This is the additional information to the user,\nextended over two lines.");

Find the taskDialog.DoModal() statement and replace that statement with the following code. This code updates the task dialog box and adds new controls:

taskDialog.SetMainInstruction(L"Warning");
taskDialog.SetCommonButtons(
    TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);
taskDialog.LoadCommandControls(TEMP_LINE1, TEMP_LINE2);
taskDialog.SetExpansionArea(
    expansionInfo, collapsedLabel, expandedLabel);
taskDialog.SetFooterText(L"This is a small footnote to the user");
taskDialog.SetVerificationCheckboxText(L"Remember your selection");

Add the following line of code that displays the task dialog box to the user and retrieves the user's selection:
```
INT_PTR result = taskDialog.DoModal();
```

Insert the following code after the call to taskDialog.DoModal(). This section of code processes the user's input:

if (taskDialog.GetVerificationCheckboxState())
{
    // PROCESS IF the user selects the verification checkbox
}

switch (result)
{
case TEMP_LINE1:
    // PROCESS IF the first command line
    break;
case TEMP_LINE2:
    // PROCESS IF the second command line
    break;
case IDYES:
    // PROCESS IF the user clicks yes
    break;
case IDNO:
    // PROCESS IF the user clicks no
    break;
case IDCANCEL:
    // PROCESS IF the user clicks cancel
    break;
default:
    // This case should not be hit because closing
    // the dialog box results in IDCANCEL
    break;
}

In the code in step 9, replace the comments that start with PROCESS IF with the code that you want to execute under the specified conditions.

Compile and run the application. The application displays the task dialog box that uses the new controls and additional information.

Displaying a CTaskDialog Without Creating a CTaskDialog Object

The following procedure shows you how to display a CTaskDialog without first creating a CTaskDialog object. This example continues the previous procedures.

To Display a CTaskDialog Without Creating a CTaskDialog Object

Open the MyProject.cpp file if it isn't already open.
Navigate to the closing bracket for the if (CTaskDialog::IsSupported()) statement.

Insert the following code immediately before the closing bracket of the if statement (before the else block):

HRESULT result2 = CTaskDialog::ShowDialog(L"My error message",
    L"Error",
    L"New Title",
    TEMP_LINE1,
    TEMP_LINE2);

Compile and run the application. The application displays two task dialog boxes. The first dialog box is from the To Add Functionality to the CTaskDialog procedure; the second dialog box is from the last procedure.

These examples don't demonstrate all the available options for a CTaskDialog, but should help you get started. See CTaskDialog Class for a full description of the class.

Deli z drugimi prek