<?xml version="1.0" encoding="UTF-8"?>
<!--

Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus 
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0 
International public license.

https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
file://../../cc-by-sa-4-0.txt

Copyright (c) 1997-2023, by the Lazarus Development Team.

-->
<fpdoc-descriptions>
<package name="lcl">
<!--
====================================================================
LCLTaskDialog
====================================================================
-->
<module name="LCLTaskDialog">
<short>Implements a TaskDialog window for LCL.</short>
<descr>
<p>
<file>lcltaskdialog.pas</file> implements a task dialog. It is implemented 
natively on Windows Vista and Windows 7 (or later). On Windows XP, it is 
emulated.
</p>
<p>
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.
</p>
<p>
The original file name is SynTaskDialog.pas.
</p>
</descr>

<!-- unresolved external references -->
<element name="Windows"/>
<element name="ctypes"/>
<element name="Classes"/>
<element name="SysUtils"/>
<element name="LazUTF8"/>
<element name="LCLType"/>
<element name="LCLStrConsts"/>
<element name="LCLIntf"/>
<element name="InterfaceBase"/>
<element name="ImgList"/>
<element name="LResources"/>
<element name="Menus"/>
<element name="Graphics"/>
<element name="Forms"/>
<element name="Controls"/>
<element name="StdCtrls"/>
<element name="ExtCtrls"/>
<element name="Buttons"/>
<element name="DialogRes"/>

<element name="TaskDialogIndirect">
<short>
Defined for the MSWINDOWS platform.
</short>
<descr>
<p>
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 <b>True</b>).
</p>
</descr>
<seealso/>
</element>
<element name="TaskDialogIndirect.Result">
<short/>
</element>
<element name="TaskDialogIndirect.AConfig">
<short/>
</element>
<element name="TaskDialogIndirect.Res">
<short/>
</element>
<element name="TaskDialogIndirect.ResRadio">
<short/>
</element>
<element name="TaskDialogIndirect.VerifyFlag">
<short/>
</element>

<element name="TCommonButton">
<short>
The standard common buttons handled by the Task Dialog.
</short>
<descr>
<p>
<var>TCommonButton</var> 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.
</p>
</descr>
<seealso>
<link id="TCommonButtons"/>
<link id="TTaskDialog.Execute"/>
<link id="TTaskDialogEx"/>
</seealso>
</element>
<element name="TCommonButton.cbOK">
<short>
Represents the <b>OK</b> button.
</short>
</element>
<element name="TCommonButton.cbYes">
<short>
Represents the <b>Yes</b> button.
</short>
</element>
<element name="TCommonButton.cbNo">
<short>
Represents the <b>No</b> button.
</short>
</element>
<element name="TCommonButton.cbCancel">
<short>
Represents the <b>Cancel</b> button.
</short>
</element>
<element name="TCommonButton.cbRetry">
<short>
Represents the <b>Retry</b> button.
</short>
</element>
<element name="TCommonButton.cbClose">
<short>
Represents the <b>Close</b> button.
</short>
</element>

<element name="TCommonButtons">
<short>
Set type used to store values from the TCommonButton enumeration.
</short>
<descr>
<p>
<var>TCommonButtons</var> is a set type used to store zero or more values 
from the <var>TCommonButton</var> 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.
</p>
</descr>
<seealso>
<link id="TCommonButton"/>
<link id="TTaskDialog.Execute"/>
<link id="TTaskDialogEx"/>
</seealso>
</element>

<element name="TTaskDialogIcon">
<short>
Represents the available main icons for a task dialog.
</short>
<descr>
<p>
Values in the <var>TTaskDialogIcon</var> enumeration represent icons that can 
be displayed as the main icon on the task dialog. 
</p>
<p>
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.
</p>
<p>
A TTaskDialogIcon enumeration value is passed as an argument to the Execute 
method in TTaskDialog.
</p>
</descr>
<seealso>
<link id="TTaskDialog.Execute"/>
</seealso>
</element>
<element name="TTaskDialogIcon.tiBlank">
<short>
Indicates the blank icon is used on a task dialog.
</short>
</element>
<element name="TTaskDialogIcon.tiWarning">
<short>
Represents the warning icon.
</short>
</element>
<element name="TTaskDialogIcon.tiQuestion">
<short>
Represents the question mark icon.
</short>
</element>
<element name="TTaskDialogIcon.tiError">
<short>
Represents the error icon.
</short>
</element>
<element name="TTaskDialogIcon.tiInformation">
<short>
Represents the information icon.
</short>
</element>
<element name="TTaskDialogIcon.tiNotUsed">
<short>
Indicates a main icon is not used on the task dialog.
</short>
</element>
<element name="TTaskDialogIcon.tiShield">
<short>
Represents the shield icon.
</short>
</element>

