Edit

Share via


CTaskDialog Class

A pop-up dialog box that functions like a message box but can display additional information to the user. The CTaskDialog also includes functionality for gathering information from the user.

Syntax

class CTaskDialog : public CObject

Members

Constructors

Name Description
CTaskDialog::CTaskDialog Constructs a CTaskDialog object.

Methods

Name Description
CTaskDialog::AddCommandControl Adds a command button control to the CTaskDialog.
CTaskDialog::AddRadioButton Adds a radio button to the CTaskDialog.
CTaskDialog::ClickCommandControl Clicks a command button control or common button programmatically.
CTaskDialog::ClickRadioButton Clicks a radio button programmatically.
CTaskDialog::DoModal Displays the CTaskDialog.
CTaskDialog::GetCommonButtonCount Retrieves the number of common buttons available.
CTaskDialog::GetCommonButtonFlag Converts a standard Windows button to the common button type associated with the CTaskDialog class.
CTaskDialog::GetCommonButtonId Converts one of the common button types associated with the CTaskDialog class to a standard Windows button.
CTaskDialog::GetOptions Returns the option flags for this CTaskDialog.
CTaskDialog::GetSelectedCommandControlID Returns the selected command button control.
CTaskDialog::GetSelectedRadioButtonID Returns the selected radio button.
CTaskDialog::GetVerificationCheckboxState Retrieves the state of the verification check box.
CTaskDialog::IsCommandControlEnabled Determines whether a command button control or common button is enabled.
CTaskDialog::IsRadioButtonEnabled Determines whether a radio button is enabled.
CTaskDialog::IsSupported Determines whether the computer that is running the application supports the CTaskDialog.
CTaskDialog::LoadCommandControls Adds command button controls by using data from the string table.
CTaskDialog::LoadRadioButtons Adds radio buttons by using data from the string table.
CTaskDialog::NavigateTo Transfers the focus to another CTaskDialog.
CTaskDialog::OnCommandControlClick The framework calls this method when the user clicks a command button control.
CTaskDialog::OnCreate The framework calls this method after it creates the CTaskDialog.
CTaskDialog::OnDestroy The framework calls this method immediately before it destroys the CTaskDialog.
CTaskDialog::OnExpandButtonClick The framework calls this method when the user clicks on the expansion button.
CTaskDialog::OnHelp The framework calls this method when the user requests help.
CTaskDialog::OnHyperlinkClick The framework calls this method when the user clicks on a hyperlink.
CTaskDialog::OnInit The framework calls this method when the CTaskDialog is initialized.
CTaskDialog::OnNavigatePage The framework calls this method when the user moves the focus with regard to controls on the CTaskDialog.
CTaskDialog::OnRadioButtonClick The framework calls this method when the user selects a radio button control.
CTaskDialog::OnTimer The framework calls this method when the timer expires.
CTaskDialog::OnVerificationCheckboxClick The framework calls this method when the user clicks the verification check box.
CTaskDialog::RemoveAllCommandControls Removes all the command controls from the CTaskDialog.
CTaskDialog::RemoveAllRadioButtons Removes all the radio buttons from the CTaskDialog.
CTaskDialog::SetCommandControlOptions Updates a command button control on the CTaskDialog.
CTaskDialog::SetCommonButtonOptions Updates a subset of common buttons to be enabled and require UAC elevation.
CTaskDialog::SetCommonButtons Adds common buttons to the CTaskDialog.
CTaskDialog::SetContent Updates the content of the CTaskDialog.
CTaskDialog::SetDefaultCommandControl Specifies the default command button control.
CTaskDialog::SetDefaultRadioButton Specifies the default radio button.
CTaskDialog::SetDialogWidth Adjusts the width of the CTaskDialog.
CTaskDialog::SetExpansionArea Updates the expansion area of the CTaskDialog.
CTaskDialog::SetFooterIcon Updates the footer icon for the CTaskDialog.
CTaskDialog::SetFooterText Updates the text on the footer of the CTaskDialog.
CTaskDialog::SetMainIcon Updates the main icon of the CTaskDialog.
CTaskDialog::SetMainInstruction Updates the main instruction of the CTaskDialog.
CTaskDialog::SetOptions Configures the options for the CTaskDialog.
CTaskDialog::SetProgressBarMarquee Configures a marquee bar for the CTaskDialog and adds it to the dialog box.
CTaskDialog::SetProgressBarPosition Adjusts the position of the progress bar.
CTaskDialog::SetProgressBarRange Adjusts the range of the progress bar.
CTaskDialog::SetProgressBarState Sets the state of the progress bar and displays it on the CTaskDialog.
CTaskDialog::SetRadioButtonOptions Enables or disables a radio button.
CTaskDialog::SetVerificationCheckbox Sets the checked state of the verification check box.
CTaskDialog::SetVerificationCheckboxText Sets the text on the right side of the verification check box.
CTaskDialog::SetWindowTitle Sets the title of the CTaskDialog.
CTaskDialog::ShowDialog Creates and displays a CTaskDialog.
CTaskDialog::TaskDialogCallback The framework calls this in response to various Windows messages.

Data Members

Name Description
m_aButtons The array of command button controls for the CTaskDialog.
m_aRadioButtons The array of radio button controls for the CTaskDialog.
m_bVerified TRUE indicates the verification check box is checked; FALSE indicates it is not.
m_footerIcon The icon in the footer of the CTaskDialog.
m_hWnd A handle to the window for the CTaskDialog.
m_mainIcon The main icon of the CTaskDialog.
m_nButtonDisabled A mask that indicates which of the common buttons are disabled.
m_nButtonElevation A mask that indicates which of the common buttons require UAC elevation.
m_nButtonId The ID of the selected command button control.
m_nCommonButton A mask that indicates which common buttons are displayed on the CTaskDialog.
m_nDefaultCommandControl The ID of the command button control that is selected when the CTaskDialog is displayed.
m_nDefaultRadioButton The ID of the radio button control that is selected when the CTaskDialog is displayed.
m_nFlags A mask that indicates the options for the CTaskDialog.
m_nProgressPos The current position for the progress bar. This value must be between m_nProgressRangeMin and m_nProgressRangeMax.
m_nProgressRangeMax The maximum value for the progress bar.
m_nProgressRangeMin The minimum value for the progress bar.
m_nProgressState The state of the progress bar. For more information, see CTaskDialog::SetProgressBarState.
m_nRadioId The ID of the selected radio button control.
m_nWidth The width of the CTaskDialog in pixels.
m_strCollapse The string the CTaskDialog displays to the right of the expansion box when the expanded information is hidden.
m_strContent The content string of the CTaskDialog.
m_strExpand The string the CTaskDialog displays to the right of the expansion box when the expanded information is displayed.
m_strFooter The footer of the CTaskDialog.
m_strInformation The expanded information for the CTaskDialog.
m_strMainInstruction The main instruction of the CTaskDialog.
m_strTitle The title of the CTaskDialog.
m_strVerification The string that the CTaskDialog displays to the right of the verification check box.

Remarks

The CTaskDialog class replaces the standard Windows message box and has additional functionality such as new controls to gather information from the user. This class is in the MFC library in Visual Studio 2010 and later. The CTaskDialog is available starting with Windows Vista. Earlier versions of Windows cannot display the CTaskDialog object. Use CTaskDialog::IsSupported to determine at runtime whether the current user can display the task dialog box. The standard Windows message box is still supported.

The CTaskDialog is available only when you build your application by using the Unicode library.

The CTaskDialog has two different constructors. One constructor enables you to specify two command buttons and a maximum of six regular button controls. You can add more command buttons after you create the CTaskDialog. The second constructor does not support any command buttons, but you can add an unlimited number of regular button controls. For more information about the constructors, see CTaskDialog::CTaskDialog.

The following image shows a sample CTaskDialog to illustrate the location of some of the controls.

Example of CTaskDialog.
CTaskDialog Sample

Requirements

Minimum required operating system: Windows Vista

Header: afxtaskdialog.h

CTaskDialog::AddCommandControl

Adds a new command button control to the CTaskDialog.

void AddCommandControl(
    int nCommandControlID,
    const CString& strCaption,
    BOOL bEnabled = TRUE,
    BOOL bRequiresElevation = FALSE);

Parameters

nCommandControlID
[in] The command control identification number.

strCaption
[in] The string that the CTaskDialog displays to the user. Use this string to explain the purpose of the command.

bEnabled
[in] A Boolean parameter that indicates if the new button is enabled or disabled.

bRequiresElevation
[in] A Boolean parameter that indicates whether a command requires elevation.

Remarks

The CTaskDialog Class can display an unlimited number of command button controls. However, if a CTaskDialog displays any command button controls, it can display a maximum of six buttons. If a CTaskDialog has no command button controls, it can display an unlimited number of buttons.

When the user selects a command button control, the CTaskDialog closes. If your application displays the dialog box by using CTaskDialog::DoModal, DoModal returns the nCommandControlID of the selected command button control.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title.
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

taskDialog.AddCommandControl(201, L"First command button control");
taskDialog.AddCommandControl(202, L"Second command button control");
taskDialog.AddCommandControl(203, L"Third command button control");

// Show the CTaskDialog and remember how the user closed it.
int selection = taskDialog.DoModal();

switch (selection)
{
case 201:
   // TODO: Place processing here for the first
   // command button control.
   break;

case 202:
   // TODO: Place processing here for the second
   // command button control.
   break;

case 203:
   // TODO: Place processing here for the third
   // command button control.
   break;

default:
   break;
}

// Remove all the command controls so that we can use the same task
// dialog with new command button controls.
taskDialog.RemoveAllCommandControls();

taskDialog.AddCommandControl(301,
                             L"New first command button control");
taskDialog.AddCommandControl(302,
                             L"New second command button control should require elevation",
                             TRUE, TRUE);
taskDialog.AddCommandControl(303,
                             L"New third command button control should be disabled");

// Change the default command button control
taskDialog.SetDefaultCommandControl(302);

