CTaskDialog 类
功能类似于消息框，但可向用户显示额外信息的弹出对话框。 CTaskDialog 还包括从用户那里收集信息的功能。
语法
class CTaskDialog : public CObject
成员
构造函数
| 名称 | 描述 |
|---|---|
| CTaskDialog::CTaskDialog | 构造 CTaskDialog 对象。 |
方法
数据成员
| 名称 | 描述 |
|---|---|
m_aButtons |
CTaskDialog 的命令按钮控件数组。 |
m_aRadioButtons |
CTaskDialog 的单选按钮控件数组。 |
m_bVerified |
TRUE 表示已选中验证复选框；FALSE 表示未选中。 |
m_footerIcon |
CTaskDialog 的页脚中的图标。 |
m_hWnd |
CTaskDialog 的窗口的句柄。 |
m_mainIcon |
CTaskDialog 的主图标。 |
m_nButtonDisabled |
一个掩码，指示禁用了哪些常见按钮。 |
m_nButtonElevation |
一个掩码，指示哪些常见按钮需要 UAC 提升。 |
m_nButtonId |
所选择的命令按钮控件的 ID。 |
m_nCommonButton |
一个掩码，指示哪些常见按钮显示在 CTaskDialog 上。 |
m_nDefaultCommandControl |
显示 CTaskDialog 时所选择的命令按钮控件的 ID。 |
m_nDefaultRadioButton |
显示 CTaskDialog 时选择的单选按钮控件的 ID。 |
m_nFlags |
一个掩码，指示 CTaskDialog 的选项。 |
m_nProgressPos |
进度栏的当前位置。 该值必须介于 m_nProgressRangeMin 和 m_nProgressRangeMax 之间。 |
m_nProgressRangeMax |
进度栏的最大值。 |
m_nProgressRangeMin |
进度栏的最小值。 |
m_nProgressState |
进度栏的状态。 有关详细信息，请参阅 CTaskDialog::SetProgressBarState。 |
m_nRadioId |
所选择的单选按钮控件的 ID。 |
m_nWidth |
CTaskDialog 的宽度（以像素为单位）。 |
m_strCollapse |
隐藏展开信息时，CTaskDialog 显示在展开框右侧的字符串。 |
m_strContent |
CTaskDialog 的内容字符串。 |
m_strExpand |
显示展开信息时，CTaskDialog 显示在展开框右侧的字符串。 |
m_strFooter |
CTaskDialog 的页脚。 |
m_strInformation |
CTaskDialog 的展开信息。 |
m_strMainInstruction |
CTaskDialog 的主说明。 |
m_strTitle |
CTaskDialog 的标题。 |
m_strVerification |
CTaskDialog 显示在验证复选框右侧的字符串。 |
注解
CTaskDialog 类将替换标准 Windows 消息框，并具有其他功能（例如新控件）以从用户那里收集信息。 此类位于 Visual Studio 2010 及更高版本中的 MFC 库中。 从 Windows Vista 开始可以使用 CTaskDialog。 早期版本的 Windows 无法显示 CTaskDialog 对象。 使用 CTaskDialog::IsSupported 可确定当前用户是否可以在运行时显示任务对话框。 仍支持标准 Windows 消息框。
仅当使用 Unicode 库生成应用程序时，CTaskDialog 才可用。
CTaskDialog 有两个不同的构造函数。 一个构造函数用于指定两个命令按钮和最多六个常见按钮控件。 可以在创建 CTaskDialog 后添加更多命令按钮。 第二个构造函数不支持任何命令按钮，但你可以添加数量不限的常见按钮控件。 有关这些构造函数的详细信息，请参阅 CTaskDialog::CTaskDialog。
下图显示了一个 CTaskDialog 示例，用于说明某些控件的位置。
CTaskDialog 示例
要求
所需的最低操作系统：Windows Vista
标头：afxtaskdialog.h
CTaskDialog::AddCommandControl
向 CTaskDialog添加新命令按钮控件。
void AddCommandControl(
int nCommandControlID,
const CString& strCaption,
BOOL bEnabled = TRUE,
BOOL bRequiresElevation = FALSE);
参数
nCommandControlID
[in] 命令控件标识号。
strCaption
[in] CTaskDialog 向用户显示的字符串。 使用此字符串可解释命令的用途。
bEnabled
[in] 一个布尔参数，指示新按钮是已启用还是已禁用。
bRequiresElevation
[in] 一个布尔参数，指示命令是否需要提升。
注解
CTaskDialog Class 可以显示数量不限的命令按钮控件。 但是，如果 CTaskDialog 显示任何命令按钮控件，则最多可以显示六个按钮。 如果 CTaskDialog 没有命令按钮控件，则可以显示数量不限的按钮。
当用户选择命令按钮控件时，CTaskDialog 会关闭。 如果应用程序使用 CTaskDialog::DoModal 来显示对话框，DoModal 将返回所选择的命令按钮控件的 nCommandControlID。
示例
// 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
向 CTaskDialog 添加单选按钮。
void CTaskDialog::AddRadioButton(
int nRadioButtonID,
const CString& strCaption,
BOOL bEnabled = TRUE);
参数
nRadioButtonID
[in] 单选按钮的标识号。
strCaption
[in] CTaskDialog 显示在单选按钮旁边的字符串。
bEnabled
[in] 一个布尔参数，指示单选按钮是否已启用。
注解
CTaskDialog 类的单选按钮使你可以从用户那里收集信息。 使用函数 CTaskDialog::GetSelectedRadioButtonID 可确定选择了哪个单选按钮。
CTaskDialog 不要求 nRadioButtonID 参数对于每个单选按钮都是唯一的。 但是，如果不对每个单选按钮使用不同的标识符，则可能会遇到意外行为。
示例
// 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
以编程方式单击命令按钮控件或常见按钮。
protected:
void ClickCommandControl(int nCommandControlID) const;
参数
nCommandControlID
[in] 要单击的控件的命令 ID。
注解
此方法将生成 Windows 消息 TDM_CLICK_BUTTON。
CTaskDialog::ClickRadioButton
以编程方式单击单选按钮。
protected:
void ClickRadioButton(int nRadioButtonID) const;
参数
nRadioButtonID
[in] 要单击的单选按钮的 ID。
备注
此方法将生成 Windows 消息 TDM_CLICK_RADIO_BUTTON。
CTaskDialog::CTaskDialog
创建 CTaskDialog 类 的实例。
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(""));
参数
strContent
[in] 要用于 CTaskDialog 内容的字符串。
strMainInstruction
[in] CTaskDialog 的主说明。
strTitle
[in] CTaskDialog 的标题。
nCommonButtons
[in] 要添加到 CTaskDialog 的常见按钮的掩码。
nTaskDialogOptions
[in] 要用于 CTaskDialog 的选项集。
strFooter
[in] 要用作页脚的字符串。
nIDCommandControlsFirst
[in] 第一个命令的字符串 ID。
nIDCommandControlsLast
[in] 最后一个命令的字符串 ID。
注解
可以通过两种方法向应用程序添加 CTaskDialog。 第一种方法是使用其中一个构造函数创建 CTaskDialog 并使用 CTaskDialog::DoModal 显示它。 第二种方法是使用静态函数 CTaskDialog::ShowDialog，这样你可以在不显式创建 CTaskDialog 对象的情况下显示 CTaskDialog 对象。
第二个构造函数使用应用程序资源文件中的数据创建命令按钮控件。 资源文件中的字符串表具有多个字符串，其中包含关联的字符串 ID。 此方法将为字符串表中 nIDCommandControlsFirst 和 nCommandControlsLast 之间（含）的每个有效条目添加一个命令按钮控件。 对于这些命令按钮控件，字符串表中的字符串是控件的标题，字符串 ID 是控件的 ID。
有关有效选项列表，请参阅 CTaskDialog::SetOptions。
示例
// 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
显示 CTaskDialog 并使其模式化。
INT_PTR DoModal (HWND hParent = ::GetActiveWindow());
参数
hParent
[in] CTaskDialog 的父窗口。
返回值
一个整数，对应于用户所做的选择。
备注
显示 CTaskDialog 的这个实例。 然后，应用程序将等待用户关闭对话框。
当用户选择常见按钮、命令链接控件或关闭 CTaskDialog 时，CTaskDialog 会关闭。 返回值是指示用户如何关闭的对话框的标识符。
示例
// 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
检索常见按钮数。
int GetCommonButtonCount() const;
返回值
可用的常见按钮数。
注解
常见按钮是你提供给 CTaskDialog::CTaskDialog 的默认按钮。 CTaskDialog 类显示对话框底部的按钮。
CommCtrl.h 中提供了按钮的枚举列表。
CTaskDialog::GetCommonButtonFlag
将标准 Windows 按钮转换为与 CTaskDialog 类关联的常见按钮类型。
int GetCommonButtonFlag(int nButtonId) const;
参数
nButtonId
[in] 标准 Windows 按钮值。
返回值
相应 CTaskDialog 常见按钮的值。 如果没有相应的常见按钮，此方法将返回 0。
CTaskDialog::GetCommonButtonId
将与 CTaskDialog 类关联的其中一种常见按钮转换为标准 Windows 按钮。
int GetCommonButtonId(int nFlag);
参数
nFlag
[in] 与 CTaskDialog 类关联的常见按钮类型。
返回值
相应标准 Windows 按钮的值。 如果没有相应的 Windows 按钮，该方法将返回 0。
CTaskDialog::GetOptions
返回此 CTaskDialog 的选项标志。
int GetOptions() const;
返回值
CTaskDialog 的标志。
备注
有关可用于 CTaskDialog 类的选项的详细信息，请参阅 CTaskDialog::SetOptions。
示例
// 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
返回所选择的命令按钮控件。
int GetSelectedCommandControlID() const;
返回值
当前命令按钮控件的 ID。
备注
无需使用此方法来检索用户选择的命令按钮的 ID。 该 ID 由 CTaskDialog::DoModal 或 CTaskDialog::ShowDialog 返回。
示例
// 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
返回所选择的单选按钮。
int GetSelectedRadioButtonID() const;
返回值
所选择的单选按钮的 ID。
备注
用户关闭对话框以检索选择的单选按钮后，可以使用此方法。
示例
// 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
检索验证复选框的状态。
BOOL GetVerificationCheckboxState() const;
返回值
如果复选框已选中，则为 TRUE；否则为 FALSE。
示例
// 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
确定是启用了命令按钮控件还是启用了按钮。
BOOL IsCommandControlEnabled(int nCommandControlID) const;
参数
nCommandControlID
[in] 要测试的命令按钮控件或按钮的 ID。
返回值
如果控件已启用，则为 TRUE，否则为 FALSE。
备注
可以使用此方法来确定命令按钮控件和 CTaskDialog 类*的常见按钮的可用性。
如果 nCommandControlID 不是常见的 CTaskDialog 按钮或命令按钮控件的有效标识符，此方法将引发异常。
示例
// 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
确定是否启用了单选按钮。
BOOL IsRadioButtonEnabled(int nRadioButtonID) const;
参数
nRadioButtonID
[in] 要测试的单选按钮的 ID。
返回值
如果单选按钮已启用，则为 TRUE，否则为 FALSE。
注解
如果 nRadioButtonID 不是单选按钮的有效标识符，此方法将引发异常。
示例
// 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
确定运行应用程序的计算机是否支持 CTaskDialog。
static BOOL IsSupported();
返回值
如果计算机支持 CTaskDialog，则为 TRUE，否则为 FALSE。
注解
使用此函数可确定运行应用程序的计算机在运行时是否支持 CTaskDialog 类。 如果计算机不支持 CTaskDialog，则应提供另一种向用户传达信息的方法。 如果应用程序尝试在不支持 CTaskDialog 类的计算机上使用 CTaskDialog，应用程序将崩溃。
示例
// 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
使用字符串表中的数据添加命令按钮控件。
void LoadCommandControls(
int nIDCommandControlsFirst,
int nIDCommandControlsLast);
参数
nIDCommandControlsFirst
[in] 第一个命令的字符串 ID。
nIDCommandControlsLast
[in] 最后一个命令的字符串 ID。
备注
此方法将使用应用程序资源文件中的数据创建命令按钮控件。 资源文件中的字符串表具有多个字符串，其中包含关联的字符串 ID。 使用此方法添加的新命令按钮控件将使用字符串作为控件标题，字符串 ID 作为控件 ID。 所选字符串的范围由 nIDCommandControlsFirst 和 nCommandControlsLast（含）提供。 如果范围内有空条目，该方法不会为该条目添加命令按钮控件。
默认情况下，新命令按钮控件已启用，并且不需要提升。
示例
// 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
使用字符串表中的数据添加单选按钮控件。
void LoadRadioButtons(
int nIDRadioButtonsFirst,
int nIDRadioButtonsLast);
参数
nIDRadioButtonsFirst
[in] 第一个单选按钮的字符串 ID。
nIDRadioButtonsLast
[in] 最后一个单选按钮的字符串 ID。
备注
此方法将使用应用程序资源文件中的数据创建单选按钮。 资源文件中的字符串表具有多个字符串，其中包含关联的字符串 ID。 使用此方法添加的新单选按钮将使用字符串作为单选按钮标题，字符串 ID 作为单选按钮 ID。 所选字符串的范围由 nIDRadioButtonsFirst 和 nRadioButtonsLast（含）提供。 如果范围内有空条目，该方法不会为该条目添加单选按钮控件。
默认情况下，将启用新的单选按钮。
示例
// 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
将焦点转移到另一个 CTaskDialog。
protected:
void NavigateTo(CTaskDialog& oTaskDialog) const;
参数
oTaskDialog
[in] 接收焦点的 CTaskDialog。
备注
此方法在显示 oTaskDialog 之前隐藏当前 CTaskDialog。 oTaskDialog 与当前 CTaskDialog 显示在相同的位置。
CTaskDialog::OnCommandControlClick
当用户单击命令按钮控件时，框架将调用此方法。
virtual HRESULT OnCommandControlClick(int nCommandControlID);
参数
nCommandControlID
[in] 用户选择的命令按钮控件的 ID。
返回值
默认实现会返回 S_OK。
注解
在派生类中重写此方法可实现自定义行为。
CTaskDialog::OnCreate
框架在创建 CTaskDialog 后调用此方法。
virtual HRESULT OnCreate();
返回值
默认实现会返回 S_OK。
注解
在派生类中重写此方法可实现自定义行为。
CTaskDialog::OnDestroy
框架在销毁 CTaskDialog 之前调用此方法。
virtual HRESULT OnDestroy();
返回值
默认实现会返回 S_OK。
备注
在派生类中重写此方法可实现自定义行为。
CTaskDialog::OnExpandButtonClick
当用户单击展开按钮时，框架将调用此方法。
virtual HRESULT OnExpandButtonClicked(BOOL bExpanded);
参数
bExpanded
[in] 非零值表示显示额外信息；0 表示隐藏额外信息。
返回值
默认实现会返回 S_OK。
注解
在派生类中重写此方法可实现自定义行为。
CTaskDialog::OnHelp
当用户请求帮助时，框架将调用此方法。
virtual HRESULT OnHelp();
返回值
默认实现会返回 S_OK。
注解
在派生类中重写此方法可实现自定义行为。
CTaskDialog::OnHyperlinkClick
当用户单击超链接时，框架将调用此方法。
virtual HRESULT OnHyperlinkClick(const CString& strHref);
参数
strHref
[in] 表示超链接的字符串。
返回值
默认实现会返回 S_OK。
备注
此方法在返回 S_OK 之前调用 ShellExecute。
在派生类中重写此方法可实现自定义行为。
CTaskDialog::OnInit
当初始化 CTaskDialog 时，框架将调用此方法。
virtual HRESULT OnInit();
返回值
默认实现会返回 S_OK。
备注
在派生类中重写此方法可实现自定义行为。
CTaskDialog::OnNavigatePage
框架调用此方法以响应 CTaskDialog::NavigateTo 方法。
virtual HRESULT OnNavigatePage();
返回值
默认实现会返回 S_OK。
备注
在派生类中重写此方法可实现自定义行为。
CTaskDialog::OnRadioButtonClick
当用户选择一个单选按钮控件时，框架将调用此方法。
virtual HRESULT OnRadioButtonClick(int nRadioButtonID);
参数
nRadioButtonID
[in] 用户单击的单选按钮控件的 ID。
返回值
默认实现会返回 S_OK。
注解
在派生类中重写此方法可实现自定义行为。
CTaskDialog::OnTimer
当计时器过期时，框架将调用此方法。
virtual HRESULT OnTimer(long lTime);
参数
lTime
[in] 创建 CTaskDialog 计时器或计时器重置后的时间（以毫秒为单位）。
返回值
默认实现会返回 S_OK。
注解
在派生类中重写此方法可实现自定义行为。
CTaskDialog::OnVerificationCheckboxClick
当用户单击验证复选框时，框架将调用此方法。
virtual HRESULT OnVerificationCheckboxClick(BOOL bChecked);
参数
bChecked
[in] TRUE 表示验证复选框已选中，FALSE 表示未选中。
返回值
默认实现会返回 S_OK。
注解
在派生类中重写此方法可实现自定义行为。
CTaskDialog::RemoveAllCommandControls
从 CTaskDialog 中移除所有命令按钮控件。
void RemoveAllCommandControls();
示例
// 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
从 CTaskDialog 中移除所有单选按钮。
void RemoveAllRadioButtons();
示例
// 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
更新 CTaskDialog 上的命令按钮控件。
void SetCommandControlOptions(
int nCommandControlID,
BOOL bEnabled,
BOOL bRequiresElevation = FALSE);
参数
nCommandControlID
[in] 要更新的命令控件的 ID。
bEnabled
[in] 一个布尔参数，指示指定的命令按钮控件是已启用还是已禁用。
bRequiresElevation
[in] 一个布尔参数，指示指定的命令按钮控件是否需要提升。
备注
使用此方法可更改命令按钮控件在添加到 CTaskDialog 类之后是已启用还是需要提升。
示例
// 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
更新要启用并且需要 UAC 提升的一个常见按钮子集。
void SetCommonButtonOptions(
int nDisabledButtonMask,
int nElevationButtonMask = 0);
参数
nDisabledButtonMask
[in] 要禁用的常见按钮的掩码。
nElevationButtonMask
[in] 需要提升的常见按钮的掩码。
备注
可以使用构造函数 CTaskDialog::CTaskDialog 和 CTaskDialog::SetCommonButtons 方法设置可用于 CTaskDialog 类实例的常见按钮。 CTaskDialog::SetCommonButtonOptions 不支持添加新的常见按钮。
如果使用此方法禁用或提升不可用于此 CTaskDialog 的常见按钮，此方法将引发异常，并显示 ENSURE 宏。
此方法将启用任何可用于 CTaskDialog 但不在 nDisabledButtonMask 中的按钮，即使以前禁用了该按钮也是如此。 此方法以类似的方式处理提升：如果常见按钮可用但未包含在 nElevationButtonMask 中，则它会记录常见按钮不需要提升。
示例
// 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
向 CTaskDialog 添加常见按钮。
void SetCommonButtons(
int nButtonMask,
int nDisabledButtonMask = 0,
int nElevationButtonMask = 0);
参数
nButtonMask
[in] 要添加到 CTaskDialog 的按钮的掩码。
nDisabledButtonMask
[in] 要禁用的按钮的掩码。
nElevationButtonMask
[in] 需要提升的按钮的掩码。
注解
为 CTaskDialog 类实例创建显示窗口后，无法调用此方法。 如果这样做，此方法将引发异常。
nButtonMask 指示的按钮将替代以前添加到 CTaskDialog 的任何常见按钮。 只有 nButtonMask 中指示的按钮可用。
如果 nDisabledButtonMask 或 nElevationButtonMask 包含不在 nButtonMask 中的按钮，则此方法将引发异常，并显示 ENSURE 宏。
默认情况下，所有常见按钮都已启用，并且不需要提升。
示例
// 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
更新 CTaskDialog 的内容。
void SetContent(const CString& strContent);
参数
strContent
[in] 要向用户显示的字符串。
备注
CTaskDialog 类的内容是对话框主部分中向用户显示的文本。
示例
// 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
指定默认命令按钮控件。
void SetDefaultCommandControl(int nCommandControlID);
参数
nCommandControlID
[in] 要设置为默认值的常见按钮控件的 ID。
备注
默认命令按钮控件是 CTaskDialog 首次向用户显示时选择的控件。
如果此方法找不到 nCommandControlID 指定的命令按钮控件，此方法将引发异常。
示例
// 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
指定默认单选按钮。
void SetDefaultRadioButton(int nRadioButtonID);
参数
nRadioButtonID
[in] 要设置为默认值的单选按钮的 ID。
注解
默认单选按钮是 CTaskDialog 首次向用户显示时选择的按钮。
如果此方法找不到 nRadioButtonID 指定的单选按钮，将引发异常。
示例
// 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
调整 CTaskDialog 的宽度。
void SetDialogWidth(int nWidth = 0);
参数
nWidth
[in] 对话框的宽度（以像素为单位）。
备注
参数 nWidth 必须大于或等于 0。 否则，此方法将引发异常。
如果 nWidth 设置为 0，此方法会将对话框设置为默认大小。
示例
// 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
更新 CTaskDialog 的展开区域。
void SetExpansionArea(
const CString& strExpandedInformation,
const CString& strCollapsedLabel = _T(""),
const CString& strExpandedLabel = _T(""));
参数
strExpandedInformation
[in] 当用户单击展开按钮时，CTaskDialog 显示在对话框的主体中的字符串。
strCollapsedLabel
[in] 折叠展开区域时，CTaskDialog 显示在展开按钮旁边的字符串。
strExpandedLabel
[in] 显示展开区域时，CTaskDialog 显示在展开按钮旁边的字符串。
备注
CTaskDialog 类的展开区域使你可以向用户提供额外信息。 展开区域位于 CTaskDialog 的主部分，在标题和内容字符串的下方。
当 CTaskDialog 首次显示时，不会显示展开的信息，并将 strCollapsedLabel 放在展开按钮的旁边。 当用户单击展开按钮时，CTaskDialog 将显示 strExpandedInformation 并将标签更改为 strExpandedLabel。
示例
// 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
更新 CTaskDialog 的页脚图标。
void SetFooterIcon(HICON hFooterIcon);
void SetFooterIcon(LPCWSTR lpszFooterIcon);
参数
hFooterIcon
[in] CTaskDialog 的新图标。
lpszFooterIcon
[in] CTaskDialog 的新图标。
备注
页脚图标显示在 CTaskDialog 类的底部。 它可以具有关联的页脚文本。 可以使用 CTaskDialog::SetFooterText 更改页脚文本。
如果显示了 或者输入参数为 NULL，此方法将引发异常，并显示 ENSURECTaskDialog 宏。
CTaskDialog 只能接受 HICON 或 LPCWSTR 作为页脚图标。 此方法通过在构造函数或 CTaskDialog::SetOptions 中设置选项 TDF_USE_HICON_FOOTER 来进行配置。 默认情况下，CTaskDialog 配置为使用 LPCWSTR 作为页脚图标的输入类型。 如果尝试使用不适当的类型设置图标，此方法将生成异常。
示例
// 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
更新 CTaskDialog 的页脚上的文本。
void SetFooterText(const CString& strFooterText);
参数
strFooterText
[in] 页脚的新文本。
备注
页脚图标显示在 CTaskDialog 底部页脚文本的旁边。 可以使用 CTaskDialog::SetFooterIcon 更改页脚图标。
示例
// 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
更新 CTaskDialog 的主图标。
void SetMainIcon(HICON hMainIcon);
void SetMainIcon(LPCWSTR lpszMainIcon);
参数
hMainIcon
[in] 新图标。
lpszMainIcon
[in] 新图标。
注解
如果显示了 或者输入参数为 NULL，此方法将引发异常，并显示 ENSURECTaskDialog 宏。
CTaskDialog 只能接受 HICON 或 LPCWSTR 作为主图标。 可以通过在构造函数或 CTaskDialog::SetOptions 方法中设置 TDF_USE_HICON_MAIN 选项来配置此方法。 默认情况下，CTaskDialog 配置为使用 LPCWSTR 作为主图标的输入类型。 如果尝试使用不适当的类型设置图标，此方法将生成异常。
示例
// 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
更新 CTaskDialog 的主说明。
void SetMainInstruction(const CString& strInstructions);
参数
strInstructions
[in] 新的主说明。
注解
CTaskDialog 类的主说明是以大粗体字体向用户显示的文本。 它位于标题栏下的对话框中。
示例
// 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
配置 CTaskDialog 的选项。
void SetOptions(int nOptionFlag);
参数
nOptionFlag
[in] 要用于 CTaskDialog 的标志集。
注解
此方法将清除 CTaskDialog 的所有当前选项。 若要保留当前选项，必须先使用 CTaskDialog::GetOptions 检索它们，并将其与要设置的选项组合在一起。
下表列出了所有有效选项。
| 名称 | 描述 |
|---|---|
| TDF_ENABLE_HYPERLINKS | 在 CTaskDialog 中启用超链接。 |
| TDF_USE_HICON_MAIN | 将 CTaskDialog 配置为将 HICON 用于主图标。 替代方法是使用 LPCWSTR。 |
| TDF_USE_HICON_FOOTER | 将 CTaskDialog 配置为将 HICON 用于页脚图标。 替代方法是使用 LPCWSTR。 |
| TDF_ALLOW_DIALOG_CANCELLATION | 允许用户使用键盘或对话框右上角的图标关闭 CTaskDialog，即使未启用“取消”按钮。 如果未设置此标志且未启用“取消”按钮，则用户无法使用 Alt+F4、Escape 键或标题栏的关闭按钮关闭对话框。 |
| TDF_USE_COMMAND_LINKS | 将 CTaskDialog 配置为使用命令按钮控件。 |
| TDF_USE_COMMAND_LINKS_NO_ICON | 将 CTaskDialog 配置为使用命令按钮控件，而不在控件旁边显示图标。 TDF_USE_COMMAND_LINKS 将替代 TDF_USE_COMMAND_LINKS_NO_ICON。 |
| TDF_EXPAND_FOOTER_AREA | 指示展开区域当前已展开。 |
| TDF_EXPANDED_BY_DEFAULT | 确定展开区域在默认情况下是否展开。 |
| TDF_VERIFICATION_FLAG_CHECKED | 指示验证复选框当前已选中。 |
| TDF_SHOW_PROGRESS_BAR | 将 CTaskDialog 配置为显示进度栏。 |
| TDF_SHOW_MARQUEE_PROGRESS_BAR | 将进度栏配置为字幕进度栏。 如果启用此选项，则必须将 TDF_SHOW_PROGRESS_BAR 设置为具有预期行为。 |
| TDF_CALLBACK_TIMER | 指示 CTaskDialog 回调间隔设置为大约 200 毫秒。 |
| TDF_POSITION_RELATIVE_TO_WINDOW | 将 CTaskDialog 配置为相对于父窗口居中。 如果未启用此标志，则 CTaskDialog 相对于监视器居中。 |
| TDF_RTL_LAYOUT | 将 CTaskDialog 配置为从右到左的阅读布局。 |
| TDF_NO_DEFAULT_RADIO_BUTTON | 指示在 CTaskDialog 出现时未选择任何单选按钮。 |
| TDF_CAN_BE_MINIMIZED | 使用户能够最大程度地减少 CTaskDialog。 若要支持此选项，CTaskDialog 不能为模式对话框。 MFC 不支持此选项，因为 MFC 不支持无模式 CTaskDialog。 |
示例
// 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
配置 CTaskDialog 的字幕栏并将其添加到对话框。
void SetProgressBarMarquee(
BOOL bEnabled = TRUE,
int nMarqueeSpeed = 0);
参数
bEnabled
[in] 设置为 TRUE 可启用字幕栏；设置为 FALSE 可禁用字幕栏并将其从 CTaskDialog 中移除。
nMarqueeSpeed
[in] 一个整数，指示字幕栏的速度。
备注
字幕栏显示在 CTaskDialog 类的主文本下方。
使用 nMarqueeSpeed 设置字幕栏的速度；较大的值表示速度较慢。 nMarqueeSpeed 的值为 0 将使字幕栏以 Windows 的默认速度移动。
如果 nMarqueeSpeed 小于 0，此方法将引发异常，并显示 ENSURE 宏。
示例
// 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
调整进度栏的位置。
void SetProgressBarPosition(int nProgressPos);
参数
nProgressPos
[in] 进度栏的位置。
注解
如果 nProgressPos 不在进度栏范围内，此方法将引发异常，并显示 ENSURE 宏。 可以使用 CTaskDialog::SetProgressBarRange 更改进度栏范围。
示例
// 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
调整进度栏的范围。
void SetProgressBarRange(
int nRangeMin,
int nRangeMax);
参数
nRangeMin
[in] 进度栏的下限。
nRangeMax
[in] 进度栏的上限。
备注
进度栏的位置相对于 nRangeMin 和 nRangeMax。 例如，如果 nRangeMin 为 50 且 nRangeMax 为 100，则 75 的位置位于进度栏的中间。 使用 CTaskDialog::SetProgressBarPosition 设置进度栏的位置。
若要显示进度栏，必须启用 TDF_SHOW_PROGRESS_BAR 选项，并且不得启用 TDF_SHOW_MARQUEE_PROGRESS_BAR。 此方法会自动设置 TDF_SHOW_PROGRESS_BAR 并清除 TDF_SHOW_MARQUEE_PROGRESS_BAR。 使用 CTaskDialog::SetOptions 为 CTaskDialog 类的此实例手动更改选项。
如果 nRangeMin 不小于 nRangeMax，此方法将引发异常，并显示 ENSURE 宏。 如果 CTaskDialog 已显示并具有字幕进度栏，此方法也会引发异常。
示例
// 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
设置进度栏的状态并将其显示在 CTaskDialog 中。
void SetProgressBarState(int nState = PBST_NORMAL);
参数
nState
[in] 进度栏的状态。 请参阅“注解”部分了解可能的值。
备注
如果 CTaskDialog 已显示并具有字幕进度栏，此方法将引发异常，并显示 ENSURE 宏。
下表列出了 nState 的可能值。 在所有这些情况下，进度栏将填充常规颜色，直到它到达指定的停止位置。 此时，它还会根据状态更改颜色。
| 名称 | 描述 |
|---|---|
| PBST_NORMAL | 进度栏填充后，CTaskDialog 不会更改进度栏的颜色。 默认情况下，常规颜色为绿色。 |
| PBST_ERROR | 进度栏填充后，CTaskDialog 将进度栏的颜色更改为错误颜色。 默认情况下为红色。 |
| PBST_PAUSED | 进度栏填充后，CTaskDialog 将进度栏的颜色更改为暂停颜色。 默认情况下为黄色。 |
可以使用 CTaskDialog::SetProgressBarPosition 设置进度栏停止的位置。
示例
// 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
启用或禁用单选按钮。
void SetRadioButtonOptions(
int nRadioButtonID,
BOOL bEnabled);
参数
nRadioButtonID
[in] 单选按钮控件的 ID。
bEnabled
[in] 设置为 TRUE 可启用单选按钮，设置为 FALSE 可禁用单选按钮。
注解
如果 nRadioButtonID 不是单选按钮的有效 ID，此方法将引发异常，并显示 ENSURE 宏。
示例
// 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
设置验证复选框的已选中状态。
void SetVerificationCheckbox(BOOL bChecked);
参数
bChecked
[in] 设置为 TRUE 可在显示 CTaskDialog 时选中验证复选框，设置为 FALSE 可在显示 CTaskDialog 验证复选框时取消选中验证复选框。
示例
// 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
设置显示在验证复选框右侧的文本。
void SetVerificationCheckboxText(CString& strVerificationText);
参数
strVerificationText
[in] 此方法显示在验证复选框旁边的文本。
备注
如果已显示 类的此实例，此方法将引发异常，并显示 ENSURECTaskDialog 宏。
示例
// 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
设置 CTaskDialog 的标题。
void SetWindowTitle(CString& strWindowTitle);
参数
strWindowTitle
[in] CTaskDialog 的新标题。
备注
示例
// 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
创建并显示 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(""));
参数
strContent
[in] 要用于 CTaskDialog 内容的字符串。
strMainInstruction
[in] CTaskDialog 的主说明。
strTitle
[in] CTaskDialog 的标题。
nIDCommandControlsFirst
[in] 第一个命令的字符串 ID。
nIDCommandControlsLast
[in] 最后一个命令的字符串 ID。
nCommonButtons
[in] 要添加到 CTaskDialog 的按钮的掩码。
nTaskDialogOptions
[in] 要用于 CTaskDialog 的选项集。
strFooter
[in] 要用作页脚的字符串。
返回值
一个整数，对应于用户所做的选择。
注解
使用此静态方法可以创建 CTaskDialog 类的实例，而无需在代码中显式创建 CTaskDialog 对象。 由于没有 CTaskDialog 对象，因此，如果使用此方法向用户显示 CTaskDialog，则无法调用 CTaskDialog 的任何其他方法。
此方法将使用应用程序资源文件中的数据创建命令按钮控件。 资源文件中的字符串表具有多个字符串，其中包含关联的字符串 ID。 此方法将为字符串表中 nIDCommandControlsFirst 和 nCommandControlsLast 之间（含）的每个有效条目添加一个命令按钮控件。 对于这些命令按钮控件，字符串表中的字符串是控件的标题，字符串 ID 是控件的 ID。
有关有效选项列表，请参阅 CTaskDialog::SetOptions。
当用户选择常见按钮、命令链接控件或关闭 CTaskDialog 时，CTaskDialog 会关闭。 返回值是指示用户如何关闭的对话框的标识符。
示例
// 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
框架调用此方法以响应各种 Window 消息。
friend:
HRESULT TaskDialogCallback(
HWND hWnd,
UINT uNotification,
WPARAM wParam,
LPARAM lParam,
LONG_PTR dwRefData);
参数
hwnd
[in] CTaskDialog 的 m_hWnd 结构的句柄。
uNotification
[in] 指定生成的消息的通知代码。
wParam
[in] 有关消息的详细信息。
lParam
[in] 有关消息的详细信息。
dwRefData
[in] 指向回调消息所应用于的 CTaskDialog 对象的指针。
返回值
取决于特定通知代码。 有关详细信息，请参阅备注部分。
注解
TaskDialogCallback 的默认实现处理特定消息，然后调用 CTaskDialog 类 的相应 On 方法。 例如，在响应 TDN_BUTTON_CLICKED 消息时，TaskDialogCallback 将调用 CTaskDialog::OnCommandControlClick。
wParam 和 lParam 的值取决于生成的特定消息。 这些值中的一个或两个可能为空。 下表列出了支持的默认通知以及 wParam 和 lParam 表示的值。 如果在派生类中重写此方法，则应为下表中的每个消息实现回调代码。
| 通知消息 | wParam 值 | lParam 值 |
|---|---|---|
| TDN_CREATED | 未使用。 | 未使用。 |
| TDN_NAVIGATED | 未使用。 | 未使用。 |
| TDN_BUTTON_CLICKED | 命令按钮控件 ID。 | 未使用。 |
| TDN_HYPERLINK_CLICKED | 未使用。 | 包含链接的 LPCWSTR 结构。 |
| TDN_TIMER | 创建 CTaskDialog 计时器或计时器重置后的时间（以毫秒为单位）。 |
未使用。 |
| TDN_DESTROYED | 未使用。 | 未使用。 |
| TDN_RADIO_BUTTON_CLICKED | 单选按钮 ID。 | 未使用。 |
| TDN_DIALOG_CONSTRUCTED | 未使用。 | 未使用。 |
| TDN_VERIFICATION_CLICKED | 如果复选框已选中，则为 1；否则为 0。 | 未使用。 |
| TDN_HELP | 未使用。 | 未使用。 |
| TDN_EXPANDO_BUTTON_CLICKED | 如果展开区域已折叠，则为 0；如果显示展开文本，则为非零值。 | 未使用。 |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