<element name="TTaskDialogFooterIcon">
<short>
Represents the available footer icons for a task dialog.
</short>
<descr>
<p>
<var>TTaskDialogFooterIcon</var> is an enumerated type with values which 
represent the available footer icons for a task dialog.
</p>
<p>
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.
</p>
<p>
A TTaskDialogFooterIcon enumeration value is passed as an argument to the 
Execute method in TTaskDialog.
</p>
</descr>
<seealso>
<link id="TTaskDialog.Execute"/>
</seealso>
</element>
<element name="TTaskDialogFooterIcon.tfiBlank">
<short>
Represents a blank icon with no image.
</short>
</element>
<element name="TTaskDialogFooterIcon.tfiWarning">
<short>
Represents the warning icon.
</short>
</element>
<element name="TTaskDialogFooterIcon.tfiQuestion">
<short>
Represents the question icon.
</short>
</element>
<element name="TTaskDialogFooterIcon.tfiError">
<short>
Represents the error icon. 
</short>
</element>
<element name="TTaskDialogFooterIcon.tfiInformation">
<short>
Represents the information icon. 
</short>
</element>
<element name="TTaskDialogFooterIcon.tfiShield">
<short>
Represents the shield icon. 
</short>
</element>

<element name="TTaskDialogFlag">
<short>
Contains flags used to control the display and behavior of a task dialog.
</short>
<descr>
<p>
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:
</p>
<p>
<url href="https://learn.microsoft.com/en-us/windows/win32/api/commctrl/ns-commctrl-taskdialogconfig">
https://learn.microsoft.com/en-us/windows/win32/api/commctrl/ns-commctrl-taskdialogconfig
</url> 
</p>
<p>
<url href="https://msdn.microsoft.com/en-us/library/bb787473(v=vs.85).aspx">
http://msdn.microsoft.com/en-us/library/bb787473(v=vs.85).aspx
</url>
</p>
<p>
Please note: TTaskDialogFlag <b>does not</b> include the TDF_SIZE_TO_CONTENT flag allowed in the Windows API.
</p>
<p>
tdfQuery, tdfQueryMasked, and tdfQueryFieldFocused are custom flags, 
implemented in Pascal code, to handle an input query.
</p>
<p>
An emulated task dialog (as opposed to a native one) will handle only 
tdfUseCommandLinks, tdfUseCommandLinksNoIcon, and tdfQuery flag options.
</p>
</descr>
<seealso/>
</element>
<element name="TTaskDialogFlag.tdfEnableHyperLinks">
<short>
Enables display of hyperlinks in the Content, InfoExpanded, and Footer values 
in a task dialog.
</short>
</element>
<element name="TTaskDialogFlag.tdfUseHIconMain">
<short>
Uses the icon specified by handle as the primary or main icon (instead of the 
pointer to an Integer resource identifier).
</short>
</element>
<element name="TTaskDialogFlag.tdfUseHIconFooter">
<short>
Uses the icon specified by handle as the footer icon (instead of the 
pointer to an Integer resource identifier).
</short>
</element>
<element name="TTaskDialogFlag.tdfAllowDialogCancellation">
<short>
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.
</short>
</element>
<element name="TTaskDialogFlag.tdfUseCommandLinks">
<short>
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.
</short>
</element>
<element name="TTaskDialogFlag.tdfUseCommandLinksNoIcon">
<short>
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.
</short>
</element>
<element name="TTaskDialogFlag.tdfExpandFooterArea">
<short>
Causes expanded information to be displayed at the bottom of the footer area 
instead of after the main content for a task dialog.
</short>
</element>
<element name="TTaskDialogFlag.tdfExpandByDefault">
<short>
Causes the expanded information to be fully visible (expanded) when a task dialog is displayed.
</short>
</element>
<element name="TTaskDialogFlag.tdfVerificationFlagChecked">
<short>
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.
</short>
</element>
<element name="TTaskDialogFlag.tdfShowProgressBar">
<short>
Causes a progress bar to be displayed on a task dialog.
</short>
</element>
<element name="TTaskDialogFlag.tdfShowMarqueeProgressBar">
<short>
Causes a progress bar using the Marquis style to be displayed on a task 
dialog.
</short>
</element>
<element name="TTaskDialogFlag.tdfCallbackTimer">
<short>
Causes the callback routine for a task dialog to be called every 200 
milliseconds.
</short>
</element>
<element name="TTaskDialogFlag.tdfPositionRelativeToWindow">
<short>
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.
</short>
</element>
<element name="TTaskDialogFlag.tdfRtlLayout">
<short>
Causes text on a task dialog to be displayed using the right-to-left 
reading direction.
</short>
</element>
<element name="TTaskDialogFlag.tdfNoDefaultRadioButton">
<short>
Causes all radio buttons on a task dialog to be unselected when it is displayed.
</short>
</element>
<element name="TTaskDialogFlag.tdfCanBeMinimized">
<short>
Allows the task dialog to be minimized. 
</short>
</element>
<element name="TTaskDialogFlag.tdfQuery">
<short>
Causes a query input control to be displayed on the task dialog.
</short>
</element>
<element name="TTaskDialogFlag.tdfQueryMasked">
<short>
Causes Asterisk ('*') characters to be displayed to obfuscate characters in 
the query input.
</short>
</element>
<element name="TTaskDialogFlag.tdfQueryFieldFocused">
<short>
Causes the query input to be focused when a task dialog is displayed.
</short>
</element>

