TASKDIALOGCONFIG 结构 (commctrl.h)

项目
08/22/2023

TASKDIALOGCONFIG 结构包含用于显示任务对话框的信息。 TaskDialogIndirect 函数使用此结构。

语法

typedef struct _TASKDIALOGCONFIG {
  UINT                           cbSize;
  HWND                           hwndParent;
  HINSTANCE                      hInstance;
  TASKDIALOG_FLAGS               dwFlags;
  TASKDIALOG_COMMON_BUTTON_FLAGS dwCommonButtons;
  PCWSTR                         pszWindowTitle;
  union {
    HICON  hMainIcon;
    PCWSTR pszMainIcon;
  } DUMMYUNIONNAME;
  PCWSTR                         pszMainInstruction;
  PCWSTR                         pszContent;
  UINT                           cButtons;
  const TASKDIALOG_BUTTON        *pButtons;
  int                            nDefaultButton;
  UINT                           cRadioButtons;
  const TASKDIALOG_BUTTON        *pRadioButtons;
  int                            nDefaultRadioButton;
  PCWSTR                         pszVerificationText;
  PCWSTR                         pszExpandedInformation;
  PCWSTR                         pszExpandedControlText;
  PCWSTR                         pszCollapsedControlText;
  union {
    HICON  hFooterIcon;
    PCWSTR pszFooterIcon;
  } DUMMYUNIONNAME2;
  PCWSTR                         pszFooter;
  PFTASKDIALOGCALLBACK           pfCallback;
  LONG_PTR                       lpCallbackData;
  UINT                           cxWidth;
} TASKDIALOGCONFIG;

成员

cbSize

类型： UINT

指定结构大小（以字节为单位）。

hwndParent

类型： HWND

父窗口的句柄。此成员可以为 NULL。

hInstance

类型： HINSTANCE

模块句柄，该模块包含 由 pszMainIcon 或 pszFooterIcon 成员标识的图标资源，以及由 pszWindowTitle、 pszMainInstruction、 pszContent、 pszVerificationText、 pszExpandedInformation、 pszExpandedControlText、 pszCollapsedControlText 或 pszFooter 成员标识的字符串资源。

dwFlags

类型： TASKDIALOG_FLAGS

指定任务对话框的行为。此参数可以是以下组中标志的组合：

值	含义
TDF_ENABLE_HYPERLINKS	为 pszContent、 pszExpandedInformation 和 pszFooter 成员中指定的字符串启用超链接处理。启用后，这些成员可能指向包含以下格式的超链接的字符串： `<A HREF="executablestring">Hyperlink Text</A>` 警告：使用来自不安全源的内容时启用超链接可能会导致安全漏洞。注意任务对话框实际上不会执行任何超链接。超链接执行必须在 pfCallback 指定的回调函数中处理。有关详细信息，请参阅 TaskDialogCallbackProc。
TDF_USE_HICON_MAIN	指示对话应使用 hMainIcon 成员中句柄引用的图标作为任务对话框中的主图标。如果指定了此标志，则忽略 pszMainIcon 成员。
TDF_USE_HICON_FOOTER	指示对话框应使用 hFooterIcon 成员中的句柄引用的图标作为任务对话框中的页脚图标。如果指定了此标志，则忽略 pszFooterIcon 成员。
TDF_ALLOW_DIALOG_CANCELLATION	指示即使 dwCommonButtons 或 pButtons 成员中未指定取消按钮，也应能够使用 Alt-F4、Escape 和标题栏的关闭按钮关闭对话框。
TDF_USE_COMMAND_LINKS	指示在 pButtons 成员中指定的按钮显示为命令链接 (使用标准任务对话框字形) 而不是按下按钮。使用命令链接时，pszButtonText 成员中第一个新行字符的所有字符将被视为命令链接main文本，其余字符将被视为命令链接的注释。如果 cButtons 成员为零，则忽略此标志。
TDF_USE_COMMAND_LINKS_NO_ICON	指示 pButtons 成员中指定的按钮显示为命令链接， (没有字形) 而不是按下按钮。使用命令链接时，pszButtonText 成员中第一个新行字符的所有字符将被视为命令链接main文本，其余字符将被视为命令链接的注释。如果 cButtons 成员为零，则忽略此标志。
TDF_EXPAND_FOOTER_AREA	指示 pszExpandedInformation 成员指定的字符串显示在对话框的页脚区域的底部，而不是紧跟在对话内容之后。如果 pszExpandedInformation 成员为 NULL，则忽略此标志。
TDF_EXPANDED_BY_DEFAULT	指示在最初显示对话框时显示 pszExpandedInformation 成员指定的字符串。如果 pszExpandedInformation 成员为 NULL，则忽略此标志。
TDF_VERIFICATION_FLAG_CHECKED	指示最初显示对话框时，对话框中的验证复选框处于选中状态。如果 pszVerificationText 参数为 NULL，则忽略此标志。
TDF_SHOW_PROGRESS_BAR	指示要显示进度栏。
TDF_SHOW_MARQUEE_PROGRESS_BAR	指示要显示“选框进度条”。
TDF_CALLBACK_TIMER	指示大约每 200 毫秒调用一次任务对话框的回调。
TDF_POSITION_RELATIVE_TO_WINDOW	指示任务对话框定位 (相对于 hwndParent 指定的窗口) 居中。如果未 (提供标志，或者未) 指定 hwndParent 成员，则相对于监视器，任务对话框将定位 (居中) 。
TDF_RTL_LAYOUT	指示文本从右到左显示。
TDF_NO_DEFAULT_RADIO_BUTTON	指示不会选择任何默认项。
TDF_CAN_BE_MINIMIZED	指示可以最小化任务对话框。
TDIF_SIZE_TO_CONTENT	此标志已弃用。请改用 TDF_SIZE_TO_CONTENT 。
TDF_SIZE_TO_CONTENT	指示任务对话框的宽度由其内容区域的宽度决定。如果未将 cxWidth 设置为 0，则忽略此标志。

