TASKDIALOGCONFIG (Compact 2013)

3/28/2014

This structure contains information used to display a task dialog.

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;
    } MainIcon;
    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;
    } FooterIcon;
    PCWSTR pszFooter;
    PFTASKDIALOGCALLBACK pfCallback;
    LONG_PTR lpCallbackData;
    UINT cxWidth;
} TASKDIALOGCONFIG;

Parameters

• cbSize
  Specifies the structure size in bytes.

• hwndParent
  Handle to the parent window. This parameter can be NULL.

• hInstance
  Handle to the module that contains the icon resource identified by pszMainIcon, and string resources identified by pszWindowTitle, pszVerificationText or pszContent.

• dwFlags
  One or more TASKDIALOG_FLAGS enumerated values that specify the behavior of the task dialog.

  If you specify TDF_USE_COMMAND_LINKS_NO_ICON, and the ID specified in pButtons falls within the range between TDCBID_COMMANDLINK_FIRST and TDCBID_COMMANDLINK_LAST, the buttons will be displayed as command links in the task dialog client area. Otherwise, they will be displayed as a central menu item.

• dwCommonButtons
  One or more TASKDIALOG_COMMON_BUTTON_FLAGS enumerated values that specify the soft keys (SK1 and SK2) displayed in the task dialog.

• pszWindowTitle
  Pointer to the string used as the task dialog title. The value can be either a null-terminated string or an integer resource identifier passed to the MAKEINTRESOURCE macro. You can retrieve the string by using GetWindowText and passing the task dialog's window handle.

  If this parameter is NULL, TaskDialogIndirect uses the filename of the executable program.

  If pszMainInstruction is NULL and pszWindowTitle is too long, the window title will be wrapped onto the second line and will be truncated at that point, using an ellipsis to indicate the truncation.

  In the Windows desktop environment, the content of pszWindowTitle is used as the caption of the task dialog and the content of pszMainInstruction is displayed next to the main icon. In Windows Embedded Compact, both pszWindowTitle and pszMainInstruction are used in the task dialog title.

• MainIcon
  Union of references to the task dialog's main icon.

• hMainIcon
  Handle to an icon displayed in the task dialog. This is ignored unless you specify TDF_USE_HICON_MAIN (from TASKDIALOG_FLAGS). If this member is NULL, no icon is displayed.

• pszMainIcon
  Pointer to the icon displayed in the task dialog. This parameter is ignored if you specify USE_HICON_MAIN (from TASKDIALOG_FLAGS). Otherwise, if this parameter is NULL or hInstance is NULL, no icon is displayed. This parameter must be an integer resource identifier passed to the MAKEINTRESOURCE macro or one of the following predefined task dialog icon definitions:

  • TD_WARNING_ICON
    A stop sign icon.
  • TD_ERROR_ICON
    An exclamation point icon.
  • TD_INFORMATION_ICON
    A icon consisting of a lowercase letter 'i' in a circle.
  • TD_SHIELD_ICON
    A shield icon.
  • TD_CONFIRMATION_ICON
    A confirmation icon.

• pszMainInstruction
  Pointer to the string used as the task dialog title. If the string is too long, it will be wrapped onto the second line and will be truncated after that and using an ellipsis. This parameter can be either a null-terminated string or an integer resource identifier passed to the MAKEINTRESOURCE macro. If the string is too long, it is truncated with an ellipsis appended.

• pszContent
  Pointer to the string used as the dialog's primary content. This parameter can be either a null-terminated string or an integer resource identifier passed to the MAKEINTRESOURCE macro.

• cButtons
  The number of entries in the pButtons array used to create buttons or command links in the dialog. If this member is zero and no common buttons have been specified with the dwCommonButtons member, then the task dialog displays a single Close button.

• pButtons
  Pointer to an array of TASKDIALOG_BUTTON structures containing the definition of the custom buttons that are to be displayed in the dialog. This array must contain at least the number of entries that are specified by the cButtons member.

  The nButtonID member can be a common button ID. If you specify a common button ID, the pszButtonText member can be NULL and the system defined label is applied.

  If the button ID falls in the range between TDCBID_COMMANDLINK_FIRST and TDCBID_COMMANDLINK_LAST and TDF_USE_COMMAND_LINKS_NO_ICON is specified in dwFlags member, this button will be shown as command link in task dialog. Otherwise, it will be a menu item in menu bar.

  The content of member pszButtonText for a command link cannot have an anchor defined in it. Otherwise, the task dialog will fail and return E_INVALIDARG. For example, command link content such as the following is not allowed:

  <A ID="12345"> new location </A>
  

  The task dialog respects the order of the TASKDIALOG_BUTTON array. That is, the order of the menu items is based on the order in this array. The task dialog adds the common buttons, if any.

  The task dialog should define at least one soft key. Either specify a common button in the dwCommonButtons member, or create an entry that is not a command link.

• nDefaultButton
  The default menu item (Soft Key 1) or command link for the dialog. It can be any of the values specified in the nButtonID member of one of the TASKDIALOG_BUTTON structures in the pButtons array, or it can be a common button ID.

  If this member is 0 or its value does not correspond to any button ID in the dialog, then the first command link in the dialog becomes the default, the first central menu item is assigned to Soft Key 1, and the second central menu item is assigned to Soft Key 2. Button IDs such as IDNO, IDCLOSE, or IDCANCEL are invalid IDs for Soft Key 1, so the task dialog treats them as invalid button IDs.

  This parameter is ignored if TDF_USE_COMMAND_LINKS_NO_ICON is not set in the dwFlags member of the TASKDIALOGCONFIG structure which used to create task dialog.

• cRadioButtons
  The number of entries in the pRadioButtons array that is used to create radio buttons in the dialog.

• pRadioButtons
  Pointer to an array of TASKDIALOG_BUTTON structures containing the definitions of the radio buttons displayed in the dialog. This array must contain at least the number of entries specified by the cRadioButtons member. This parameter can be NULL.

  The radio button ID must not conflict with any one of common button IDs (IDOK, IDYES, IDNO, IDCANCEL, IDRETRY, IDCLOSE) or specified button ID. If this occurs, the calling function returns E_INVALIDARG.

• nDefaultRadioButton
  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
  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
  Not supported. Set to 0.

• pszExpandedControlText
  Not supported. Set to 0.

• pszCollapsedControlText
  Not supported. Set to 0.

• FooterIcon
  Union of references to the task dialog's footer icon.

• hFooterIcon
  Not supported. Set to 0.

• pszFooterIcon
  Not supported. Set to 0.

• pszFooter
  Not supported. Set to 0.

• pfCallback
  Pointer to an application-defined callback function, which receives messages from the task dialog when specified events occur (such as TDN_BUTTON_CLICKED). For information on specifying events for the callback function, see TaskDialogCallbackProc.

• lpCallbackData
  A pointer to application-defined reference data. This value is defined by the caller.

• cxWidth
  Not supported. Set to 0.

Requirements

Header

shellctrls.h

See Also

Reference

Task Dialogs Structures
TaskDialogIndirect
TDM_UPDATE_ICON