<element name="TTaskDialogFlags">
<short>
Set type used to store values from the TTaskDialogFlag enumeration.
</short>
<descr>
<p>
Contains the configuration flags enabled for a task dialog. 
<var>TTaskDialogFlags</var> is the type used to implement the Flags property 
in <var>TCustomTaskDialog</var>.
</p>
</descr>
<seealso>
<link id="#lcl.dialogs.TCustomTaskDialog.Flags">TCustomTaskDialog.Flags</link>
</seealso>
</element>

<element name="PTaskDialog">
<short>
Pointer to the TTaskDialog record type.
</short>
<descr/>
<seealso/>
</element>

<element name="TTaskDialogButtonClickedEvent">
<short>
Specifies a callback routine executed when a button is clicked on a task 
dialog.
</short>
<descr>
<p>
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 
<b>False</b>. Otherwise, the task dialog is closed and the button ID is 
returned via the original TTaskDialog.Execute() result.
</p>
<p>
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.
</p>
</descr>
<seealso/>
</element>
<element name="TTaskDialogButtonClickedEvent.Sender">
<short>
Handle to the task dialog form for the callback.
</short>
</element>
<element name="TTaskDialogButtonClickedEvent.AButtonID">
<short>
Button identifier for the callback notification.
</short>
</element>
<element name="TTaskDialogButtonClickedEvent.ACanClose">
<short>
Indicates if the dialog can be closed. Set to <b>True</b> in the callback 
implementation to allow the task dialog to be closed. Set to <b>False</b> to 
prevent closing the dialog.
</short>
</element>

<element name="TTaskDialogElement">
<short>
Represents visual elements which can be displayed on a task dialog.
</short>
<descr>
<p>
<var>TTaskDialogElement</var> 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.
</p>
<p>
TTaskDialogElement are passed as an argument to the SetElementText method in 
TTaskDialog used to set the value for the visual element.
</p>
</descr>
<seealso>
<link id="TTaskDialog.SetElementText"/>
</seealso>
</element>
<element name="TTaskDialogElement.tdeContent">
<short>
Represents the primary content for a dialog.
</short>
</element>
<element name="TTaskDialogElement.tdeExpandedInfo">
<short>
Represents additional text which can be displayed in the expandable area for 
a task dialog.
</short>
</element>
<element name="TTaskDialogElement.tdeFooter">
<short>
Represents the text displayed in the footer area for a task dialog.
</short>
</element>
<element name="TTaskDialogElement.tdeMainInstruction">
<short>
Represents the main instruction displayed at the top of the task dialog. When 
omitted, a resource string describing the main icon is used.
</short>
</element>
<element name="TTaskDialogElement.tdeEdit">
<short>
Represents the query input value for the task dialog.
</short>
</element>
<element name="TTaskDialogElement.tdeVerif">
<short>
Represents the verification text displayed in a check box at the bottom of 
the task dialog.
</short>
</element>

