TASKDIALOGCONFIG structure (commctrl.h)
The TASKDIALOGCONFIG structure contains information used to display a task dialog. The TaskDialogIndirect function uses this structure.
Syntax
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;
Members
cbSize
Type: UINT
Specifies the structure size, in bytes.
hwndParent
Type: HWND
Handle to the parent window. This member can be NULL.
hInstance
Type: HINSTANCE
Handle to the module that contains the icon resource identified by the pszMainIcon or pszFooterIcon members, and the string resources identified by the pszWindowTitle, pszMainInstruction, pszContent, pszVerificationText, pszExpandedInformation, pszExpandedControlText, pszCollapsedControlText or pszFooter members.
dwFlags
Type: TASKDIALOG_FLAGS
Specifies the behavior of the task dialog. This parameter can be a combination of flags from the following group:
| Value | Meaning |
|---|---|
|
Enables hyperlink processing for the strings specified in the pszContent, pszExpandedInformation and pszFooter members. When enabled, these members may point to strings that contain hyperlinks in the following form:
Warning: Enabling hyperlinks when using content from an unsafe source may cause security vulnerabilities. Note Task Dialogs will not actually execute any hyperlinks. Hyperlink execution must be handled in the callback function specified by pfCallback. For more details, see TaskDialogCallbackProc.
|
|
Indicates that the dialog should use the icon referenced by the handle in the hMainIcon member as the primary icon in the task dialog. If this flag is specified, the pszMainIcon member is ignored. |
|
Indicates that the dialog should use the icon referenced by the handle in the hFooterIcon member as the footer icon in the task dialog. If this flag is specified, the pszFooterIcon member is ignored. |
|
Indicates that the dialog should be able to be closed using Alt-F4, Escape, and the title bar's close button even if no cancel button is specified in either the dwCommonButtons or pButtons members. |
|
Indicates that the buttons specified in the pButtons member are to be displayed as command links (using a standard task dialog glyph) instead of push buttons. When using command links, all characters up to the first new line character in the pszButtonText member will be treated as the command link's main text, and the remainder will be treated as the command link's note. This flag is ignored if the cButtons member is zero. |
|
Indicates that the buttons specified in the pButtons member are to be displayed as command links (without a glyph) instead of push buttons. When using command links, all characters up to the first new line character in the pszButtonText member will be treated as the command link's main text, and the remainder will be treated as the command link's note. This flag is ignored if the cButtons member is zero. |
|
Indicates that the string specified by the pszExpandedInformation member is displayed at the bottom of the dialog's footer area instead of immediately after the dialog's content. This flag is ignored if the pszExpandedInformation member is NULL. |
|
Indicates that the string specified by the pszExpandedInformation member is displayed when the dialog is initially displayed. This flag is ignored if the pszExpandedInformation member is NULL. |
|
Indicates that the verification checkbox in the dialog is checked when the dialog is initially displayed. This flag is ignored if the pszVerificationText parameter is NULL. |
|
Indicates that a Progress Bar is to be displayed. |
|
Indicates that an Marquee Progress Bar is to be displayed. |
|
Indicates that the task dialog's callback is to be called approximately every 200 milliseconds. |
|
Indicates that the task dialog is positioned (centered) relative to the window specified by hwndParent. If the flag is not supplied (or no hwndParent member is specified), the task dialog is positioned (centered) relative to the monitor. |
|
Indicates that text is displayed reading right to left. |
|
Indicates that no default item will be selected. |
|
Indicates that the task dialog can be minimized. |
|
This flag is deprecated. Use TDF_SIZE_TO_CONTENT instead. |
|
Indicates that the width of the task dialog is determined by the width of its content area. This flag is ignored if cxWidth is not set to 0. |
dwCommonButtons
Type: TASKDIALOG_COMMON_BUTTON_FLAGS
Specifies the push buttons displayed in the task dialog. If no common buttons are specified and no custom buttons are specified using the cButtons and pButtons members, the task dialog will contain the OK button by default. This parameter may be a combination of flags from the following group:
pszWindowTitle
Type: PCWSTR
Pointer that references the string to be used for the task dialog title. This parameter can be either a null-terminated string or an integer resource identifier passed to the MAKEINTRESOURCE macro. If this parameter is NULL, the filename of the executable program is used.
DUMMYUNIONNAME
DUMMYUNIONNAME.hMainIcon
Type: HICON
A handle to an Icon that is to be displayed in the task dialog. This member is ignored unless the TDF_USE_HICON_MAIN flag is specified. If this member is NULL and the TDF_USE_HICON_MAIN is specified, no icon will be displayed.
DUMMYUNIONNAME.pszMainIcon
Type: PCWSTR
Pointer that references the icon to be displayed in the task dialog. This parameter is ignored if the USE_HICON_MAIN flag is specified. Otherwise, if this parameter is NULL or the hInstance parameter is NULL, no icon will be displayed. This parameter must be an integer resource identifier passed to the MAKEINTRESOURCE macro or one of the following predefined values:
pszMainInstruction
Type: PCWSTR
Pointer that references the string to be used for the main instruction. This parameter can be either a null-terminated string or an integer resource identifier passed to the MAKEINTRESOURCE macro.
pszContent
Type: PCWSTR
Pointer that references the string to be used for the dialog's primary content. This parameter can be either a null-terminated string or an integer resource identifier passed to the MAKEINTRESOURCE macro. If the ENABLE_HYPERLINKS flag is specified for the dwFlags member, then this string may contain hyperlinks in the form: <A HREF="executablestring">Hyperlink Text</A>. WARNING: Enabling hyperlinks when using content from an unsafe source may cause security vulnerabilities.
cButtons
Type: UINT
The number of entries in the pButtons array that is used to create buttons or command links in the task dialog. If this member is zero and no common buttons have been specified using the dwCommonButtons member, then the task dialog will have a single OK button displayed.
pButtons
Type: const TASKDIALOG_BUTTON*
Pointer to an array of TASKDIALOG_BUTTON structures containing the definition of the custom buttons that are to be displayed in the task dialog. This array must contain at least the number of entries that are specified by the cButtons member.
nDefaultButton
Type: int
The default button for the task dialog. This may be any of the values specified in nButtonID members of one of the TASKDIALOG_BUTTON structures in the pButtons array, or one of the IDs corresponding to the buttons specified in the dwCommonButtons member:
| IDCANCEL | Make the Cancel button the default. |
| IDNO | Make the No button the default. |
| IDOK | Make the OK button the default. |
| IDRETRY | Make the Retry button the default. |
| IDYES | Make the Yes button the default. |
| IDCLOSE | Make the Close button the default. |
If this member is zero or its value does not correspond to any button ID in the dialog, then the first button in the dialog will be the default.
cRadioButtons
Type: UINT
The number of entries in the pRadioButtons array that is used to create radio buttons in the task dialog.
pRadioButtons
Type: const TASKDIALOG_BUTTON*
Pointer to an array of TASKDIALOG_BUTTON structures containing the definition of the radio buttons that are to be displayed in the task dialog. This array must contain at least the number of entries that are specified by the cRadioButtons member. This parameter can be NULL.
nDefaultRadioButton
Type: int
The button ID of the radio button that is selected by default. If this value does not correspond to a button ID, the first button in the array is selected by default.
pszVerificationText
Type: PCWSTR
Pointer that references the string to be used to label the verification checkbox. This parameter can be either a null-terminated string or an integer resource identifier passed to the MAKEINTRESOURCE macro. If this parameter is NULL, the verification checkbox is not displayed in the task dialog. If the pfVerificationFlagChecked parameter of TaskDialogIndirect is NULL, the checkbox is not enabled.
pszExpandedInformation
Type: PCWSTR
Pointer that references the string to be used for displaying additional information. This parameter can be either a null-terminated string or an integer resource identifier passed to the MAKEINTRESOURCE macro. The additional information is displayed either immediately below the content or below the footer text depending on whether the TDF_EXPAND_FOOTER_AREA flag is specified. If the TDF_ENABLE_HYPERLINKS flag is specified for the dwFlags member, then this string may contain hyperlinks in the form: <A HREF="executablestring">Hyperlink Text</A>. WARNING: Enabling hyperlinks when using content from an unsafe source may cause security vulnerabilities.
pszExpandedControlText
Type: PCWSTR
Pointer that references the string to be used to label the button for collapsing the expandable information. This parameter can be either a null-terminated string or an integer resource identifier passed to the MAKEINTRESOURCE macro. This member is ignored when the pszExpandedInformation member is NULL. If this member is NULL and the pszCollapsedControlText is specified, then the pszCollapsedControlText value will be used for this member as well.
pszCollapsedControlText
Type: PCWSTR
Pointer that references the string to be used to label the button for expanding the expandable information. This parameter can be either a null-terminated string or an integer resource identifier passed to the MAKEINTRESOURCE macro. This member is ignored when the pszExpandedInformation member is NULL. If this member is NULL and the pszCollapsedControlText is specified, then the pszCollapsedControlText value will be used for this member as well.
DUMMYUNIONNAME2
DUMMYUNIONNAME2.hFooterIcon
Type: HICON
A handle to an Icon that is to be displayed in the footer of the task dialog. This member is ignored unless the TDF_USE_HICON_FOOTER flag is specified and the pszFooterIcon is not. If this member is NULL and the TDF_USE_HICON_FOOTER is specified, no icon is displayed.
DUMMYUNIONNAME2.pszFooterIcon
Type: PCWSTR
Pointer that references the icon to be displayed in the footer area of the task dialog. This parameter is ignored if the TDF_USE_HICON_FOOTER flag is specified, or if pszFooter is NULL. Otherwise, if this parameter is NULL or the hInstance parameter is NULL, no icon is displayed. This parameter must be an integer resource identifier passed to the MAKEINTRESOURCE macro or one of the predefined values listed for pszMainIcon.
pszFooter
Type: PCWSTR
Pointer to the string to be used in the footer area of the task dialog. This parameter can be either a null-terminated string or an integer resource identifier passed to the MAKEINTRESOURCE macro. If the TDF_ENABLE_HYPERLINKS flag is specified for the dwFlags member, then this string may contain hyperlinks in this form.
<A HREF="executablestring">Hyperlink Text</A>
pfCallback
Type: PFTASKDIALOGCALLBACK
Pointer to an application-defined callback function. For more information see TaskDialogCallbackProc.
lpCallbackData
Type: LONG_PTR
A pointer to application-defined reference data. This value is defined by the caller.
cxWidth
Type: UINT
The width of the task dialog's client area, in dialog units. If 0, the task dialog manager will calculate the ideal width.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Header | commctrl.h |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for