Deprecated. Implements a TaskDialog window for LCL.

lcltaskdialog.pas implements a task dialog. It is implemented natively on Windows Vista and Windows 7 (or later). On Windows XP, it is emulated.

This unit was originally a part of the freeware Synopse mORMot framework, licensed under a MPL/GPL/LGPL tri-license; version 1.19. It has been relicensed with permission from Arnaud Bouchez, the original author, and all contributors.

The original file name is SynTaskDialog.pas.

Deprecated in LCL version 4.0. Use TTaskDialog in dialogs.pp instead. Defined for the MSWINDOWS platform.

Filled once in the initialization section. You can set this reference to Nil to force Delphi dialogs even on Windows Vista/Seven (e.g. make sense if TaskDialogBiggerButtons is True).

The standard common buttons handled by the Task Dialog.

TCommonButton is an enumeration type with values that represent common or standard buttons which can be displayed on a Task Dialog. Values in TCommonButton are stored in the TCommonButtons set type, and used in the implementation of the TTaskDialog and TTaskDialogEx record types.

Represents the OK button. Represents the Yes button. Represents the No button. Represents the Cancel button. Represents the Retry button. Represents the Close button. Set type used to store values from the TCommonButton enumeration.

TCommonButtons is a set type used to store zero or more values from the TCommonButton enumeration. It represents the common or standard buttons which are enabled on a Task Dialog. TCommonButtons and TCommonButton are used in the implementation of the TTaskDialog and TTaskDialogEx record types. It is passed as an argument to the Execute method in TTaskDialog, and used to configure the buttons displayed on the task dialog form.

Represents the available main icons for a task dialog.

Values in the TTaskDialogIcon enumeration represent icons that can be displayed as the main icon on the task dialog.

Values in the enumeration are used as an index into arrays with resource identifiers declared in the implementation section for the unit. The values are also passed as an argument to implementation routines which to get resource strings for the index values.

A TTaskDialogIcon enumeration value is passed as an argument to the Execute method in TTaskDialog.

Indicates the blank icon is used on a task dialog. Represents the warning icon. Represents the question mark icon. Represents the error icon. Represents the information icon. Indicates a main icon is not used on the task dialog. Represents the shield icon. Represents the available footer icons for a task dialog.

TTaskDialogFooterIcon is an enumerated type with values which represent the available footer icons for a task dialog.

A TTaskDialogFooterIcon enumeration value is passed as an argument to the Execute method in TTaskDialog.

Represents a blank icon with no image. Represents the warning icon. Represents the question icon. Represents the error icon. Represents the information icon. Represents the shield icon. Contains flags used to control the display and behavior of a task dialog.

The TTaskDialogFlag enumeration contains the available configuration flags for the Task Dialog. Most are standard TDF_* flags used for the Windows Vista/Seven native API. See the following TASKDIALOG_FLAGS references:

https://learn.microsoft.com/en-us/windows/win32/api/commctrl/ns-commctrl-taskdialogconfig

http://msdn.microsoft.com/en-us/library/bb787473(v=vs.85).aspx

tdfQuery, tdfQueryMasked, and tdfQueryFieldFocused are custom flags, implemented in Pascal code, to handle an input query.

An emulated task dialog (as opposed to a native one) will handle only tdfUseCommandLinks, tdfUseCommandLinksNoIcon, and tdfQuery flag options.

Modified in LCL 4.0 to include tdfNoSetForeGround and tdfSizeToContent flag values. Enables display of hyperlinks in the Content, InfoExpanded, and Footer values in a task dialog. Uses the icon specified by handle as the primary or main icon (instead of the pointer to an Integer resource identifier). Uses the icon specified by handle as the footer icon (instead of the pointer to an Integer resource identifier). Allows the dialog to be closed using Alt+F4, by pressing the Escape key, or using the Close button in the window decorations. Does not require a cancel button on a task dialog. Causes buttons define on a task dialog to be displayed as command links with standard glyph images instead of as plain push buttons. The first line of text in a button caption is used as the main text for button. Following lines are displayed as additional notes for the command link. Causes buttons define on a task dialog to be displayed as command links but without standard glyph images. The first line of text in a button caption is used as the main text for button. Following lines are displayed as additional notes for the command link. Causes expanded information to be displayed at the bottom of the footer area instead of after the main content for a task dialog. Causes the expanded information to be fully visible (expanded) when a task dialog is displayed. Indicates that the verification check box is in a checked state when a task dialog is displayed. Ignored when the verification text for the dialog is empty. Causes a progress bar to be displayed on a task dialog. Causes a progress bar using the Marquis style to be displayed on a task dialog. Causes the callback routine for a task dialog to be called every 200 milliseconds. Causes the task dialog to be centered relative to the parent window for the dialog. When omitted, or when a handle for the parent window has not been specified, the dialog is centered on the active monitor for an application. Causes text on a task dialog to be displayed using the right-to-left reading direction. Causes all radio buttons on a task dialog to be unselected when it is displayed. Allows the task dialog to be minimized. Prevents the task dialog from being brought to the foreground when it is activated. Defined for Windows 8 or later version. Indicates the width for the dialog is determined by the text in the content area. The flag is ignored if the dialog width is not set to 0 (zero). Causes a query input control to be displayed on the task dialog. Causes Asterisk ('*') characters to be displayed to obfuscate characters in the query input. Causes the query input to be focused when a task dialog is displayed. Set type used to store values from the TTaskDialogFlag enumeration.