<element name="TEmulatedTaskDialog">
<short>
Form class displayed when a native dialog class is not available.
</short>
<descr>
<p>
<var>TEmulatedTaskDialog</var> is a <var>TForm</var> 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.
</p>
<p>
TLabels instances are used to represent the visual elements on the dialog as 
defined in the TTaskDialogElement enumeration. 
</p>
<p>
It provides a TComboBox used for a selection list, a TEdit control used for 
query input, and a TCheckBox used for the verification text.
</p>
<p>
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.
</p>
<p>
Use the aNonNative argument in the TTaskDialog.Execute method to specify use 
of an emulated task dialog at run-time.
</p>
</descr>
<seealso>
<link id="TTaskDialog.Execute"/>
<link id="TTaskDialogElement"/>
<link id="TTaskDialogFlag"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialog.Execute"/>
<link id="#lcl.forms.TForm">TForm</link>
</seealso>
</element>

<element name="TEmulatedTaskDialog.HandleEmulatedButtonClicked">
<short>
Calls the OnButtonClicked event handler for the task dialog which owns the 
emulated dialog form.
</short>
<descr>
<p>
<var>HandleEmulatedButtonClicked</var> 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.
</p>
<p>
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.
</p>
</descr>
<seealso/>
</element>
<element name="TEmulatedTaskDialog.HandleEmulatedButtonClicked.Sender">
<short>
Object instance (TButton) for the click event processed in the method.
</short>
</element>

<element name="TEmulatedTaskDialog.KeyDown">
<short>
Handles Alt+F4 and Esc key down events for the emulated task dialog.
</short>
<descr>
<p>
<var>KeyDown</var> is an overridden method in <var>TEmulatedTaskDialog</var>. 
It handles key down events which may close the emulated task dialog form.
</p>
<p>
If the form has a system menu icon in BorderIcons, the Escape key causes the 
form to be closed by calling the Close method.
</p>
<p>
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.
</p>
<p>
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.
</p>
</descr>
<seealso/>
</element>
<element name="TEmulatedTaskDialog.KeyDown.Key">
<short>
Virtual key code for the key down event.
</short>
</element>
<element name="TEmulatedTaskDialog.KeyDown.Shift">
<short>
Shift, Ctrl, or Alt modifier for the key event.
</short>
</element>

<element name="TEmulatedTaskDialog.CreateNew">
<short>
Constructor for the form instance.
</short>
<descr>
<p>
<var>CreateNew</var> 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.
</p>
<p>
CreateNew calls the inherited method on entry to initialize properties for 
the form instance and to register the form on the current Screen. 
</p>
<p>
The overridden constructor sets the value in KeyPreview to <b>True</b>. 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.
</p>
</descr>
<seealso>
<link id="#lcl.forms.TCustomForm.CreateNew">TCustomForm.CreateNew</link>
<link id="#lcl.forms.TForm.KeyPreview">TForm.KeyPreview</link>
<link id="#lcl.forms.Screen">Screen</link>
<link id="#lcl.forms.TScreen">TScreen</link>
</seealso>
</element>
<element name="TEmulatedTaskDialog.CreateNew.AOwner">
<short>
Component which owns the emulated task dialog form.
</short>
</element>
<element name="TEmulatedTaskDialog.CreateNew.Num">
<short>
Contains a specific instance number for the form. The default value is 0.
</short>
</element>

<element name="TEmulatedTaskDialog.Owner">
<short>
Owner of the emulated task dialog form instance.
</short>
<descr>
<p>
Contains the 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.
</p>
</descr>
<seealso>
<link id="TTaskDialog"/>
<link id="#rtl.classes.TComponent.Owner">TComponent.Owner</link>
</seealso>
</element>

<element name="TEmulatedTaskDialog.Element">
<short>
Provides indexed access to the label for a visual element on the task dialog 
form by its TTaskDialogElement value.
</short>
<descr>
<p>
<var>Element</var> 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:
</p>
<code>
// 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.';
</code>
<p>
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.
</p>
</descr>
<seealso>
<link id="TEmulatedTaskDialog.Combo"/>
<link id="TEmulatedTaskDialog.Edit"/>
<link id="TEmulatedTaskDialog.Verif"/>
<link id="TTaskDialogElement"/>
</seealso>
</element>