dwCommonButtons

类型： TASKDIALOG_COMMON_BUTTON_FLAGS

指定任务对话框中显示的按钮。如果未指定常用按钮，并且未使用 cButtons 和 pButtons 成员指定自定义按钮，则任务对话框将默认包含 “确定” 按钮。此参数可以是以下组中标志的组合：

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

pszWindowTitle

类型： PCWSTR

引用要用于任务对话框标题的字符串的指针。此参数可以是以 null 结尾的字符串，也可以是传递给 MAKEINTRESOURCE 宏的整数资源标识符。如果此参数为 NULL，则使用可执行程序的文件名。

DUMMYUNIONNAME

DUMMYUNIONNAME.hMainIcon

类型： HICON

将在任务对话框中显示的图标的句柄。除非指定了TDF_USE_HICON_MAIN标志，否则将忽略此成员。如果此成员为 NULL 并且指定了TDF_USE_HICON_MAIN，则不会显示任何图标。

DUMMYUNIONNAME.pszMainIcon

类型： PCWSTR

引用要显示在任务对话框中的图标的指针。如果指定了USE_HICON_MAIN标志，则忽略此参数。否则，如果此参数为 NULL 或 hInstance 参数为 NULL，则不会显示任何图标。此参数必须是传递给 MAKEINTRESOURCE 宏的整数资源标识符或以下预定义值之一：

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

pszMainInstruction

类型： PCWSTR

引用要用于main指令的字符串的指针。此参数可以是以 null 结尾的字符串，也可以是传递给 MAKEINTRESOURCE 宏的整数资源标识符。

pszContent

类型： PCWSTR

引用要用于对话的主要内容的字符串的指针。此参数可以是以 null 结尾的字符串，也可以是传递给 MAKEINTRESOURCE 宏的整数资源标识符。如果为 dwFlags 成员指定了ENABLE_HYPERLINKS标志，则此字符串可能包含以下形式的超链接： <A HREF=“executablestring”>Hyperlink Text</A>。 警告：使用来自不安全源的内容时启用超链接可能会导致安全漏洞。

cButtons

类型： UINT

pButtons 数组中用于在任务对话框中创建按钮或命令链接的条目数。如果此成员为零，并且未使用 dwCommonButtons 成员指定公共按钮，则任务对话框将显示一个 “确定” 按钮。

pButtons

类型： const TASKDIALOG_BUTTON*

指向 TASKDIALOG_BUTTON 结构的数组的指针，其中包含要显示在任务对话框中的自定义按钮的定义。此数组必须至少包含 cButtons 成员指定的条目数。

nDefaultButton

类型： int

任务对话框的默认按钮。这可以是 pButtons 数组中TASKDIALOG_BUTTON结构之一的 nButtonID 成员中指定的任何值，也可以是与 dwCommonButtons 成员中指定的按钮对应的 ID 之一：

IDCANCEL	将 “取消 ”按钮设为默认值。
IDNO	将 “否 ”按钮设为默认值。
IDOK	将 “确定 ”按钮设为默认值。
IDRETRY	将 “重试 ”按钮设为默认值。
IDYES	将“ 是 ”按钮设为默认值。
IDCLOSE	将 “关闭 ”按钮设为默认值。