Contains the configuration flags enabled for a task dialog. TTaskDialogFlags is the type used to implement the Flags property in TCustomTaskDialog.

TCustomTaskDialog.Flags Pointer to the TTaskDialog record type. Specifies a callback routine executed when a button is clicked on a task dialog.

This callback will be triggered when a task dialog button is clicked. To prevent the task dialog from closing, the application must set ACanClose to False. Otherwise, the task dialog is closed and the button ID is returned via the original TTaskDialog.Execute() result.

TTaskDialogButtonClickedEvent is the type used to implement the OnButtonClicked event handler in the TTaskDialogImplementation and TTaskDialogEx record types. The type is also passed as an argument to the Execute method in TTaskDialog.

Handle to the task dialog form for the callback. Button identifier for the callback notification. Indicates if the dialog can be closed. Set to True in the callback implementation to allow the task dialog to be closed. Set to False to prevent closing the dialog. Represents visual elements which can be displayed on a task dialog.

TTaskDialogElement is an enumerated type with values that represent the visual elements for a task dialog. The values map to low-level TDE_CONTENT...TDE_MAIN_INSTRUCTION constants, the query editor, or the check box on a dialog. tdeEdit is for the query editor. tdeVerif is for the check box.

TTaskDialogElement are passed as an argument to the SetElementText method in TTaskDialog used to set the value for the visual element.

Represents the primary content for a dialog. Represents additional text which can be displayed in the expandable area for a task dialog. Represents the text displayed in the footer area for a task dialog. Represents the main instruction displayed at the top of the task dialog. When omitted, a resource string describing the main icon is used. Represents the query input value for the task dialog. Represents the verification text displayed in a check box at the bottom of the task dialog. Form class displayed when a native dialog class is not available.

TEmulatedTaskDialog is a TForm descendant which implements the form displayed for an emulated task dialog. It provides a LCL implementation of the task dialog. It is used when a native task dialog implementation is not available, or is explicitly requested when a task dialog is executed.

TLabels instances are used to represent the visual elements on the dialog as defined in the TTaskDialogElement enumeration.

It provides a TComboBox used for a selection list, a TEdit control used for query input, and a TCheckBox used for the verification text.

There are restrictions to the task dialog flags used on an emulated task dialog. Only the tdfUseCommandLinks, tdfUseCommandLinksNoIcon, and tdfQuery flag options are supported. Other values passed requested in the caller are ignored for an emulated task dialog.

Use the aNonNative argument in the TTaskDialog.Execute method to specify use of an emulated task dialog at run-time.

TForm Calls the OnButtonClicked event handler for the task dialog which owns the emulated dialog form.

HandleEmulatedButtonClicked is a method used to signal an assigned OnButtonClicked event handler on the task dialog which owns the emulated dialog form. No actions are performed in the method if Owner (the TTaskDialog passed in the constructor) or its OnButtonClicked event handler have not been assigned.

HandleEmulatedButtonClicked signals the OnButtonClicked event in the Owner using the modal result value in Sender as an argument. If the event handler indicates that the dialog cannot be closed, the ModalResult property in the form is set to mrNone. Other modal result values are handled by the TaskDialog.Execute method.

Object instance (TButton) for the click event processed in the method. Handles Alt+F4 and Esc key down events for the emulated task dialog.

KeyDown is an overridden method in TEmulatedTaskDialog. It handles key down events which may close the emulated task dialog form.

If the form has a system menu icon in BorderIcons, the Escape key causes the form to be closed by calling the Close method.

If a system menu is not used in BorderIcons, use of Alt+F4 to close the dialog form is prevented. The value in Key is set to 0 to discard the key event.

KeyDown calls the inherited method prior to exit using the values in Key and Shift as arguments. This allows the ancestor to signal OnKeyDown event handler(s) used in the application.