<element name="TEmulatedTaskDialog.Combo">
<short>
Control with the selection list for the task dialog form.
</short>
<descr>
<p>
<var>Combo</var> is a <var>TComboBox</var> member with the list of selectable 
items displayed on the task dialog form.
</p>
<p>
Use Edit to access the control used for the query input value on the dialog.
</p>
<p>
Use Verif to access the control with the verification text displayed on the 
dialog.
</p>
<p>
Use Element to access other visual elements with textual values displayed on 
the dialog.
</p>
</descr>
<seealso>
<link id="TEmulatedTaskDialog.Edit"/>
<link id="TEmulatedTaskDialog.Verif"/>
<link id="TEmulatedTaskDialog.Element"/>
<link id="#lcl.stdctrls.TComboBox">TComboBox</link>
</seealso>
</element>

<element name="TEmulatedTaskDialog.Edit">
<short>
Control used to edit the optional query input for the task dialog dialog.
</short>
<descr>
<p>
<var>Edit</var> is a <var>TEdit</var> member with the control used to edit 
the optional query input value for the dialog form.
</p>
<p>
Use Combo to access the selection list displayed on the dialog.
</p>
<p>
Use Verif to access the control with the verification text displayed on the 
dialog.
</p>
<p>
Use Element to access other visual elements with textual values displayed on 
the dialog.
</p>
</descr>
<seealso>
<link id="TEmulatedTaskDialog.Combo"/>
<link id="TEmulatedTaskDialog.Verif"/>
<link id="TEmulatedTaskDialog.Element"/>
<link id="#lcl.stdctrls.TEdit">TEdit</link>
</seealso>
</element>

<element name="TEmulatedTaskDialog.Verif">
<short>
Check box control for the verification text displayed on the task dialog form.
</short>
<descr>
<p>
<var>Verif</var> is a <var>TCheckBox</var> member with the control used for 
the verification text displayed on the dialog form.
</p>
<p>
Use Edit to access the query input value for the dialog.
</p>
<p>
Use Combo to access the selection list displayed on the dialog.
</p>
<p>
Use Element to access other visual elements with textual values displayed on 
the dialog.
</p>
</descr>
<seealso>
<link id="TEmulatedTaskDialog.Edit"/>
<link id="TEmulatedTaskDialog.Verif"/>
<link id="TEmulatedTaskDialog.Element"/>
<link id="#lcl.stdctrls.TCheckBox">TCheckBox</link>
</seealso>
</element>

<element name="TTaskDialogImplementation">
<short>
Provides access to the task dialog implementation.
</short>
<descr>
<p>
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.
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialogImplementation.OnButtonClicked">
<short>
Event handler signalled for a button click on the task dialog.
</short>
</element>

<element name="TTaskDialogImplementation.Emulated">
<short>
<b>True</b> if a TEmulatedTaskDialog form is needed. <b>False</b> if the 
handle to a native dialog is needed.
</short>
</element>

<element name="TTaskDialogImplementation.Wnd">
<short>
Handle to the native dialog used in the implementation.
</short>
</element>

<element name="TTaskDialogImplementation.Form">
<short>
TEmulatedTaskDialog instance used in the implementation.
</short>
</element>

<element name="TTaskDialog">
<short>
Implements a task dialog.
</short>
<descr>
<p>
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.
</p>
<p>
RadioRes, SelectionRes, and VerifyChecked will be used to reflect the state 
after execution of the dialog.
</p>
<p>
Typical usage:
</p>
<code>
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;
</code>
</descr>
<seealso/>
</element>

<element name="TTaskDialog.Title">
<short>
The main title for the task dialog window.
</short>
<descr>
<p>
When unassigned, the title from the application main form is used.
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialog.Inst">
<short>
The main instruction displayed on the dialog.
</short>
<descr>
<p>
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 <file>LCLStrConsts</file>.
</p>
</descr>
<seealso>
<link id="#lcl.lclstrconsts.rsMtWarning">rsMtWarning</link>
<link id="#lcl.lclstrconsts.rsMtError">rsMtError</link>
<link id="#lcl.lclstrconsts.rsMtInformation">rsMtInformation</link>
<link id="#lcl.lclstrconsts.rsMtConfirmation">rsMtConfirmation</link>
<link id="#lcl.lclstrconsts.rsMtAuthentication">rsMtAuthentication</link>
<link id="#lcl.lclstrconsts.rsMtCustom">rsMtCustom</link>
</seealso>
</element>