// Make sure the third option is disabled.
if (taskDialog.IsCommandControlEnabled(303))
{
   taskDialog.SetCommandControlOptions(303, FALSE);
}

taskDialog.DoModal();

switch (taskDialog.GetSelectedCommandControlID())
{
case 301:
   // TODO: Place processing here for new first
   // command button control.
   break;

case 302:
   // TODO: Place processing here for new second
   // command button control.
   break;

case 303:
   // TODO: Place processing here for the new third
   // command button control.
   break;

default:
   break;
}

// Remove all the command button controls and add new ones from
// the string table resource.
taskDialog.RemoveAllCommandControls();
taskDialog.LoadCommandControls(1001, 1005);

CTaskDialog::AddRadioButton

Adds a radio button to the CTaskDialog.

void CTaskDialog::AddRadioButton(
    int nRadioButtonID,
    const CString& strCaption,
    BOOL bEnabled = TRUE);

Parameters

nRadioButtonID
[in] The identification number of the radio button.

strCaption
[in] The string that the CTaskDialog displays next to the radio button.

bEnabled
[in] A Boolean parameter that indicates whether the radio button is enabled.

Remarks

The radio buttons for the CTaskDialog Class enable you to gather information from the user. Use the function CTaskDialog::GetSelectedRadioButtonID to determine which radio button is selected.

The CTaskDialog does not require that the nRadioButtonID parameters are unique for each radio button. However, you may experience unexpected behavior if you do not use a distinct identifier for each radio button.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

taskDialog.AddRadioButton(201, L"First option");
taskDialog.AddRadioButton(202, L"Second option");
taskDialog.AddRadioButton(203, L"Third option");

taskDialog.DoModal();
int selection = taskDialog.GetSelectedRadioButtonID();

switch (selection)
{
case 201:
   // TODO: Place processing here for the first
   // radio button.
   break;

case 202:
   // TODO: Place processing here for the second
   // radio button.
   break;

case 203:
   // TODO: Place processing here for the third
   // radio button.
   break;

default:
   break;
}

// Remove all the radio buttons so that we can use the same task
// dialog with new radio buttons.
taskDialog.RemoveAllRadioButtons();

taskDialog.AddRadioButton(301, L"New first option");
taskDialog.AddRadioButton(302, L"New second option");
taskDialog.AddRadioButton(303,
                          L"New third option should be disabled");

// Change the default radio button to the second option
taskDialog.SetDefaultRadioButton(302);

// Make sure the third option is disabled.
if (taskDialog.IsRadioButtonEnabled(303))
{
   taskDialog.SetRadioButtonOptions(303, FALSE);
}

taskDialog.DoModal();
selection = taskDialog.GetSelectedRadioButtonID();

switch (taskDialog.GetSelectedRadioButtonID())
{
case 301:
   // TODO: Place processing here for new first
   // command button control.
   break;

case 302:
   // TODO: Place processing here for new second
   // command button control.
   break;

case 303:
   // TODO: Place processing here for the new third
   // command button control.
   break;

default:
   break;
}

// Remove all the radio button controls and add new ones from
// the string table resource.
taskDialog.RemoveAllRadioButtons();
taskDialog.LoadRadioButtons(1001, 1005);

CTaskDialog::ClickCommandControl

Clicks a command button control or common button programmatically.

protected:
void ClickCommandControl(int nCommandControlID) const;

Parameters

nCommandControlID
[in] The command ID of the control to click.

Remarks

This method generates the windows message TDM_CLICK_BUTTON.

CTaskDialog::ClickRadioButton

Clicks a radio button programmatically.

protected:
void ClickRadioButton(int nRadioButtonID) const;

Parameters

nRadioButtonID
[in] The ID of the radio button to click.

Remarks

This method generates the windows message TDM_CLICK_RADIO_BUTTON.

CTaskDialog::CTaskDialog

Creates an instance of the CTaskDialog Class.

CTaskDialog(
    const CString& strContent,
    const CString& strMainInstruction,
    const CString& strTitle,
    int nCommonButtons = TDCBF_OK_BUTTON | TDCBF_CANCEL_BUTTON,
    int nTaskDialogOptions = TDF_ENABLE_HYPERLINKS | TDF_USE_COMMAND_LINKS,
    const CString& strFooter = _T(""));

CTaskDialog(
    const CString& strContent,
    const CString& strMainInstruction,
    const CString& strTitle,
    int nIDCommandControlsFirst,
    int nIDCommandControlsLast,
    int nCommonButtons,
    int nTaskDialogOptions = TDF_ENABLE_HYPERLINKS | TDF_USE_COMMAND_LINKS,
    const CString& strFooter = _T(""));

Parameters

strContent
[in] The string to use for the content of the CTaskDialog.

strMainInstruction
[in] The main instruction of the CTaskDialog.

strTitle
[in] The title of the CTaskDialog.

nCommonButtons
[in] A mask of the common buttons to add to the CTaskDialog.

nTaskDialogOptions
[in] The set of options to use for the CTaskDialog.

strFooter
[in] The string to use as the footer.

nIDCommandControlsFirst
[in] The string ID of the first command.

nIDCommandControlsLast
[in] The string ID of the last command.

Remarks

There are two ways that you can add a CTaskDialog to your application. The first way is to use one of the constructors to create a CTaskDialog and display it using CTaskDialog::DoModal. The second way is to use the static function CTaskDialog::ShowDialog, which enables you to display a CTaskDialog without explicitly creating a CTaskDialog object.

The second constructor creates command button controls by using data from the resource file of your application. The string table in the resource file has several strings with associated string IDs. This method adds a command button control for each valid entry in the string table between nIDCommandControlsFirst and nCommandControlsLast, inclusive. For these command button controls, the string in the string table is the control's caption and the string ID is the control's ID.

See CTaskDialog::SetOptions for a list of valid options.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Setting new information to be able to reuse the dialog resource
taskDialog.SetWindowTitle(L"New title for the task dialog");
taskDialog.SetContent(L"New message to show the user.");
taskDialog.SetMainInstruction(L"Even more important!");
taskDialog.SetMainIcon(TD_ERROR_ICON);
taskDialog.SetDialogWidth(300);

// Add a footer
taskDialog.SetFooterText(L"Footer information for the dialog.");
taskDialog.SetFooterIcon(TD_INFORMATION_ICON);

// Add expansion information
taskDialog.SetExpansionArea(L"Additional information\non two lines.",
                            L"Click here for more information.",
                            L"Click here to hide the extra information.");

// Change the options to show the expanded information by default.
// It is necessary to retrieve the current options first.
int options = taskDialog.GetOptions();
options |= TDF_EXPANDED_BY_DEFAULT;
taskDialog.SetOptions(options);

taskDialog.DoModal();

CTaskDialog::DoModal

Shows the CTaskDialog and makes it modal.

INT_PTR DoModal (HWND hParent = ::GetActiveWindow());

Parameters

hParent
[in] The parent window for the CTaskDialog.

Return Value

An integer that corresponds to the selection made by the user.

Remarks

Displays this instance of the CTaskDialog. The application then waits for the user to close the dialog box.

The CTaskDialog closes when the user selects a common button, a command link control, or closes the CTaskDialog. The return value is the identifier that indicates how the user closed the dialog box.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Setting new information to be able to reuse the dialog resource
taskDialog.SetWindowTitle(L"New title for the task dialog");
taskDialog.SetContent(L"New message to show the user.");
taskDialog.SetMainInstruction(L"Even more important!");
taskDialog.SetMainIcon(TD_ERROR_ICON);
taskDialog.SetDialogWidth(300);

// Add a footer
taskDialog.SetFooterText(L"Footer information for the dialog.");
taskDialog.SetFooterIcon(TD_INFORMATION_ICON);

// Add expansion information
taskDialog.SetExpansionArea(L"Additional information\non two lines.",
                            L"Click here for more information.",
                            L"Click here to hide the extra information.");

// Change the options to show the expanded information by default.
// It is necessary to retrieve the current options first.
int options = taskDialog.GetOptions();
options |= TDF_EXPANDED_BY_DEFAULT;
taskDialog.SetOptions(options);

taskDialog.DoModal();

CTaskDialog::GetCommonButtonCount

Retrieves the number of common buttons.

int GetCommonButtonCount() const;

Return Value

The number of common buttons available.

Remarks

The common buttons are the default buttons that you provide to CTaskDialog::CTaskDialog. The CTaskDialog Class displays the buttons along the bottom of the dialog box.

The enumerated list of buttons is provided in CommCtrl.h.

CTaskDialog::GetCommonButtonFlag

Converts a standard Windows button to the common button type associated with the CTaskDialog Class.

int GetCommonButtonFlag(int nButtonId) const;

Parameters

nButtonId
[in] The standard Windows button value.

Return Value

The value of the corresponding CTaskDialog common button. If there is no corresponding common button, this method returns 0.

CTaskDialog::GetCommonButtonId

Converts one of the common button types associated with the CTaskDialog Class to a standard Windows button.

int GetCommonButtonId(int nFlag);

Parameters

nFlag
[in] The common button type associated with the CTaskDialog class.

Return Value

The value of the corresponding standard Windows button. If there is no corresponding Windows button, the method returns 0.

CTaskDialog::GetOptions

Returns the option flags for this CTaskDialog.

int GetOptions() const;

Return Value

The flags for the CTaskDialog.

Remarks

For more information about the options available to the CTaskDialog Class, see CTaskDialog::SetOptions.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Setting new information to be able to reuse the dialog resource
taskDialog.SetWindowTitle(L"New title for the task dialog");
taskDialog.SetContent(L"New message to show the user.");
taskDialog.SetMainInstruction(L"Even more important!");
taskDialog.SetMainIcon(TD_ERROR_ICON);
taskDialog.SetDialogWidth(300);

// Add a footer
taskDialog.SetFooterText(L"Footer information for the dialog.");
taskDialog.SetFooterIcon(TD_INFORMATION_ICON);