Virtual key code for the key down event. Shift, Ctrl, or Alt modifier for the key event. Constructor for the form instance.

CreateNew is the overridden constructor for the form class instance. CreateNew is used to create a form instance which does not have a resource (.lfm) file.

CreateNew calls the inherited method on entry to initialize properties for the form instance and to register the form on the current Screen.

The overridden constructor sets the value in KeyPreview to True. This allows the form instance to intercept KeyDown, KeyUp, and KeyPress events from child controls before they are applied to the active control on the form. This is commonly done on modal dialog forms to allow the parent form to handle specific interactions with the user.

TCustomForm.CreateNew TForm.KeyPreview Screen TScreen Component which owns the emulated task dialog form. Contains a specific instance number for the form. The default value is 0. Owner of the emulated task dialog form instance.

Contains the task dialog instance (TTaskDialog) which owns the form instance. The value for the member is passed as an argument to the CreateNew constructor. Re-implements the Owner property defined in the TComponent ancestor.

TComponent.Owner Provides indexed access to the label for a visual element on the task dialog form by its TTaskDialogElement value.

Element is an indexed array member with the TLabel instances used for the visual elements on the control. Elements allows access to the properties and methods for the specific element identified by a TTaskDialogElement enumeration value. For instance:


// set the value for the main instruction element
AForm.Element[tdeContent].Caption := 'What is this?';

// set the value for the main content element
AForm.Element[tdeContent].Caption := 
  'This is the main content for the task dialog form.' + #10 + 
  'It is kind of important.';

A subset of TTaskDialogElement values in the range tdeContent..tdeMainInstruction are supported for the Elements member. The other visual elements are represented as controls, like Edit and Verif. Use the Combo member to access the selection list for the task dialog form.

Control with the selection list for the task dialog form.

Combo is a TComboBox member with the list of selectable items displayed on the task dialog form.

Use Edit to access the control used for the query input value on the dialog.

Use Verif to access the control with the verification text displayed on the dialog.

Use Element to access other visual elements with textual values displayed on the dialog.

TComboBox Control used to edit the optional query input for the task dialog dialog.

Edit is a TEdit member with the control used to edit the optional query input value for the dialog form.

Use Combo to access the selection list displayed on the dialog.

Use Verif to access the control with the verification text displayed on the dialog.

Use Element to access other visual elements with textual values displayed on the dialog.

TEdit Check box control for the verification text displayed on the task dialog form.

Verif is a TCheckBox member with the control used for the verification text displayed on the dialog form.

Use Edit to access the query input value for the dialog.

Use Combo to access the selection list displayed on the dialog.

Use Element to access other visual elements with textual values displayed on the dialog.

TCheckBox Provides access to the task dialog implementation.

Structure which provides low-level access to the task dialog implementation. Points either to the HWND handle of the new TaskDialog API or to the emulation dialog.

Event handler signalled for a button click on the task dialog. True if a TEmulatedTaskDialog form is needed. False if the handle to a native dialog is needed. Handle to the native dialog used in the implementation. TEmulatedTaskDialog instance used in the implementation. Implements a task dialog.

Uses the new TaskDialog API under Vista/Seven, and emulates it with Pascal/LCL code and standard themed components under XP or Windows 2000. Creating a TTaskDialog object/record on the stack will initialize all of its string parameters to ''. Set the appropriate string parameters, then call Execute() with all additional parameters.

RadioRes, SelectionRes, and VerifyChecked will be used to reflect the state after execution of the dialog.

Typical usage:


var Task: TTaskDialog;
begin
  Task.Inst := 'Saving application settings';
  Task.Content := 'This is the content';
  Task.Radios := 'Store settings in registry' +#10+ ' Store settings in XML file';
  Task.Verify := 'Do no ask for this setting next time';
  Task.VerifyChecked := true;
  Task.Footer := 'XML file is perhaps a better choice';
  Task.Execute([],0,[],tiQuestion,tfiInformation,200);
  ShowMessage(IntToStr(Task.RadioRes)); // 200=Registry, 201=XML
  if Task.VerifyChecked then
  ShowMessage(Task.Verify);
end;

The main title for the task dialog window.

When unassigned, the title from the application main form is used.

The main instruction displayed on the dialog.

The main instruction (first line displayed at the top of dialog). If not assigned (contains ''), the text is taken from resource strings for the message type defined in LCLStrConsts.

rsMtWarning rsMtError rsMtInformation rsMtConfirmation rsMtAuthentication rsMtCustom The text displayed as the primary content for the dialog.

The value is used in the Execute method to add a label displayed in the dialog.