<element name="TTaskDialog.Content">
<short>
The text displayed as the primary content for the dialog.
</short>
<descr>
<p>
The value is used in the Execute method to add a label displayed in the 
dialog.
</p>
<remark>
In previous LCL versions, '\n' characters sequences were converted to 
LineEnding characters. This action is no longer performed as of revision 
64975.
</remark>
</descr>
<seealso/>
</element>

<element name="TTaskDialog.Buttons">
<short>
Delimited list of captions for the custom buttons displayed on the dialog.
</short>
<descr>
<p>
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).
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialog.Radios">
<short>
Delimited list of captions for radio buttons on the dialog.
</short>
<descr>
<p>
A <b>#13#10</b> or <b>#10</b> 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).
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialog.Info">
<short>
The text for the expandable information content.
</short>
<descr>
<p>
The Delphi emulation will always show the Info content (there is no collapse 
or expand button).
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialog.InfoExpanded">
<short>
The button caption to be displayed when the information is expanded. 
</short>
<descr>
<p>
Not used under XP: the Delphi emulation will always show the Info content.
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialog.InfoCollapse">
<short>
The button caption to be displayed when the information is collapsed.
</short>
<descr>
<p>
Not used under XP. The Delphi emulation will always show the Info content.
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialog.Footer">
<short>
The text content displayed in the footer area for the dialog.
</short>
<descr/>
<seealso/>
</element>

<element name="TTaskDialog.Verify">
<short>
The verification text for the optional check box at the bottom of the dialog.
</short>
<descr/>
<seealso/>
</element>

<element name="TTaskDialog.Selection">
<short>
A delimited list of items which can be selected in the dialog.
</short>
<descr>
<p>
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).
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialog.Query">
<short>
Input query which can be edited on the dialog.
</short>
<descr>
<p>
If tdfQuery is in the flags, this will contain the default query text.
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialog.RadioRes">
<short>
The selected radio button on the dialog.
</short>
<descr>
<p>
The selected radio button; the first button is at ordinal position 0.
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialog.SelectionRes">
<short>
The currently selected item in the selection list or combo-box.
</short>
<descr>
<p>
After execution, it contains the selected item from the Selection list.
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialog.VerifyChecked">
<short>
Checked state for the verification check box.
</short>
<descr>
<p>
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 <b>True</b> 
before execution of the dialog. After execution, it will contain the returned 
check box state.
</p>
</descr>
<version>
Modified in LCL version 3.0 to use the LongBool type (instead of Boolean).
</version>
<seealso/>
</element>

<element name="TTaskDialog.Dialog">
<short>
Provides access to the task dialog implementation.
</short>
<descr>
<p>
<var>TTaskDialogImplementation</var> type which provides low-level access to 
the task dialog implementation.
</p>
</descr>
<seealso>
<link id="TTaskDialogImplementation"/>
</seealso>
</element>