// Add expansion information
taskDialog.SetExpansionArea(L"Additional information\non two lines.",
                            L"Click here for more information.",
                            L"Click here to hide the extra information.");

// Change the options to show the expanded information by default.
// It is necessary to retrieve the current options first.
int options = taskDialog.GetOptions();
options |= TDF_EXPANDED_BY_DEFAULT;
taskDialog.SetOptions(options);

taskDialog.DoModal();

CTaskDialog::GetSelectedCommandControlID

Returns the selected command button control.

int GetSelectedCommandControlID() const;

Return Value

The ID of the currently selected command button control.

Remarks

You do not have to use this method to retrieve the ID of the command button that the user selected. That ID is returned by either CTaskDialog::DoModal or CTaskDialog::ShowDialog.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title.
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

taskDialog.AddCommandControl(201, L"First command button control");
taskDialog.AddCommandControl(202, L"Second command button control");
taskDialog.AddCommandControl(203, L"Third command button control");

// Show the CTaskDialog and remember how the user closed it.
int selection = taskDialog.DoModal();

switch (selection)
{
case 201:
   // TODO: Place processing here for the first
   // command button control.
   break;

case 202:
   // TODO: Place processing here for the second
   // command button control.
   break;

case 203:
   // TODO: Place processing here for the third
   // command button control.
   break;

default:
   break;
}

// Remove all the command controls so that we can use the same task
// dialog with new command button controls.
taskDialog.RemoveAllCommandControls();

taskDialog.AddCommandControl(301,
                             L"New first command button control");
taskDialog.AddCommandControl(302,
                             L"New second command button control should require elevation",
                             TRUE, TRUE);
taskDialog.AddCommandControl(303,
                             L"New third command button control should be disabled");

// Change the default command button control
taskDialog.SetDefaultCommandControl(302);

// Make sure the third option is disabled.
if (taskDialog.IsCommandControlEnabled(303))
{
   taskDialog.SetCommandControlOptions(303, FALSE);
}

taskDialog.DoModal();

switch (taskDialog.GetSelectedCommandControlID())
{
case 301:
   // TODO: Place processing here for new first
   // command button control.
   break;

case 302:
   // TODO: Place processing here for new second
   // command button control.
   break;

case 303:
   // TODO: Place processing here for the new third
   // command button control.
   break;

default:
   break;
}

// Remove all the command button controls and add new ones from
// the string table resource.
taskDialog.RemoveAllCommandControls();
taskDialog.LoadCommandControls(1001, 1005);

CTaskDialog::GetSelectedRadioButtonID

Returns the selected radio button.

int GetSelectedRadioButtonID() const;

Return Value

The ID of the selected radio button.

Remarks

You can use this method after the user closes the dialog box to retrieve the selected radio button.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

taskDialog.AddRadioButton(201, L"First option");
taskDialog.AddRadioButton(202, L"Second option");
taskDialog.AddRadioButton(203, L"Third option");

taskDialog.DoModal();
int selection = taskDialog.GetSelectedRadioButtonID();

switch (selection)
{
case 201:
   // TODO: Place processing here for the first
   // radio button.
   break;

case 202:
   // TODO: Place processing here for the second
   // radio button.
   break;

case 203:
   // TODO: Place processing here for the third
   // radio button.
   break;

default:
   break;
}

// Remove all the radio buttons so that we can use the same task
// dialog with new radio buttons.
taskDialog.RemoveAllRadioButtons();

taskDialog.AddRadioButton(301, L"New first option");
taskDialog.AddRadioButton(302, L"New second option");
taskDialog.AddRadioButton(303,
                          L"New third option should be disabled");

// Change the default radio button to the second option
taskDialog.SetDefaultRadioButton(302);

// Make sure the third option is disabled.
if (taskDialog.IsRadioButtonEnabled(303))
{
   taskDialog.SetRadioButtonOptions(303, FALSE);
}

taskDialog.DoModal();
selection = taskDialog.GetSelectedRadioButtonID();

switch (taskDialog.GetSelectedRadioButtonID())
{
case 301:
   // TODO: Place processing here for new first
   // command button control.
   break;

case 302:
   // TODO: Place processing here for new second
   // command button control.
   break;

case 303:
   // TODO: Place processing here for the new third
   // command button control.
   break;

default:
   break;
}

// Remove all the radio button controls and add new ones from
// the string table resource.
taskDialog.RemoveAllRadioButtons();
taskDialog.LoadRadioButtons(1001, 1005);

CTaskDialog::GetVerificationCheckboxState

Retrieves the state of the verification check box.

BOOL GetVerificationCheckboxState() const;

Return Value

TRUE if the check box is checked, FALSE if it is not.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Add the verification checkbox and set the default state.
taskDialog.SetVerificationCheckboxText(L"Remember your selection.");
taskDialog.SetVerificationCheckbox(false);

taskDialog.DoModal();

if (taskDialog.GetVerificationCheckboxState())
{
   // TODO: Write settings of the task dialog to the registry
}

CTaskDialog::IsCommandControlEnabled

Determines whether a command button control or button is enabled.

BOOL IsCommandControlEnabled(int nCommandControlID) const;

Parameters

nCommandControlID
[in] The ID of the command button control or button to test.

Return Value

TRUE if the control is enabled, FALSE if it is not.

Remarks

You can use this method to determine the availability of both command button controls and the common buttons of the CTaskDialog Class*.

If nCommandControlID is not a valid identifier for either a common CTaskDialog button or a command button control, this method throws an exception.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title.
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

taskDialog.AddCommandControl(201, L"First command button control");
taskDialog.AddCommandControl(202, L"Second command button control");
taskDialog.AddCommandControl(203, L"Third command button control");

// Show the CTaskDialog and remember how the user closed it.
int selection = taskDialog.DoModal();

switch (selection)
{
case 201:
   // TODO: Place processing here for the first
   // command button control.
   break;

case 202:
   // TODO: Place processing here for the second
   // command button control.
   break;

case 203:
   // TODO: Place processing here for the third
   // command button control.
   break;

default:
   break;
}

// Remove all the command controls so that we can use the same task
// dialog with new command button controls.
taskDialog.RemoveAllCommandControls();

taskDialog.AddCommandControl(301,
                             L"New first command button control");
taskDialog.AddCommandControl(302,
                             L"New second command button control should require elevation",
                             TRUE, TRUE);
taskDialog.AddCommandControl(303,
                             L"New third command button control should be disabled");

// Change the default command button control
taskDialog.SetDefaultCommandControl(302);

// Make sure the third option is disabled.
if (taskDialog.IsCommandControlEnabled(303))
{
   taskDialog.SetCommandControlOptions(303, FALSE);
}

taskDialog.DoModal();

switch (taskDialog.GetSelectedCommandControlID())
{
case 301:
   // TODO: Place processing here for new first
   // command button control.
   break;

case 302:
   // TODO: Place processing here for new second
   // command button control.
   break;

case 303:
   // TODO: Place processing here for the new third
   // command button control.
   break;

default:
   break;
}

// Remove all the command button controls and add new ones from
// the string table resource.
taskDialog.RemoveAllCommandControls();
taskDialog.LoadCommandControls(1001, 1005);

CTaskDialog::IsRadioButtonEnabled

Determines whether a radio button is enabled.

BOOL IsRadioButtonEnabled(int nRadioButtonID) const;

Parameters

nRadioButtonID
[in] The ID of the radio button to test.

Return Value

TRUE if the radio button is enabled, FALSE if it is not.

Remarks

If nRadioButtonID is not a valid identifier for a radio button, this method throws an exception.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

taskDialog.AddRadioButton(201, L"First option");
taskDialog.AddRadioButton(202, L"Second option");
taskDialog.AddRadioButton(203, L"Third option");

taskDialog.DoModal();
int selection = taskDialog.GetSelectedRadioButtonID();

switch (selection)
{
case 201:
   // TODO: Place processing here for the first
   // radio button.
   break;

case 202:
   // TODO: Place processing here for the second
   // radio button.
   break;

case 203:
   // TODO: Place processing here for the third
   // radio button.
   break;

default:
   break;
}

// Remove all the radio buttons so that we can use the same task
// dialog with new radio buttons.
taskDialog.RemoveAllRadioButtons();

taskDialog.AddRadioButton(301, L"New first option");
taskDialog.AddRadioButton(302, L"New second option");
taskDialog.AddRadioButton(303,
                          L"New third option should be disabled");

// Change the default radio button to the second option
taskDialog.SetDefaultRadioButton(302);

// Make sure the third option is disabled.
if (taskDialog.IsRadioButtonEnabled(303))
{
   taskDialog.SetRadioButtonOptions(303, FALSE);
}

taskDialog.DoModal();
selection = taskDialog.GetSelectedRadioButtonID();

switch (taskDialog.GetSelectedRadioButtonID())
{
case 301:
   // TODO: Place processing here for new first
   // command button control.
   break;

case 302:
   // TODO: Place processing here for new second
   // command button control.
   break;

case 303:
   // TODO: Place processing here for the new third
   // command button control.
   break;

default:
   break;
}

// Remove all the radio button controls and add new ones from
// the string table resource.
taskDialog.RemoveAllRadioButtons();
taskDialog.LoadRadioButtons(1001, 1005);

CTaskDialog::IsSupported

Determines whether the computer that is running the application supports the CTaskDialog.

static BOOL IsSupported();

Return Value

TRUE if the computer supports the CTaskDialog; FALSE otherwise.

Remarks

Use this function to determine at runtime if the computer that is running your application supports the CTaskDialog class. If the computer does not support the CTaskDialog, you should provide another method of communicating information to the user. Your application will crash if it tries to use a CTaskDialog on a computer that does not support the CTaskDialog class.

Example

// TODO: Replace the string below with the actual message to the user
CString message("Important information to the user");
// TODO: Replace the string below with the title of this project
CString title("Project Title");

CString emptyString;