In previous LCL versions, '\n' characters sequences were converted to LineEnding characters. This action is no longer performed as of revision 64975. Delimited list of captions for the custom buttons displayed on the dialog.

A #13#10 or #10 separated list of custom buttons. They will be identified with an ID number starting at 100. By default, the buttons will be created at the dialog bottom, just like the common buttons. If tdfUseCommandLinks flag is set, the custom buttons will be created as big button in the middle of the dialog window; in this case, any '\n' will be converted as note text (shown with smaller text under native Vista/Seven TaskDialog, or as popup hint within Delphi emulation).

Delimited list of captions for radio buttons on the dialog.

A #13#10 or #10 delimited list of custom radio buttons. They will be identified with an ID number starting at 200. aRadioDef parameter can be set to define the default selected value. '\n' will be converted as note text (shown with smaller text under native Vista/Seven TaskDialog, or as popup hint within Delphi emulation).

The text for the expandable information content.

The Delphi emulation will always show the Info content (there is no collapse or expand button).

The button caption to be displayed when the information is expanded.

Not used under XP: the Delphi emulation will always show the Info content.

The button caption to be displayed when the information is collapsed.

Not used under XP. The Delphi emulation will always show the Info content.

The text content displayed in the footer area for the dialog. The verification text for the optional check box at the bottom of the dialog. A delimited list of items which can be selected in the dialog.

A #13#10 or #10 separated list of items to be selected. If set, a Combo Box will be displayed to select. If tdfQuery is in the flags, the combo box will be in addition mode and the user will be able to edit the Query text or fill the field with one item of the selection. This selection is not handled via the Vista/Seven TaskDialog, but with our Delphi emulation code (via a TComboBox).

Input query which can be edited on the dialog.

If tdfQuery is in the flags, this will contain the default query text.

The selected radio button on the dialog.

The selected radio button; the first button is at ordinal position 0.

The currently selected item in the selection list or combo-box.

After execution, it contains the selected item from the Selection list.

Checked state for the verification check box.

Indicates whether state for the optional check box state at the bottom of the dialog. If Verify is not set to '', then VerifyChecked is set to True before execution of the dialog. After execution, it will contain the returned check box state.

Modified in LCL version 3.0 to use the LongBool type (instead of Boolean). Provides access to the task dialog implementation.

TTaskDialogImplementation type which provides low-level access to the task dialog implementation.

Launches the task dialog form.

Some common buttons can be set via aCommonButtons. In emulation mode, aFlags will handle only tdfUseCommandLinks, tdfUseCommandLinksNoIcon, and tdfQuery options.

Returns 0 on error, or the Button ID (e.g. mrOk for the OK button or 100 for the first custom button defined in Buttons string).

If Buttons have been defined, aButtonDef can set the selected Button ID on the dialog.

If radio buttons have been defined in Radios, values in ARadioDef and AFlags are used to control the default radio button which is Checked on the dialog. If tdfNoDefaultRadioButton has not been included in AFlags, aRadioDef is used as the default radio button. When aRadioDef is unassigned (0), the first radio button is Checked. If tdfNoDefaultRadioButton has been included in AFlags, all radio buttons are unchecked by default on the dialog.

aDialogIcon and aFooterIcon are used to specify the icons displayed on the dialog form.

aWidth can be used to supply a custom form width (in pixels). When set to a value <= 0, the length of the text in Inst and Content are used to determine the width for the dialog form. When an emulated task dialog is used, the upper limit for the value is 480 pixels and the lower limit is 120 pixels.

aParent can be set to any HWND instance - by default, Application.DialogHandle.

If aNonNative is True, the Delphi emulation code will always be used.

aEmulateClassicStyle can be set to enforce conformity when using a non-themed user interface (classic) - see http://synopse.info/forum/viewtopic.php?pid=2867#p2867. This argument is set to True if the tfEmulateClassicStyle flag has been included in the Flags property for the TCustomTaskDialog. When enabled, the following visual changes are applied to the dialog:

Labels use a taller font height with Bold in the font style.
Buttons are wider but smaller in height.
The default font is either Calibri, Tahoma, or Arial on the dialog form.
Panels use the clDefault color instead of clWindow.

aOnButtonClicked can be set to a callback routine executed when a button is clicked.

Modified in LCL version 2.2.6+ for native dialogs on the Windows platform. An explicit dialog width (in pixels) is converted to dialog base units for use in the TaskDialogIndirect Windows API.

Modified in LCL 4.0 to provide support on the Windows platform for the TDF_NO_SET_FOREGROUND and TDF_SIZE_TO_CONTENT flags not implemented in CommCtrl for FPC versions prior to 3.3.1.

