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.
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);
CTaskDialog::NavigateTo
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