if (CTaskDialog::IsSupported())
{
   CTaskDialog::ShowDialog(message, emptyString, title, 0, 0,
                           TDCBF_OK_BUTTON);
}
else
{
   AfxMessageBox(message);
}

CTaskDialog::LoadCommandControls

Adds command button controls by using data from the string table.

void LoadCommandControls(
    int nIDCommandControlsFirst,
    int nIDCommandControlsLast);

Parameters

nIDCommandControlsFirst
[in] The string ID of the first command.

nIDCommandControlsLast
[in] The string ID of the last command.

Remarks

This method creates command button controls by using data from the resource file of your application. The string table in the resource file has several strings with associated string IDs. New command button controls added by using this method use the string for the control's caption and the string ID for the control's ID. The range of strings selected is provided by nIDCommandControlsFirst and nCommandControlsLast, inclusive. If there is an empty entry in the range, the method does not add a command button control for that entry.

By default, new command button controls are enabled and do not require elevation.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title.
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

taskDialog.AddCommandControl(201, L"First command button control");
taskDialog.AddCommandControl(202, L"Second command button control");
taskDialog.AddCommandControl(203, L"Third command button control");

// Show the CTaskDialog and remember how the user closed it.
int selection = taskDialog.DoModal();

switch (selection)
{
case 201:
   // TODO: Place processing here for the first
   // command button control.
   break;

case 202:
   // TODO: Place processing here for the second
   // command button control.
   break;

case 203:
   // TODO: Place processing here for the third
   // command button control.
   break;

default:
   break;
}

// Remove all the command controls so that we can use the same task
// dialog with new command button controls.
taskDialog.RemoveAllCommandControls();

taskDialog.AddCommandControl(301,
                             L"New first command button control");
taskDialog.AddCommandControl(302,
                             L"New second command button control should require elevation",
                             TRUE, TRUE);
taskDialog.AddCommandControl(303,
                             L"New third command button control should be disabled");

// Change the default command button control
taskDialog.SetDefaultCommandControl(302);

// Make sure the third option is disabled.
if (taskDialog.IsCommandControlEnabled(303))
{
   taskDialog.SetCommandControlOptions(303, FALSE);
}

taskDialog.DoModal();

switch (taskDialog.GetSelectedCommandControlID())
{
case 301:
   // TODO: Place processing here for new first
   // command button control.
   break;

case 302:
   // TODO: Place processing here for new second
   // command button control.
   break;

case 303:
   // TODO: Place processing here for the new third
   // command button control.
   break;

default:
   break;
}

// Remove all the command button controls and add new ones from
// the string table resource.
taskDialog.RemoveAllCommandControls();
taskDialog.LoadCommandControls(1001, 1005);

CTaskDialog::LoadRadioButtons

Adds radio button controls by using data from the string table.

void LoadRadioButtons(
    int nIDRadioButtonsFirst,
    int nIDRadioButtonsLast);

Parameters

nIDRadioButtonsFirst
[in] The string ID of the first radio button.

nIDRadioButtonsLast
[in] The string ID of the last radio button.

Remarks

This method creates radio buttons by using data from the resource file of your application. The string table in the resource file has several strings with associated string IDs. New radio buttons added by using this method use the string for the radio button's caption and the string ID for the radio button's ID. The range of strings selected is provided by nIDRadioButtonsFirst and nRadioButtonsLast, inclusive. If there is an empty entry in the range, the method does not add a radio button for that entry.

By default, new radio buttons are enabled.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

taskDialog.AddRadioButton(201, L"First option");
taskDialog.AddRadioButton(202, L"Second option");
taskDialog.AddRadioButton(203, L"Third option");

taskDialog.DoModal();
int selection = taskDialog.GetSelectedRadioButtonID();

switch (selection)
{
case 201:
   // TODO: Place processing here for the first
   // radio button.
   break;

case 202:
   // TODO: Place processing here for the second
   // radio button.
   break;

case 203:
   // TODO: Place processing here for the third
   // radio button.
   break;

default:
   break;
}

// Remove all the radio buttons so that we can use the same task
// dialog with new radio buttons.
taskDialog.RemoveAllRadioButtons();

taskDialog.AddRadioButton(301, L"New first option");
taskDialog.AddRadioButton(302, L"New second option");
taskDialog.AddRadioButton(303,
                          L"New third option should be disabled");

// Change the default radio button to the second option
taskDialog.SetDefaultRadioButton(302);

// Make sure the third option is disabled.
if (taskDialog.IsRadioButtonEnabled(303))
{
   taskDialog.SetRadioButtonOptions(303, FALSE);
}

taskDialog.DoModal();
selection = taskDialog.GetSelectedRadioButtonID();

switch (taskDialog.GetSelectedRadioButtonID())
{
case 301:
   // TODO: Place processing here for new first
   // command button control.
   break;

case 302:
   // TODO: Place processing here for new second
   // command button control.
   break;

case 303:
   // TODO: Place processing here for the new third
   // command button control.
   break;

default:
   break;
}

// Remove all the radio button controls and add new ones from
// the string table resource.
taskDialog.RemoveAllRadioButtons();
taskDialog.LoadRadioButtons(1001, 1005);

Transfers the focus to another CTaskDialog.

protected:
void NavigateTo(CTaskDialog& oTaskDialog) const;

Parameters

oTaskDialog
[in] The CTaskDialog that receives the focus.

Remarks

This method hides the current CTaskDialog when it displays the oTaskDialog. The oTaskDialog is displayed in the same location as the current CTaskDialog.

CTaskDialog::OnCommandControlClick

The framework calls this method when the user clicks a command button control.

virtual HRESULT OnCommandControlClick(int nCommandControlID);

Parameters

nCommandControlID
[in] The ID of the command button control that the user selected.

Return Value

The default implementation returns S_OK.

Remarks

Override this method in a derived class to implement custom behavior.

CTaskDialog::OnCreate

The framework calls this method after it creates the CTaskDialog.

virtual HRESULT OnCreate();

Return Value

The default implementation returns S_OK.

Remarks

Override this method in a derived class to implement custom behavior.

CTaskDialog::OnDestroy

The framework calls this method immediately before it destroys the CTaskDialog.

virtual HRESULT OnDestroy();

Return Value

The default implementation returns S_OK.

Remarks

Override this method in a derived class to implement custom behavior.

CTaskDialog::OnExpandButtonClick

The framework calls this method when the user clicks on the expansion button.

virtual HRESULT OnExpandButtonClicked(BOOL bExpanded);

Parameters

bExpanded
[in] A nonzero value indicates the extra information is displayed; 0 indicates the extra information is hidden.

Return Value

The default implementation returns S_OK.

Remarks

Override this method in a derived class to implement custom behavior.

CTaskDialog::OnHelp

The framework calls this method when the user requests help.

virtual HRESULT OnHelp();

Return Value

The default implementation returns S_OK.

Remarks

Override this method in a derived class to implement custom behavior.

CTaskDialog::OnHyperlinkClick

The framework calls this method when the user clicks on a hyperlink.

virtual HRESULT OnHyperlinkClick(const CString& strHref);

Parameters

strHref
[in] The string that represents the hyperlink.

Return Value

The default implementation returns S_OK.

Remarks

This method calls ShellExecute before it returns S_OK.

Override this method in a derived class to implement custom behavior.

CTaskDialog::OnInit

The framework calls this method when the CTaskDialog is initialized.

virtual HRESULT OnInit();

Return Value

The default implementation returns S_OK.

Remarks

Override this method in a derived class to implement custom behavior.

CTaskDialog::OnNavigatePage

The framework calls this method in response to the CTaskDialog::NavigateTo method.

virtual HRESULT OnNavigatePage();

Return Value

The default implementation returns S_OK.

Remarks

Override this method in a derived class to implement custom behavior.

CTaskDialog::OnRadioButtonClick

The framework calls this method when the user selects a radio button control.

virtual HRESULT OnRadioButtonClick(int nRadioButtonID);

Parameters

nRadioButtonID
[in] The ID of the radio button control that the user clicked.

Return Value

The default implementation returns S_OK.

Remarks

Override this method in a derived class to implement custom behavior.

CTaskDialog::OnTimer

The framework calls this method when the timer expires.

virtual HRESULT OnTimer(long lTime);

Parameters

lTime
[in] Time in milliseconds since the CTaskDialog was created or the timer was reset.

Return Value

The default implementation returns S_OK.

Remarks

Override this method in a derived class to implement custom behavior.

CTaskDialog::OnVerificationCheckboxClick

The framework calls this method when the user clicks the verification check box.

virtual HRESULT OnVerificationCheckboxClick(BOOL bChecked);

Parameters

bChecked
[in] TRUE indicates the verification check box is selected; FALSE indicates it is not.

Return Value

The default implementation returns S_OK.

Remarks

Override this method in a derived class to implement custom behavior.

CTaskDialog::RemoveAllCommandControls

Removes all the command button controls from the CTaskDialog.

void RemoveAllCommandControls();

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title.
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

taskDialog.AddCommandControl(201, L"First command button control");
taskDialog.AddCommandControl(202, L"Second command button control");
taskDialog.AddCommandControl(203, L"Third command button control");

// Show the CTaskDialog and remember how the user closed it.
int selection = taskDialog.DoModal();

switch (selection)
{
case 201:
   // TODO: Place processing here for the first
   // command button control.
   break;

case 202:
   // TODO: Place processing here for the second
   // command button control.
   break;

case 203:
   // TODO: Place processing here for the third
   // command button control.
   break;

default:
   break;
}

// Remove all the command controls so that we can use the same task
// dialog with new command button controls.
taskDialog.RemoveAllCommandControls();

taskDialog.AddCommandControl(301,
                             L"New first command button control");
taskDialog.AddCommandControl(302,
                             L"New second command button control should require elevation",
                             TRUE, TRUE);
taskDialog.AddCommandControl(303,
                             L"New third command button control should be disabled");

// Change the default command button control
taskDialog.SetDefaultCommandControl(302);