Modal result value returned from the dialog. Set of common or standard buttons enabled on the task dialog form. Indicates the button which is the default for the task dialog form. Set of flags used to configure the task dialog and specify its behavior. Specifies the main icon displayed on the task dialog. Specifies the icon displayed in the footer area for the task dialog. Ordinal position for the default radio button selected on the task dialog. Specifies the display width for the task dialog form, or 0 to automatically calculate the width. Window handle for the parent window of the task dialog. 0 causes the active form on the current monitor to be used. True causes Delphi emulation code to be used during execution of the task dialog. True forces a non-themed (classic) user interface to be used. Contains the callback executed when a button is clicked. Sets the value for the specified visual element on the dialog.

Allows a OnButtonClicked callback to change the value for a Task Dialog main element. Note that tdeVerif could be modified only in emulation mode, since the API does not give any run-time access to the check box caption. Other elements will work in both emulated and native modes.

TTaskDialogElement enumeration value for the visual element updated in the method. New value for the specified dialog element. Assigned to the Caption or Text property in the corresponding element. Provides a wrapper for the Execute method in TTaskDialog.

A wrapper around the TTaskDialog.Execute method. Used to provide "flat" access to task dialog parameters.

The TTaskDialog instance accessed in the implementation.

The associated main TTaskDialog instance.

Common command buttons displayed on the task dialog.

Some common buttons to be displayed.

The identifier for the default button on the task dialog. The default button ID. Task dialog flags enabled for the dialog.

The associated configuration flags for this Task Dialog. In emulation mode, aFlags will handle only tdfUseCommandLinks, tdfUseCommandLinksNoIcon, and tdfQuery options.

Indicates the image displayed as the main icon on the dialog. Used to specify the dialog icon. Indicates the image displayed as the footer icon on the dialog. Used to specify the footer icon. Default radio button enabled when the task dialog is displayed. The default radio button ID. Default width for the task dialog. Can be used to force a custom form width (in pixels). Indicates whether an emulated task dialog form is used.

If True, the emulated (non-native) code will always be used.

Forces the user interface to used non-themed interfacfe elements. Can be used to enforce conformity with the non-themed user interface. Event handler signalled when a button is clicked on the task dialog. This event handler will be fired on a button dialog click. Initializes the dialog parameters to common default values.

Can be used to display some information with less parameters. For example:


var TaskEx: TTaskDialogEx;
// ...
TaskEx.Init;
TaskEx.Base.Title := 'Task Dialog Test';
TaskEx.Base.Inst := 'Callback Test';
TaskEx.Execute;

Sets the record instance to the per-initialized value in the DefaultTaskDialog variable.

Method used to display and execute the extended task dialog.

Execute is an Integer function used to display the dialog and capture its result. It is a wrapper around the TTaskDialog.Execute method. TTaskDialogEx passes its member values as arguments to the Execute method in the base TTaskDialog type.

Before calling Execute, assign a routine to the OnButtonClicked event handler to perform actions needed for a specific button clicked on the dialog.

The return value contains the modal result value returned from the base task dialog.

Modal result value for the dialog. Contains the identifier for the button clicked on the dialog. Handle for the window which is the parent for the dialog. 0 (the default) is the unassigned value. Gets a string with Ampersand characters removed from the specified value.

Returns the specified text without any '&' (Ampersand) characters used as a accelerator or hot key prefix.

String with all Ampersand characters removed. String examined and converted in the routine. The default Task Dialog wrapper instance.

Can be used to display a task dialog using fewer parameters, just like the TTaskDialogEx.Init method. For example:


var TaskEx: TTaskDialogEx;
// ...
TaskEx := DefaultTaskDialog;
TaskEx.Base.Title := 'Task Dialog Test';
TaskEx.Base.Inst := 'Callback Test';
TaskEx.Execute;

Defines a function used to translate a caption used on a task dialog.

TTaskDialogTranslate is the type used to implement the TaskDialog_Translate variable.

Translated value for the specified caption. Caption value translated in the routine. Function used to translate the content on an emulated task dialog. Assigns the default font used for task dialogs when one has not already been chosen.

DefaultFont creates a TFont instance used in the implementation for the unit. The default font name and size are updated in the font instance returned as the Result for the routine.

The default font name value is 'default', and causes the default font for the platform or operating system to be used. The default size is 10 (points).

For the Windows platform, a different font name (and size) may be used. When the Calibri typeface is installed, it is used with an 11 point font size. Otherwise, Tahoma or Arial are used as the fallback font names (in that order) using a 10 point font size.

TFont instance with the default typeface and font size for a task dialog.