A task dialog is a dialog box that can be used to display information and receive simple input from the user. Like a message box, it is formatted by the operating system according to parameters you set. However, a task dialog has many more features than a message box.
Note Task dialogs require the single-threaded apartment (STA) model.
The following topics are discussed in this section.
Parts of a Task Dialog
A task dialog consists of several elements, most of which are optional. The following illustration shows the various parts of a task dialog.
.jpg)
In the following illustration, the user has clicked the button beside the collapsed control text, causing alternative text to be displayed there and in the footer.
.jpg)
The illustrations show the following parts:
| Part | Description | TASKDIALOGCONFIG member |
|---|
| Window title | Caption of the window. | pszWindowTitle |
| Main icon | A large icon that signifies the purpose of the dialog. | hMainIcon or pszMainIcon |
| Main instruction | Principal text. | pszMainInstruction |
| Content | Extra text. | pszContent |
| Progress bar | An animated bar that shows the progress of some task. | dwFlags |
| Radio buttons | Application-defined options for the user. | pRadioButtons |
| Custom button | A button that is not one of the common buttons. This can be either a normal button or, as shown in the illustration, a command link with up to two lines of text. | pButtons |
| Expand/collapse button | A button that can be used to toggle between the application-defined collapsed control text (such as "See more details") and the expanded control text, which can be on two or more lines. When the control text is expanded, the additional text in pszExpandedInformation is also shown, either after the content text, or (as shown in the second illustration) in the footer. | pszCollapsedControlText and pszExpandedControlText |
| Verification check box | A checkbox, accompanied by application-defined text, for simple choices such as "Do not show this dialog again." | pszVerificationText |
| Footer icon | A small icon that signifies the purpose of the footer text. | hFooterIcon or pszFooterIcon |
| Footer text | Additional text. In the illustrations, the text contains a hyperlink. | pszFooter |
| Common button | A standard button; in the illustrations, the OK button. | dwCommonButtons |
Creating a Task Dialog
A task dialog is created and shown by using either the TaskDialog function or the TaskDialogIndirect function.
TaskDialog is suitable for simple dialog boxes that present textual information and ask for a standard choice. This creation function does not support progress bars, check boxes, footers, expand/collapse buttons, custom buttons, or radio buttons.
TaskDialogIndirect is more powerful, supporting all available interface elements and also enabling you to to capture events in a callback procedure so that your application can update a progress bar or respond to a click on a hyperlink or button.
Getting User Input from a Task Dialog
When the user closes a task dialog by clicking one of the common buttons, you can identify the button that was clicked by examining the pnButton parameter of the calling function. You can also identify the selected radio button from the pnRadioButton parameter of TaskDialogIndirect, and the state of the verification check box from the pfVerificationFlagChecked parameter.
Clicks on buttons and hyperlinks are received by the TaskDialogCallbackProc function in the form of TDN_BUTTON_CLICKED and TDN_HYPERLINK_CLICKED notifications. If your callback function returns S_OK after handling a button notification, the task dialog closes and the command identifier of the button is returned in pnButton. If you return S_FALSE, or do not have a callback function, the task dialog remains open.