// Make sure the third option is disabled.
if (taskDialog.IsCommandControlEnabled(303))
{
   taskDialog.SetCommandControlOptions(303, FALSE);
}

taskDialog.DoModal();

switch (taskDialog.GetSelectedCommandControlID())
{
case 301:
   // TODO: Place processing here for new first
   // command button control.
   break;

case 302:
   // TODO: Place processing here for new second
   // command button control.
   break;

case 303:
   // TODO: Place processing here for the new third
   // command button control.
   break;

default:
   break;
}

// Remove all the command button controls and add new ones from
// the string table resource.
taskDialog.RemoveAllCommandControls();
taskDialog.LoadCommandControls(1001, 1005);

CTaskDialog::RemoveAllRadioButtons

Removes all the radio buttons from the CTaskDialog.

void RemoveAllRadioButtons();

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

taskDialog.AddRadioButton(201, L"First option");
taskDialog.AddRadioButton(202, L"Second option");
taskDialog.AddRadioButton(203, L"Third option");

taskDialog.DoModal();
int selection = taskDialog.GetSelectedRadioButtonID();

switch (selection)
{
case 201:
   // TODO: Place processing here for the first
   // radio button.
   break;

case 202:
   // TODO: Place processing here for the second
   // radio button.
   break;

case 203:
   // TODO: Place processing here for the third
   // radio button.
   break;

default:
   break;
}

// Remove all the radio buttons so that we can use the same task
// dialog with new radio buttons.
taskDialog.RemoveAllRadioButtons();

taskDialog.AddRadioButton(301, L"New first option");
taskDialog.AddRadioButton(302, L"New second option");
taskDialog.AddRadioButton(303,
                          L"New third option should be disabled");

// Change the default radio button to the second option
taskDialog.SetDefaultRadioButton(302);

// Make sure the third option is disabled.
if (taskDialog.IsRadioButtonEnabled(303))
{
   taskDialog.SetRadioButtonOptions(303, FALSE);
}

taskDialog.DoModal();
selection = taskDialog.GetSelectedRadioButtonID();

switch (taskDialog.GetSelectedRadioButtonID())
{
case 301:
   // TODO: Place processing here for new first
   // command button control.
   break;

case 302:
   // TODO: Place processing here for new second
   // command button control.
   break;

case 303:
   // TODO: Place processing here for the new third
   // command button control.
   break;

default:
   break;
}

// Remove all the radio button controls and add new ones from
// the string table resource.
taskDialog.RemoveAllRadioButtons();
taskDialog.LoadRadioButtons(1001, 1005);

CTaskDialog::SetCommandControlOptions

Updates a command button control on the CTaskDialog.

void SetCommandControlOptions(
    int nCommandControlID,
    BOOL bEnabled,
    BOOL bRequiresElevation = FALSE);

Parameters

nCommandControlID
[in] The ID of the command control to update.

bEnabled
[in] A Boolean parameter that indicates if the specified command button control is enabled or disabled.

bRequiresElevation
[in] A Boolean parameter that indicates if the specified command button control requires elevation.

Remarks

Use this method to change whether a command button control is enabled or requires elevation after it has been added to the CTaskDialog class.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title.
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

taskDialog.AddCommandControl(201, L"First command button control");
taskDialog.AddCommandControl(202, L"Second command button control");
taskDialog.AddCommandControl(203, L"Third command button control");

// Show the CTaskDialog and remember how the user closed it.
int selection = taskDialog.DoModal();

switch (selection)
{
case 201:
   // TODO: Place processing here for the first
   // command button control.
   break;

case 202:
   // TODO: Place processing here for the second
   // command button control.
   break;

case 203:
   // TODO: Place processing here for the third
   // command button control.
   break;

default:
   break;
}

// Remove all the command controls so that we can use the same task
// dialog with new command button controls.
taskDialog.RemoveAllCommandControls();

taskDialog.AddCommandControl(301,
                             L"New first command button control");
taskDialog.AddCommandControl(302,
                             L"New second command button control should require elevation",
                             TRUE, TRUE);
taskDialog.AddCommandControl(303,
                             L"New third command button control should be disabled");

// Change the default command button control
taskDialog.SetDefaultCommandControl(302);

// Make sure the third option is disabled.
if (taskDialog.IsCommandControlEnabled(303))
{
   taskDialog.SetCommandControlOptions(303, FALSE);
}

taskDialog.DoModal();

switch (taskDialog.GetSelectedCommandControlID())
{
case 301:
   // TODO: Place processing here for new first
   // command button control.
   break;

case 302:
   // TODO: Place processing here for new second
   // command button control.
   break;

case 303:
   // TODO: Place processing here for the new third
   // command button control.
   break;

default:
   break;
}

// Remove all the command button controls and add new ones from
// the string table resource.
taskDialog.RemoveAllCommandControls();
taskDialog.LoadCommandControls(1001, 1005);

CTaskDialog::SetCommonButtonOptions

Updates a subset of common buttons to be enabled and to require UAC elevation.

void SetCommonButtonOptions(
    int nDisabledButtonMask,
    int nElevationButtonMask = 0);

Parameters

nDisabledButtonMask
[in] A mask for the common buttons to disable.

nElevationButtonMask
[in] A mask for the common buttons that require elevation.

Remarks

You can set the common buttons available to an instance of the CTaskDialog Class by using the constructor CTaskDialog::CTaskDialog and the method CTaskDialog::SetCommonButtons. CTaskDialog::SetCommonButtonOptions does not support adding new common buttons.

If you use this method to disable or elevate a common button that is not available for this CTaskDialog, this method throws an exception by using the ENSURE macro.

This method enables any button that is available to the CTaskDialog but is not in the nDisabledButtonMask, even if it was previously disabled. This method treats elevation in a similar manner: it records common buttons as not requiring elevation if the common button is available but not included in nElevationButtonMask.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title);

// Create a button mask.
int buttons = TDCBF_OK_BUTTON | TDCBF_CANCEL_BUTTON;
buttons |= TDCBF_RETRY_BUTTON | TDCBF_CLOSE_BUTTON;

taskDialog.SetCommonButtons(buttons);

// Disable the close button and make the retry button require
// elevation.
taskDialog.SetCommonButtonOptions(TDCBF_CLOSE_BUTTON,
                                  TDCBF_RETRY_BUTTON);

taskDialog.DoModal();

CTaskDialog::SetCommonButtons

Adds common buttons to the CTaskDialog.

void SetCommonButtons(
    int nButtonMask,
    int nDisabledButtonMask = 0,
    int nElevationButtonMask = 0);

Parameters

nButtonMask
[in] A mask of the buttons to add to the CTaskDialog.

nDisabledButtonMask
[in] A mask of the buttons to disable.

nElevationButtonMask
[in] A mask of the buttons that require elevation.

Remarks

You cannot call this method after the display window for this instance of the CTaskDialog class is created. If you do, this method throws an exception.

The buttons indicated by nButtonMask override any common buttons previously added to the CTaskDialog. Only the buttons indicated in nButtonMask are available.

If either nDisabledButtonMask or nElevationButtonMask contain a button that is not in nButtonMask, this method throws an exception by using the ENSURE macro.

By default, all common buttons are enabled and do not require elevation.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title);

// Create a button mask.
int buttons = TDCBF_OK_BUTTON | TDCBF_CANCEL_BUTTON;
buttons |= TDCBF_RETRY_BUTTON | TDCBF_CLOSE_BUTTON;

taskDialog.SetCommonButtons(buttons);

// Disable the close button and make the retry button require
// elevation.
taskDialog.SetCommonButtonOptions(TDCBF_CLOSE_BUTTON,
                                  TDCBF_RETRY_BUTTON);

taskDialog.DoModal();

CTaskDialog::SetContent

Updates the content of the CTaskDialog.

void SetContent(const CString& strContent);

Parameters

strContent
[in] The string to display to the user.

Remarks

The content of the CTaskDialog class is the text that is displayed to the user in the main section of the dialog box.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Setting new information to be able to reuse the dialog resource
taskDialog.SetWindowTitle(L"New title for the task dialog");
taskDialog.SetContent(L"New message to show the user.");
taskDialog.SetMainInstruction(L"Even more important!");
taskDialog.SetMainIcon(TD_ERROR_ICON);
taskDialog.SetDialogWidth(300);

// Add a footer
taskDialog.SetFooterText(L"Footer information for the dialog.");
taskDialog.SetFooterIcon(TD_INFORMATION_ICON);

// Add expansion information
taskDialog.SetExpansionArea(L"Additional information\non two lines.",
                            L"Click here for more information.",
                            L"Click here to hide the extra information.");

// Change the options to show the expanded information by default.
// It is necessary to retrieve the current options first.
int options = taskDialog.GetOptions();
options |= TDF_EXPANDED_BY_DEFAULT;
taskDialog.SetOptions(options);

taskDialog.DoModal();

CTaskDialog::SetDefaultCommandControl

Specifies the default command button control.

void SetDefaultCommandControl(int nCommandControlID);

Parameters

nCommandControlID
[in] The ID of the command button control to be the default.

Remarks

The default command button control is the control that is selected when the CTaskDialog is first displayed to the user.

This method throws an exception if it cannot find the command button control specified by nCommandControlID.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title.
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

taskDialog.AddCommandControl(201, L"First command button control");
taskDialog.AddCommandControl(202, L"Second command button control");
taskDialog.AddCommandControl(203, L"Third command button control");

// Show the CTaskDialog and remember how the user closed it.
int selection = taskDialog.DoModal();

switch (selection)
{
case 201:
   // TODO: Place processing here for the first
   // command button control.
   break;

case 202:
   // TODO: Place processing here for the second
   // command button control.
   break;

case 203:
   // TODO: Place processing here for the third
   // command button control.
   break;

default:
   break;
}

// Remove all the command controls so that we can use the same task
// dialog with new command button controls.
taskDialog.RemoveAllCommandControls();

taskDialog.AddCommandControl(301,
                             L"New first command button control");
