TaskDialog 函数 (commctrl.h)

项目
02/26/2024

TaskDialog 函数创建、显示和操作任务对话框。任务对话框包含应用程序定义的消息文本和标题、图标以及预定义的按钮的任意组合。此函数不支持注册回调函数以接收通知。

语法

HRESULT TaskDialog(
  [in]  HWND                           hwndOwner,
  [in]  HINSTANCE                      hInstance,
  [in]  PCWSTR                         pszWindowTitle,
  [in]  PCWSTR                         pszMainInstruction,
  [in]  PCWSTR                         pszContent,
  [in]  TASKDIALOG_COMMON_BUTTON_FLAGS dwCommonButtons,
  [in]  PCWSTR                         pszIcon,
  [out] int                            *pnButton
);

参数

[in] hwndOwner

类型： HWND

要创建的任务对话框的所有者窗口的句柄。如果此参数为 NULL，则任务对话框没有所有者窗口。

[in] hInstance

类型： HINSTANCE

模块句柄，该模块包含 由 pszIcon 成员标识的图标资源，以及 由 pszWindowTitle 和 pszMainInstruction 成员标识的字符串资源。如果此参数为 NULL， 则 pszIcon 必须为 NULL 或指向以 null 结尾的 Unicode 字符串的指针，该字符串包含系统资源标识符，例如，TD_ERROR_ICON。

[in] pszWindowTitle

类型： PCWSTR

指向要用于任务对话框标题的字符串的指针。此参数是一个以 null 结尾的 Unicode 字符串，其中包含文本或通过 MAKEINTRESOURCE 宏传递的整数资源标识符。如果此参数为 NULL，则使用可执行程序的文件名。

[in] pszMainInstruction

类型： PCWSTR

指向要用于main指令的字符串的指针。此参数是一个以 null 结尾的 Unicode 字符串，其中包含文本或通过 MAKEINTRESOURCE 宏传递的整数资源标识符。如果不需要main指令，此参数可以为 NULL。

[in] pszContent

类型： PCWSTR

指向字符串的指针，该字符串用于以较小的字体显示在main指令下方的其他文本。此参数是一个以 null 结尾的 Unicode 字符串，其中包含文本或通过 MAKEINTRESOURCE 宏传递的整数资源标识符。如果不需要其他文本，可以为 NULL 。

[in] dwCommonButtons

类型： TASKDIALOG_COMMON_BUTTON_FLAGS

指定对话框中显示的按钮。此参数可以是以下组中标志的组合。

注意如果未指定任何按钮，则默认情况下，对话框将包含 “确定” 按钮。

值	含义
TDCBF_OK_BUTTON	任务对话框包含“ 确定”按钮。
TDCBF_YES_BUTTON	任务对话框包含按钮：是。
TDCBF_NO_BUTTON	任务对话框包含按下按钮：否。
TDCBF_CANCEL_BUTTON	任务对话框包含“ 取消”按钮。必须指定此按钮，对话框才能响应典型的取消操作 (Alt-F4 和转义) 。
TDCBF_RETRY_BUTTON	任务对话框包含“ 重试”按钮。
TDCBF_CLOSE_BUTTON	任务对话框包含“ 关闭”按钮。

[in] pszIcon

类型： PCWSTR

指向标识要显示在任务对话框中的图标的字符串的指针。此参数必须是传递给 MAKEINTRESOURCE 宏的整数资源标识符或以下预定义值之一。如果此参数为 NULL，则不会显示任何图标。如果 hInstance 参数为 NULL ，并且未使用其中一个预定义值， 则 TaskDialog 函数将失败。

值	含义
TD_ERROR_ICON	任务对话框中将显示一个停止符号图标。
TD_INFORMATION_ICON	任务对话框中将显示一个由圆圈中的小写字母 i 组成的图标。
TD_SHIELD_ICON	任务对话框中会显示一个安全防护图标。
TD_WARNING_ICON	任务对话框中将显示一个感叹号图标。

[out] pnButton

类型： int*

当此函数返回时，包含指向接收以下值之一的整数位置的指针：

值	说明
0	函数调用失败。有关详细信息，请参阅返回值。
IDCANCEL	已选择“取消”按钮、按下 Alt-F4、按下 Escape 或用户单击关闭窗口按钮。
IDNO	未选择任何按钮。
IDOK	已选择“确定”按钮。
IDRETRY	已选择“重试”按钮。
IDYES	已选择“是”按钮。
IDCLOSE	已选择“关闭”按钮。

如果此值为 NULL，则不返回任何值。

返回值

类型： HRESULT

此函数可以返回其中一个值。

返回代码	说明
S_OK	操作已成功完成。
E_OUTOFMEMORY	内存不足，无法完成操作。
E_INVALIDARG	一个或多个参数无效。
E_FAIL	此操作失败。

注解

使用任务对话框指示系统内存不足时，不应从资源文件中获取 pszMainInstruction 和 pszWindowTitle 参数指向的字符串，因为尝试加载资源可能会失败。

如果在存在对话框时创建任务对话框，请使用对话框的句柄作为 hWndParent 参数。 hWndParent 参数不应标识子窗口，例如对话框中的控件。

由于任务对话框使用正确的系统定义的 UI 元素，因此应使用它们，而不是使用使用 MessageBox 函数创建的消息框。若要实现更多功能，请使用 TaskDialogIndirect。

以下示例代码将作为更大的程序的一部分包含，演示如何创建任务对话框和捕获输入。


int nButtonPressed = 0;
TaskDialog(NULL, hInst, 
    MAKEINTRESOURCE(IDS_APPLICATION_TITLE),
    MAKEINTRESOURCE(IDS_DOSOMETHING), 
    MAKEINTRESOURCE(IDS_SOMECONTENT), 
    TDCBF_OK_BUTTON | TDCBF_CANCEL_BUTTON,
    TD_WARNING_ICON, 
    &nButtonPressed);

if (IDOK == nButtonPressed)
{
    // OK button pressed
}
else if (IDCANCEL == nButtonPressed)
{
    // Cancel pressed
}

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	commctrl.h (包括 Commctrl.h)
Library	Comctl32.lib
DLL	Comctl32.dll (版本 6)

另请参阅

对话框

通过

TaskDialog 函数 (commctrl.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源