TCustomTaskDialog class

In unit Dialogs

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

Declaration

pascal

TCustomTaskDialog = class(TLCLComponent)

Inheritance

Descends from it: TTaskDialog

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.

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

Properties

`Button`	public	Not used in the current LCL version.
`Buttons`	public	Collection with the buttons for the Task dialog.
`Caption`	public	Caption text displayed on the title bar for the Task dialog.
`CustomFooterIcon`	public	Contains a custom icon displayed in the footer area on the dialog.
`CustomMainIcon`	public	Contains a custom icon displayed in the main content area on the dialog.
`CommonButtons`	public	Set of common buttons displayed on the Task dialog.
`CollapseButtonCaption`	public	Caption text for the "expando" button on the task dialog.
`DefaultButton`	public	Index of the default button, from the set in the CommonButtons property.
`ExpandButtonCaption`	public	Caption displayed for the expand/collapse button on the dialog.
`ExpandedText`	public	Text that is displayed in the expandable / collapsible area on the Task dialog.
`Flags`	public	Set of options enabled for the Task dialog.
`FooterIcon`	public	Icon for the footer area displayed at the bottom of the dialog.
`FooterText`	public	Text that is displayed in the footer area on the Task dialog.
`MainIcon`	public	Icon displayed beside the Title for the dialog.
`Handle`	public	Handle for the form displayed for the task dialog.
`ModalResult`	public	Modal result value returned when the Task dialog was executed.
`ProgressBar`	public	Contains information used to configure and update a progress bar enabled on the task dialog.
`QueryChoices`	public	Predefined values for the query control on the task dialog.
`QueryItemIndex`	public	Ordinal position for the value in QueryChoices selected when the task dialog is executed.
`QueryResult`	public	String representation for the query entered or selected on the dialog form.
`RadioButton`	public	The radio button selected on the Task dialog.
`RadioButtons`	public	Collection with the optional radio buttons defined for the Task dialog.
`SimpleQuery`	public	Contains the text displayed and edited using the query control on the task dialog.
`SimpleQueryPasswordChar`	public	Character value used to obfuscate text in SimpleQuery for the query control.
`Text`	public	Text displayed as main content for the Task dialog.
`Title`	public	Text displayed at the top of dialog adjacent to the main icon.
`VerificationText`	public	Optional caption for the verification check box displayed near the bottom of the Task dialog.
`Width`	public	Sets the width in pixels for the task dialog form.
`URL`	public	Universal Resource Locator (or identifier) for a hyperlink clicked on the task dialog.
`Expanded`	public	Indicates the expanded or collapsed state for the ExpandedText on the task dialog form.

Methods

`WSRegisterClass`	protected	Registers the task dialog class in the widgetset when needed.
`DoExecute`	protected	Performs actions to configure and execute the dialog.
`DoOnButtonClicked`	protected	Signals the OnButtonClicked event handler (when assigned) for the button with the specified modal result value.
`DoOnRadioButtonClicked`	protected	Sets the active radio button and signals the OnRadioButtonClicked event handler (when assigned).
`DoOnDialogConstructed`	protected	Signals the OnDialogConstructed event handler (when assigned).
`DoOnDialogCreated`	protected	Signals the OnDialogCreated event handler (when assigned).
`DoOnDialogDestroyed`	protected	Signals the OnDialogDestroyed event handler (when assigned).
`DoOnExpandButtonClicked`	protected	Updates the value in the Expanded property and signals the OnExpanded event handler (when assigned).
`DoOnTimer`	protected	Signals the OnTimer event handler (when assigned) using the specified parameter values.
`DoOnVerificationClicked`	protected	Updates Flags to reflect the checked state for the verification control and signals the OnVerificationClicked event handler (when assigned).
`DoOnHelp`	protected	Signals the OnHelp event handler (when assigned).
`DoOnHyperlinkClicked`	protected	Updates the value in URL and signals the OnHyperlinkClicked event handler (when assigned).
`DoOnNavigated`	protected	Signals the OnNavigated event handler (when assigned).
`InternalSetDialogHandle`	protected	Sets the value for the Handle property.
`SetRadioButtonFromRadioIndex`	protected	Makes the radio button with the specified identifier the active RadioButton on the task dialog.
`Create`	public	Constructor for the class instance.
`Destroy`	public	Destructor for the class instance.
`ButtonIDToModalResult`	public	Gets the modal result value for the button with the specified identifier.
`Execute`	public	Displays the task dialog and captures the modal result value.

Events

`OnButtonClicked`	public	Event handler signalled for the button clicked when the Task dialog was executed.
`OnDialogConstructed`	public	Event handler signalled when the constructor for the dialog form instance has completed.
`OnDialogCreated`	public	Event handler signalled when a form instance has been created for the dialog.
`OnDialogDestroyed`	public	Event handler signalled when the task dialog form has been freed for the class instance.
`OnVerificationClicked`	public	Event handler signalled when the verification check box has been clicked on the task dialog.
`OnExpanded`	public	Event handler signalled when the ExpandedText on the dialog has been expanded or collapsed.
`OnTimer`	public	Event handler signalled when the interval for the timer on the dialog has elapsed.
`OnRadioButtonClicked`	public	Event handler signalled when a radio button on the dialog has been clicked.
`OnHyperlinkClicked`	public	Event handler signalled when a hyperlink in one of the text areas has been clicked.
`OnNavigated`	public
`OnHelp`	public	Event handler signalled to display help for the task dialog.