如果此成员为零或其值与对话框中的任何按钮 ID 不对应，则对话框中的第一个按钮将是默认值。

cRadioButtons

类型： UINT

pRadioButtons 数组中用于在任务对话框中创建单选按钮的条目数。

pRadioButtons

类型： const TASKDIALOG_BUTTON*

指向 TASKDIALOG_BUTTON 结构的数组的指针，其中包含要显示在任务对话框中的单选按钮的定义。此数组必须至少包含 cRadioButtons 成员指定的条目数。此参数可以为 NULL。

nDefaultRadioButton

类型： int

默认选择的单选按钮的按钮 ID。如果此值与按钮 ID 不对应，则默认情况下会选择数组中的第一个按钮。

pszVerificationText

类型： PCWSTR

引用用于标记验证复选框的字符串的指针。此参数可以是以 null 结尾的字符串，也可以是传递给 MAKEINTRESOURCE 宏的整数资源标识符。如果此参数为 NULL，则任务对话框中不会显示验证复选框。如果 TaskDialogIndirect 的 pfVerificationFlagChecked 参数为 NULL，则不启用该复选框。

pszExpandedInformation

类型： PCWSTR

引用要用于显示其他信息的字符串的指针。此参数可以是以 null 结尾的字符串，也可以是传递给 MAKEINTRESOURCE 宏的整数资源标识符。附加信息显示在内容下方或页脚文本下方，具体取决于是否指定了TDF_EXPAND_FOOTER_AREA标志。如果为 dwFlags 成员指定了 TDF_ENABLE_HYPERLINKS 标志，则此字符串可能包含以下形式的超链接： <A HREF=“executablestring”>Hyperlink Text</A>。 警告：使用来自不安全源的内容时启用超链接可能会导致安全漏洞。

pszExpandedControlText

类型： PCWSTR

引用字符串的指针，该字符串用于标记折叠可展开信息的按钮。此参数可以是以 null 结尾的字符串，也可以是传递给 MAKEINTRESOURCE 宏的整数资源标识符。当 pszExpandedInformation 成员为 NULL 时，将忽略此成员。如果此成员为 NULL 并且指定 了 pszCollapsedControlText ，则 pszCollapsedControlText 值也将用于此成员。

pszCollapsedControlText

类型： PCWSTR

引用字符串的指针，该字符串用于标记按钮以展开可展开的信息。此参数可以是以 null 结尾的字符串，也可以是传递给 MAKEINTRESOURCE 宏的整数资源标识符。当 pszExpandedInformation 成员为 NULL 时，将忽略此成员。如果此成员为 NULL 并且指定 了 pszCollapsedControlText ，则 pszCollapsedControlText 值也将用于此成员。

DUMMYUNIONNAME2

DUMMYUNIONNAME2.hFooterIcon

类型： HICON

将在任务对话框的页脚中显示的图标的句柄。除非指定了 TDF_USE_HICON_FOOTER 标志，但 pszFooterIcon 未指定，否则将忽略此成员。如果此成员为 NULL 并且指定了TDF_USE_HICON_FOOTER，则不显示任何图标。

DUMMYUNIONNAME2.pszFooterIcon

类型： PCWSTR

引用要显示在任务对话框的页脚区域中的图标的指针。如果指定了TDF_USE_HICON_FOOTER标志，或者 pszFooter 为 NULL，则忽略此参数。否则，如果此参数为 NULL 或 hInstance 参数为 NULL，则不显示图标。此参数必须是传递给 MAKEINTRESOURCE 宏的整数资源标识符或 为 pszMainIcon 列出的预定义值之一。

pszFooter

类型： PCWSTR

指向要用于任务对话框页脚区域的字符串的指针。此参数可以是以 null 结尾的字符串，也可以是传递给 MAKEINTRESOURCE 宏的整数资源标识符。如果为 dwFlags 成员指定了TDF_ENABLE_HYPERLINKS标志，则此字符串可能包含此格式的超链接。

<A HREF="executablestring">Hyperlink Text</A>

警告使用来自不安全源的内容时启用超链接可能会导致安全漏洞。

pfCallback

类型： PFTASKDIALOGCALLBACK

指向应用程序定义的回调函数的指针。有关详细信息，请参阅 TaskDialogCallbackProc。

lpCallbackData

类型： LONG_PTR

指向应用程序定义的引用数据的指针。此值由调用方定义。

cxWidth

类型： UINT

任务对话框工作区的宽度（以对话单元为单位）。如果为 0，则任务对话框管理器将计算理想宽度。

要求


最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
标头	commctrl.h

通过

TASKDIALOGCONFIG 结构 (commctrl.h)

语法

成员

要求

反馈

其他资源