<element name="TTaskDialog.Execute">
<short>
Launches the task dialog form.
</short>
<descr>
<p>
Some common buttons can be set via <var>aCommonButtons</var>. In emulation 
mode, <var>aFlags</var> will handle only tdfUseCommandLinks, 
tdfUseCommandLinksNoIcon, and tdfQuery options.
</p>
<p>
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).
</p>
<p>
If Buttons have been defined, <var>aButtonDef</var> can set the selected 
Button ID on the dialog. 
</p>
<p>
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.
</p>
<p>
<var>aDialogIcon</var> and <var>aFooterIcon</var> are used to specify the 
icons displayed on the dialog form.
</p>
<p>
<var>aWidth</var> can be used to supply a custom form width (in pixels). When 
set to a value &amp;lt;= 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.
</p>
<p>
<var>aParent</var> can be set to any HWND instance - by default, 
Application.DialogHandle.
</p>
<p>
If <var>aNonNative</var> is <b>True</b>, the Delphi emulation code will always 
be used.
</p>
<p>
<var>aEmulateClassicStyle</var> can be set to enforce conformity when using a 
non-themed user interface (classic) - see 
<url href="http://synopse.info/forum/viewtopic.php?pid=2867#p2867">
http://synopse.info/forum/viewtopic.php?pid=2867#p2867</url>. This argument 
is set to <b>True</b> 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:
</p>
<ul>
<li>Labels use a taller font height with Bold in the font style.</li>
<li>Buttons are wider but smaller in height.</li>
<li>
The default font is either Calibri, Tahoma, or Arial on the dialog form.
</li>
<li>Panels use the clDefault color instead of clWindow.</li>
</ul>
<p>
<var>aOnButtonClicked</var> can be set to a callback routine executed when a 
button is clicked.
</p>
</descr>
<seealso/>
<version>
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.
</version>
</element>
<element name="TTaskDialog.Execute.Result">
<short>
Modal result value returned from the dialog.
</short>
</element>
<element name="TTaskDialog.Execute.aCommonButtons">
<short>
Set of common or standard buttons enabled on the task dialog form.
</short>
</element>
<element name="TTaskDialog.Execute.aButtonDef">
<short>
Indicates the button which is the default for the task dialog form.
</short>
</element>
<element name="TTaskDialog.Execute.aFlags">
<short>
Set of flags used to configure the task dialog and specify its behavior.
</short>
</element>
<element name="TTaskDialog.Execute.aDialogIcon">
<short>
Specifies the main icon displayed on the task dialog.
</short>
</element>
<element name="TTaskDialog.Execute.aFooterIcon">
<short>
Specifies the icon displayed in the footer area for the task dialog.
</short>
</element>
<element name="TTaskDialog.Execute.aRadioDef">
<short>
Ordinal position for the default radio button selected on the task dialog.
</short>
</element>
<element name="TTaskDialog.Execute.aWidth">
<short>
Specifies the display width for the task dialog form, or 0 to automatically calculate the width.
</short>
</element>
<element name="TTaskDialog.Execute.aParent">
<short>
Window handle for the parent window of the task dialog. 0 causes the active 
form on the current monitor to be used.
</short>
</element>
<element name="TTaskDialog.Execute.aNonNative">
<short>
<b>True</b> causes Delphi emulation code to be used during execution of the 
task dialog.
</short>
</element>
<element name="TTaskDialog.Execute.aEmulateClassicStyle">
<short>
<b>True</b> forces a non-themed (classic) user interface to be used.
</short>
</element>
<element name="TTaskDialog.Execute.aOnButtonClicked">
<short>
Contains the callback executed when a button is clicked.
</short>
</element>

<element name="TTaskDialog.SetElementText">
<short>
Sets the value for the specified visual element on the dialog.
</short>
<descr>
<p>
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.
</p>
</descr>
<seealso>
<link id="TTaskDialogElement"/>
</seealso>
</element>
<element name="TTaskDialog.SetElementText.element">
<short>
TTaskDialogElement enumeration value for the visual element updated in the 
method.
</short>
</element>
<element name="TTaskDialog.SetElementText.Text">
<short>
New value for the specified dialog element. Assigned to the Caption or Text property in the corresponding element.
</short>
</element>

<element name="TTaskDialogEx">
<short>
Provides a wrapper for the Execute method in TTaskDialog.
</short>
<descr>
<p>
A wrapper around the TTaskDialog.Execute method. Used to provide "flat" 
access to task dialog parameters.
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialogEx.Base">
<short>
The TTaskDialog instance accessed in the implementation.
</short>
<descr>
<p>
The associated main TTaskDialog instance.
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialogEx.CommonButtons">
<short>
Common command buttons displayed on the task dialog.
</short>
<descr>
<p>
Some common buttons to be displayed.
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialogEx.ButtonDef">
<short>
The identifier for the default button on the task dialog.
</short>
<descr>
The default button ID.
</descr>
<seealso/>
</element>

<element name="TTaskDialogEx.Flags">
<short>
Task dialog flags enabled for the dialog.
</short>
<descr>
<p>
The associated configuration flags for this Task Dialog. In emulation mode, 
aFlags will handle only tdfUseCommandLinks, tdfUseCommandLinksNoIcon, and 
tdfQuery options.
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialogEx.DialogIcon">
<short>
Indicates the image displayed as the main icon on the dialog.
</short>
<descr>
Used to specify the dialog icon.
</descr>
<seealso/>
</element>

<element name="TTaskDialogEx.FooterIcon">
<short>
Indicates the image displayed as the footer icon on the dialog.
</short>
<descr>
Used to specify the footer icon.
</descr>
<seealso/>
</element>

<element name="TTaskDialogEx.RadioDef">
<short>
Default radio button enabled when the task dialog is displayed.
</short>
<descr>
The default radio button ID.
</descr>
<seealso/>
</element>

<element name="TTaskDialogEx.Width">
<short>
Default width for the task dialog.
</short>
<descr>
Can be used to force a custom form width (in pixels).
</descr>
<seealso/>
</element>

