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

# TTaskDialog

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

Implements a configurable modal task dialog.

## Declaration

Source position: dialogs.pp line 859

`type TTaskDialog = class(TCustomTaskDialog)`
`published`
`property Buttons: TTaskDialogButtons;` |  | Collection with the buttons for the Task dialog.
`property Caption: TTranslateString;` |  | Caption text displayed on the title bar for the Task dialog.
`property CommonButtons: TTaskDialogCommonButtons;` |  | Set of common buttons displayed on the Task dialog.
`property CollapseButtonCaption: TTranslateString;` |  | Caption text for the "expando" button on the task dialog.
`property CustomFooterIcon: TIcon;` |  | Contains a custom icon displayed in the footer area on the dialog.
`property CustomMainIcon: TIcon;` |  | Contains a custom icon displayed in the main content area on the dialog.
`property DefaultButton: TTaskDialogCommonButton;` |  | Index of the default button, from the set in the CommonButtons property.
`property ExpandButtonCaption: TTranslateString;` |  | Caption displayed for the expand/collapse button on the dialog.
`property ExpandedText: TTranslateString;` |  | Text that is displayed in the expandable / collapsible area on the Task dialog.
`property Flags: TTaskDialogFlags;` |  | Set of options enabled for the Task dialog.
`property FooterIcon: TTaskDialogIcon;` |  | Icon for the footer area displayed at the bottom of the dialog.
`property FooterText: TTranslateString;` |  | Text that is displayed in the footer area on the Task dialog.
`property MainIcon: TTaskDialogIcon;` |  | Icon displayed beside the Title for the dialog.
`property ProgressBar: TTaskDialogProgressBar;` |  | Contains information used to configure and update a progress bar enabled on the task dialog.
`property RadioButtons: TTaskDialogButtons;` |  | Collection with the optional radio buttons defined for the Task dialog.
`property QueryChoices: TStrings;` |  | Predefined values for the query control on the task dialog.
`property QueryItemIndex: Integer;` |  | Ordinal position for the value in QueryChoices selected when the task dialog is executed.
`property SimpleQuery: string;` |  | Contains the text displayed and edited using the query control on the task dialog.
`property SimpleQueryPasswordChar: Char;` |  | Character value used to obfuscate text in SimpleQuery for the query control.
`property Text: TTranslateString;` |  | Text displayed as main content for the Task dialog.
`property Title: TTranslateString;` |  | Text displayed at the top of dialog adjacent to the main icon.
`property VerificationText: TTranslateString;` |  | Optional caption for the verification check box displayed near the bottom of the Task dialog.
`property Width: Integer;` |  | Sets the width in pixels for the task dialog form.
`property OnButtonClicked: TTaskDlgClickEvent;` |  | Event handler signalled for the button clicked when the Task dialog was executed.
`property OnDialogConstructed: TNotifyEvent;` |  | Event handler signalled when the constructor for the dialog form instance has completed.
`property OnDialogCreated: TNotifyEvent;` |  | Event handler signalled when a form instance has been created for the dialog.
`property OnDialogDestroyed: TNotifyEvent;` |  | Event handler signalled when the task dialog form has been freed for the class instance.
`property OnVerificationClicked: TNotifyEvent;` |  | Event handler signalled when the verification check box has been clicked on the task dialog.
`property OnExpanded: TNotifyEvent;` |  | Event handler signalled when the ExpandedText on the dialog has been expanded or collapsed.
`property OnTimer: TTaskDlgTimerEvent;` |  | Event handler signalled when the interval for the timer on the dialog has elapsed.
`property OnRadioButtonClicked: TNotifyEvent;` |  | Event handler signalled when a radio button on the dialog has been clicked.
`property OnHyperlinkClicked: TNotifyEvent;` |  | Event handler signalled when a hyperlink in one of the text areas has been clicked.
`end;`

## Inheritance

`TTaskDialog` |  | Implements a configurable modal task dialog.
`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

TTaskDialog is a TCustomTaskDialog descendant which implements 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.

TTaskDialog sets the visibility for properties introduced in ancestor classes, 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 TTaskDialog is 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.

Using TTaskDialog at Run-time.

    procedure TForm1.Button1Click(Sender: TObject);
      var ATaskDialog: TTaskDialog; // requires Dialogs in uses clause
    begin
      ATaskDialog := TTaskDialog.Create(Self);
      with ATaskDialog do
      begin
         Caption := 'Let''s do this...';
         MainIcon := tdiShield;
         Title := 'Task Title';

        Text := 'This tells the user the purpose for the dialog. ' +
          'Please read and accept the Terms of Service. '+#10+#10+
          'Some users prefer a little conversation before they will agree. ' +
          'Along with a progress bar. Please tell us your level of interest.';

        RadioButtons.Clear;
        RadioButtons.Add.Caption := 'Low';
        RadioButtons.Add.Caption := 'Medium';
        RadioButtons.Add.Caption := 'High';

        CommonButtons := [tcbOk,tcbCancel,tcbRetry];

        ExpandedText := 'The Terms of Service grants a waiver of responsibility '+
          'to Acme Corporation LLC for any insane acts a Coyote might perform '+
          'using products or services provided by the Corporation.'+#10+#10+
          'There is no legal venue where the Corporation is responsible. ' +
          'Especially Albuquerque, NM USA. ' +#10+#10+
          'Buyer beware. All rights reserved. Shipping fees and taxes may apply.';

        VerificationText := 'I agree to everything.';

        FooterIcon := tdiWarning;
        FooterText := 'This is your <a href="#terminus">final</a> warning.';

        Flags := [tfEnableHyperlinks, tfAllowDialogCancellation,
          tfExpandedByDefault, tfVerificationFlagChecked];

        if Execute then ; // do something based on ModalResult
        Free;
      end;
    end;

## 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

TCustomTaskDialog |  | Defines a configurable, modal task dialog at run-time.
TLCLTaskDialog |  | Implements an emulated (non-native) task dialog form.