CTaskDialog 类

功能类似于消息框,但可向用户显示额外信息的弹出对话框。 CTaskDialog 还包括从用户那里收集信息的功能。

语法

class CTaskDialog : public CObject

成员

构造函数

名称 描述
CTaskDialog::CTaskDialog 构造 CTaskDialog 对象。

方法

名称 描述
CTaskDialog::AddCommandControl CTaskDialog 添加命令按钮控件。
CTaskDialog::AddRadioButton CTaskDialog 添加单选按钮。
CTaskDialog::ClickCommandControl 以编程方式单击命令按钮控件或常见按钮。
CTaskDialog::ClickRadioButton 以编程方式单击单选按钮。
CTaskDialog::DoModal 显示CTaskDialog
CTaskDialog::GetCommonButtonCount 检索可用的常见按钮数。
CTaskDialog::GetCommonButtonFlag 将标准 Windows 按钮转换为与 CTaskDialog 类关联的常见按钮类型。
CTaskDialog::GetCommonButtonId 将与 CTaskDialog 类关联的其中一种常见按钮转换为标准 Windows 按钮。
CTaskDialog::GetOptions 返回此 CTaskDialog 的选项标志。
CTaskDialog::GetSelectedCommandControlID 返回所选择的命令按钮控件。
CTaskDialog::GetSelectedRadioButtonID 返回所选择的单选按钮。
CTaskDialog::GetVerificationCheckboxState 检索验证复选框的状态。
CTaskDialog::IsCommandControlEnabled 确定是启用了命令按钮控件还是启用了常见按钮。
CTaskDialog::IsRadioButtonEnabled 确定是否启用了单选按钮。
CTaskDialog::IsSupported 确定运行应用程序的计算机是否支持 CTaskDialog
CTaskDialog::LoadCommandControls 使用字符串表中的数据添加命令按钮控件。
CTaskDialog::LoadRadioButtons 使用字符串表中的数据添加单选按钮。
CTaskDialog::NavigateTo 将焦点转移到另一个 CTaskDialog
CTaskDialog::OnCommandControlClick 当用户单击命令按钮控件时,框架将调用此方法。
CTaskDialog::OnCreate 框架在创建 CTaskDialog 后调用此方法。
CTaskDialog::OnDestroy 框架在销毁 CTaskDialog 之前调用此方法。
CTaskDialog::OnExpandButtonClick 当用户单击展开按钮时,框架将调用此方法。
CTaskDialog::OnHelp 当用户请求帮助时,框架将调用此方法。
CTaskDialog::OnHyperlinkClick 当用户单击超链接时,框架将调用此方法。
CTaskDialog::OnInit 当初始化 CTaskDialog 时,框架将调用此方法。
CTaskDialog::OnNavigatePage 当用户将焦点向 CTaskDialog 上的控件移动时,框架将调用此方法。
CTaskDialog::OnRadioButtonClick 当用户选择一个单选按钮控件时,框架将调用此方法。
CTaskDialog::OnTimer 当计时器过期时,框架将调用此方法。
CTaskDialog::OnVerificationCheckboxClick 当用户单击验证复选框时,框架将调用此方法。
CTaskDialog::RemoveAllCommandControls CTaskDialog 中移除所有命令控件。
CTaskDialog::RemoveAllRadioButtons CTaskDialog 中移除所有单选按钮。
CTaskDialog::SetCommandControlOptions 更新 CTaskDialog 上的命令按钮控件。
CTaskDialog::SetCommonButtonOptions 更新要启用并且需要 UAC 提升的一个常见按钮子集。
CTaskDialog::SetCommonButtons CTaskDialog 添加常见按钮。
CTaskDialog::SetContent 更新 CTaskDialog 的内容。
CTaskDialog::SetDefaultCommandControl 指定默认命令按钮控件。
CTaskDialog::SetDefaultRadioButton 指定默认单选按钮。
CTaskDialog::SetDialogWidth 调整 CTaskDialog 的宽度。
CTaskDialog::SetExpansionArea 更新 CTaskDialog 的展开区域。
CTaskDialog::SetFooterIcon 更新 CTaskDialog 的页脚图标。
CTaskDialog::SetFooterText 更新 CTaskDialog 的页脚上的文本。
CTaskDialog::SetMainIcon 更新 CTaskDialog 的主图标。
CTaskDialog::SetMainInstruction 更新 CTaskDialog 的主说明。
CTaskDialog::SetOptions 配置 CTaskDialog 的选项。
CTaskDialog::SetProgressBarMarquee 配置 CTaskDialog 的字幕栏并将其添加到对话框。
CTaskDialog::SetProgressBarPosition 调整进度栏的位置。
CTaskDialog::SetProgressBarRange 调整进度栏的范围。
CTaskDialog::SetProgressBarState 设置进度栏的状态并将其显示在 CTaskDialog 中。
CTaskDialog::SetRadioButtonOptions 启用或禁用单选按钮。
CTaskDialog::SetVerificationCheckbox 设置验证复选框的已选中状态。
CTaskDialog::SetVerificationCheckboxText 设置验证复选框右侧的文本。
CTaskDialog::SetWindowTitle 设置 CTaskDialog 的标题。
CTaskDialog::ShowDialog 创建并显示 CTaskDialog
CTaskDialog::TaskDialogCallback 框架会调用此方法以响应各种 Window 消息。

数据成员

名称 描述
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_nProgressRangeMinm_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 的示例。
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::DoModalCTaskDialog::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

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::CTaskDialogCTaskDialog::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 只能接受 HICONLPCWSTR 作为页脚图标。 此方法通过在构造函数或 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 只能接受 HICONLPCWSTR 作为主图标。 可以通过在构造函数或 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::SetOptionsCTaskDialog 类的此实例手动更改选项。

如果 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] CTaskDialogm_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;如果显示展开文本,则为非零值。 未使用。

另请参阅


CObject 类
层次结构图
演练:向应用程序添加 CTaskDialog