<element name="TTaskDialogEx.NonNative">
<short>
Indicates whether an emulated task dialog form is used.
</short>
<descr>
<p>
If <b>True</b>, the emulated (non-native) code will always be used.
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialogEx.EmulateClassicStyle">
<short>
Forces the user interface to used non-themed interfacfe elements.
</short>
<descr>
Can be used to enforce conformity with the non-themed user interface.
</descr>
<seealso/>
</element>

<element name="TTaskDialogEx.OnButtonClicked">
<short>
Event handler signalled when a button is clicked on the task dialog.
</short>
<descr>
This event handler will be fired on a button dialog click.
</descr>
<seealso/>
</element>

<element name="TTaskDialogEx.Init">
<short>
Initializes the dialog parameters to common default values.
</short>
<descr>
<p>
Can be used to display some information with less parameters. For example:
</p>
<code>
var TaskEx: TTaskDialogEx;
// ...
TaskEx.Init;
TaskEx.Base.Title := 'Task Dialog Test';
TaskEx.Base.Inst := 'Callback Test';
TaskEx.Execute;
</code>
<p>
Sets the record instance to the per-initialized value in the 
DefaultTaskDialog variable.
</p>
</descr>
<seealso/>
</element>

<element name="TTaskDialogEx.Execute">
<short>
Method used to display and execute the extended task dialog.
</short>
<descr>
<p>
<var>Execute</var> is an <var>Integer</var> 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.
</p>
<p>
Before calling Execute, assign a routine to the OnButtonClicked event handler 
to perform actions needed for a specific button clicked on the dialog.
</p>
<p>
The return value contains the modal result value returned from the base task 
dialog.
</p>
</descr>
<seealso>
<link id="TTaskDialog.Execute"/>
</seealso>
</element>
<element name="TTaskDialogEx.Execute.Result">
<short>
Modal result value for the dialog. Contains the identifier for the button 
clicked on the dialog.
</short>
</element>
<element name="TTaskDialogEx.Execute.aParent">
<short>
Handle for the window which is the parent for the dialog. 0 (the default) is 
the unassigned value.
</short>
</element>

<element name="UnAmp">
<short>
Gets a string with Ampersand characters removed from the specified value.
</short>
<descr>
<p>
Returns the specified text without any '&amp;' (Ampersand) characters used as 
a accelerator or hot key prefix.
</p>
</descr>
<seealso/>
</element>
<element name="UnAmp.Result">
<short>
String with all Ampersand characters removed.
</short>
</element>
<element name="UnAmp.s">
<short>
String examined and converted in the routine.
</short>
</element>

<element name="DefaultTaskDialog">
<short>
The default Task Dialog wrapper instance.
</short>
<descr>
<p>
Can be used to display a task dialog using fewer parameters, just like the 
TTaskDialogEx.Init method. For example:
</p>
<code>
var TaskEx: TTaskDialogEx;
// ...
TaskEx := DefaultTaskDialog;
TaskEx.Base.Title := 'Task Dialog Test';
TaskEx.Base.Inst := 'Callback Test';
TaskEx.Execute;
</code>
</descr>
<seealso/>
</element>

<element name="TTaskDialogTranslate">
<short>
Defines a function used to translate a caption used on a task dialog.
</short>
<descr>
<p>
TTaskDialogTranslate is the type used to implement the TaskDialog_Translate 
variable.
</p>
</descr>
<seealso>
<link id="TaskDialog_Translate"/>
</seealso>
</element>
<element name="TTaskDialogTranslate.Result">
<short>
Translated value for the specified caption.
</short>
</element>
<element name="TTaskDialogTranslate.aString">
<short>
Caption value translated in the routine.
</short>
</element>

<element name="TaskDialog_Translate">
<short>
Function used to translate the content on an emulated task dialog.
</short>
<descr/>
<seealso/>
</element>

<element name="DefaultFont">
<short>
Assigns the default font used for task dialogs when one has not already been 
chosen. 
</short>
<descr>
<p>
<var>DefaultFont</var> creates a <var>TFont</var> 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.
</p>
<p>
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).
</p>
<p>
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.
</p>
</descr>
<seealso/>
</element>
<element name="DefaultFont.Result">
<short>
TFont instance with the default typeface and font size for a task dialog.
</short>
</element>

</module>
<!-- LCLTaskDialog -->
</package>
</fpdoc-descriptions>