taskDialog.AddCommandControl(302,
                             L"New second command button control should require elevation",
                             TRUE, TRUE);
taskDialog.AddCommandControl(303,
                             L"New third command button control should be disabled");

// Change the default command button control
taskDialog.SetDefaultCommandControl(302);

// Make sure the third option is disabled.
if (taskDialog.IsCommandControlEnabled(303))
{
   taskDialog.SetCommandControlOptions(303, FALSE);
}

taskDialog.DoModal();

switch (taskDialog.GetSelectedCommandControlID())
{
case 301:
   // TODO: Place processing here for new first
   // command button control.
   break;

case 302:
   // TODO: Place processing here for new second
   // command button control.
   break;

case 303:
   // TODO: Place processing here for the new third
   // command button control.
   break;

default:
   break;
}

// Remove all the command button controls and add new ones from
// the string table resource.
taskDialog.RemoveAllCommandControls();
taskDialog.LoadCommandControls(1001, 1005);

CTaskDialog::SetDefaultRadioButton

Specifies the default radio button.

void SetDefaultRadioButton(int nRadioButtonID);

Parameters

nRadioButtonID
[in] The ID of the radio button to be the default.

Remarks

The default radio button is the button that is selected when the CTaskDialog is first displayed to the user.

This method throws an exception if it cannot find the radio button specified by nRadioButtonID.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

taskDialog.AddRadioButton(201, L"First option");
taskDialog.AddRadioButton(202, L"Second option");
taskDialog.AddRadioButton(203, L"Third option");

taskDialog.DoModal();
int selection = taskDialog.GetSelectedRadioButtonID();

switch (selection)
{
case 201:
   // TODO: Place processing here for the first
   // radio button.
   break;

case 202:
   // TODO: Place processing here for the second
   // radio button.
   break;

case 203:
   // TODO: Place processing here for the third
   // radio button.
   break;

default:
   break;
}

// Remove all the radio buttons so that we can use the same task
// dialog with new radio buttons.
taskDialog.RemoveAllRadioButtons();

taskDialog.AddRadioButton(301, L"New first option");
taskDialog.AddRadioButton(302, L"New second option");
taskDialog.AddRadioButton(303,
                          L"New third option should be disabled");

// Change the default radio button to the second option
taskDialog.SetDefaultRadioButton(302);

// Make sure the third option is disabled.
if (taskDialog.IsRadioButtonEnabled(303))
{
   taskDialog.SetRadioButtonOptions(303, FALSE);
}

taskDialog.DoModal();
selection = taskDialog.GetSelectedRadioButtonID();

switch (taskDialog.GetSelectedRadioButtonID())
{
case 301:
   // TODO: Place processing here for new first
   // command button control.
   break;

case 302:
   // TODO: Place processing here for new second
   // command button control.
   break;

case 303:
   // TODO: Place processing here for the new third
   // command button control.
   break;

default:
   break;
}

// Remove all the radio button controls and add new ones from
// the string table resource.
taskDialog.RemoveAllRadioButtons();
taskDialog.LoadRadioButtons(1001, 1005);

CTaskDialog::SetDialogWidth

Adjusts the width of the CTaskDialog.

void SetDialogWidth(int nWidth = 0);

Parameters

nWidth
[in] The width of the dialog box, in pixels.

Remarks

The parameter nWidth must be greater than or equal to 0. Otherwise, this method throws an exception.

If nWidth is set to 0, this method sets the dialog box to the default size.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Setting new information to be able to reuse the dialog resource
taskDialog.SetWindowTitle(L"New title for the task dialog");
taskDialog.SetContent(L"New message to show the user.");
taskDialog.SetMainInstruction(L"Even more important!");
taskDialog.SetMainIcon(TD_ERROR_ICON);
taskDialog.SetDialogWidth(300);

// Add a footer
taskDialog.SetFooterText(L"Footer information for the dialog.");
taskDialog.SetFooterIcon(TD_INFORMATION_ICON);

// Add expansion information
taskDialog.SetExpansionArea(L"Additional information\non two lines.",
                            L"Click here for more information.",
                            L"Click here to hide the extra information.");

// Change the options to show the expanded information by default.
// It is necessary to retrieve the current options first.
int options = taskDialog.GetOptions();
options |= TDF_EXPANDED_BY_DEFAULT;
taskDialog.SetOptions(options);

taskDialog.DoModal();

CTaskDialog::SetExpansionArea

Updates the expansion area of the CTaskDialog.

void SetExpansionArea(
    const CString& strExpandedInformation,
    const CString& strCollapsedLabel = _T(""),
    const CString& strExpandedLabel = _T(""));

Parameters

strExpandedInformation
[in] The string that the CTaskDialog displays in the main body of the dialog box when the user clicks the expansion button.

strCollapsedLabel
[in] The string that the CTaskDialog displays next to the expansion button when the expanded area is collapsed.

strExpandedLabel
[in] The string that the CTaskDialog displays next to the expansion button when the expanded area is displayed.

Remarks

The expansion area of the CTaskDialog class enables you to provide additional information to the user. The expansion area is in the main part of the CTaskDialog, located immediately underneath the title and content string.

When the CTaskDialog is first displayed, it does not show the expanded information and puts strCollapsedLabel next to the expansion button. When the user clicks the expansion button, the CTaskDialog displays strExpandedInformation and changes the label to strExpandedLabel.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Setting new information to be able to reuse the dialog resource
taskDialog.SetWindowTitle(L"New title for the task dialog");
taskDialog.SetContent(L"New message to show the user.");
taskDialog.SetMainInstruction(L"Even more important!");
taskDialog.SetMainIcon(TD_ERROR_ICON);
taskDialog.SetDialogWidth(300);

// Add a footer
taskDialog.SetFooterText(L"Footer information for the dialog.");
taskDialog.SetFooterIcon(TD_INFORMATION_ICON);

// Add expansion information
taskDialog.SetExpansionArea(L"Additional information\non two lines.",
                            L"Click here for more information.",
                            L"Click here to hide the extra information.");

// Change the options to show the expanded information by default.
// It is necessary to retrieve the current options first.
int options = taskDialog.GetOptions();
options |= TDF_EXPANDED_BY_DEFAULT;
taskDialog.SetOptions(options);

taskDialog.DoModal();

CTaskDialog::SetFooterIcon

Updates the footer icon of the CTaskDialog.

void SetFooterIcon(HICON hFooterIcon);
void SetFooterIcon(LPCWSTR lpszFooterIcon);

Parameters

hFooterIcon
[in] The new icon for the CTaskDialog.

lpszFooterIcon
[in] The new icon for the CTaskDialog.

Remarks

The footer icon is displayed on the bottom of the CTaskDialog Class. It can have associated footer text. You can change the footer text with CTaskDialog::SetFooterText.

This method throws an exception with the ENSURE macro if the CTaskDialog is displayed or the input parameter is NULL.

A CTaskDialog can only accept an HICON or LPCWSTR as a footer icon. This is configured by setting the option TDF_USE_HICON_FOOTER in the constructor or CTaskDialog::SetOptions. By default, the CTaskDialog is configured to use LPCWSTR as the input type for the footer icon. This method generates an exception if you try to set the icon using the inappropriate type.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Setting new information to be able to reuse the dialog resource
taskDialog.SetWindowTitle(L"New title for the task dialog");
taskDialog.SetContent(L"New message to show the user.");
taskDialog.SetMainInstruction(L"Even more important!");
taskDialog.SetMainIcon(TD_ERROR_ICON);
taskDialog.SetDialogWidth(300);

// Add a footer
taskDialog.SetFooterText(L"Footer information for the dialog.");
taskDialog.SetFooterIcon(TD_INFORMATION_ICON);

// Add expansion information
taskDialog.SetExpansionArea(L"Additional information\non two lines.",
                            L"Click here for more information.",
                            L"Click here to hide the extra information.");

// Change the options to show the expanded information by default.
// It is necessary to retrieve the current options first.
int options = taskDialog.GetOptions();
options |= TDF_EXPANDED_BY_DEFAULT;
taskDialog.SetOptions(options);

taskDialog.DoModal();

CTaskDialog::SetFooterText

Updates the text on the footer of the CTaskDialog.

void SetFooterText(const CString& strFooterText);

Parameters

strFooterText
[in] The new text for the footer.

Remarks

The footer icon appears next to the footer text on the bottom of the CTaskDialog. You can change the footer icon with CTaskDialog::SetFooterIcon.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Setting new information to be able to reuse the dialog resource
taskDialog.SetWindowTitle(L"New title for the task dialog");
taskDialog.SetContent(L"New message to show the user.");
taskDialog.SetMainInstruction(L"Even more important!");
taskDialog.SetMainIcon(TD_ERROR_ICON);
taskDialog.SetDialogWidth(300);

// Add a footer
taskDialog.SetFooterText(L"Footer information for the dialog.");
taskDialog.SetFooterIcon(TD_INFORMATION_ICON);

// Add expansion information
taskDialog.SetExpansionArea(L"Additional information\non two lines.",
                            L"Click here for more information.",
                            L"Click here to hide the extra information.");

// Change the options to show the expanded information by default.
// It is necessary to retrieve the current options first.
int options = taskDialog.GetOptions();
options |= TDF_EXPANDED_BY_DEFAULT;
taskDialog.SetOptions(options);

taskDialog.DoModal();

CTaskDialog::SetMainIcon

Updates the main icon of the CTaskDialog.

void SetMainIcon(HICON hMainIcon);
void SetMainIcon(LPCWSTR lpszMainIcon);

Parameters

hMainIcon
[in] The new icon.

lpszMainIcon
[in] The new icon.

Remarks

This method throws an exception with the ENSURE macro if the CTaskDialog is displayed or the input parameter is NULL.

