[Overview][Constants][Types][Classes][Procedures and functions][Variables][Index] | Reference for unit 'Dialogs' (#lcl)

# TCustomTaskDialog

[Properties (by Name)] [Methods (by Name)] [Events (by Name)]

Defines a configurable, modal task dialog at run-time.

## Declaration

Source position: dialogs.pp line 738

`type TCustomTaskDialog = class(TLCLComponent)`
`protected`
`class procedure WSRegisterClass; override;` |  | Registers the task dialog class in the widgetset when needed.
`function DoExecute(); dynamic;` |  | Performs actions to configure and execute the dialog.
`procedure DoOnButtonClicked(); dynamic;` |  | Signals the OnButtonClicked event handler (when assigned) for the button with the specified modal result value.
`procedure DoOnRadioButtonClicked(); dynamic;` |  | Sets the active radio button and signals the OnRadioButtonClicked event handler (when assigned).
`procedure DoOnDialogConstructed; dynamic;` |  | Signals the OnDialogConstructed event handler (when assigned).
`procedure DoOnDialogCreated; dynamic;` |  | Signals the OnDialogCreated event handler (when assigned).
`procedure DoOnDialogDestroyed; dynamic;` |  | Signals the OnDialogDestroyed event handler (when assigned).
`procedure DoOnExpandButtonClicked(); dynamic;` |  | Updates the value in the Expanded property and signals the OnExpanded event handler (when assigned).
`procedure DoOnTimer(); dynamic;` |  | Signals the OnTimer event handler (when assigned) using the specified parameter values.
`procedure DoOnVerificationClicked(); dynamic;` |  | Updates Flags to reflect the checked state for the verification control and signals the OnVerificationClicked event handler (when assigned).
`procedure DoOnHelp; dynamic;` |  | Signals the OnHelp event handler (when assigned).
`procedure DoOnHyperlinkClicked(); dynamic;` |  | Updates the value in URL and signals the OnHyperlinkClicked event handler (when assigned).
`procedure DoOnNavigated; dynamic;` |  | Signals the OnNavigated event handler (when assigned).
`procedure InternalSetDialogHandle();` |  | Sets the value for the Handle property.
`procedure SetRadioButtonFromRadioIndex();` |  | Makes the radio button with the specified identifier the active RadioButton on the task dialog.
`public`
`constructor Create(); override;` |  | Constructor for the class instance.
`destructor Destroy; override;` |  | Destructor for the class instance.
`function ButtonIDToModalResult();` |  | Gets the modal result value for the button with the specified identifier.
`function Execute();` |  | Displays the task dialog and captures the modal result value.
`property Button: TTaskDialogButtonItem; [rw]` |  | Not used in the current LCL version.
`property Buttons: TTaskDialogButtons; [rw]` |  | Collection with the buttons for the Task dialog.
`property Caption: TTranslateString; [rw]` |  | Caption text displayed on the title bar for the Task dialog.
`property CustomFooterIcon: TIcon; [rws]` |  | Contains a custom icon displayed in the footer area on the dialog.
`property CustomMainIcon: TIcon; [rws]` |  | Contains a custom icon displayed in the main content area on the dialog.
`property CommonButtons: TTaskDialogCommonButtons; [rw]` |  | Set of common buttons displayed on the Task dialog.
`property CollapseButtonCaption: TTranslateString; [rw]` |  | Caption text for the "expando" button on the task dialog.
`property DefaultButton: TTaskDialogCommonButton; [rw]` |  | Index of the default button, from the set in the CommonButtons property.
`property ExpandButtonCaption: TTranslateString; [rw]` |  | Caption displayed for the expand/collapse button on the dialog.
`property ExpandedText: TTranslateString; [rw]` |  | Text that is displayed in the expandable / collapsible area on the Task dialog.
`property Flags: TTaskDialogFlags; [rw]` |  | Set of options enabled for the Task dialog.
`property FooterIcon: TTaskDialogIcon; [rw]` |  | Icon for the footer area displayed at the bottom of the dialog.
`property FooterText: TTranslateString; [rw]` |  | Text that is displayed in the footer area on the Task dialog.
`property MainIcon: TTaskDialogIcon; [rw]` |  | Icon displayed beside the Title for the dialog.
`property Handle: THandle; [r]` |  | Handle for the form displayed for the task dialog.
`property ModalResult: TModalResult; [rw]` |  | Modal result value returned when the Task dialog was executed.
`property ProgressBar: TTaskDialogProgressBar; [rw]` |  | Contains information used to configure and update a progress bar enabled on the task dialog.
`property QueryChoices: TStrings; [rw]` |  | Predefined values for the query control on the task dialog.
`property QueryItemIndex: Integer; [rw]` |  | Ordinal position for the value in QueryChoices selected when the task dialog is executed.
`property QueryResult: string; [rw]` |  | String representation for the query entered or selected on the dialog form.
`property RadioButton: TTaskDialogRadioButtonItem; [r]` |  | The radio button selected on the Task dialog.
`property RadioButtons: TTaskDialogButtons; [rw]` |  | Collection with the optional radio buttons defined for the Task dialog.
`property SimpleQuery: string; [rw]` |  | Contains the text displayed and edited using the query control on the task dialog.
`property SimpleQueryPasswordChar: Char; [rw]` |  | Character value used to obfuscate text in SimpleQuery for the query control.
`property Text: TTranslateString; [rw]` |  | Text displayed as main content for the Task dialog.
`property Title: TTranslateString; [rw]` |  | Text displayed at the top of dialog adjacent to the main icon.
`property VerificationText: TTranslateString; [rw]` |  | Optional caption for the verification check box displayed near the bottom of the Task dialog.
`property Width: Integer; [rw]` |  | Sets the width in pixels for the task dialog form.
`property URL: string; [r]` |  | Universal Resource Locator (or identifier) for a hyperlink clicked on the task dialog.
`property Expanded: Boolean; [r]` |  | Indicates the expanded or collapsed state for the ExpandedText on the task dialog form.
`property OnButtonClicked: TTaskDlgClickEvent; [rw]` |  | Event handler signalled for the button clicked when the Task dialog was executed.
`property OnDialogConstructed: TNotifyEvent; [rw]` |  | Event handler signalled when the constructor for the dialog form instance has completed.
`property OnDialogCreated: TNotifyEvent; [rw]` |  | Event handler signalled when a form instance has been created for the dialog.
`property OnDialogDestroyed: TNotifyEvent; [rw]` |  | Event handler signalled when the task dialog form has been freed for the class instance.
`property OnVerificationClicked: TNotifyEvent; [rw]` |  | Event handler signalled when the verification check box has been clicked on the task dialog.
`property OnExpanded: TNotifyEvent; [rw]` |  | Event handler signalled when the ExpandedText on the dialog has been expanded or collapsed.
`property OnTimer: TTaskDlgTimerEvent; [rw]` |  | Event handler signalled when the interval for the timer on the dialog has elapsed.
`property OnRadioButtonClicked: TNotifyEvent; [rw]` |  | Event handler signalled when a radio button on the dialog has been clicked.
`property OnHyperlinkClicked: TNotifyEvent; [rw]` |  | Event handler signalled when a hyperlink in one of the text areas has been clicked.
`property OnNavigated: TNotifyEvent; [rw]` |  |
`property OnHelp: TNotifyEvent; [rw]` |  | Event handler signalled to display help for the task dialog.
`end;`

## Inheritance

`TCustomTaskDialog` |  | Defines a configurable, modal task dialog at run-time.
`TLCLComponent` |  | The base class for LCL components which have an associated widget.
`TComponent`
?
`TObject`

## Description

TCustomTaskDialog is a TLCLComponent descendant which defines a configurable, modal task dialog. It can be used to display and edit information on a dialog form with more features than those available on a standard message box. TCustomTaskDialog includes values like:

- A Title for the dialog.
- A Caption for the dialog.
- A main Icon for the dialog.
- Text to describe the task dialog.
- A footer to display additional information on the dialog.
- An expandable / collapsible text area which can be displayed in the main content area or the footer for the dialog.
- Standard buttons used to return a modal result value.
- Custom command buttons for task-specific actions.
- Radio buttons to select dialog options.
- A progress bar using either the standard or marquee display styles.
- A query field to capture user input as text or by selecting a value from a list of values in a combo-box control.
- A verification message and check box.
- Support for hyperlinks in text areas.

TCustomTaskDialog is the base class for TaskDialog, and provides a multi-platform implementation of the Windows TaskDialog API. It provides properties which can be used to configure the task dialog at design-time or at run-time. At run-time, the Execute method handles converting properties and calling routines and methods in the widgetset which implement the task dialog for a given platform.

Platform Support

The TaskDialog API, upon which TCustomTaskDialog and TTaskDialog are based, is available only on Windows Vista or later versions. On these platforms, the form displayed at run-time is the native form for the platform. On older Windows versions, and other platforms, the TaskDialog API is not available or supported. For these platforms, a standard LCL form is created and populated at run-time to emulate the appearance and behaviors for the Windows implementation. This occurs in the widget set class and uses the components found in the taskdlgemulation.pp unit. It can be forced by including a value in the Flags property for the class instance.

## Version info

Modified in LCL version 4.0. The implementation for the most part is rewritten, and includes additional features not found in previous versions.

## See also

TTaskDialog |  | Implements a configurable modal task dialog.
TLCLTaskDialog |  | Implements an emulated (non-native) task dialog form.
TLCLComponent |  | The base class for LCL components which have an associated widget.