A CTaskDialog can only accept an HICON or LPCWSTR as a main icon. You can configure this by setting the TDF_USE_HICON_MAIN option in the constructor or in the CTaskDialog::SetOptions method. By default, the CTaskDialog is configured to use LPCWSTR as the input type for the main icon. This method generates an exception if you try to set the icon using the inappropriate type.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Setting new information to be able to reuse the dialog resource
taskDialog.SetWindowTitle(L"New title for the task dialog");
taskDialog.SetContent(L"New message to show the user.");
taskDialog.SetMainInstruction(L"Even more important!");
taskDialog.SetMainIcon(TD_ERROR_ICON);
taskDialog.SetDialogWidth(300);

// Add a footer
taskDialog.SetFooterText(L"Footer information for the dialog.");
taskDialog.SetFooterIcon(TD_INFORMATION_ICON);

// Add expansion information
taskDialog.SetExpansionArea(L"Additional information\non two lines.",
                            L"Click here for more information.",
                            L"Click here to hide the extra information.");

// Change the options to show the expanded information by default.
// It is necessary to retrieve the current options first.
int options = taskDialog.GetOptions();
options |= TDF_EXPANDED_BY_DEFAULT;
taskDialog.SetOptions(options);

taskDialog.DoModal();

CTaskDialog::SetMainInstruction

Updates the main instruction of the CTaskDialog.

void SetMainInstruction(const CString& strInstructions);

Parameters

strInstructions
[in] The new main instruction.

Remarks

The main instruction of the CTaskDialog class is text displayed to the user in a large bold font. It is located in the dialog box underneath the title bar.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Setting new information to be able to reuse the dialog resource
taskDialog.SetWindowTitle(L"New title for the task dialog");
taskDialog.SetContent(L"New message to show the user.");
taskDialog.SetMainInstruction(L"Even more important!");
taskDialog.SetMainIcon(TD_ERROR_ICON);
taskDialog.SetDialogWidth(300);

// Add a footer
taskDialog.SetFooterText(L"Footer information for the dialog.");
taskDialog.SetFooterIcon(TD_INFORMATION_ICON);

// Add expansion information
taskDialog.SetExpansionArea(L"Additional information\non two lines.",
                            L"Click here for more information.",
                            L"Click here to hide the extra information.");

// Change the options to show the expanded information by default.
// It is necessary to retrieve the current options first.
int options = taskDialog.GetOptions();
options |= TDF_EXPANDED_BY_DEFAULT;
taskDialog.SetOptions(options);

taskDialog.DoModal();

CTaskDialog::SetOptions

Configures the options for the CTaskDialog.

void SetOptions(int nOptionFlag);

Parameters

nOptionFlag
[in] The set of flags to use for the CTaskDialog.

Remarks

This method clears all the current options for the CTaskDialog. To preserve the current options, you must retrieve them first with CTaskDialog::GetOptions and combine them with the options that you want to set.

The following table lists all the valid options.

Name Description
TDF_ENABLE_HYPERLINKS Enables hyperlinks in the CTaskDialog.
TDF_USE_HICON_MAIN Configures the CTaskDialog to use a HICON for the main icon. The alternative is to use a LPCWSTR.
TDF_USE_HICON_FOOTER Configures the CTaskDialog to use a HICON for the footer icon. The alternative is to use a LPCWSTR.
TDF_ALLOW_DIALOG_CANCELLATION Enables the user to close the CTaskDialog by using the keyboard or by using the icon in the upper-right corner of the dialog box, even if the Cancel button is not enabled. If this flag is not set and the Cancel button is not enabled, the user cannot close the dialog box by using Alt+F4, the Escape key, or the title bar's close button.
TDF_USE_COMMAND_LINKS Configures the CTaskDialog to use command button controls.
TDF_USE_COMMAND_LINKS_NO_ICON Configures the CTaskDialog to use command button controls without displaying an icon next to the control. TDF_USE_COMMAND_LINKS overrides TDF_USE_COMMAND_LINKS_NO_ICON.
TDF_EXPAND_FOOTER_AREA Indicates the expansion area is currently expanded.
TDF_EXPANDED_BY_DEFAULT Determines whether the expansion area is expanded by default.
TDF_VERIFICATION_FLAG_CHECKED Indicates the verification check box is currently selected.
TDF_SHOW_PROGRESS_BAR Configures the CTaskDialog to display a progress bar.
TDF_SHOW_MARQUEE_PROGRESS_BAR Configures the progress bar to be a marquee progress bar. If you enable this option, you must set TDF_SHOW_PROGRESS_BAR to have the expected behavior.
TDF_CALLBACK_TIMER Indicates that the CTaskDialog callback interval is set to approximately 200 milliseconds.
TDF_POSITION_RELATIVE_TO_WINDOW Configures the CTaskDialog to be centered relative to the parent window. If this flag is not enabled, the CTaskDialog is centered relative to the monitor.
TDF_RTL_LAYOUT Configures the CTaskDialog for a right-to-left reading layout.
TDF_NO_DEFAULT_RADIO_BUTTON Indicates that no radio button is selected when the CTaskDialog appears.
TDF_CAN_BE_MINIMIZED Enables the user to minimize the CTaskDialog. To support this option, the CTaskDialog cannot be modal. MFC does not support this option because MFC does not support a modeless CTaskDialog.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Setting new information to be able to reuse the dialog resource
taskDialog.SetWindowTitle(L"New title for the task dialog");
taskDialog.SetContent(L"New message to show the user.");
taskDialog.SetMainInstruction(L"Even more important!");
taskDialog.SetMainIcon(TD_ERROR_ICON);
taskDialog.SetDialogWidth(300);

// Add a footer
taskDialog.SetFooterText(L"Footer information for the dialog.");
taskDialog.SetFooterIcon(TD_INFORMATION_ICON);

// Add expansion information
taskDialog.SetExpansionArea(L"Additional information\non two lines.",
                            L"Click here for more information.",
                            L"Click here to hide the extra information.");

// Change the options to show the expanded information by default.
// It is necessary to retrieve the current options first.
int options = taskDialog.GetOptions();
options |= TDF_EXPANDED_BY_DEFAULT;
taskDialog.SetOptions(options);

taskDialog.DoModal();

CTaskDialog::SetProgressBarMarquee

Configures a marquee bar for the CTaskDialog and adds it to the dialog box.

void SetProgressBarMarquee(
    BOOL bEnabled = TRUE,
    int nMarqueeSpeed = 0);

Parameters

bEnabled
[in] TRUE to enable the marquee bar; FALSE to disable the marquee bar and remove it from the CTaskDialog.

nMarqueeSpeed
[in] An integer that indicates the speed of the marquee bar.

Remarks

The marquee bar appears underneath the main text of the CTaskDialog class.

Use nMarqueeSpeed to set the speed of the marquee bar; larger values indicate a slower speed. A value of 0 for nMarqueeSpeed makes the marquee bar move at the default speed for Windows.

This method throws an exception with the ENSURE macro if nMarqueeSpeed is less than 0.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Add a marquee progress bar.
taskDialog.SetProgressBarMarquee();

taskDialog.DoModal();

// Remove the marquee bar and replace it with a standard progress bar
taskDialog.SetProgressBarMarquee(0);
taskDialog.SetProgressBarRange(0, 100);
taskDialog.SetProgressBarPosition(75);
taskDialog.SetProgressBarState();

taskDialog.DoModal();

CTaskDialog::SetProgressBarPosition

Adjusts the position of the progress bar.

void SetProgressBarPosition(int nProgressPos);

Parameters

nProgressPos
[in] The position for the progress bar.

Remarks

This method throws an exception with the ENSURE macro if nProgressPos is not in the progress bar range. You can change the progress bar range with CTaskDialog::SetProgressBarRange.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Add a marquee progress bar.
taskDialog.SetProgressBarMarquee();

taskDialog.DoModal();

// Remove the marquee bar and replace it with a standard progress bar
taskDialog.SetProgressBarMarquee(0);
taskDialog.SetProgressBarRange(0, 100);
taskDialog.SetProgressBarPosition(75);
taskDialog.SetProgressBarState();

taskDialog.DoModal();

CTaskDialog::SetProgressBarRange

Adjusts the range of the progress bar.

void SetProgressBarRange(
    int nRangeMin,
    int nRangeMax);

Parameters

nRangeMin
[in] The lower bound of the progress bar.

nRangeMax
[in] The upper bound of the progress bar.

Remarks

The position of the progress bar is relative to nRangeMin and nRangeMax. For example, if nRangeMin is 50 and nRangeMax is 100, a position of 75 is halfway across the progress bar. Use CTaskDialog::SetProgressBarPosition to set the position of the progress bar.

To display the progress bar, the option TDF_SHOW_PROGRESS_BAR must be enabled and TDF_SHOW_MARQUEE_PROGRESS_BAR must not be enabled. This method automatically sets TDF_SHOW_PROGRESS_BAR and clears TDF_SHOW_MARQUEE_PROGRESS_BAR. Use CTaskDialog::SetOptions to manually change the options for this instance of the CTaskDialog Class.

This method throws an exception with the ENSURE macro if nRangeMin is not less than nRangeMax. This method also throws an exception if the CTaskDialog is already displayed and has a marquee progress bar.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Add a marquee progress bar.
taskDialog.SetProgressBarMarquee();

taskDialog.DoModal();

// Remove the marquee bar and replace it with a standard progress bar
taskDialog.SetProgressBarMarquee(0);
taskDialog.SetProgressBarRange(0, 100);
taskDialog.SetProgressBarPosition(75);
taskDialog.SetProgressBarState();

taskDialog.DoModal();

CTaskDialog::SetProgressBarState

Sets the state of the progress bar and displays it on the CTaskDialog.

void SetProgressBarState(int nState = PBST_NORMAL);

Parameters

nState
[in] The state of the progress bar. See the Remarks section for the possible values.

Remarks

This method throws an exception with the ENSURE macro if the CTaskDialog is already displayed and has a marquee progress bar.

The following table lists the possible values for nState. In all these cases, the progress bar will fill with the regular color until it reaches the designated stop position. At that point it will change color based on the state.

Name Description
PBST_NORMAL After the progress bar fills, the CTaskDialog does not change the color of the bar. By default, the regular color is green.
PBST_ERROR After the progress bar fills, the CTaskDialog changes the color of the bar to the error color. By default, this is red.
PBST_PAUSED After the progress bar fills, the CTaskDialog changes the color of the bar to the paused color. By default, this is yellow.

You can set where the progress bar stops with CTaskDialog::SetProgressBarPosition.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Add a marquee progress bar.
taskDialog.SetProgressBarMarquee();

taskDialog.DoModal();

// Remove the marquee bar and replace it with a standard progress bar
taskDialog.SetProgressBarMarquee(0);
taskDialog.SetProgressBarRange(0, 100);
taskDialog.SetProgressBarPosition(75);
taskDialog.SetProgressBarState();

taskDialog.DoModal();

CTaskDialog::SetRadioButtonOptions

Enables or disables a radio button.

void SetRadioButtonOptions(
    int nRadioButtonID,
    BOOL bEnabled);

Parameters

nRadioButtonID
[in] The ID of the radio button control.

bEnabled
[in] TRUE to enable the radio button; FALSE to disable the radio button.

Remarks

This method throws an exception with the ENSURE macro if nRadioButtonID is not a valid ID for a radio button.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

taskDialog.AddRadioButton(201, L"First option");
taskDialog.AddRadioButton(202, L"Second option");
taskDialog.AddRadioButton(203, L"Third option");

taskDialog.DoModal();
int selection = taskDialog.GetSelectedRadioButtonID();

switch (selection)
{
case 201:
   // TODO: Place processing here for the first
   // radio button.
   break;

case 202:
   // TODO: Place processing here for the second
   // radio button.
   break;

case 203:
   // TODO: Place processing here for the third
   // radio button.
   break;

default:
   break;
}

// Remove all the radio buttons so that we can use the same task
// dialog with new radio buttons.
taskDialog.RemoveAllRadioButtons();

taskDialog.AddRadioButton(301, L"New first option");
taskDialog.AddRadioButton(302, L"New second option");
taskDialog.AddRadioButton(303,
                          L"New third option should be disabled");

// Change the default radio button to the second option
taskDialog.SetDefaultRadioButton(302);

// Make sure the third option is disabled.
if (taskDialog.IsRadioButtonEnabled(303))
{
   taskDialog.SetRadioButtonOptions(303, FALSE);
}

taskDialog.DoModal();
selection = taskDialog.GetSelectedRadioButtonID();

switch (taskDialog.GetSelectedRadioButtonID())
{
case 301:
   // TODO: Place processing here for new first
   // command button control.
   break;

case 302:
   // TODO: Place processing here for new second
   // command button control.
   break;

case 303:
   // TODO: Place processing here for the new third
   // command button control.
   break;

default:
   break;
}

// Remove all the radio button controls and add new ones from
// the string table resource.
taskDialog.RemoveAllRadioButtons();
taskDialog.LoadRadioButtons(1001, 1005);

CTaskDialog::SetVerificationCheckbox

Sets the checked state of the verification check box.

void SetVerificationCheckbox(BOOL bChecked);

Parameters

bChecked
[in] TRUE to have the verification check box selected when the CTaskDialog is displayed; FALSE to have the verification check box unselected when the CTaskDialog is displayed.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Add the verification checkbox and set the default state.
taskDialog.SetVerificationCheckboxText(L"Remember your selection.");
taskDialog.SetVerificationCheckbox(false);

taskDialog.DoModal();

if (taskDialog.GetVerificationCheckboxState())
{
   // TODO: Write settings of the task dialog to the registry
}

CTaskDialog::SetVerificationCheckboxText

Sets the text that is displayed to the right of the verification check box.

void SetVerificationCheckboxText(CString& strVerificationText);

Parameters

strVerificationText
[in] The text that this method displays next to the verification check box.

Remarks

This method throws an exception with the ENSURE macro if this instance of the CTaskDialog class is already displayed.

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Add the verification checkbox and set the default state.
taskDialog.SetVerificationCheckboxText(L"Remember your selection.");
taskDialog.SetVerificationCheckbox(false);

taskDialog.DoModal();

if (taskDialog.GetVerificationCheckboxState())
{
   // TODO: Write settings of the task dialog to the registry
}

CTaskDialog::SetWindowTitle

Sets the title of the CTaskDialog.

void SetWindowTitle(CString& strWindowTitle);

Parameters

strWindowTitle
[in] The new title for the CTaskDialog.

Remarks

Example

// TODO: Replace the strings below with the appropriate message,
// main instruction, and dialog title
CString message("This is an important message to the user.");
CString mainInstruction("Important!\nPlease read!");
CString title("Alert Dialog");

CTaskDialog taskDialog(message, mainInstruction, title,
                       TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);

// Setting new information to be able to reuse the dialog resource
taskDialog.SetWindowTitle(L"New title for the task dialog");
taskDialog.SetContent(L"New message to show the user.");
taskDialog.SetMainInstruction(L"Even more important!");
taskDialog.SetMainIcon(TD_ERROR_ICON);
taskDialog.SetDialogWidth(300);

// Add a footer
taskDialog.SetFooterText(L"Footer information for the dialog.");
taskDialog.SetFooterIcon(TD_INFORMATION_ICON);

// Add expansion information
taskDialog.SetExpansionArea(L"Additional information\non two lines.",
                            L"Click here for more information.",
                            L"Click here to hide the extra information.");

// Change the options to show the expanded information by default.
// It is necessary to retrieve the current options first.
int options = taskDialog.GetOptions();
options |= TDF_EXPANDED_BY_DEFAULT;
taskDialog.SetOptions(options);

taskDialog.DoModal();

CTaskDialog::ShowDialog

Creates and displays a CTaskDialog.

static INT_PTR ShowDialog(
    const CString& strContent,
    const CString& strMainInstruction,
    const CString& strTitle,
    int nIDCommandControlsFirst,
    int nIDCommandControlsLast,
    int nCommonButtons = TDCBF_YES_BUTTON | TDCBF_NO_BUTTON,
    int nTaskDialogOptions = TDF_ENABLE_HYPERLINKS | TDF_USE_COMMAND_LINKS,
    const CString& strFooter = _T(""));

Parameters

strContent
[in] The string to use for the content of the CTaskDialog.

strMainInstruction
[in] The main instruction of the CTaskDialog.

strTitle
[in] The title of the CTaskDialog.

nIDCommandControlsFirst
[in] The string ID of the first command.

nIDCommandControlsLast
[in] The string ID of the last command.

nCommonButtons
[in] A mask of the buttons to add to the CTaskDialog.

nTaskDialogOptions
[in] The set of options to use for the CTaskDialog.

strFooter
[in] The string to use as the footer.

Return Value

An integer that corresponds to the selection made by the user.

Remarks

This static method enables you to create an instance of the CTaskDialog class without explicitly creating a CTaskDialog object in your code. Because there is no CTaskDialog object, you cannot call any other methods of the CTaskDialog if you use this method to show a CTaskDialog to the user.

This method creates command button controls by using data from the resource file of your application. The string table in the resource file has several strings with associated string IDs. This method adds a command button control for each valid entry in the string table between nIDCommandControlsFirst and nCommandControlsLast, inclusive. For these command button controls, the string in the string table is the control's caption and the string ID is the control's ID.

See CTaskDialog::SetOptions for a list of valid options.

The CTaskDialog closes when the user selects a common button, a command link control, or closes the CTaskDialog. The return value is the identifier that indicates how the user closed the dialog box.

Example

// TODO: Replace the string below with the actual message to the user
CString message("Important information to the user");
// TODO: Replace the string below with the title of this project
CString title("Project Title");

CString emptyString;

if (CTaskDialog::IsSupported())
{
   CTaskDialog::ShowDialog(message, emptyString, title, 0, 0,
                           TDCBF_OK_BUTTON);
}
else
{
   AfxMessageBox(message);
}

CTaskDialog::TaskDialogCallback

The framework calls this method in response to various Windows messages.

friend:
HRESULT TaskDialogCallback(
    HWND hWnd,
    UINT uNotification,
    WPARAM wParam,
    LPARAM lParam,
    LONG_PTR dwRefData);

Parameters

hwnd
[in] A handle to the m_hWnd structure for the CTaskDialog.

uNotification
[in] The notification code that specifies the generated message.

wParam
[in] More information about the message.

lParam
[in] More information about the message.

dwRefData
[in] A pointer to the CTaskDialog object that the callback message applies to.

Return Value

Depends on the specific notification code. See the Remarks section for more information.

Remarks

The default implementation of TaskDialogCallback handles the specific message and then calls the appropriate On method of the CTaskDialog Class. For example, in response to the TDN_BUTTON_CLICKED message, TaskDialogCallback calls CTaskDialog::OnCommandControlClick.

The values for wParam and lParam depend on the specific generated message. It is possible for either or both of these values to be empty. The following table lists the default notifications that are supported and what the values of wParam and lParam represent. If you override this method in a derived class, you should implement the callback code for each message in the following table.

Notification Message wParam Value lParam Value
TDN_CREATED Not used. Not used.
TDN_NAVIGATED Not used. Not used.
TDN_BUTTON_CLICKED The command button control ID. Not used.
TDN_HYPERLINK_CLICKED Not used. A LPCWSTR structure that contains the link.
TDN_TIMER Time in milliseconds since the CTaskDialog was created or the timer was reset. Not used.
TDN_DESTROYED Not used. Not used.
TDN_RADIO_BUTTON_CLICKED The radio button ID. Not used.
TDN_DIALOG_CONSTRUCTED Not used. Not used.
TDN_VERIFICATION_CLICKED 1 if the check box is checked, 0 if it is not. Not used.
TDN_HELP Not used. Not used.
TDN_EXPANDO_BUTTON_CLICKED 0 if the expansion area is collapsed; nonzero if the expansion text is displayed. Not used.

See also

Classes
CObject Class
Hierarchy Chart
Walkthrough: Adding a CTaskDialog to an Application