<?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
https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/docs/cc-by-sa-4-0.txt

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

-->
<fpdoc-descriptions>
<package name="lcl">
<!--
====================================================================
Dialogs
====================================================================
-->
<module name="Dialogs">
<short>
Contains common dialogs used in Lazarus LCL applications.
</short>
<descr>
<p>
<file>dialogs.pp</file> contains classes, types, and routines used to 
implement common dialogs in an application. <file>dialogs.pp</file> is part of 
the Lazarus Component Library (<b>LCL</b>).
</p>
<p>
The following components are added to the Lazarus IDE component palette:
</p>
<p>
<b>Dialogs</b> Tab
</p>
<ul>
<li>TOpenDialog</li>
<li>TSaveDialog</li>
<li>TSelectDirectoryDialog</li>
<li>TColorDialog</li>
<li>TFontDialog</li>
<li>TFindDialog</li>
<li>TReplaceDialog</li>
<li>TTaskDialog</li>
</ul>
<p>
<b>Misc</b> Tab
</p>
<ul>
<li>TColorButton</li>
</ul>
</descr>

<element name="Types"/>
<element name="TypInfo"/>
<element name="Classes"/>
<element name="SysUtils"/>
<element name="System.UITypes"/>
<element name="LMessages"/>
<element name="LResources"/>
<element name="LCLIntf"/>
<element name="InterfaceBase"/>
<element name="LCLStrConsts"/>
<element name="LCLType"/>
<element name="Forms"/>
<element name="Controls"/>
<element name="Themes"/>
<element name="Graphics"/>
<element name="Buttons"/>
<element name="ButtonPanel"/>
<element name="StdCtrls"/>
<element name="ExtCtrls"/>
<element name="LCLClasses"/>
<element name="ClipBrd"/>
<element name="Menus"/>
<element name="DialogRes"/>
<element name="ComCtrls"/>
<element name="GraphType"/>
<element name="FileUtil"/>
<element name="LazFileUtils"/>
<element name="LazStringUtils"/>
<element name="LazLoggerBase"/>

<!-- 
Link to the topic content in system.uitypes when it exists in RTL.CHM. 
-->
<element name="TMsgDlgType">
<short>
Identifies the type or style for a message dialog.
</short>
<descr>
<p>
<var>TMsgDlgType</var> is an alias to the <var>TMsgDlgType</var> enumerated 
type in the RTL <file>system.uitypes.pp</file> unit. TMsgDlgType defines a 
type of dialog implemented in a message box. Values in the enumeration 
determine the caption, icon, string literals, and buttons displayed in various 
dialog types.
</p>
<p>
Values from the enumeration can be represented using the descriptive modal 
dialog type constants, such as: mtWarning, mtError, mtInformation, 
mtConfirmation, and mtCustom.
</p>
<p>
Values from TMsgDlgType are used in several routines, such as: 
<var>MessageDlg</var>, <var>MessageDlgPos</var>,<var> MessageDlgPosHelp</var>, 
<var>CreateMessageDialog</var>, <var>QuestionDlg</var>, and 
<var>LazMessageDlg</var>.
</p>
</descr>
<seealso>
<!--
TODO: Uncomment when system.uitypes exists in RTL.CHM.
<link id="#rtl.system.uitypes.TMsgDlgType">System.UITypes.TMsgDlgType</link> 
-->
<link id="mtWarning"/>
<link id="mtError"/>
<link id="mtInformation"/>
<link id="mtConfirmation"/>
<link id="mtCustom"/>
<link id="MessageDlg"/>
<link id="MessageDlgPos"/>
<link id="MessageDlgPosHelp"/>
<link id="CreateMessageDialog"/>
<link id="QuestionDlg"/>
<link id="#lcl.lazdialogs.LazMessageDlg">LazMessageDlg</link>
</seealso>
</element>

<!-- 
Link to the topic content in system.uitypes when it exists in RTL.CHM. 
-->
<element name="TMsgDlgBtn">
<short>Identifies dialog button types.</short>
<descr>
<p>
<var>TMsgDlgBtn</var> is an alias to the <var>TMsgDlgBtn</var> type in 
<file>system.uitypes.pp</file>. TMsgDlgBtn is an enumeration type with values 
that define the buttons that can be displayed in a message dialog. TMsgDlgBtn 
values also determine the modal result returned from the dialog when the 
corresponding button is clicked.
</p>
<p>
Values from the enumeration can be represented using the descriptive message 
button constants, such as: mbYes, mbNo, mbOK, mbCancel, mbAbort, mbRetry, 
mbIgnore, mbAll, mbNoToAll, mbYesToAll, mbHelp, and mbClose.
</p>
<p>
Values in the enumeration are used in various routines, such as: <var>
MessageDlg</var>, <var>MessageDlgPos</var>, <var>MessageDlgPosHelp</var>, 
<var>CreateMessageDialog</var>, <var>QuestionDlg</var>, and 
<var>LazMessageDlg</var>.
</p>
</descr>
<seealso>
<!--
TODO: Uncomment when system.uitypes exists in RTL.CHM.
<link id="#rtl.system.uitypes.TMsgDlgBtn">System.UITypes.TMsgDlgBtn</link> 
-->
<link id="mbYes"/>
<link id="mbNo"/>
<link id="mbOK"/>
<link id="mbCancel"/>
<link id="mbAbort"/>
<link id="mbRetry"/>
<link id="mbIgnore"/>
<link id="mbAll"/>
<link id="mbNoToAll"/>
<link id="mbYesToAll"/>
<link id="mbHelp"/>
<link id="mbClose"/>
<link id="MessageDlg"/>
<link id="MessageDlgPos"/>
<link id="MessageDlgPosHelp"/>
<link id="CreateMessageDialog"/>
<link id="QuestionDlg"/>
<link id="#lcl.lazdialogs.LazMessageDlg">LazMessageDlg</link>
</seealso>
</element>

<!-- 
Link to the topic content in system.uitypes when it exists in RTL.CHM. 
-->
<element name="TMsgDlgButtons">
<short>
Set type used to store the buttons on a message dialog.
</short>
<descr>
<p>
<var>TMsgDlgButtons</var> is an alias to the <var>TMsgDlgButtons</var> type in 
<file>system.uitypes.pp</file>. TMsgDlgButtons is a set type used to store 
zero or more values from the TMsgDlgBtn enumeration. TMsgDlgButtons is passed 
as an argument to routines like: <var>MessageDlg</var>, 
<var>MessageDlgPos</var>, <var>MessageDlgPosHelp</var>, 
<var>CreateMessageDialog</var>, <var>QuestionDlg</var>, and 
<var>LazMessageDlg</var>.
</p>
</descr>
<seealso>
<!--
TODO: Uncomment when system.uitypes exists in RTL.CHM.
<link id="#rtl.system.uitypes.TMsgDlgButtons">System.UITypes.TMsgDlgButtons</link>
<link id="#rtl.system.uitypes.TMsgDlgBtn">System.UITypes.TMsgDlgBtn</link>
-->
<link id="TMsgDlgBtn"/>
</seealso>
</element>

<element name="mtWarning">
<short>
Alias to the TMsgDlgType enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>
<element name="mtError">
<short>
Alias to the TMsgDlgType enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>
<element name="mtInformation">
<short>
Alias to the TMsgDlgType enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>
<element name="mtConfirmation">
<short>
Alias to the TMsgDlgType enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>
<element name="mtCustom">
<short>
Alias to the TMsgDlgType enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>

<element name="mbYes">
<short>
Alias to the TMsgDlgBtn enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>
<element name="mbNo">
<short>
Alias to the TMsgDlgBtn enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>
<element name="mbOK">
<short>
Alias to the TMsgDlgBtn enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>
<element name="mbCancel">
<short>
Alias to the TMsgDlgBtn enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>
<element name="mbAbort">
<short>
Alias to the TMsgDlgBtn enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>
<element name="mbRetry">
<short>
Alias to the TMsgDlgBtn enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>
<element name="mbIgnore">
<short>
Alias to the TMsgDlgBtn enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>
<element name="mbAll">
<short>
Alias to the TMsgDlgBtn enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>
<element name="mbNoToAll">
<short>
Alias to the TMsgDlgBtn enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>
<element name="mbYesToAll">
<short>
Alias to the TMsgDlgBtn enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>
<element name="mbHelp">
<short>
Alias to the TMsgDlgBtn enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>
<element name="mbClose">
<short>
Alias to the TMsgDlgBtn enumeration value in <file>system.uitypes.pp</file>.
</short>
</element>

<element name="mbYesNoCancel">
<short>A set constant with Yes, No, Cancel buttons.</short>
<descr>
<p>
A set constant used to show Yes, No, and Cancel buttons on a message dialog.
</p>
</descr>
<seealso/>
</element>

<element name="mbYesNo">
<short>A set constant with Yes, No buttons.</short>
<descr>
<p>
A set constant used to show Yes and No buttons on a message dialog.
</p>
</descr>
<seealso/>
</element>

<element name="mbOKCancel">
<short>
A set constant to show an OK and a Cancel button on a message dialog.
</short>
<descr>
<p>
A set constant to show an OK and a Cancel button on a message dialog.
</p>
</descr>
<seealso/>
</element>

<element name="mbAbortRetryIgnore">
<short>
A set constant to show an Abort, Retry , Ignore buttons on a message dialog.
</short>
<descr>
<p>
A set constant to show an Abort, Retry and Ignore buttons on a message dialog.
</p>
</descr>
<seealso/>
</element>

<element name="MsgDlgBtnToBitBtnKind">
<short>
A constant array used to convert the kind of message buttons to the kind of 
BitButton.
</short>
<descr>
<p>
This array gives you for each possible button type in a messagebox the 
corresponding kind of BitButton.
</p>
<p>
For instance MsgDlgBtnToBitBtnKind[mbYes] has the value of bkYes.
</p>
<p>
It is the reverse of BitBtnKindToMsgDlgBtn.
</p>
</descr>
<seealso/>
</element>

<element name="BitBtnKindToMsgDlgBtn">
<short>
A constant array used to convert the kind of BitButton to the kind of message 
buttons.
</short>
<descr>
<p>
This array gives you for each BitButton the corresponding type of button on a 
message dialog. For instance BitBtnKindToMsgDlgBtn[bkOK] has the value of 
mbOK. It is the reverse if MsgDlgBtnToBitBtnKind.
</p>
</descr>
<seealso/>
</element>

<element name="TCDWSEventCapability">
<short>Represents events handled in a custom-drawn widgetset.</short>
<descr>
<p>
Not used in the current LCL version.
</p>
</descr>
<seealso>
<link id="TCDWSEventCapabilities"/>
</seealso>
</element>
<element name="TCDWSEventCapability.cdecWSPerformsDoShow">
<short>
Not used in the current LCL version.
</short>
</element>
<element name="TCDWSEventCapability.cdecWSPerformsDoCanClose">
<short>
Not used in the current LCL version.
</short>
</element>
<element name="TCDWSEventCapability.cdecWSPerformsDoClose">
<short>
Not used in the current LCL version.
</short>
</element>
<element name="TCDWSEventCapability.cdecWSNOCanCloseSupport">
<short>
Not used in the current LCL version.
</short>
</element>

<element name="TCDWSEventCapabilities">
<short>
Set type used to store values from the TCDWSEventCapability enumeration.
</short>
<descr>
<p>
Not used in the current LCL version.
</p>
</descr>
<seealso/>
</element>

<element name="TDialogResultEvent">
<short>
Specifies an event signalled when a result is returned in a dialog.
</short>
<descr>
<p>
<var>TDialogResultEvent</var> is the type used to implement the 
<var>OnDialogResult</var> event handler in <var>TCommonDialog</var>.
</p>
</descr>
<seealso>
<link id="TCommonDialog.OnDialogResult"/>
</seealso>
</element>
<element name="TDialogResultEvent.Sender">
<short>Object for the event notification.</short>
</element>
<element name="TDialogResultEvent.Success">
<short><b>True</b> if the dialog was successfully executed.</short>
</element>

<element name="TCommonDialog">
<short>The base type from which other dialogs are derived.</short>
<descr>
<p>
TCommonDialog is the base type from which all other dialogs are derived.
</p>
<p>
Use Create to make an instance of the dialog, and the Execute method to show 
it to the user. Use the Close method to release it and free the used 
resources.
</p>
</descr>
<seealso/>
</element>

<element name="TCommonDialog.FAttachTo"/>
<element name="TCommonDialog.FHandle"/>
<element name="TCommonDialog.FHeight"/>
<element name="TCommonDialog.FOnDialogResult"/>
<element name="TCommonDialog.FWidth"/>
<element name="TCommonDialog.FOnCanClose"/>
<element name="TCommonDialog.FOnShow"/>
<element name="TCommonDialog.FTitle"/>
<element name="TCommonDialog.FUserChoice"/>
<element name="TCommonDialog.FHelpContext"/>
<element name="TCommonDialog.FDoCanCloseCalled"/>
<element name="TCommonDialog.FDoShowCalled"/>
<element name="TCommonDialog.FDoCloseCalled"/>
<element name="TCommonDialog.FClosing"/>
<element name="TCommonDialog.FWSEventCapabilities"/>

<element name="TCommonDialog.SetHandle">
<short>Sets the value for the Handle property.</short>
<descr/>
<seealso>
<link id="TCommonDialog.Handle"/>
</seealso>
</element>
<element name="TCommonDialog.SetHandle.AValue">
<short>New value for the property.</short>
</element>

<element name="TCommonDialog.IsTitleStored">
<short>Implements the storage specifier for the Title property.</short>
<descr>
<p>
Returns <b>True</b> when <var>Title</var> contains a value other than 
<var>DefaultTitle</var>.
</p>
</descr>
<seealso>
<link id="TCommonDialog.Title"/>
<link id="TCommonDialog.DefaultTitle"/>
</seealso>
</element>
<element name="TCommonDialog.IsTitleStored.Result">
<short><b>True</b> when an explicit value has been assigned to Title.</short>
</element>

<element name="TCommonDialog.WSRegisterClass" link="#lcl.lclclasses.TLCLComponent.WSRegisterClass"/>

<element name="TCommonDialog.DoExecute">
<short>The function that actually takes care of executing the dialog.</short>
<descr/>
<seealso/>
</element>
<element name="TCommonDialog.DoExecute.Result">
<short>Returns <b>True</b> if the correct exit button was pressed.</short>
</element>

<element name="TCommonDialog.DefaultTitle">
<short>
<var>DefaultTitle</var> returns the default title for a dialog.
</short>
<descr>
<p>
<var>DefaultTitle</var> returns an empty string ('') in 
<var>TCommonDialog</var>. The method is overridden in descendent classes to 
return the value needed for the derived class.
</p>
</descr>
<seealso/>
</element>
<element name="TCommonDialog.DefaultTitle.Result">
<short>
String used as the default title or caption for the dialog form.
</short>
</element>

<element name="TCommonDialog.GetHeight">
<short>Gets the value for the Height property.</short>
<descr/>
<seealso>
<link id="TCommonDialog.Height"/>
</seealso>
</element>
<element name="TCommonDialog.GetHeight.Result">
<short>Value for the property.</short>
</element>

<element name="TCommonDialog.GetWidth">
<short>Gets the value for the Width property.</short>
<descr/>
<seealso>
<link id="TCommonDialog.Width"/>
</seealso>
</element>
<element name="TCommonDialog.GetWidth.Result">
<short>Value for the property.</short>
</element>

<element name="TCommonDialog.SetHeight">
<short>Sets the value for the Height property.</short>
<descr/>
<seealso>
<link id="TCommonDialog.Height"/>
</seealso>
</element>
<element name="TCommonDialog.SetHeight.AValue">
<short>New value for the property.</short>
</element>

<element name="TCommonDialog.SetWidth">
<short>Sets the value for the Width property.</short>
<descr/>
<seealso>
<link id="TCommonDialog.Width"/>
</seealso>
</element>
<element name="TCommonDialog.SetWidth.AValue">
<short>New value for the property.</short>
</element>

<element name="TCommonDialog.ResetShowCloseFlags">
<short>Resets the values in internal state flags for the dialog.</short>
<descr>
<p>
Called from the <var>Execute</var> method before the widgetset Handle is 
allocated and the dialog is displayed.
</p>
</descr>
<seealso>
<link id="TCommonDialog.Execute"/>
<link id="TCommonDialog.Handle"/>
<link id="TCommonDialog.DoExecute"/>
</seealso>
</element>

<element name="TCommonDialog.AttachTo">
<short>
Form which created the dialog class instance.
</short>
<descr>
<p>
AttachTo is a platform-specific property which provides the form instance 
which created the dialog. It is used primarily for the MacOS Cocoa interface 
to provide the window handle needed for the platform.
</p>
</descr>
<seealso/>
</element>

<element name="TCommonDialog.OnDialogResult">
<short>
Event handler signalled when a result is available for the dialog.
</short>
<descr>
<p>
<var>OnDialogResult</var> is a <var>TDialogResultEvent</var> property with 
the event handler signalled when a result is available for the dialog.
</p>
<p>
OnDialogResult is a platform-specific property, and may not be used in all 
widgetsets. It provides a way for platforms which use native dialogs in their 
implementation to notify the dialog that a result is available.
</p>
</descr>
<seealso>
<link id="TDialogResultEvent"/>
</seealso>
</element>

<element name="TCommonDialog.FCompStyle">
<short>Internal member used to store component style flags.</short>
</element>

<element name="TCommonDialog.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the constructor for <var>TCommonDialog</var>, and calls 
the inherited <var>Create</var> method and adds default Title.
</p>
</descr>
<seealso>
<link id="#rtl.Classes.TComponent.Create">TComponent.Create</link>
</seealso>
</element>
<element name="TCommonDialog.Create.TheOwner">
<short>The owner of the dialog: the component that called it.</short>
</element>

<element name="TCommonDialog.Execute">
<short>Displays the dialog and captures the result.</short>
<descr>
<p>
Use the Execute method to display the dialog and capture the result.
</p>
<p>
Execute notifies the Application that a modal display is started, and 
disables the current form. The widgetset handle is allocated for the dialog, 
and the <var>DoExecute</var> method is called to process the modal dialog. 
The form is re-enabled and its active control is re-selected. The Application 
is notified that the modal display is completed.
</p>
<p>
The return value is set to <b>True</b> if the <b>OK</b> button was pressed to 
exit the dialog.
</p>
</descr>
<seealso>
<link id="TCommonDialog.DoExecute"/>
<link id="#lcl.forms.Application">Application</link>
<link id="#lcl.forms.TApplication.ModalStarted">TApplication.ModalStarted</link>
<link id="#lcl.forms.TApplication.ModalFinished">TApplication.ModalFinished</link>
</seealso>
</element>
<element name="TCommonDialog.Execute.Result">
<short>Returns <b>True</b> if the user pressed the OK button.</short>
</element>

<element name="TCommonDialog.Handle">
<short>
Contains the handle for the dialog form.
</short>
<descr>
<p>
<var>Handle</var> is a <var>TLCLHandle</var> property with the handle for the 
dialog form. Its value is assigned in the Execute method and contains the 
handle from the widgetset class instance. Handle is checked during execution 
of the dialog to ensure that it does not contain an unassigned value. The 
unassigned value for Handle is 0 (zero). Handle is destroyed when the Close 
method is executed.
</p>
</descr>
<version>
Modified in LCL version 4.0 to use the TLCLHandle type instead of the 
deprecated THandle type in the property.
</version>
<seealso>
<link id="TCommonDialog.Execute"/>
<link id="TCommonDialog.Close"/>
<link id="TCommonDialog.HandleAllocated"/>
<link id="#lcl.lcltype.TLCLHandle">TLCLHandle</link>
</seealso>
</element>

<element name="TCommonDialog.UserChoice">
<short>
Contains the modal result value selected by the user.
</short>
<descr>
<p>
<var>UserChoice</var> is an <var>Integer</var> property which contains the 
modal result value returned for the dialog. It uses values from the modal 
result constants like mrOk, mrCancel, et. al. as defined in this unit and in 
the <file>system.uitypes.pp</file> unit. Its value is updated by methods in 
the widgetset class when they display and process the dialog for the platform.
</p>
</descr>
<seealso>
<link id="TCommonDialog.Execute"/>
<link id="TCommonDialog.DoExecute"/>
<link id="TModalResult"/>
<!-- 
TODO: Uncomment when system.uitypes exists in RTL.CHM. 
<link id="#rtl.system.uitypes.TModalResult">System.UITypes.TModalResult</link>
-->
</seealso>
</element>

<element name="TCommonDialog.Close">
<short>Closes the dialog and frees its resources.</short>
<descr>
<p>
<var>Close</var> is a method used to perform actions needed to close the 
dialog. This can include signalling the <var>OnClose</var> event handler 
(when assigned and used for the platform). Close frees the widgetset 
<var>Handle</var> allocated for the dialog.
</p>
<p>
No actions are performed in the method if a Handle is not allocated for the 
dialog, or the Close method has already been called.
</p>
<p>
Close is called from the <var>Execute</var> method when the 
<var>DoExecute</var> method has been completed, and occurs before the active 
form is re-enabled and focused.
</p>
</descr>
<seealso>
<link id="TCommonDialog.Execute"/>
<link id="TCommonDialog.DoExecute"/>
<link id="TCommonDialog.Handle"/>
<link id="TCommonDialog.OnClose"/>
</seealso>
</element>

<element name="TCommonDialog.DoShow">
<short>Performs actions needed when the dialog is displayed.</short>
<descr>
<p>
<var>DoShow</var> is a method used to perform actions needed when the form 
for the modal dialog is displayed. DoShow sets an internal flag to indicate 
that the dialog has been displayed, and signals the <var>OnShow</var> event 
handler (when assigned).
</p>
<p>
No actions are performed in the method if the dialog has already been 
displayed.
</p>
<p>
DoShow is called from the <var>DoExecute</var> method.
</p>
</descr>
<seealso>
<link id="TCommonDialog.Execute"/>
<link id="TCommonDialog.DoExecute"/>
<link id="TCommonDialog.OnShow"/>
</seealso>
</element>

<element name="TCommonDialog.DoCanClose">
<short>
Performs actions needed to determine if the dialog can be closed.
</short>
<descr>
<p>
<var>DoCanClose</var> is a method which determines if the dialog can be 
closed. It updates an internal flag which indicates the method has been 
called, and signals the <var>OnCanClose</var> event handler (when assigned 
and supported for the platform).
</p>
<p>
Use the OnCanClose to implement any required logic to determine if the dialog 
can actually be closed. The value in the CanClose argument is updated in the 
event handler.
</p>
<p>
DoCanClose is called from the <var>DoExecute</var> method when the widgetset 
class has attempted to close the dialog.
</p>
</descr>
<seealso>
<link id="TCommonDialog.OnCanClose"/>
<link id="TCommonDialog.Execute"/>
<link id="TCommonDialog.DoExecute"/>
</seealso>
</element>
<element name="TCommonDialog.DoCanClose.CanClose">
<short>
<b>True</b> if the OnCanClose event handler determines the dialog can be 
closed.
</short>
</element>

<element name="TCommonDialog.DoClose">
<short>Performs actions needed when the dialog is closed.</short>
<descr>
<p>
<var>DoClose</var> is a method used to perform actions needed when the dialog 
is closed. It updates an internal flag which indicates the method has been 
called, and signals the <var>OnClose</var> event handler (when assigned).
</p>
<p>
DoClose is called from the <var>Close</var> method, and occurs before the 
widgetset <var>Handle</var> for the dialog is freed.
</p>
</descr>
<seealso>
<link id="TCommonDialog.OnClose"/>
<link id="TCommonDialog.Execute"/>
<link id="TCommonDialog.DoExecute"/>
<link id="TCommonDialog.Close"/>
<link id="TCommonDialog.Handle"/>
</seealso>
</element>

<element name="TCommonDialog.HandleAllocated">
<short>
Returns <b>True</b> if a widgetset Handle has been allocated for the dialog.
</short>
<descr/>
<seealso>
<link id="TCommonDialog.Handle"/>
</seealso>
</element>
<element name="TCommonDialog.HandleAllocated.Result">
<short>
<b>True</b> if a widgetset Handle has been allocated for the dialog.
</short>
</element>

<element name="TCommonDialog.Width">
<short>The width of the dialog.</short>
<descr/>
<seealso/>
</element>

<element name="TCommonDialog.Height">
<short>The height of the dialog.</short>
<descr/>
<seealso/>
</element>

<element name="TCommonDialog.OnClose">
<short>Event handler signalled when the dialog is closed.</short>
<descr/>
<seealso/>
</element>

<element name="TCommonDialog.OnCanClose">
<short>
Event handler signalled to determine if the dialog can be closed.
</short>
<descr/>
<seealso/>
</element>

<element name="TCommonDialog.OnShow">
<short>Event handler signalled when the dialog is displayed.</short>
<descr/>
<seealso/>
</element>

<element name="TCommonDialog.HelpContext">
<short>
Help context identifier for the help message displayed for the dialog.
</short>
<descr/>
<seealso>
<link id="#lcl.forms.TApplication.HelpContext">TApplication.HelpContext</link>
<link id="#lcl.forms.TCustomForm.HelpFile">TCustomForm.HelpFile</link>
</seealso>
</element>

<element name="TCommonDialog.Title">
<short>The Title or Caption displayed for the dialog.</short>
<descr>
<p>
<var>Title</var> can be used to provide a usage context for the re-usable 
dialog. It is defined using the <var>TTranslateString</var> type which allows 
the value to be recognized and translated using the localization facilities 
found in the LCL and the Lazarus IDE. When an explicit value has been 
assigned for the property, it is included the LCL component streaming 
mechanism.
</p>
<p>
The default value for the property is provided by the <var>DefaultTitle</var> 
method, and assigned in the <var>Create</var> constructor.
</p>
</descr>
<seealso>
<link id="TCommonDialog.DefaultTitle"/>
<link id="TCommonDialog.Create"/>
<link id="#lcl.lcltype.TTranslateString">TTranslateString</link>
</seealso>
</element>

<element name="TFileDialog">
<short>
<var>TFileDialog</var> allows selection of a file from the current directory.
</short>
<descr>
<p>
<var>TFileDialog</var> allows selection of a file from the current directory. 
This is also the base class for the Open and Save (As) dialogs.
</p>
</descr>
<seealso>
<link id="TOpenDialog"/>
<link id="TSaveDialog"/>
</seealso>
</element>

<!-- private -->
<element name="TFileDialog.FInternalFilterIndex"/>
<element name="TFileDialog.FDefaultExt"/>
<element name="TFileDialog.FFileName"/>
<element name="TFileDialog.FFiles"/>
<element name="TFileDialog.FFilter"/>
<element name="TFileDialog.FFilterIndex"/>
<element name="TFileDialog.FHistoryList"/>
<element name="TFileDialog.FInitialDir"/>
<element name="TFileDialog.FOnHelpClicked"/>
<element name="TFileDialog.FOnTypeChange"/>

<element name="TFileDialog.SetDefaultExt"/>
<element name="TFileDialog.SetDefaultExt.AValue"/>
<element name="TFileDialog.SetFilterIndex"/>
<element name="TFileDialog.SetFilterIndex.AValue"/>

<element name="TFileDialog.WSRegisterClass" link="#lcl.lclclasses.TLCLComponent.WSRegisterClass"/>

<element name="TFileDialog.GetFilterIndex">
<short>
Gets the value for the FilterIndex property.
</short>
<descr/>
<seealso>
<link id="TFileDialog.FilterIndex"/>
</seealso>
</element>
<element name="TFileDialog.GetFilterIndex.Result">
<short>
Value for the FilterIndex property.
</short>
</element>

<element name="TFileDialog.SetFileName">
<short>
Set the value for the FileName property.
</short>
<descr/>
<seealso>
<link id="TFileDialog.FileName"/>
</seealso>
</element>
<element name="TFileDialog.SetFileName.Value">
<short>
New value for the FileName property.
</short>
</element>

<element name="TFileDialog.SetFilter">
<short>
Sets the value for the Filter property.
</short>
<descr/>
<seealso>
<link id="TFileDialog.Filter"/>
</seealso>
</element>
<element name="TFileDialog.SetFilter.Value">
<short>
New value for the Filter property.
</short>
</element>

<element name="TFileDialog.SetHistoryList">
<short>
Sets the value for the HistoryList property.
</short>
<descr/>
<seealso>
<link id="TFileDialog.HistoryList"/>
</seealso>
</element>
<element name="TFileDialog.SetHistoryList.AValue">
<short>
New value for the HistoryList property. 
</short>
</element>

<element name="TFileDialog.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the constructor for <var>TFileDialog</var>, and calls 
the inherited <var>Create</var> method. It allocates resources needed for the 
files and history, and initializes the filter index.
</p>
</descr>
<seealso>
<link id="#LCL.Dialogs.TCommonDialog.Create">TCommonDialog.Create</link>
</seealso>
</element>
<element name="TFileDialog.Create.TheOwner">
<short>Owner of the class instance.</short>
</element>

<element name="TFileDialog.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the destructor for <var>TFileDialog</var>, and frees 
file and history lists then calls the inherited <var>Destroy</var> method.
</p>
</descr>
<seealso>
</seealso>
</element>

<element name="TFileDialog.DoCanClose">
<short>
Performs actions needed to determine if the dialog can be closed.
</short>
<descr>
<p>
<var>DoCanClose</var> is an overridden method in <var>TFileDialog</var> used 
to perform actions needed when an attempt is made to close the dialog. It 
ensures that the inherited method is called only when the OK button was 
pressed on the dialog. If the Esc key was pressed, or the dialog is closed 
using the close icon, the inherited method is <b>not</b> called. This 
prevents the OnCanClose event from being signalled when the dialog has 
actually been cancelled. CanClose is set to <b>True</b> in this situation.
</p>
<p>
This is done to maintain compatibility with Delphi VCL behavior.
</p>
<p>
Use the OnCanClose event handler to perform validation or error checking 
needed for the value in FileName. Set the value in its CanClose argument to 
False to prevent closing the dialog form.
</p>
</descr>
<seealso>
<link id="TFileDialog.FileName"/>
<link id="TCommonDialog.UserChoice"/>
<link id="TCommonDialog.DoCanClose"/>
<link id="TCommonDialog.OnCanClose"/>
<link id="TCommonDialog.OnDialogResult"/>
</seealso>
</element>
<element name="TFileDialog.DoCanClose.CanClose">
<short>
Contains <b>True</b> if the dialog can be closed. <b>False</b> to prevent the 
dialog from being closed.
</short>
</element>

<element name="TFileDialog.DoTypeChange">
<short>
Performs actions needed when the value in FilterIndex has been changed.
</short>
<descr>
<p>
<var>DoTypeChange</var> is called when a new value is assigned to the 
FilterIndex property. It occurs after then value is FilterIndex has been 
stored to its property member. 
</p>
<p>
DoTypeChange signals the <var>OnTypeChange</var> event handler (when 
assigned) using the TFileDialog instance as the control for the notification.
</p>
</descr>
<seealso>
<link id="TFileDialog.Filter"/>
<link id="TFileDialog.FilterIndex"/>
<link id="TFileDialog.OnTypeChange"/>
</seealso>
</element>

<element name="TFileDialog.Files">
<short>
Stores the names of files (or directories) selected using the dialog.
</short>
<descr>
<p>
<var>Files</var> is a <var>TStrings</var> property used to store values 
selected using the file dialog. A TStringList instance is created and 
assigned to the property in the Create constructor.
</p>
<p>
Files is used in descendent classes, like TOpenDialog and 
TSelectDirectoryDialog, to store the directory or one or more file names 
chosen using the derived classes.
</p>
<p>
Use HistoryList to access the list of previous file or directory names used 
in the derived dialog classes.
</p>
</descr>
<seealso>
<link id="TFileDialog.Create"/>
<link id="TOpenDialog"/>
<link id="TSelectDirectoryDialog"/>
<link id="#rtl.classes.TStrings">TStrings</link>
<link id="#rtl.classes.TStringList">TStringList</link>
</seealso>
</element>

<element name="TFileDialog.HistoryList">
<short>
<var>HistoryList</var> - stringlist containing the names of files recently 
accessed.
</short>
<descr>
<p>
<var>HistoryList</var> is a <var>TStrings</var> property used to store the 
previous values selected using the file dialog. A <var>TStringList</var> 
instance is created and stored to the property in the Create constructor.
</p>
<p>
HistoryList is used in descendent classes, like TOpenDialog and 
TSelectDirectoryDialog, to store values that have previously been assigned to the FileName property.
</p>
<p>
Use FileName or Files to access the directory or one or more file names 
selected using the derived classes.
</p>
</descr>
<seealso>
<link id="TFileDialog.Create"/>
<link id="TFileDialog.FileName"/>
<link id="TFileDialog.Files"/>
<link id="TOpenDialog"/>
<link id="TSelectDirectoryDialog"/>
<link id="#rtl.classes.TStrings">TStrings</link>
<link id="#rtl.classes.TStringList">TStringList</link>
</seealso>
</element>

<element name="TFileDialog.IntfFileTypeChanged">
<short>
Signals the OnTypeChange event handler when the value in FilterIndex is 
changed by the widgetset class instance.
</short>
<descr>
<p>
<var>IntfFileTypeChanged</var> is a callback routine used by the widgetset 
class when it applies a change to the value in the FilterIndex property. It 
occurs when the FilterIndex returned from the native dialog is handled by the 
widget.
</p>
<p>
IntfFileTypeChanged stores the value in NewFilterIndex to its internal 
member, and calls DoTypeChange to signal the OnTypeChange event handler (when 
assigned).
</p>
<p>
Use the OnTypeChange event handler to perform actions needed when the value 
in FilterIndex has been modified.
</p>
</descr>
<seealso>
<link id="TFileDialog.FilterIndex"/>
<link id="TFileDialog.OnTypeChange"/>
</seealso>
</element>
<element name="TFileDialog.IntfFileTypeChanged.NewFilterIndex">
<short>
New value for the FilterIndex property.
</short>
</element>

<element name="TFileDialog.Title" link="#lcl.dialogs.TCommonDialog.Title"/>

<element name="TFileDialog.DefaultExt">
<short>
Contains the default extension for file names in the dialog.
</short>
<descr>
<p>
<var>DefaultExt</var> is a <var>String</var> property which contains the 
default file extension used for the FileName or Files in the file dialog. It 
can contain a value like 'pas' or '.pas'. If the Period character is not 
present in the first position, it is inserted before the property value is 
stored.
</p>
<p>
DefaultExt is used in descendent classes, like TOpenDialog, and provides the 
value that is appended to a file name when an extension or a Filter has not been provided.
</p>
</descr>
<seealso>
<link id="TFileDialog.FileName"/>
<link id="TFileDialog.Files"/>
<link id="TFileDialog.FilterIndex"/>
<link id="TFileDialog.Filter"/>
<link id="TOpenDialog.CheckFile"/>
</seealso>
</element>

<element name="TFileDialog.FileName">
<short>
Contains the UTF-8-encoded name for a file chosen using the dialog.
</short>
<descr>
<p>
<var>FileName</var> is a <var>String</var> property with the name for a 
file chosen using the dialog. As a String type, it can contain UTF-8-encoded 
values. If you need the file name using the system encoding, you can use 
<var>UTF8ToSys</var> from the <file>LazUTF8</file> unit.
</p>
<p>
The value in FileName may be used in a different context in descendent 
classes. For example, it represents a directory name in the 
<var>TSelectDirectoryDialog</var> descendant.
</p>
</descr>
<seealso>
<link id="#lazutils.lazutf8.UTF8ToSys">UTF8ToSys</link>
</seealso>
</element>

<element name="TFileDialog.Filter">
<short>
A string which contains available filename filters used to select files by 
their file extensions.
</short>
<descr>
<p>
This is a string which contains the filters a user can choose from. The filters 
contain descriptive text for the filters and their file masks. The component 
values in the filter are separated by the Pipe (|) symbol.
</p>
<p>
A value can be assigned to the property using notation like:
</p>
<code>'All files|*.*|Lazarus Project files|*.lpr'</code>
<p>
A filter can contain multiple file masks separated by the Semicolon (;) 
character, like:
</p>
<code>'Pascal units|*.pas;*.pp;*.p|All files|*.*'</code>
</descr>
</element>

<element name="TFileDialog.FilterIndex">
<short>This property sets which file filter is the default.</short>
<descr>
<p>
This property sets which file filter is the default. For example, set this 
property to 2 to set the second filter as default.
</p>
</descr>
</element>

<element name="TFileDialog.InitialDir">
<short>
Contains the initial directory displayed when the dialog is opened.
</short>
<descr>
<p>
<var>InitialDir</var> is a <var>String</var> property which contains the name 
for the initial directory displayed when the dialog is opened. When omitted, 
or set to an empty string, the directory for the application executable is 
used.
</p>
<p>
Assign the value in InitialDir prior to calling the Execute method to display 
the dialog.
</p>
<p>
For the windows platform, there are some CLSID values which can be used in 
InitialDir. They are GUIDs representing locations like 'This PC' or 'Network' 
used the Windows file explorer. The following values are know to work in 
InitialDir:
</p>
<dl>
<dt>Opens 'This PC'</dt>
<dd>'::{20D04FE0-3AEA-1069-A2D8-08002B30309D}'</dd>
<dt>Opens Network</dt>
<dd>'::{F02C1A0D-BE21-4350-88B0-7367FC96EF3C}'</dd>
</dl>
<p>
There are others which may, or may not, work for your Windows version:
</p>
<p>
<url href="https://www.elevenforum.com/t/list-of-windows-11-clsid-key-guid-shortcuts.1075/">
List of Windows 11 CLSID Key (GUID) Shortcuts
</url>
</p>
</descr>
<seealso>
<link id="TCommonDialog.Execute"/>
</seealso>
</element>

<element name="TFileDialog.OnHelpClicked">
<short>
Event handler signalled when the Help button is clicked.
</short>
<descr>
<p>
Used at run-time when a widgetset class responds to a Help button click. The 
Sender argument is the dialog instance for the event notification.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TNotifyEvent">TNotifyEvent</link>
</seealso>
</element>

<element name="TFileDialog.OnTypeChange">
<short>
Event handler signalled when the selected file type or filter index is 
changed.
</short>
<descr>
<p>
Used at run-time when the FilterIndex value is changed in a widgetset class. 
The Sender argument is the dialog instance for the event notification.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TNotifyEvent">TNotifyEvent</link>
</seealso>
</element>

<element name="TOpenOption">
<short>Options which can be used in a TOpenDialog instance.</short>
<descr>
<p>
<var>TOpenOption</var> contains a list of possible options which can be used 
in Open or Save dialogs. Values from the enumeration are stored in the 
<var>TOpenOptions</var> set type which is used to implement the Options 
property in TOpenDialog and descendent classes. When an option value is 
included in the set, it is enabled during execution of the dialog. The values 
are applied to the native dialog before it is executed. Some option values are 
included or excluded to represent the actions performed when the native dialog 
was executed.
</p>
<p>
Please note that some option values may not be available for a given platform 
where the LCL is supported. The help for the option values indicate the 
platforms where the value is relevant.
</p>
</descr>
<seealso>
<link id="TOpenDialog.Options"/>
<link id="TOpenOptions"/>
<link id="TSaveDialog"/>
<link id="TSelectDirectoryDialog"/>
</seealso>
</element>
<element name="TOpenOption.ofReadOnly">
<short>
For the <b>Windows</b> platform (with <var>ofOldStyleDialog</var> or before
Vista), it is responsible for the state of the "Read only" check box when 
opening the dialog and before closing it. The user can set this check box to 
ask the program to open a file in read-only mode. For <b>QT-based</b> 
platforms, it indicates that the entire dialog model is read-only.
</short>
</element>
<element name="TOpenOption.ofOverwritePrompt">
<short>
If the selected file exists, a message is displayed to confirm rewriting the 
file.
</short>
</element>
<element name="TOpenOption.ofHideReadOnly">
<short>
Windows only (with <var>ofOldStyleDialog</var> or before Vista): Hides the
"Read only" check box on the dialog.
</short>
</element>
<element name="TOpenOption.ofNoChangeDir">
<short>Do not change the current directory.</short>
</element>
<element name="TOpenOption.ofShowHelp">
<short>Show a help button.</short>
</element>
<element name="TOpenOption.ofNoValidate">
<short>
Windows only: Disables file name validation using
<var>OFN_NOVALIDATE</var>/<var>FOS_NOVALIDATE</var> flags. Allows file names
with invalid characters.
</short>
</element>
<element name="TOpenOption.ofAllowMultiSelect">
<short>
Allows selection of multiple files (or folders).  The selection list can be 
read in the <var>Files</var> property (<var>FileName</var> also contains the 
first file in the list). Affects the <var>ofExtensionDifferent</var> and
<var>ofCreatePrompt</var> flags. Not available in <var>TSaveDialog</var>.
</short>
<seealso>
<link id="TFileDialog.FileName"/>
<link id="TFileDialog.Files"/>
</seealso>
</element>
<element name="TOpenOption.ofExtensionDifferent">
<short>
This is a returned flag that is set when the extension of the selected
file differs from <var>DefaultExt</var>. It can only be returned when
<var>DefaultExt</var> is not empty, and the dialog call was successful
(<var>Execute</var> is true). For compatibility with Delphi, it is never
set if multiple files are selected (possibly with 
<var>ofAllowMultiSelect</var>).
</short>
<seealso>
<link id="TFileDialog.FileName"/>
<link id="TFileDialog.DefaultExt"/>
<link id="TCommonDialog.Execute"/>
</seealso>
</element>
<element name="TOpenOption.ofPathMustExist">
<short>
Prevents selection of a non-existent path. Depending on the widget set, the 
error will be displayed in the dialog itself or after it is closed, when 
<var>Execute</var> returns false.
</short>
<seealso>
<link id="TCommonDialog.Execute"/>
</seealso>
</element>
<element name="TOpenOption.ofFileMustExist">
<short>Doesn't allow to select a non-existent file. Depending on the
widget set, the error will be displayed in the dialog itself or after its
closing, when <var>Execute</var> returns false.</short>
<seealso>
<link id="TCommonDialog.Execute"/>
</seealso>
</element>
<element name="TOpenOption.ofCreatePrompt">
<short>
Windows only: Enables a verification prompt when a file or directory needs to
be created for a file dialog. If the user decides to create a file, the dialog
box closes. Otherwise, the dialog box remains open. When using 
<var>ofAllowMultiSelect</var>, it allows a single non-existing file to be 
specified.
</short>
<seealso>
<link id="TFileDialog.FileName"/>
</seealso>
</element>
<element name="TOpenOption.ofShareAware">
<short>
Windows only: Ignore network sharing violation errors.
</short>
</element>
<element name="TOpenOption.ofNoReadOnlyReturn">
<short>
Indicates that a dialog cannot be used to choose a read-only file. For the 
<b>Windows</b> platform, TOpenDialog displays an error message if a read-only 
file is selected - but it does not close the dialog. TSaveDialog will always 
display an error message if the user selects a read-only file - regardless of 
the state of this flag. For <b>other</b> platforms, TOpenDiaLog / TSaveDialog 
use the value to ensure that a file or directory selected with the dialog has 
write access permissions. A 'File is not writable' error message is displayed 
if the file or directory is read-only. See TOpenDialog.CheckFile.
</short>
</element>
<element name="TOpenOption.ofNoTestFileCreate">
<short>
Windows only: The OS does not check if the item specified in a
<var>TSaveDialog</var> can actually be created (it does not check for write 
protection, a full disk, an open drive door, or network protection).
</short>
</element>
<element name="TOpenOption.ofNoNetworkButton">
<short>
Windows only: Hides and disables the "Network" button.
</short>
</element>
<element name="TOpenOption.ofNoLongNames">
<short>
Windows only (with <var>ofOldStyleDialog</var>): Disables long file names and
force use the 8.3 file names format.
</short>
</element>
<element name="TOpenOption.ofOldStyleDialog">
<short>
Windows only: Shows the dialog in the Win9x style. In this style, an additional
"Read only" check box for the file opening mode can be displayed (depending on
<var>ofReadOnly</var> and <var>ofHideReadOnly</var>).
</short>
</element>
<element name="TOpenOption.ofNoDereferenceLinks">
<short>
Windows only: When choosing a file shortcut (*.lnk), return the shortcut 
itself and not the target file.
</short>
</element>
<element name="TOpenOption.ofNoResolveLinks">
<short>
Do not resolve links after Execute. This value is not explicitly used in any 
of the widgetset implementations.
</short>
<seealso>
<link id="TCommonDialog.Execute"/>
</seealso>
</element>
<element name="TOpenOption.ofEnableIncludeNotify">
<short>
Not used in the current LCL version. Defined for compatibility with Delphi.
</short>
</element>
<element name="TOpenOption.ofEnableSizing">
<short>Dialog can be resized, e.g. via the mouse.</short>
</element>
<element name="TOpenOption.ofDontAddToRecent">
<short>
Windows only: Do not add the path to the history list.
</short>
</element>
<element name="TOpenOption.ofForceShowHidden">
<short>Show hidden files.</short>
</element>
<element name="TOpenOption.ofViewDetail">
<short>
Indicates that the preview pane should be displayed on the Open dialog box. 
Used in gtk1, qt4, qt5, and qt6 widgetsets. Note: not implemented for gtk2 and 
gtk3.
</short>
</element>
<element name="TOpenOption.ofAutoPreview">
<short>
For Windows Vista (and later versions), indicates that the preview pane should 
always be displayed on an Open dialog box. Causes the FOS_FORCEPREVIEWPANEON 
flag to be included for a dialog using the Windows widgetset.
</short>
</element>

<element name="TOpenOptions">
<short>
Set type used to store <var>TOpenOption</var> enumeration values.
</short>
<descr>
<p>
<var>TOpenOptions</var> is a set type used to store 0 (zero) or more values 
from the <var>TOpenOption</var> enumeration. TOpenOptions is the type used to 
implement the Options property in TOpenDialog. When a value s included in the 
set, it is enabled during execution of the dialog.
</p>
</descr>
<seealso>
<link id="TOpenDialog.Options"/>
<link id="TOpenOption"/>
<link id="DefaultOpenDialogOptions"/>
</seealso>
</element>

<element name="TOpenOptionEx">
<short>
Widgetset-specific open options which cannot be mapped to the standard values 
in TOpenOptions.
</short>
<descr>
<p>
Values from <var>TOpenOptionEx</var> are stored in the TOpenOptionsEx set type 
used to implement the OptionsEx property in TOpenDialog.
</p>
<p>
The current implementation contains values that are specific to the IFileDialog 
interface (ShlObj) and represent dialog options available in Windows Vista or 
later versions.
</p>
<p>
Values which are intentionally not supported include: ofDefaultNoMiniMode and 
ofHideMruPlaces. These values are not supported as of Windows 7.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TOpenOptionsEx"/>
<link id="TOpenDialog.OptionsEx"/>
</seealso>
</element>
<element name="TOpenOptionEx.ofHidePinnedPlaces">
<short>
Hides items shown by default in the view's navigation pane. (Windows Vista+)
</short>
</element>
<element name="TOpenOptionEx.ofStrictFileTypes">
<short>
In a Save dialog, restrict the file extension to a file type available in the 
Filter property for the dialog. (Windows Vista+)
</short>
</element>
<element name="TOpenOptionEx.ofPickFolders">
<short>
Turns the dialog into a TSelectDirectoryDialog. (Windows Vista+)
</short>
</element>
<element name="TOpenOptionEx.ofOkButtonNeedsInteraction">
<short>
The OK button will be disabled until the user navigates the view or edits the 
filename (if applicable). (Windows Vista+)
</short>
</element>
<element name="TOpenOptionEx.ofForceFileSystem">
<short>
Ensures that returned items are file system items. (Windows Vista+)
</short>
</element>
<element name="TOpenOptionEx.ofAllNonStorageItems">
<short>
Allows the user to choose any item in the Shell namespace, not just those with 
SFGAO_STREAM or SFGAO_FILESYSTEM attributes. This flag cannot be combined with 
FOS_FORCEFILESYSTEM. (Windows Vista+)
</short>
</element>

<element name="TOpenOptionsEx">
<short>
Set type used to store values from the TOpenOptionEx enumeration.
</short>
<descr>
<p>
<var>TOpenOptionsEx</var> is a set type used to store zero (0) or more values 
from the <var>TOpenOptionEx</var> enumeration. It is the type used to implement 
the OptionsEx property in TOpenDialog, and contains the widgetset-specific 
options enabled for a dialog.
</p>
<p>
In the current implementation, TOpenOptionsEx contains values specific to 
Windows Vista or later versions. It contains values which cannot be mapped 
directly to values in the TOpenOption enumeration.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TOpenOptionEx"/>
<link id="TOpenOption"/>
<link id="TOpenOptions"/>
<link id="TOpenDialog.OptionsEx"/>
<link id="TOpenDialog.Options"/>
</seealso>
</element>

<element name="ofExNoPlacesBar">
<short>
Mapped to the ofHidePinnedPlaces option in TOpenOptionEx. Maintains code 
compatibility with older Delphi versions.
</short>
<version>
Added in LCL version 4.0.
</version>
</element>

<element name="DefaultOpenDialogOptions">
<short>
Set constant with the default Open Dialog options used in TOpenDialog.
</short>
<descr>
<p>
Contains the following values from the TOpenOption enumeration:
</p>
<dl>
<dt>ofEnableSizing</dt>
<dd>
Allows the dialog to be resized.
</dd>
<dt>ofViewDetail</dt>
<dd>
Enables the preview pane on an Open dialog.
</dd>
</dl>
<p>
DefaultOpenDialogOptions is used as the default value for the Options 
property in TOpenDialog.
</p>
</descr>
<seealso>
<link id="TOpenDialog.Options"/>
<link id="TOpenOption"/>
</seealso>
</element>

<element name="TOpenDialog">
<short>
Implements a File / Open dialog used to select one or more files on the local 
file system.
</short>
<descr>
<p>
<var>TOpenDialog</var> is a <var>TFileDialog</var> descendent which 
implements a dialog used to select one or more files that can be opened in an 
application. TOpenDialog is implemented as a wrapper for the native file 
selection dialogs on the various platforms / widgetsets.
</p>
<p>
Use the Options property to configure the features and behaviors enabled when 
the dialog is executed. Please note that some of the options are 
platform-specific, and may not be available on all of the platforms supported 
by the Lazarus LCL.
</p>
<p>
Use InitialDir to specify the directory with the files displayed when the 
dialog is executed.
</p>
<p>
Use the event handlers to perform actions needed when the directory or file 
selection(s) is changed during execution of the dialog.
</p>
<p>
Use the FileName or Files properties to access the file(s) selected using the 
dialog.
</p>
<p>
Use the Filter and FilterIndex properties to determine the file extensions 
displayed in the dialog. Use the OnTypeChange event handler to perform 
actions needed when the active filter is changed.
</p>
<p>
Use the UserChoice property to determine the button pressed to close the 
dialog.
</p>
</descr>
<seealso>
<link id="TFileDialog"/>
</seealso>
</element>

<element name="TOpenDialog.FOnFolderChange"/>
<element name="TOpenDialog.FOnSelectionChange"/>
<element name="TOpenDialog.FOptions"/>
<element name="TOpenDialog.FLastSelectionChangeFilename"/>

<element name="TOpenDialog.WSRegisterClass" link="#lcl.lclclasses.TLCLComponent.WSRegisterClass"/>

<element name="TOpenDialog.ResolveLinks">
<short>
Gets physical file names for symbolic links or file references.
</short>
<descr>
<p>
<var>ResolveLinks</var> is a procedure used to get physical file names for 
file references or symbolic links used in the <var>Filename</var> and 
<var>Files</var> properties.
</p>
<p>
Called from <var>DereferenceLinks</var> when the dialog is executed and 
<var>ofNoResolveLinks</var> is <b>NOT</b> included in the <var>Options</var> 
property.
</p>
</descr>
<seealso>
<link id="TOpenDialog.DoExecute"/>
<link id="TOpenDialog.Options"/>
<link id="TFileDialog.Filename"/>
<link id="TFileDialog.Files"/>
<link id="TOpenOption"/>
</seealso>
</element>

<element name="TOpenDialog.CheckFile">
<short>
Ensures the specified file name meets the requirements for the dialog.
</short>
<descr>
<p>
<var>CheckFile</var> is a Boolean function used to examine and update the 
specified file name. AFilename is a variable argument which contains the path 
to the file and can include its extension. The return value is <b>True</b> if 
the file name satisfies the filter, extension, and options used for the open 
dialog.
</p>
<p>
Values in DefaultExt, Filter, and FilterIndex are used to get a file 
extension when AFilename does not already include one. The file extension is 
appended to the value in AFilename.
</p>
<p>
Values in Options are used to determine if the file name is usable, including:
</p>
<dl>
<dt>ofPathMustExist</dt>
<dd>
The path in AFilename must already exist on the local file system. If it does 
not exist, a rsfdPathNoExist message is displayed and the method is exited.
</dd>
<dt>ofFileMustExist</dt>
<dd>
Calls CheckFileMustExist to ensure that the file already exists on the local 
file system. A message is displayed if the file name and extension are not 
found, and the method is exited.
</dd>
<dt>ofNoReadOnlyReturn</dt>
<dd>
The file and / or directory in AFilename must be writable. A rsfdFileReadOnly 
is displayed if the file or directory is read-only, and the method is exited. 
</dd>
</dl>
<p>
CheckFile is used in the CheckAllFiles method to validate the entries in the 
Files property.
</p>
</descr>
<version>
Modified in LCL version 2.2.6 to include an additional helper function 
(ExtractFilterValues) in the implementation.
</version>
<seealso>
<link id="TOpenDialog.Options"/>
<link id="TOpenDialog.CheckAllFiles"/>
<link id="TOpenDialog.CheckFileMustExist"/>
<link id="TFileDialog.Files"/>
<link id="TFileDialog.FileName"/>
<link id="TFileDialog.DefaultExt"/>
<link id="TFileDialog.Filter"/>
<link id="TFileDialog.FilterIndex"/>
<link id="TOpenOption"/>
</seealso>
</element>
<element name="TOpenDialog.CheckFile.Result">
<short>
<b>True</b> if the file name is valid for the open dialog.
</short>
</element>
<element name="TOpenDialog.CheckFile.AFilename">
<short>
Fully-qualified file name or directory path examined and possibly updated in 
the method.
</short>
</element>

<element name="TOpenDialog.CheckFileMustExist">
<short>
Determines whether the specified file name exists.
</short>
<descr>
<p>
<var>CheckFileMustExist</var> is a <var>Boolean</var> function used to check 
whether the file in <var>AFilename</var> exists on the local file system. The 
return value is <b>True</b> when FileExistsUTF8 finds the specified file 
name. If the file is not found, an error message is displayed with the value 
in rsfdFileNotExist.
</p>
<p>
CheckFileMustExist is used in the implementation of the CheckFile method.
</p>
</descr>
<seealso>
<link id="TOpenDialog.CheckFile"/>
<link id="TOpenDialog.CheckAllFiles"/>
<link id="TFileDialog.FileName"/>
<link id="TFileDialog.Files"/>
</seealso>
</element>
<element name="TOpenDialog.CheckFileMustExist.Result">
<short>
<b>True</b> if the specified file exists on the local file system.
</short>
</element>
<element name="TOpenDialog.CheckFileMustExist.AFileName">
<short>
File name (including path) checked in the method.
</short>
</element>

<element name="TOpenDialog.CheckAllFiles">
<short>
Ensures that values in the FileName and Files properties are valid for the 
Options in the dialog.
</short>
<descr>
<p>
<var>CheckAllFiles</var> is a <var>Boolean</var> function used to validate 
values in the FileName and Files properties using the Options enabled for the 
dialog. 
</p>
<p>
<var>FileName</var> is checked when a non-empty string value has been 
assigned to the property, or when ofAllowMultiSelect has been <b>omitted</b> 
from the Options property. The lines of text in the Files property are 
validated when ofAllowMultiSelect has been <b>included</b> in the Options 
property.
</p>
<p>
CheckAllFiles calls the CheckFile method to validate and potentially update a 
file name. A file name modified in CheckFile to include a file extension is 
stored in the origin property (FileName or Files).
</p>
<p>
The return value is <b>True</b> if the file name(s) meet the requirements for 
the Options property and the local file system. 
</p>
</descr>
<seealso>
<link id="TOpenDialog.CheckFile"/>
<link id="TOpenDialog.Options"/>
<link id="TFileDialog.FileName"/>
<link id="TFileDialog.Files"/>
<link id="TOpenOption"/>
</seealso>
</element>
<element name="TOpenDialog.CheckAllFiles.Result">
<short>
<b>True</b> if the file names are valid for Options in the dialog.
</short>
</element>

<element name="TOpenDialog.DoExecute">
<short>
Performs actions needed to display the dialog and capture its result.
</short>
<descr>
<p>
<var>DoExecute</var> is an overridden <var>Boolean</var> function in 
<var>TOpenDialog</var>. It ensures that the value ofExtensionDifferent is 
excluded from the Options property prior to executing the dialog. It calls the 
inherited method (in TCommonDialog) to display the dialog form and to get the 
UserChoice used to complete execution of the dialog.
</p>
<p>
DoExecute extends the execution loop for the dialog to use the Options enabled 
for the dialog, including:
</p>
<dl>
<dt>ofNoResolveLinks</dt>
<dd>
Calls ResolveLinks to follow symbolic links when ofNoResolveLinks has been 
<b>omitted</b>.
</dd>
<dt>ofNoChangeDir</dt>
<dd>
Updates the InitialDir property when a path in FileName or Files has been 
changed and ofNoChangeDir has been <b>omitted</b>.
</dd>
</dl>
<p>
The return value is <b>True</b> when all of the steps are successfully 
completed. The return value is <b>False</b> if any mechanism other than the OK
button was used to close the dialog.
</p>
<p>
If execution of the inherited method was successfully completed, the 
CheckAllFiles method is called to validate the values in the FileName and 
Files properties.
</p>
<p>
The return value is set to <b>True</b> if the selected FileName or Files is/are 
valid for the dialog. Options is updated to exclude the value 
ofExtensionDifferent when Files contains more than 1 (one) file entry. This  
avoids the erratic behavior displayed when multiple file selections are enabled 
and used on the dialog, and mimics the behavior used in Delphi 7.
</p>
<p>
If a single file is selected on the dialog, and has an extension which does not 
match the assigned value in DefaultExt, the value ofExtensionDifferent is 
included in Options to indicate the condition.
</p>
<p>
DoExecute is called from the Execute method in the TCommonDialog ancestor, and 
occurs immediately before the Close method is called.
</p>
</descr>
<seealso>
<link id="TOpenDialog.Options"/>
<link id="TOpenDialog.CheckAllFiles"/>
<link id="TOpenDialog.CheckFile"/>
<link id="TOpenDialog.ResolveLinks"/>
<link id="TFileDialog.FileName"/>
<link id="TFileDialog.Files"/>
<link id="TCommonDialog.DoExecute"/>
<link id="TCommonDialog.Execute"/>
<link id="TOpenOption"/>
<link id="TOpenOptions"/>
</seealso>
</element>
<element name="TOpenDialog.DoExecute.Result">
<short>
<b>True</b> when the selected file(s) are valid and the method is 
successfully completed.
</short>
</element>

<element name="TOpenDialog.DefaultTitle">
<short>Gets the default title used for the Open Dialog.</short>
<descr>
<p>
<var>DefaultTitle</var> is overridden in <var>TOpenDialog</var> to return the 
default title for the dialog. Uses the value in <var>rsfdOpenFile</var> as 
the return value.
</p>
<p>
Used in the inherited constructor to set the default value for the 
<var>Title</var> property.
</p>
</descr>
<seealso>
<link id="TFileDialog.Title"/>
<link id="TCommonDialog.Create"/>
<link id="#lcl.lclstrconsts.rsfdOpenFile">rsfdOpenFile</link>
</seealso>
</element>
<element name="TOpenDialog.DefaultTitle.Result">
<short>Default title for the dialog.</short>
</element>

<element name="TOpenDialog.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the constructor for <var>TOpenDialog</var>, and calls 
the inherited <var>Create</var> method then loads the default options for the 
dialog.
</p>
</descr>
<seealso>
<link id="#LCL.Dialogs.TFileDialog.Create">TFileDialog.Create</link>
</seealso>
</element>
<element name="TOpenDialog.Create.TheOwner">
<short>Owner of the class instance.</short>
</element>

<element name="TOpenDialog.DoCanClose">
<short>
Performs actions to determine if the dialog can be closed.
</short>
<descr>
<p>
<var>DoCanClose</var> is an overridden method in <var>TOpenDialog</var>. It 
ensures that a dialog using the classic style (where ofOldStyleDialog is 
included in Options) does not call the OnCanClose event handler in the 
inherited method. In this situation, the CanClose argument is set to 
<b>True</b> and the internal flag used in the execution loop is set 
indicating that DoCanClose was called.
</p>
<p>
This behavior is Delphi VCL compatible.
</p>
<p>
For Explorer-style dialogs (where ofOldStyleDialog is <b>not</b> included in 
Options), the inherited method is called. This allows the CanClose argument 
to be updated when the OnCanClose event handler is signalled.
</p>
</descr>
<seealso>
<link id="TOpenDialog.Options"/>
<link id="TCommonDialog.OnCanClose"/>
<link id="TOpenOption"/>
</seealso>
</element>
<element name="TOpenDialog.DoCanClose.CanClose">
<short>
Variable argument which indicates if the dialog can be closed.
</short>
</element>

<element name="TOpenDialog.DoFolderChange">
<short>
Signals the OnFolderChange event handler when a new directory is selected 
during execution of the dialog.
</short>
<descr>
<p>
<var>DoFolderChange</var> is a method used to perform actions needed when a 
new directory is selected using the open dialog. DoFolderChange signals the 
<var>OnFolderChange</var> event handler (when assigned) using the dialog 
instance as the object for the notification.
</p>
<p>
DoFolderChange is called from the widgetset class when directory navigation 
has occurred in the native dialog. FileName contains the path for the newly 
selected directory when the method is called.
</p>
<p>
Use InitialDir to specify the initial directory displayed when the dialog is 
executed.
</p>
<p>
Use OnSelectionChange to perform actions needed when a new file is selected 
using the dialog and the value in FileName is modified.
</p>
</descr>
<seealso>
<link id="TOpenDialog.OnFolderChange"/>
<link id="TOpenDialog.OnSelectionChange"/>
<link id="TFileDialog.FileName"/>
<link id="TFileDialog.InitialDir"/>
</seealso>
</element>

<element name="TOpenDialog.DoSelectionChange">
<short>
Performs actions when the selected file in FileName has been changed.
</short>
<descr>
<p>
<var>DoSelectionChange</var> is a method used to perform action needed when 
the selected file in the dialog has been change. It is called from methods in 
the widgetset class when a new value has been assigned to the FileName 
property.
</p>
<p>
DoSelectionChange updates an internal member used to track the current and 
previous value for the FileName property. It signals the 
<var>OnSelectionChange</var> event handler (when assigned) using the dialog 
class instance as the object for the notification.
</p>
<p>
Use HistoryList for the previously selected file name values in the dialog.
</p>
</descr>
<seealso>
<link id="TOpenDialog.OnSelectionChange"/>
<link id="TFileDialog.FileName"/>
</seealso>
</element>

<element name="TOpenDialog.IntfSetOption">
<short>
Implements the callback used to update values in Options when the widgetset 
class processes the dialog result.
</short>
<descr/>
<seealso/>
</element>
<element name="TOpenDialog.IntfSetOption.AOption">
<short>
TOpenOption enumeration value updated in the Options for the dialog.
</short>
</element>
<element name="TOpenDialog.IntfSetOption.AValue">
<short>
<b>True</b> to include the option in the class instance. <b>False</b> to 
exclude the option.
</short>
</element>

<element name="TOpenDialog.Options">
<short>Options to be used for this dialog.</short>
<descr>
<p>
<var>Options</var> is a <var>TOpenOptions</var> property with the set used to 
store options enabled in the dialog. Options contain 0 (zero) or more values 
from the <var>TOpenOption</var> enumeration. When a value is included in the 
set, it is enabled when the dialog is executed.
</p>
<p>
The default value for the property is defined in the DefaultOpenDialogOptions 
constant, and contains:
</p>
<dl>
<dt>ofEnableSizing</dt>
<dd>
Allows the dialog to be resized at run-time.
</dd>
<dt>ofViewDetail</dt>
<dd>
Enables the preview pane on an Open dialog.
</dd>
</dl>
<p>
See <link id="TOpenOption"/> for a complete list of enumeration values and 
their meanings.
</p>
<p>
Values in Options are used at run-time in methods like:
</p>
<ul>
<li>CheckAllFiles</li>
<li>CheckFile</li>
<li>DoExecute</li>
<li>DoCanClose</li>
</ul>
<p>
In addition, values in Options may be updated when the IntfSetOption callback 
method is used to apply changes from the widgetset class instance.
</p>
</descr>
<seealso>
<link id="TOpenDialog.DoExecute"/>
<link id="TOpenDialog.IntfSetOption"/>
<link id="TOpenOptions"/>
<link id="TOpenOption"/>
<link id="DefaultOpenDialogOptions"/>
</seealso>
</element>

<element name="TOpenDialog.OptionsEx">
<short>
Widgetset-specific options enabled for the dialog.
</short>
<descr>
<p>
<var>OptionsEx</var> is a <var>TOpenOptionsEx</var> property which contains the 
widgetset-specific options enabled when the dialog is executed. It can contain 
zero (0) or more values from the TOpenOptionEx enumeration. The default value 
for the property is an empty set ([]).
</p>
<p>
OptionsEx is used in the widgetset class instance to apply values which cannot 
be represented using TOpenOptions and TOpenOption, which are used on all of the 
supported LCL platforms. In the current LCL version, OptionsEx is used for the 
Windows platform and supports Windows Vista or later version.
</p>
</descr>
<seealso>
<link id="TOpenDialog.Options"/>
<link id="TOpenOptionsEx"/>
<link id="TOpenOptionEx"/>
</seealso>
</element>

<element name="TOpenDialog.OnFolderChange">
<short>
Event signalled when a new directory is selected in the dialog.
</short>
<descr>
<p>
<var>OnFolderChange</var> is a <var>TNotifyEvent</var> property with the 
event handler signalled when the current directory is changed using the 
dialog. OnFolderChange is signalled (when assigned) from the DoFolderChange 
method when it is called from methods in the widgetset class instance. It is 
called when the value in FileName has been changed as a result of directory 
navigation using the native dialog for the platform.
</p>
<p>
The dialog class instance is used as the Sender object for the event 
notification.
</p>
<p>
Please note that changing the current folder (and updating FileName with the 
new directory) will also trigger the OnSelectionChange event.
</p>
</descr>
<seealso>
<link id="TOpenDialog.Options"/>
<link id="TOpenDialog.DoFolderChange"/>
<link id="TOpenDialog.OnSelectionChange"/>
<link id="TFileDialog.FileName"/>
<link id="TFileDialog.Files"/>
</seealso>
</element>

<element name="TOpenDialog.OnSelectionChange">
<short>
Event triggered when the user changes the folder of file selection(s) made in 
the OpenDialog.
</short>
<descr>
<p>
<var>OnSelectionChange</var> is a <var>TNotifyEvent</var> property with the 
event handler signalled when the folder or file selection for the dialog has 
been changed. It is signalled (when assigned) from the DoSelectionChange 
method. The dialog class instance is used as the object for the notification.
</p>
<p>
OnSelectionChange occurs at run-time when the value in <var>FileName</var> is 
changed using the native dialog for the platform. The value in FileName has 
been updated and also stored as the text value for the Files property prior 
to the event.
</p>
<p>
When multi-selection is enabled by including ofAllowMultiSelect in Options, 
OnSelectionChange is signalled for the first value in the range of selected 
files only. It will, however, be signalled again when the first selection is 
changed. Other selected file names in Files, which are not the first selected 
file, are not signalled at all.
</p>
<p>
Please note that both the OnSelectionChange and OnFolderChange events are 
signalled during execution when the folder (or directory) is changed to value 
that does not match the previous value in FileName. OnSelectionChange is 
signalled first.
</p>
</descr>
<seealso>
<link id="TOpenDialog.DoSelectionChange"/>
<link id="TOpenDialog.OnFolderChange"/>
<link id="TOpenDialog.Options"/>
<link id="TFileDialog.FileName"/>
<link id="TFileDialog.Files"/>
</seealso>
</element>

<element name="TSaveDialog">
<short>
<var>TSaveDialog</var> - Dialog for saving the current buffer to a file.
</short>
<descr>
<p>
<var>TSaveDialog</var> is a <var>TOpenDialog</var> descendant which 
implements a dialog used when an application needs to save a file. It is a 
wrapper for the native Save / Save As dialogs on the platforms where the LCL 
is supported.
</p>
<p>
TSaveDialog extends the ancestor class to provide the correct default title 
for the derived dialog class.
</p>
<p>
TSaveDialog is used to implement the TFileSaveAs dialog defined in the 
<file>stdactns.pas</file> unit.
</p>
</descr>
<seealso>
<link id="TOpenDialog"/>
<link id="#lcl.stdactns.TFileSaveAs">TFileSaveAs</link>
</seealso>
</element>

<element name="TSaveDialog.WSRegisterClass" link="#lcl.lclclasses.TLCLComponent.WSRegisterClass"/>

<element name="TSaveDialog.DefaultTitle">
<short>Gets the default title used for the Save Dialog.</short>
<descr>
<p>
<var>DefaultTitle</var> is overridden in <var>TSaveDialog</var> to return the 
default title for the dialog. Uses the value in <var>rsfdFileSaveAs</var> as 
the return value.
</p>
<p>
Used in the inherited constructor to set the default value for the 
<var>Title</var> property.
</p>
</descr>
<seealso>
<link id="TOpenDialog.DefaultTitle"/>
<link id="TFileDialog.Title"/>
<link id="TCommonDialog.Create"/>
<link id="#lcl.lclstrconsts.rsfdFileSaveAs">rsfdFileSaveAs</link>
</seealso>
</element>
<element name="TSaveDialog.DefaultTitle.Result">
<short>Default title for the dialog.</short>
</element>

<element name="TSaveDialog.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the overridden constructor for the class instance, and 
calls the inherited constructor on entry. Create updates the component style 
flags to the value needed (csSaveFileDialog) for the dialog type.
</p>
</descr>
<seealso>
<link id="TOpenDialog.Create"/>
<link id="TCommonDialog.FCompStyle"/>
<link id="#lcl.lcltype.csSaveFileDialog">csSaveFileDialog</link>
</seealso>
</element>
<element name="TSaveDialog.Create.AOwner">
<short>Owner of the class instance.</short>
</element>

<element name="TSelectDirectoryDialog">
<short>Implements a select directory dialog.</short>
<descr>
<p>
<var>TSelectDirectoryDialog</var> is a <var>TOpenDialog</var> descendant 
which allows the user to select a directory name by navigating file system 
entries. It is implemented using the native selection dialog for the platform.
</p>
<p>
Use the InitialDir property to specify the active directory when the dialog 
is displayed.
</p>
<p>
The FileName property contains the selected directory when the dialog is 
closed using the 'Select Folder' button.
</p>
<p>
The Options property can be used to control the features and behaviors enabled for the selection dialog.
</p>
<p>
Use the OnFolderChange event handler to perform actions when a new directory 
is entered / chosen during navigation on the dialog.
</p>
<p>
Use the OnSelectionChange handler to perform actions when a new directory is 
selected or highlighted using the mouse or cursor keys on the dialog.
</p>
</descr>
<seealso>
<link id="TOpenDialog"/>
<link id="#lcl.editbtn.TDirectoryEdit">TDirectoryEdit</link>
</seealso>
</element>

<element name="TSelectDirectoryDialog.WSRegisterClass" link="#lcl.lclclasses.TLCLComponent.WSRegisterClass"/>

<element name="TSelectDirectoryDialog.CheckFileMustExist">
<short>
Checks whether a specified directory already exists, and displays a message 
when missing.
</short>
<descr>
<p>
<var>CheckFileMustExist</var> is an overridden <var>Boolean</var> function in 
<var>TSelectDirectoryDialog</var>. It is check whether the directory 
specified in <var>AFilename</var> already exists on the file system. The 
return value is <b>True</b> if the directory in AFilename already exists. It 
is <b>False</b> if the directory does not exist.
</p>
<p>
CheckFileMustExist re-implements the method inherited from 
<var>TOpenDialog</var> to use directory-specific resource strings when messages are displayed for a missing value in AFilename.
</p>
<p>
CheckFileMustExist is called from the <var>CheckFile</var> method in TOpenDialog.
</p>
</descr>
<seealso>
<link id="TOpenDialog.CheckFileMustExist"/>
<link id="TOpenDialog.CheckFile"/>
<link id="#lazutils.lazfileutils.DirPathExists">DirPathExists</link>
</seealso>
</element>
<element name="TSelectDirectoryDialog.CheckFileMustExist.Result">
<short>
<b>True</b> if the specified directory exists, and <b>False</b> when it is 
missing.
</short>
</element>
<element name="TSelectDirectoryDialog.CheckFileMustExist.AFilename">
<short>
Directory name examined in the method.
</short>
</element>

<element name="TSelectDirectoryDialog.DefaultTitle">
<short>
Gets the default title for the dialog.
</short>
<descr>
<p>
<var>DefaultTitle</var> is an overridden <var>String</var> function used to 
get the default title displayed on the directory selection dialog. It returns 
the value assigned to the <var>rsfdSelectDirectory</var> resource string used 
in the LCL.
</p>
</descr>
<seealso>
<link id="TOpenDialog.DefaultTitle"/>
<link id="TCommonDialog.DefaultTitle"/>
<link id="#lcl.lclstrconsts.rsfdSelectDirectory">rsfdSelectDirectory</link>
</seealso>
</element>

<element name="TSelectDirectoryDialog.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<p>
<var>Create</var> is the overridden constructor for the class instance. It 
calls the inherited constructor on entry, and sets the component style flag 
to the value <var>csSelectDirectoryDialog</var>.
</p>
</descr>
<seealso>
<link id="TOpenDialog.Create"/>
<link id="#lcl.lcltype.csSelectDirectoryDialog">csSelectDirectoryDialog</link>
</seealso>
</element>
<element name="TSelectDirectoryDialog.Create.AOwner">
<short>
Owner of the class instance used in notification events.
</short>
</element>

<element name="TColorDialogOption">
<short>
Represents the options which can be enabled during execution of a color dialog.
</short>
<descr>
<p>
Values from the enumeration are stored in the TColorDialogOptions set type used 
to implement the TColorDialog.Options property.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TColorDialogOptions"/>
<link id="TColorDialog.Options"/>
</seealso>
</element>
<element name="TColorDialogOption.cdFullOpen">
<short>
Causes the dialog box to display the additional controls that allow the user to 
create custom colors.
</short>
</element>
<element name="TColorDialogOption.cdPreventFullOpen">
<short>
Disables the "Define Custom Color" button.
</short>
</element>
<element name="TColorDialogOption.cdShowHelp">
<short>
Causes the dialog box to display the Help button.
</short>
</element>
<element name="TColorDialogOption.cdSolidColor">
<short>
Causes the dialog box to display only solid colors in the set of basic colors.
</short>
</element>
<element name="TColorDialogOption.cdAnyColor">
<short>
Causes the dialog box to display all available colors in the set of basic 
colors.
</short>
</element>

<element name="TColorDialogOptions">
<short>
Set type used to store values from the TColorDialogOption enumeration.
</short>
<descr>
<p>
<var>TColorDialogOptions</var> is used to zero (0) for more values from the 
<var>TColorDialogOption</var> enumeration. TColorDialogOptions is the typed 
used to implement the Options property in TColorDialog. It contains the options 
which are enabled at run-time when the TColorDialog is executed.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TColorDialogOption"/>
<link id="TColorDialog.Options"/>
</seealso>
</element>

<element name="DefaultColorDialogOptions">
<short>
Specifies the default options enabled in TColorDialog.
</short>
<descr>
<p>
Provided for compatibility with previous LCL versions. This is probably not 
Delphi compatible.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TColorDialogOption"/>
<link id="TColorDialogOptions"/>
</seealso>
</element>

<element name="TColorDialog">
<short>
Implements a dialog used to select a TColor value.
</short>
<descr>
<p>
<var>TColorDialog</var> is a TCommonDialog descendant which implements a 
dialog used to select a color value from a palette of colors. It is a wrapper 
for the native color selection dialog on platforms supported by the LCL (when 
available).
</p>
<p>
The dialog allows a TColor value to be selected from a group of predefined 
basic colors, custom colors, or using a color wheel or pad. On some 
platforms, the color can be specified using RGB or HSL (Hue, Saturation, 
Luminosity) values.
</p>
<p>
Use the CustomColors property to define color values using identifiers and 
hexadecimal RGB values for the custom colors.
</p>
<p>
Set the value for the Title property (when needed) prior to displaying the 
color selection dialog.
</p>
<p>
Call the <var>Execute</var> method to display the color dialog and capture 
the color value. If the user clicks on the OK button in the dialog, the 
selected color value is returned in the Color property and the UserChoice 
property is set to mrOK. A value other than mrOK indicates that the color 
selection dialog was cancelled or closed without selecting a color value.
</p>
</descr>
<seealso>
<link id="TColorDialog.Color"/>
<link id="TColorDialog.CustomColors"/>
<link id="TCommonDialog.Title"/>
<link id="TCommonDialog.Execute"/>
<link id="TCommonDialog.UserChoice"/>
</seealso>
</element>

<element name="TColorDialog.FColor">
<short>Internal member used to store the value for he selected color.</short>
</element>

<element name="TColorDialog.FCustomColors">
<short>Internal member used to store user-specified colors.</short>
</element>

<element name="TColorDialog.SetCustomColors">
<short>
Sets the value for the CustomColors property.
</short>
<descr/>
<seealso>
<link id="TColorDialog.CustomColors"/>
</seealso>
</element>
<element name="TColorDialog.SetCustomColors.AValue">
<short>
New value for the CustomColors property.
</short>
</element>

<element name="TColorDialog.AddDefaultColor">
<short>
Adds a value to the CustomColors property.
</short>
<descr/>
<seealso/>
</element>
<element name="TColorDialog.AddDefaultColor.s">
<short>
String with the identifier and hexadecimal RGB color value added in the 
method.
</short>
</element>

<element name="TColorDialog.WSRegisterClass" link="#lcl.lclclasses.TLCLComponent.WSRegisterClass"/>

<element name="TColorDialog.DefaultTitle">
<short>
Gets the default title used in the caption for the color selection dialog.
</short>
<descr>
<p>
The return values contains the string data found in the rsSelectcolorTitle 
constant.
</p>
</descr>
<seealso>
<link id="TCommonDialog.Title"/>
<link id="#lcl.dialogs.TCommonDialog.DefaultTitle">TCommonDialog.DefaultTitle</link>
</seealso>
</element>
<element name="TColorDialog.DefaultTitle.Result">
<short>
Returns the values defined in the rsSelectcolorTitle constant.
</short>
</element>

<element name="TColorDialog.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<p>
<var>Create</var> is the constructor for <var>TColorDialog</var>, and calls 
the inherited <var>Create</var> method. Create allocates resources for and 
initializes the default values for the CustomColors and Options properties. 
Component style flags are also updated in the method.
</p>
</descr>
<seealso>
<link id="#LCL.Dialogs.TCommonDialog.Create">TCommonDialog.Create</link>
</seealso>
</element>
<element name="TColorDialog.Create.TheOwner">
<short>Owner of the class instance.</short>
</element>

<element name="TColorDialog.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for <var>TColorDialog</var>. 
It frees resources allocated for the CustomColors property and calls the 
inherited <var>Destroy</var> method.
</p>
</descr>
<seealso>
<link id="TColorDialog.CustomColors"/>
<link id="#lcl.lclclasses.TLCLComponent.Destroy">TLCLComponent.Destroy</link>
</seealso>
</element>

<element name="TColorDialog.Title">
<short>The Title or Caption displayed in the title bar for the dialog.</short>
<descr>
<p>
<var>Title</var> can be used to provide a usage context for the re-usable 
dialog. The default value for the property is provided by the DefaultTitle 
method. Set the value for the property before calling the Execute method.
</p>
<remark>
For the macOS Carbon widgetset, the Title property is not supported.
</remark>
</descr>
<seealso>
<link id="TCommonDialog.DefaultTitle"/>
<link id="#lcl.dialogs.TCommonDialog.Title">TCommonDialog.Title</link>
</seealso>
</element>

<element name="TColorDialog.Color">
<short>Color selected by the user in the color dialog.</short>
<descr>
<p>
<var>Color</var> is a TColor property with the color selected using the 
dialog. A value can be pre-set in Color and accepted, but a new value may 
also be chosen. When the Color dialog is displayed and the user pressed OK, 
the Color property contains the chosen color.
</p>
<p>
Use CustomColors to define a palette with color names and their hexadecimal 
values available in the dialog.
</p>
</descr>
<seealso>
<link id="TColorDialog.CustomColors"/>
<link id="TCommonDialog.Execute"/>
</seealso>
</element>

<element name="TColorDialog.CustomColors">
<short>
Defines the color names and values available in the color dialog.
</short>
<descr>
<p>
<var>CustomColors</var> is a <var>TStrings</var> property which contains the 
color names and hexadecimal values available in the color dialog. It allows a 
custom color palette to be used in place of the default colors for the 
platform.
</p>
<p>
Values added to CustomColors are in the "name=hexvalue" format. For example:
</p>
<code>
ADialog.CustomColors.Add('ColorA=FFFF00');
// or
ADialog.CustomColors.Values['ColorA'] := 'FFFF00';
</code>
<p>
The hexadecimal color value is 6-digits representing the RGB components for 
the color.
</p>
<p>
The default values in CustomColors are assigned in the Create constructor to 
the standard and extended colors for the platform. It does not include the 
equivalents for clDefault and clNone.
</p>
<p>
Use Color to get the TColor value selected using the dialog when the Execute 
method was called.
</p>
</descr>
<seealso>
<link id="TColorDialog.Color"/>
<link id="TCommonDialog.Execute"/>
</seealso>
</element>

<element name="TColorDialog.Options">
<short>
Indicates the optional features enabled (or disabled) for the color dialog.
</short>
<descr>
<p>
<var>Options</var> is a <var>TColorDialogOptions</var> property which contains 
the optional features used when the color dialog is executed. It contains zero 
(0) or more values from the <link id="TColorDialogOption"/> enumeration; when a 
value is present in the set type, the feature is enabled for the dialog.
</p>
<p>
The default value for the property is defined in the 
<link id="DefaultColorDialogOptions"/> constant.
</p>
<p>
Options is used by the widgetset to create the flag values associated with the 
Handle created for the dialog.
</p>
<remark>
Options is currently enabled for the Windows widgetset only. Its implementation 
is modeled on the use of flag values in the CHOOSECOLOR function from the 
Windows API.
(https://learn.microsoft.com/en-us/windows/win32/api/commdlg/ns-commdlg-choosecolora-r1)
</remark>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TColorDialogOption"/>
<link id="TColorDialogOptions"/>
<link id="DefaultColorDialogOptions"/>
</seealso>
</element>

<element name="TColorButton">
<short>
<var>TColorButton</var> - a SpeedButton designed to be used with the Color 
dialog, allowing a color to be selected for text or graphics.
</short>
<descr>
<p>
<var>TColorButton</var> - a SpeedButton designed to be used with the Color 
dialog, allowing a color to be selected for text or graphics.
</p>
<p>
To use the ColorButton, first select the ColorButton icon from the Component 
Palette and place it on the Form Designer in the location you want it to 
occupy, then place a TColorDialog on the Form Designer, give it a name (or 
accept the default name) and select this named dialog as the ColorDialog 
property in the Object Inspector for the ColorButton.
</p>
<p>
The default appearance of the ColorButton is a rectangle containing a color; 
if you wish to include a caption beside the block of color, you may need to 
adjust the size of the control to accommodate the text, and you can then 
enter some text in the Caption property of the ColorButton; this text will 
appear next to the color block.
</p>
<p>
At run-time the ColorButton is visible with a default or preselected 
ButtonColor in the block, and any optional caption beside it; the ColorDialog 
is not visible until the ColorButton is clicked, when the ColorDialog pops up 
and offers a choice of colors, either from a list or a palette, and if the 
user makes a selection and closes the dialog by pressing OK, the ColorButton 
will display the color that was chosen in the ColorDialog.
</p>
<p>
Note that in the context of ColorButton, properties with the name ButtonColor 
refer to the color that has been selected and is displayed in the color 
block; properties entitled Color without 'Button' attached refer to the color 
of the control itself, usually the same as the background or the default 
button face color.
</p>
</descr>
<seealso/>
</element>

<element name="TColorButton.FBorderWidth"/>
<element name="TColorButton.FButtonColorAutoSize"/>
<element name="TColorButton.FButtonColorSize"/>
<element name="TColorButton.FButtonColor"/>
<element name="TColorButton.FColorDialog"/>
<element name="TColorButton.FOnColorChanged"/>
<element name="TColorButton.FDisabledPattern"/>

<element name="TColorButton.IsButtonColorAutoSizeStored">
<short>
Implements the storage specifier for the ButtonColorAutoSize property.
</short>
<descr/>
<seealso/>
</element>
<element name="TColorButton.IsButtonColorAutoSizeStored.Result">
<short><b>True</b> when ButtonColorAutoSize is set to <b>False</b>.</short>
</element>

<element name="TColorButton.SetBorderWidth">
<short>Sets the value for the BorderWidth property.</short>
<descr/>
<seealso>
<link id="TColorButton.BorderWidth"/>
</seealso>
</element>
<element name="TColorButton.SetBorderWidth.AValue">
<short>New value for the BorderWidth property.</short>
</element>

<element name="TColorButton.SetButtonColor">
<short>Sets the value for the ButtonColor property.</short>
<descr/>
<seealso>
<link id="TColorButton.ButtonColor"/>
</seealso>
</element>
<element name="TColorButton.SetButtonColor.AValue">
<short>New value for the ButtonColor property.</short>
</element>

<element name="TColorButton.SetButtonColorAutoSize">
<short>Sets the value for the ButtonColorAutoSize property.</short>
<descr/>
<seealso>
<link id="TColorButton.ButtonColorAutoSize"/>
</seealso>
</element>
<element name="TColorButton.SetButtonColorAutoSize.AValue">
<short>New value for the ButtonColorAutoSize property.</short>
</element>

<element name="TColorButton.SetButtonColorSize">
<short>Sets the value for the ButtonColorSize property.</short>
<descr/>
<seealso>
<link id="TColorButton.ButtonColorSize"/>
</seealso>
</element>
<element name="TColorButton.SetButtonColorSize.AValue">
<short>New value for the ButtonColorSize property.</short>
</element>

<element name="TColorButton.WSRegisterClass" link="#lcl.lclclasses.TLCLComponent.WSRegisterClass"/>

<element name="TColorButton.DoAutoAdjustLayout">
<short>
Applies auto-layout changes using the specified policy and scaling 
proportions to the control.
</short>
<descr>
<p>
<var>DoAutoAdjustLayout</var> is an overridden method in 
<var>TColorButton</var> used to implement changes to control and border sizes 
for the AutoAdjustLayout method. These methods are called when High-DPI and 
scaling have been enabled in the project options for an application.
</p>
<p>
<var>AMode</var> indicates the automatic layout policy applied in the method. 
It is a value from the TLayoutAdjustmentPolicy enumeration, and determines 
whether horizontal / vertical / or both sizes are adjusted in the method. It 
generally reflects the constraints for the device type where the application 
is running.
</p>
<p>
<var>AXProportion</var> and <var>AYProportion</var> contain the scaling 
factors applied to the horizontal and/or vertical sizes.
</p>
<p>
DoAutoAdjustLayout calls the inherited method on entry. It extends the 
method to update the ButtonColorSize and BorderWidth properties when AMode 
indicates that either horizontal or high DPI scaling are used.
</p>
</descr>
<seealso>
<link id="#lcl.controls.TControl.DoAutoAdjustLayout">TControl.DoAutoAdjustLayout</link>
</seealso>
<version>
Added in LCL version 3.0.
</version>
</element>
<element name="TColorButton.DoAutoAdjustLayout.AMode">
<short>
Identifies the auto-layout policy applied in the method.
</short>
</element>
<element name="TColorButton.DoAutoAdjustLayout.AXProportion">
<short>Scaling factor for horizontal dimensions.</short>
</element>
<element name="TColorButton.DoAutoAdjustLayout.AYProportion">
<short>Scaling factor for vertical dimensions.</short>
</element>

<element name="TColorButton.DrawGlyph">
<short>
Re-implements drawing the glyph for the control to use the selected color.
</short>
<descr>
<p>
<var>DrawGlyph</var> is an overridden method in <var>TColorButton</var>. It 
re-implements the ancestor method to draw the button face and color block (or 
swatch) for the control using the arguments passed to the method.
</p>
<p>
The value in AState determines the appearance for the glyph (color swatch). 
When set to bsDisabled, a bitmap with a disabled pattern (dotted lines) is 
drawn using the Color for the button face. Otherwise, the value in 
ButtonColor is used to draw the glyph. GetGlyphSize is called to get the 
dimensions for the glyph based on the settings in ButtonColorAutoSize and 
ButtonColorSize.
</p>
<p>
The return value is a TRect instance with the bounds affected in the drawing 
operation.
</p>
<p>
DrawGlyph calls the Rectangle method for the TCanvas instance in the Canvas 
argument using the return value for the method as an argument.
</p>
<p>
DrawGlyph does <b>not</b> call the inherited method which draws the glyph 
image for the speed button.
</p>
<p>
DrawGlyph is called from the MeasureDraw method in the ancestor class.
</p>
</descr>
<seealso>
<link id="TColorButton.Color"/>
<link id="TColorButton.ButtonColor"/>
<link id="TColorButton.ButtonColorAutoSize"/>
<link id="TColorButton.ButtonColorSize"/>
<link id="TColorButton.GetGlyphSize"/>
<link id="#lcl.buttons.TCustomSpeedButton.DrawGlyph">TCustomSpeedButton.DrawGlyph</link>
<link id="#lcl.buttons.TCustomSpeedButton.DrawGlyph">TCustomSpeedButton.MeasureDraw</link>
<link id="#lcl.buttons.TButtonState">TButtonState</link>
</seealso>
</element>
<element name="TColorButton.DrawGlyph.Result">
<short>Rectangle where the color block is drawn for the control.</short>
</element>
<element name="TColorButton.DrawGlyph.ACanvas">
<short>Drawing surface where the control is drawn.</short>
</element>
<element name="TColorButton.DrawGlyph.AClient">
<short>
Client rectangle where the button face / color block is rendered.
</short>
</element>
<element name="TColorButton.DrawGlyph.AOffset">
<short>
TPoint with horizontal and vertical offsets in AClient where the glyph is 
drawn.
</short>
</element>
<element name="TColorButton.DrawGlyph.AState">
<short>
Button state for the glyph; bsDisabled draws the disabled pattern for the 
button control.
</short>
</element>
<element name="TColorButton.DrawGlyph.ATransparent">
<short>Not used in the method.</short>
</element>
<element name="TColorButton.DrawGlyph.BiDiFlags">
<short>Not used in the method.</short>
</element>

<element name="TColorButton.GetDisabledPattern">
<short>Gets a bitmap with the disabled pattern for the control.</short>
<descr>
<p>
GetDisabledPattern is a TBitmap function used to get the bitmap with the 
disabled pattern drawn on the control. It is used when the Enabled property 
(in the control or one of its parents) is set to <b>False</b>.
</p>
<p>
GetDisabledPattern ensures that a TBitmap instance has been created and 
assigned to an internal member for the class instance. The bitmap contains a 
pattern with dotted lines that indicate the control cannot accept input 
values. The allocated bitmap is freed (when assigned) in the destructor for 
the class instance.
</p>
<p>
GetDisabledPattern is called from the DrawGlyph method when its button state 
argument is set to bsDisabled.
</p>
</descr>
<seealso/>
</element>
<element name="TColorButton.GetDisabledPattern.Result">
<short>
TBitmap instance with the disabled pattern drawn for the control.
</short>
</element>

<element name="TColorButton.GetGlyphSize">
<short>
Gets the size for the glyph (color block / swatch) on the button control.
</short>
<descr>
<p>
<var>GetGlyphSize</var> is an overridden <var>TSize</var> function used to 
get the dimensions for the glyph (color block / swatch) displayed on the 
button control. Values in ButtonColorAutoSize and ButtonColorSize determine 
the height and width used for the color block displayed on the control.
</p>
<p>
When ButtonColorAutoSize is set to <b>True</b>, the color block is auto-sized 
to fill the unused client area for the control specified in the PaintRect 
argument. Space is reserved for the Caption (color name), Spacing, 
BorderWidth, and Margin properties assigned to the control.
</p>
<p>
When ButtonColorAutoSize is <b>False</b>, ButtonColorSize is used as both the 
width and height for the color block.
</p>
<p>
The return value is a TSize instance where the width and height for the color 
block are stored in the CX and CY members (respectively). Layout determines 
whether spacing is reserved in the horizontal (blGlyphLeft, blGlyphRight) or 
vertical (blGlyphTop, blGlyphBottom) dimensions.
</p>
</descr>
<seealso>
<link id="TColorButton.ButtonColorAutoSize"/>
<link id="TColorButton.ButtonColorSize"/>
<link id="TColorButton.BorderWidth"/>
<link id="TCustomSpeedButton.GetTextSize"/>
<link id="TCustomSpeedButton.Spacing"/>
<link id="TCustomSpeedButton.Layout"/>
<link id="TCustomSpeedButton.Margin"/>
<link id="#lcl.controls.TControl.Caption">TControl.Caption</link>
</seealso>
</element>
<element name="TColorButton.GetGlyphSize.Result">
<short>TSize instance with the dimensions for the glyph (color block).</short>
</element>
<element name="TColorButton.GetGlyphSize.Drawing">
<short>
<b>True</b> if a drawing operation is active; never set to <b>False</b> in 
LCL code.
</short>
</element>
<element name="TColorButton.GetGlyphSize.PaintRect">
<short>TRect instance with the display area for the button control.</short>
</element>

<element name="TColorButton.GetControlClassDefaultSize" link="#lcl.controls.TControl.GetControlClassDefaultSize"/>
<element name="TColorButton.GetControlClassDefaultSize.Result" link="#lcl.controls.TControl.GetControlClassDefaultSize.Result"/>

<element name="TColorButton.Notification">
<short>
Performs actions when the specified component is added to or removed from the 
control.
</short>
<descr>
<p>
<var>Notification</var> is an overridden method in <var>TColorButton</var>, 
and calls the inherited method on entry. It ensures that the 
<var>ColorDialog</var> property is set to <b>Nil</b> when 
<var>AComponent</var> and <var>Operation</var> indicate the dialog class 
instance has been removed from the control.
</p>
</descr>
<seealso/>
</element>
<element name="TColorButton.Notification.AComponent">
<short>Component for the notification.</short>
</element>
<element name="TColorButton.Notification.Operation">
<short>Operation performed for the specified component.</short>
</element>

<element name="TColorButton.ShowColorDialog">
<short>Displays a Color dialog and captures its result.</short>
<descr>
<p>
<var>ShowColorDialog</var> is a method used to display a 
<var>TColorDialog</var> and capture its result.
</p>
<p>
ShowColorDialog uses an existing dialog instance in <var>ColorDialog</var> 
when assigned. Otherwise, a new <var>TColorDialog</var> instance is created 
and temporarily stored in the property. The value in <var>ButtonColor</var> 
is used as the default color value in the dialog. The <var>Execute</var> 
method in the dialog is called to get the selected TColor value, and it is 
stored in the <var>ButtonColor</var> property.
</p>
</descr>
<seealso>
<link id="TColorButton.ButtonColor"/>
<link id="TColorButton.ColorDialog"/>
<link id="TCommonDialog.Execute"/>
</seealso>
</element>

<element name="TColorButton.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the constructor for <var>TColorButton</var>, and calls 
the inherited <var>Create</var> method. Create sets the initial bounds for 
the controls to their default values, and sets the values for properties 
including:
</p>
<ul>
<li>ButtonColorSize (16)</li>
<li>BorderWidth (2)</li>
<li>ButtonColorAutoSize (True)</li>
</ul>
</descr>
<seealso>
<link id="#lcl.buttons.TCustomSpeedButton.Create">TCustomSpeedButton.Create</link>
</seealso>
</element>
<element name="TColorButton.Create.AnOwner">
<short>Owner of the class instance.</short>
</element>

<element name="TColorButton.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
Destroy is the overridden destructor for the class instance. It ensures that 
the internal bitmap with the pattern displayed for the disabled control is 
freed (when assigned). Destroy calls the inherited destructor prior to 
exiting from the method.
</p>
</descr>
<seealso>
<link id="#lcl.buttons.TCustomSpeedButton.Destroy">TCustomSpeedButton.Destroy</link>
</seealso>
</element>

<element name="TColorButton.Click">
<short>Performs actions needed when the control is clicked.</short>
<descr>
<p>
Click is an overridden method in TColorButton used to perform actions needed 
when the control is clicked or the Space key is pressed when the control has 
focus. It calls the inherited method on entry to execute the Action for the 
control, or signal its OnClick event handler (when assigned). It calls the 
ShowColorDialog method to configure, display, and execute the ColorDialog for 
the control. ButtonColor is updated to contain the new color selected when 
the dialog was executed.
</p>
</descr>
<seealso>
<link id="#lcl.buttons.TCustomSpeedButton.Click">TCustomSpeedButton.Click</link>
<link id="#lcl.controls.TControl.Click">TControl.Click</link>
</seealso>
</element>

<element name="TColorButton.Action" link="#lcl.controls.TControl.Action"/>
<element name="TColorButton.Align" link="#lcl.controls.TControl.Align"/>
<element name="TColorButton.Anchors" link="#lcl.controls.TControl.Anchors"/>
<element name="TColorButton.AllowAllUp" link="#lcl.buttons.TCustomSpeedButton.AllowAllUp"/>
<element name="TColorButton.BorderSpacing" link="#lcl.controls.TControl.BorderSpacing"/>

<element name="TColorButton.BorderWidth">
<short>Width for the borders on the button control.</short>
<descr/>
<seealso/>
</element>

<element name="TColorButton.ButtonColorAutoSize">
<short>
<b>True</b> if the color block for the button can be automatically resized to 
fill the unused client area.
</short>
<descr>
<p>
<var>ButtonColorAutoSize</var> is a <var>Boolean</var> property which 
indicates if the color block for the button can be automatically resized to 
fill the unused client area in the button control.
</p>
<p>
When set to <b>True</b>, the client area is examined to determine the 
dimensions for the color block. Space is reserved using the Caption, 
BorderWidth, Spacing, and Margin properties defined for the control. The 
unused area in the client rectangle is drawn using a frame filled with the 
selected ButtonColor for the control.
</p>
<p>
When set to <b>False</b>, the value in ButtonColorSize is used as both the 
height and width for the color block or swatch.
</p>
<p>
The default value for the property is <b>True</b> as assigned in the 
constructor for the class instance. Setting a new value for the property 
causes the control to be redrawn. When ButtonColorAutoSize is <b>True</b>, 
setting a new value for BorderWidth also causes the control to be redrawn.
</p>
<p>
ButtonColorAutoSize and ButtonColorSize are used in the GetGlyphSize method.
</p>
</descr>
<seealso>
<link id="TColorButton.Create"/>
<link id="TColorButton.GetGlyphSize"/>
<link id="TColorButton.ButtonColorSize"/>
<link id="TColorButton.BorderWidth"/>
<link id="TCustomSpeedButton.GetTextSize"/>
<link id="TCustomSpeedButton.Spacing"/>
<link id="TCustomSpeedButton.Layout"/>
<link id="TCustomSpeedButton.Margin"/>
<link id="#lcl.controls.TControl.Caption">TControl.Caption</link>
</seealso>
</element>

<element name="TColorButton.ButtonColorSize">
<short>
Size of the color block (or swatch) on the button control.
</short>
<descr>
<p>
<var>ButtonColorSize</var> is an <var>Integer</var> property with the size 
for the color block (or swatch) displayed on the control. The default value 
for the property is 16 (pixels) as assigned in the constructor for the class 
instance. Its value is used in the <var>GetGlyphSize</var> method when 
<var>ButtonColorAutoSize</var> is set to <b>False</b>, and represents both 
the width and height returned for the button glyph.
</p>
<p>
Changing the value for the property causes the control to be redrawn.
</p>
</descr>
<seealso>
<link id="TColorButton.ButtonColorAutoSize"/>
<link id="TColorButton.GetGlyphSize"/>
<link id="TColorButton.Create"/>
</seealso>
</element>

<element name="TColorButton.ButtonColor">
<short>
The TColor value selected in the button control.
</short>
<descr>
<p>
ButtonColor is a TColor property which contains the selected color for the 
button control.
</p>
<p>
The value in ButtonColor is used as the initial selected color value when the 
ColorDialog is displayed in the ShowColorDialog method. It is updated with 
the newly selected color value when the ColorDialog is executed.
</p>
<p>
Setting a new value for the property causes the OnColorChanged event handler 
to be signalled (when assigned) and the control is redrawn.
</p>
<p>
Use Color to set the color used for the button face on the control.
</p>
</descr>
<seealso>
<link id="TColorButton.ColorDialog"/>
<link id="TColorButton.ShowColorDialog"/>
<link id="TColorButton.OnColorChanged"/>
<link id="TColorButton.Click"/>
<link id="#lcl.graphics.TColor">TColor</link>
</seealso>
</element>

<element name="TColorButton.ColorDialog">
<short>
The color selection dialog displayed when the control is clicked, or the 
ShowColorDialog method is called.
</short>
<descr>
<p>
ColorDialog is a TColorDialog property which contains the color selection 
dialog displayed for the button control. ColorDialog is used in the 
ShowColorDialog method. A TColorDialog instance is created if one has not 
already been assigned to the property. It is freed (when created) when the 
color selection dialog is closed. A TColorDialog instance not created by the 
button control is not freed prior to exiting from the method or destroying 
the control.
</p>
<p>
The value in ButtonColor is assigned as the initial color selection for the 
dialog, and the Execute method in the dialog is called to capture the newly 
selected color value (when available). The new color selection is stored in 
the ButtonColor property.
</p>
</descr>
<seealso>
<link id="TColorButton.ShowColorDialog"/>
<link id="TColorButton.Click"/>
<link id="TColorButton.ButtonColor"/>
<link id="TColorDialog"/>
</seealso>
</element>

<element name="TColorButton.Constraints" link="#lcl.controls.TControl.Constraints"/>

<element name="TColorButton.Caption">
<short>Text displayed next to the color block on the button control.</short>
<descr>
<p>
Caption is a String property with the text displayed beside the color block 
(or swatch) on the button control. When it has been assigned a non-empty 
value, space is reserved on the client area for the text plus the number of 
pixels in Spacing. When empty, no space is reserved for the text or the space 
between the text and the color block.
</p>
<p>
In general, Caption can be used to provide a human-readable value for the 
selected color in ButtonColor. The value in Caption is not, however, 
automatically linked to the selected color value. Use the OnColorChanged 
event handler to update the value in Caption as needed when the color 
selection has been changed.
</p>
<p>
The Layout property determines the order of the Caption and color block 
values on the button surface. Layout refers to the alignment for the glyph 
(color block).
</p>
<p>
Set ButtonColorAutoSize to <b>True</b> to allow the color block to fill the 
unused client area for the control. Use ButtonColorSize to set the dimensions 
for the color block when ButtonColorAutoSize is <b>False</b>.
</p>
</descr>
<seealso>
<link id="TColorButton.ButtonColorAutoSize"/>
<link id="TColorButton.ButtonColorSize"/>
<link id="TColorButton.OnColorChanged"/>
<link id="TCustomSpeedButton.Spacing"/>
<link id="TCustomSpeedButton.Layout"/>
</seealso>
</element>

<element name="TColorButton.Color">
<short>
The <var>Color</var> of the control itself, i.e. the parts that are not the 
color display block; edges, background etc.
</short>
<descr/>
<seealso>
<link id="#lcl.buttons.TCustomSpeedButton.Color">TCustomSpeedButton.Color</link>
</seealso>
</element>

<element name="TColorButton.Down" link="#lcl.buttons.TCustomSpeedButton.Down"/>
<element name="TColorButton.Enabled" link="#lcl.controls.TControl.Enabled"/>
<element name="TColorButton.Flat" link="#lcl.buttons.TCustomSpeedButton.Flat"/>
<element name="TColorButton.Font" link="#lcl.controls.TControl.Font"/>
<element name="TColorButton.Hint" link="#lcl.controls.TControl.Hint"/>
<element name="TColorButton.Layout" link="#lcl.buttons.TCustomSpeedButton.Layout"/>
<element name="TColorButton.Margin" link="#lcl.buttons.TCustomSpeedButton.Margin"/>
<element name="TColorButton.Spacing" link="#lcl.buttons.TCustomSpeedButton.Spacing"/>
<element name="TColorButton.Transparent" link="#lcl.buttons.TCustomSpeedButton.Transparent"/>
<element name="TColorButton.Visible" link="#lcl.controls.TControl.Visible"/>
<element name="TColorButton.OnClick" link="#lcl.controls.TControl.OnClick"/>

<element name="TColorButton.OnColorChanged">
<short>
Event handler signalled when the button color has been changed.
</short>
<descr>
<p>
<var>OnColorChanged</var> is a <var>TNotifyEvent</var> property with the 
event handler signalled when the selected color in ButtonColor has been 
changed. An application must implement and assign an object procedure to the 
property to respond to the event notification.
</p>
<p>
OnColorChanged is signalled (when assigned) when a new TColor value is 
assigned to the ButtonColor property. A common use for the event handler is 
to update the value in Caption when the value in ButtonColor has been 
updated. OnColorchanged is not signalled during LCL component streaming 
(csLoading in ComponentState).
</p>
</descr>
<seealso>
<link id="TColorButton.ButtonColor"/>
<link id="TColorButton.Caption"/>
<link id="#rtl.classes.TNotifyEvent">TNotifyEvent</link>
</seealso>
</element>

<element name="TColorButton.OnDblClick" link="#lcl.controls.TControl.OnDblClick"/>
<element name="TColorButton.OnMouseDown" link="#lcl.controls.TControl.OnMouseDown"/>
<element name="TColorButton.OnMouseEnter" link="#lcl.controls.TControl.OnMouseEnter"/>
<element name="TColorButton.OnMouseLeave" link="#lcl.controls.TControl.OnMouseLeave"/>
<element name="TColorButton.OnMouseMove" link="#lcl.controls.TControl.OnMouseMove"/>
<element name="TColorButton.OnMouseUp" link="#lcl.controls.TControl.OnMouseUp"/>
<element name="TColorButton.OnMouseUp" link="#lcl.controls.TControl.OnMouseUp"/>
<element name="TColorButton.OnMouseWheel" link="#lcl.controls.TControl.OnMouseWheel"/>
<element name="TColorButton.OnMouseWheelDown" link="#lcl.controls.TControl.OnMouseWheelDown"/>
<element name="TColorButton.OnMouseWheelUp" link="#lcl.controls.TControl.OnMouseWheelUp"/>
<element name="TColorButton.OnPaint" link="#lcl.controls.TGraphicControl.OnPaint"/>
<element name="TColorButton.OnResize" link="#lcl.controls.TControl.OnResize"/>
<element name="TColorButton.OnChangeBounds" link="#lcl.controls.TControl.OnChangeBounds"/>
<element name="TColorButton.ShowHint" link="#lcl.controls.TControl.ShowHint"/>
<element name="TColorButton.ParentFont" link="#lcl.controls.TControl.ParentFont"/>
<element name="TColorButton.ParentShowHint" link="#lcl.controls.TControl.ParentShowHint"/>
<element name="TColorButton.PopupMenu" link="#lcl.controls.TControl.PopupMenu"/>

<element name="TFontDialogOption">
<short>
An enumerated list of constants to set the options of a Font dialog.
</short>
<descr/>
<seealso/>
</element>
<element name="TFontDialogOption.fdAnsiOnly">
<short>
Limits the font name selection list to font using ANSI character sets.
</short>
</element>
<element name="TFontDialogOption.fdTrueTypeOnly">
<short>Limits the font name selection list to TrueType fonts.</short>
</element>
<element name="TFontDialogOption.fdEffects">
<short>
Displays check boxes for strike-through, underline, et. al. font effects in 
the dialog.
</short>
</element>
<element name="TFontDialogOption.fdFixedPitchOnly">
<short>
Limits the font name selection list to fixed-pitch (mono-spaced) fonts.
</short>
</element>
<element name="TFontDialogOption.fdForceFontExist">
<short>
Raises an error if a font or style is (some how) selected that does not exist 
in the font dialog.
</short>
</element>
<element name="TFontDialogOption.fdNoFaceSel">
<short>Hides the font name selection list in the dialog.</short>
</element>
<element name="TFontDialogOption.fdNoOEMFonts">
<short>Excludes OEM fonts from the font selection list.</short>
</element>
<element name="TFontDialogOption.fdNoSimulations">
<short>Excludes bitmapped fonts that emulate sizes by scaling.</short>
</element>
<element name="TFontDialogOption.fdNoSizeSel">
<short>Hides the Size selection list in the dialog.</short>
</element>
<element name="TFontDialogOption.fdNoStyleSel">
<short>Hides the style selection list in the dialog.</short>
</element>
<element name="TFontDialogOption.fdNoVectorFonts">
<short>Excludes vector fonts from the list of font names.</short>
</element>
<element name="TFontDialogOption.fdShowHelp">
<short>Makes the Help button visible in the dialog.</short>
</element>
<element name="TFontDialogOption.fdWysiwyg">
<short>Displays font names using a WYSIWYG preview.</short>
</element>
<element name="TFontDialogOption.fdLimitSize">
<short>
Restricts font sizes to the range in MinFontSize and MaxFontSize.
</short>
</element>
<element name="TFontDialogOption.fdScalableOnly">
<short>
Limits the font selection list to scalable fonts; no bitmapped fonts.
</short>
</element>
<element name="TFontDialogOption.fdApplyButton">
<short>Makes the Apply button visible in the dialog.</short>
</element>

<element name="TFontDialogOptions">
<short>Set type used to store font dialog options.</short>
<descr/>
<seealso/>
</element>

<element name="TFontDialog">
<short>Dialog used to select a font typeface and size.</short>
<descr>
<p>
<var>TFontDialog</var> is a <var>TCommonDialog</var> descendant which 
implements a font selection dialog.
</p>
<p>
TFontDialog displays selection lists for font name, size, style, and color. 
It can be configured to limit the available typefaces, sizes, and visual 
presentations using the Options, MinFontSize and MaxFontSize properties.
</p>
<p>
At run-time, TFontDialog is mapped to the native font selection dialog used 
for a given platform. Use Options to enable or disable features or behaviors 
in the dialog. Enabling an option does not mean that it is automatically 
available. Some options may not be supported in the native dialog for a given 
platform.
</p>
<p>
When the dialog is executed, the selected font and its attributes is made 
available in the Font property. The OnApplyClicked event handler can be used 
to perform actions needed when the optional Apply button is clicked in the 
dialog. Please note that the Apply button is available on the GTK2, GTK3, and 
Windows platforms. It is not currently implemented for QT platforms.
</p>
</descr>
<seealso>
<link id="TFontDialog.Font"/>
<link id="TFontDialog.Options"/>
<link id="TFontDialog.OnApplyClicked"/>
<link id="TCommonDialog"/>
<link id="TFontDialogOptions"/>
<link id="TFontDialogOption"/>
</seealso>
</element>

<element name="TFontDialog.FFont"/>
<element name="TFontDialog.FMaxFontSize"/>
<element name="TFontDialog.FMinFontSize"/>
<element name="TFontDialog.FOnApplyClicked"/>
<element name="TFontDialog.FOptions"/>
<element name="TFontDialog.FPreviewText"/>

<element name="TFontDialog.SetFont">
<short>Sets the value for the Font property.</short>
<descr/>
<seealso>
<link id="TFontDialog.Font"/>
</seealso>
</element>
<element name="TFontDialog.SetFont.AValue">
<short>New value for the property.</short>
</element>

<element name="TFontDialog.WSRegisterClass" link="#lcl.lclclasses.TLCLComponent.WSRegisterClass"/>
<element name="TFontDialog.DefaultTitle" link="#lcl.dialogs.TCommonDialog.DefaultTitle"/>

<element name="TFontDialog.ApplyClicked">
<short>
Performs actions needed when a font is selected using the dialog.
</short>
<descr>
<p>
<var>ApplyClicked</var> is a used to perform actions needed when a font is 
applied using the Apply button in the dialog. The Apply button is made 
visible by a setting in Options, and must be enabled; the default buttons are 
Ok and Cancel.
</p>
<p>
ApplyClicked signals the OnApplyClicked event handler (when assigned).
</p>
<remark>
Widgetset classes in the current LCL implementaion do not call ApplyClicked; 
they signal the OnApplyClicked event handler directly.
</remark>
</descr>
<seealso>
<link id="TFontDialog.OnApplyClicked"/>
<link id="TFontDialog.Options"/>
</seealso>
</element>

<element name="TFontDialog.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the overridden constructor for the class instance, and 
calls the inherited constructor on entry. Create allocates resources needed 
for the <var>Font</var> property, and sets the default values in the 
<var>Options</var> property.
</p>
</descr>
<seealso>
<link id="TFontDialog.Font"/>
<link id="TFontDialog.Options"/>
</seealso>
</element>
<element name="TFontDialog.Create.AOwner">
<short>Owner of the class instance.</short>
</element>

<element name="TFontDialog.Destroy">
<short>Destructor for the class instance.</short>
<descr/>
<seealso/>
</element>

<element name="TFontDialog.Title" link="#lcl.dialogs.TCommonDialog.Title"/>

<element name="TFontDialog.Font">
<short>Contains the Font selected in the dialog.</short>
<descr>
<p>
<var>Font</var> is a <var>TFont</var> property with the font selected using 
the dialog. The value in Font is updated in widgetset classes when the 
<b>OK</b> or <b>Apply</b> button is clicked during execution of the dialog. 
It includes any attributes applied to font in the native font selection 
dialog for the platform.
</p>
<p>
Use the <var>OnApplyClicked</var> event handler to perform actions needed 
when the <b>Apply</b> button is enabled and clicked in the dialog.
</p>
</descr>
<seealso>
<link id="TFontDialog.Options"/>
<link id="TFontDialog.OnApplyClicked"/>
<link id="TFontDialog.ApplyClicked"/>
<link id="#lcl.graphics.TFont">TFont</link>
</seealso>
</element>

<element name="TFontDialog.MinFontSize">
<short>Minimum font size allowed in the font selection dialog.</short>
<descr>
<p>
<var>MinFontSize</var> is an Integer property which contains the minimum font 
size allowed in the font selection dialog. Limiting font size selection to 
the range in <var>MinFontSize</var> and <var>MaxFontSize</var> must be 
enabled by including <var>fdLimitSize</var> in the <var>Options</var> 
property.
</p>
</descr>
<seealso>
<link id="TFontDialog.MaxFontSize"/>
<link id="TFontDialog.Options"/>
<link id="TFontDialogOption"/>
</seealso>
</element>

<element name="TFontDialog.MaxFontSize">
<short>Maximum font size allowed in the font selection dialog.</short>
<descr>
<p>
<var>MaxFontSize</var> is an Integer property which contains the maximum font 
size allowed in the font selection dialog. Limiting font size selection to 
the range in <var>MinFontSize</var> and <var>MaxFontSize</var> must be 
enabled by including <var>fdLimitSize</var> in the <var>Options</var> 
property.
</p>
</descr>
<seealso>
<link id="TFontDialog.MinFontSize"/>
<link id="TFontDialog.Options"/>
<link id="TFontDialogOption"/>
</seealso>
</element>

<element name="TFontDialog.Options">
<short>A set of TFontDialogOption options enabled for the dialog.</short>
<descr>
<p>
<var>Options</var> is a <var>TFontDialogOptions</var> property which controls 
the options enabled for the font selection dialog. Options contains zero or 
more values from the <var>TFontDialogOption</var> enumeration. The default 
value for the property is <var>[fdEffects]</var>, and enables the font 
effects check boxes in the dialog.
</p>
<p>
See <link id="TFontDialogOption">TFontDialogOption</link> for more 
information about the values in the enumeration and their usage.
</p>
<p>
Include or Exclude values for the property prior to calling the 
<var>Execute</var> method.
</p>
<remark>
Enabling a value in Options does not mean that the feature or behavior is 
supported in the native font selection dialog for a platform. Some options 
may not be available on a given platform. For example, the Apply button 
enabled using fdApplyButton is not implemented for all of the LCL platforms. 
It is not currently implemented in the QT widgetsets.
</remark>
</descr>
<seealso>
<link id="TFontDialogOptions"/>
<link id="TFontDialogOption"/>
<link id="TCommonDialog.Execute"/>
</seealso>
</element>

<element name="TFontDialog.OnApplyClicked">
<short>
Event handler signalled when the Apply button is clicked in the font dialogs.
</short>
<descr>
<p>
<var>OnApplyClicked</var> is a <var>TNotifyEvent</var> property with the 
event handler signalled when the Apply button is clicked in the font dialog. 
The Apply button must be enabled in the Options property to receive the event 
notification.
</p>
<p>
OnApplyClicked allows the application to perform actions needed when a Font 
has been applied. This can include assigning the value in Font to another 
control. Similar actions need to be performed when the Execute method returns 
<b>True</b>, indicating that the OK button was clicked.
</p>
<p>
OnApplyClicked is signalled from the ApplyClicked method, and triggered 
directly from methods in widgetset classes.
</p>
</descr>
<seealso>
<link id="TFontDialog.ApplyClicked"/>
<link id="TFontDialog.Options"/>
<link id="TFontDialog.Font"/>
<link id="TCommonDialog.Execute"/>
<link id="TFontDialogOption"/>
<link id="TFontDialogOptions"/>
</seealso>
</element>

<element name="TFontDialog.PreviewText">
<short>
A text snippet displayed as a preview for the selected font in the dialog.
</short>
<descr>
<p>
<var>PreviewText</var> is a <var>String</var> property with a short snippet 
of text to display using the currently selected font in the dialog. It acts 
as a WYSIWYG preview mechanism.
</p>
<p>
Please note that use of PreviewText is dependent on platform / widgetset 
support. For instance, Windows does render PreviewText. It uses its own 
"Sample", and renders the font name in the selection list using the typeface. 
QT and QT5 have the same behavior as Windows. It is implemented for the GTK, 
GTK2 and MUI widgetsets.
</p>
</descr>
<seealso/>
</element>

<element name="TFindOption">
<short>A list of possible options which can be used in Find dialogs.</short>
<descr>
<p>
<var>TFindOption</var> is an enumerated type with values representing options 
that can enabled in TFindDialog and descendants. Values from TFindOption are 
stored in the <var>TFindOptions</var> set type, and used to implement the 
<var>TFindDialog.Options</var> property.
</p>
</descr>
<seealso>
<link id="TFindOptions"/>
<link id="TFindDialog.Options"/>
</seealso>
</element>
<element name="TFindOption.frDown">
<short>If set the "Down" radio button is selected.</short>
</element>
<element name="TFindOption.frFindNext">
<short>This option will be set when the user presses "Find Next"</short>
</element>
<element name="TFindOption.frHideMatchCase">
<short>
If set the "Match case" check box is hidden on the Find dialog.
</short>
</element>
<element name="TFindOption.frHideWholeWord">
<short>
If set the "Whole word" check box is hidden on the Find dialog.
</short>
</element>
<element name="TFindOption.frHideUpDown">
<short>
If set the "Up" and "Down" radio buttons are hidden from the Find dialog.
</short>
</element>
<element name="TFindOption.frMatchCase">
<short>
This flag is set when the user checks the "Match case" checkbox.
</short>
</element>
<element name="TFindOption.frDisableMatchCase">
<short>
If set the "Match case" check box is disabled on the Find dialog.
</short>
</element>
<element name="TFindOption.frDisableUpDown">
<short>
If set the "Up" and "Down" radio buttons are disabled in the Find dialog.
</short>
</element>
<element name="TFindOption.frDisableWholeWord">
<short>
If set the "Whole word" check box is disabled on the Find dialog.
</short>
</element>
<element name="TFindOption.frReplace">
<short>
This flag is set if only the first occurrence of the search string is to be 
replaced with the replace string.
</short>
</element>
<element name="TFindOption.frReplaceAll">
<short>
This flag is set if all occurrences of the search string are to be replaced 
with the replace string.
</short>
</element>
<element name="TFindOption.frWholeWord">
<short>
This flag is set when the user checks the "Whole word" checkbox.
</short>
</element>
<element name="TFindOption.frShowHelp">
<short>If set the dialog will display a help button.</short>
</element>
<element name="TFindOption.frPromptOnReplace">
<short>
This flag is set when the user checks the "Prompt on replace" checkbox.
</short>
</element>
<element name="TFindOption.frHidePromptOnReplace">
<short>
If set the "Prompt on replace" check box is hidden on the Find dialog.
</short>
</element>

<element name="TFindOptions">
<short>Set type used to store TFindOption enumeration values.</short>
<descr>
<p>
<var>TFindOptions</var> is a set type used to store zero (0) or more values 
from the <var>TFindOption</var> enumeration type. Adding an enumeration value 
to the set indicates that the option is enabled.
</p>
<p>
TFindOptions is the type used to implement the TFindDialog.Options property.
</p>
</descr>
<seealso>
<link id="TFindOption"/>
<link id="TFindDialog.Options"/>
</seealso>
</element>

<element name="TFindDialog">
<short>
<var>TFindDialog</var> - a dialog used for finding text within the current 
editor or text buffer.
</short>
<descr>
<p>
Opens a dialog box allowing the user to enter text for searching, for example 
in a text editor.
</p>
<p>
As TFindDialog is the parent class for the TReplaceDialog, it contains 
definitions for the Replace method, but the Replace option does not actually 
appear when the dialog is displayed: you need to use TReplaceDialog to do 
that.
</p>
</descr>
<seealso>
<link id="TReplaceDialog"/>
</seealso>
</element>

<!-- private -->
<element name="TFindDialog.FFormLeft"/>
<element name="TFindDialog.FFormTop"/>
<element name="TFindDialog.GetReplaceText"/>
<element name="TFindDialog.GetReplaceText.Result"/>
<element name="TFindDialog.GetFindText"/>
<element name="TFindDialog.GetFindText.Result"/>
<element name="TFindDialog.GetLeft"/>
<element name="TFindDialog.GetLeft.Result"/>
<element name="TFindDialog.GetPosition"/>
<element name="TFindDialog.GetPosition.Result"/>
<element name="TFindDialog.GetTop"/>
<element name="TFindDialog.GetTop.Result"/>
<element name="TFindDialog.SetFindText"/>
<element name="TFindDialog.SetFindText.AValue"/>
<element name="TFindDialog.SetLeft"/>
<element name="TFindDialog.SetLeft.AValue"/>
<element name="TFindDialog.SetPosition"/>
<element name="TFindDialog.SetPosition.AValue"/>
<element name="TFindDialog.SetTop"/>
<element name="TFindDialog.SetTop.AValue"/>
<element name="TFindDialog.SetReplaceText"/>
<element name="TFindDialog.SetReplaceText.AValue"/>

<element name="TFindDialog.FFindForm">
<short>
<var>FFindForm</var> - local variable holding the form used for the Find 
dialog.
</short>
<descr/>
<seealso/>
</element>

<element name="TFindDialog.FOnReplace">
<short>
<var>FOnReplace</var> - local variable identifying the event handler for 
replacing.
</short>
<descr/>
<seealso/>
</element>

<element name="TFindDialog.FOnFind">
<short>
<var>FOnFind</var> - local variable identifying the event handler for finding.
</short>
<descr/>
<seealso/>
</element>

<element name="TFindDialog.FOptions">
<short>
<var>FOptions</var> - local variable holding the set of current options.
</short>
<descr/>
<seealso/>
</element>

<element name="TFindDialog.FOnHelpClicked">
<short>
<var>FOnHelpClicked</var> - local variable identifying the help event handler.
</short>
<descr/>
<seealso/>
</element>

<element name="TFindDialog.FReplaceText">
<short>
<var>FReplaceText</var> - local variable holding the Replace text.
</short>
<descr/>
<seealso/>
</element>

<element name="TFindDialog.FFindText">
<short>
<var>FFindText</var> - local variable containing the text to be found.
</short>
<descr/>
<seealso/>
</element>

<element name="TFindDialog.DefaultTitle">
<short>
Returns the default title displayed on the dialog.
</short>
<descr>
<p>
<var>DefaultTitle</var> is an overridden String function in 
<var>TFindDialog</var>. It reimplements the method to return the value in the 
<var>rsFind</var> constant as the default caption or title for the dialog. 
The return value is assigned to the Title property in the inherited 
constructor for the class instance.
</p>
</descr>
<seealso>
<link id="TCommonDialog.Title"/>
<link id="TCommonDialog.Create"/>
<link id="#lcl.lclstrconsts.rsFind">rsFind</link>
</seealso>
</element>
<element name="TFindDialog.DefaultTitle.Result">
<short>
Default title for the find dialog.
</short>
</element>

<element name="TFindDialog.FindClick">
<short>
Implements the OnClick event handler for the Find button on the dialog.
</short>
<descr>
<p>
<var>FindClick</var> is a method which implements the event handler signalled 
when the Find button on the dialog form is clicked.
</p>
<p>
FindClick calls GetFormValues to update Options from the settings on the 
internal form instance for the dialog. It also ensures that Options contains 
only find-related enumeration values, and not those intended for a replace 
dialog.
</p>
<p>
FindClick calls Find to signal the OnFind event handler (when assigned).
</p>
<p>
The method is assigned to the OnClick event handler for the Find button in 
the CreateForm method.
</p>
</descr>
<seealso>
<link id="TFindDialog.GetFormValues"/>
<link id="TFindDialog.Options"/>
<link id="TFindDialog.Find"/>
<link id="TFindDialog.OnFind"/>
<link id="TFindDialog.CreateForm"/>
<link id="TFindOption"/>
<link id="#lcl.stdctrls.TButton.OnClick">TButton.OnClick</link>
</seealso>
</element>
<element name="TFindDialog.FindClick.Sender">
<short>Object (TFindDialog) for the event notification.</short>
</element>

<element name="TFindDialog.HelpClick">
<short>
Implements the OnClick event handler for the Help button on the dialog.
</short>
<descr>
<p>
<var>HelpClick</var> is a method which implements the event handler signalled 
when the Help button on the dialog form is clicked.
</p>
<p>
HelpClick calls the Help method to signal the OnHelpClicked event handler 
(when assigned).
</p>
<p>
The method is assigned to the OnClick event handler for the Help button in 
the CreateForm method.
</p>
</descr>
<seealso>
<link id="TFindDialog.Help"/>
<link id="TFindDialog.OnHelpClicked"/>
<link id="TFindDialog.CreateForm"/>
<link id="#lcl.stdctrls.TButton.OnClick">TButton.OnClick</link>
</seealso>
</element>
<element name="TFindDialog.HelpClick.Sender">
<short>Object (TFindDialog) for the event notification.</short>
</element>

<element name="TFindDialog.CancelClick">
<short>
Implements the OnClick event handler for the Cancel button on the dialog.
</short>
<descr>
<p>
<var>CancelClick</var> is a method which implements the event handler 
signalled when the Cancel button on the dialog form is clicked.
</p>
<p>
CancelClick calls the CloseDialog method to close the internal form instance 
for the dialog (when assigned).
</p>
<p>
The method is assigned to the OnClick event handler for the Cancel button in 
the CreateForm method.
</p>
</descr>
<seealso>
<link id="TFindDialog.CloseDialog"/>
<link id="TFindDialog.DoCloseForm"/>
<link id="TFindDialog.CreateForm"/>
<link id="TCommonDialog.OnClose"/>
<link id="TCommonDialog.OnCanClose"/>
<link id="#lcl.stdctrls.TButton.OnClick">TButton.OnClick</link>
</seealso>
</element>
<element name="TFindDialog.CancelClick.Sender">
<short>Object (TFindDialog) for the event notification.</short>
</element>

<element name="TFindDialog.GetHeight">
<short>
Get the value for the Height property.
</short>
<descr>
<p>
<var>GetHeight</var> is an overridden method in <var>TFindDialog</var>. It 
checks whether the internal TForm instance has been assigned for the dialog, 
and returns the form height when it is available. Otherwise, the inherited 
method is called to get the value in the Height member.
</p>
</descr>
<seealso>
<link id="TCommonDialog.Height"/>
<link id="#lcl.controls.TControl.Height">TControl.Height</link>
</seealso>
</element>
<element name="TFindDialog.GetHeight.Result">
<short>
Value for the Height property.
</short>
</element>

<element name="TFindDialog.GetWidth">
<short>
Gets the value for the Width property.
</short>
<descr>
<p>
<var>GetWidth</var> is an overridden method in <var>TFindDialog</var>. It 
checks whether the internal TForm instance has been assigned for the dialog, 
and returns the form width when it is available. Otherwise, the inherited 
method is called to get the value in the Width member.
</p>
</descr>
<seealso>
<link id="TCommonDialog.Width"/>
<link id="#lcl.controls.TControl.Width">TControl.Width</link>
</seealso>
</element>
<element name="TFindDialog.GetWidth.Result">
<short>
Value for the Width property.
</short>
</element>

<element name="TFindDialog.DoCloseForm">
<short>
Implements the OnClose event handler on the internal form displayed for the 
dialog.
</short>
<descr>
<p>
<var>DoCloseForm</var> is a method which implements the event handler 
signalled when the internal form instance for the dialog is closed. No 
actions are performed in the method at design-time (csDesigning is in 
ComponentState property).
</p>
<p>
DoCloseForm stores the Left and Top coordinates from the form to the 
corresponding properties in the class instance. The property values are 
assigned as default values when a new form instance is created in CreateForm.
</p>
<p>
DoCloseForm is assigned to the OnClose event handler for the internal TForm 
instance when the Execute method is called.
</p>
</descr>
<seealso>
<link id="TFindDialog.CloseDialog"/>
<link id="TFindDialog.Left"/>
<link id="TFindDialog.Top"/>
<link id="TFindDialog.Execute"/>
<link id="TCommonDialog.OnClose"/>
<link id="#lcl.forms.TCustomForm.Close">TCustomForm.Close</link>
<link id="#lcl.forms.TCustomForm.CloseQuery">TCustomForm.CloseQuery</link>
<link id="#lcl.forms.TForm.OnClose">TForm.OnClose</link>
</seealso>
</element>
<element name="TFindDialog.DoCloseForm.Sender">
<short>Object (TFindDialog) for the event notification.</short>
</element>
<element name="TFindDialog.DoCloseForm.CloseAction">
<short>
Not used in the current implementation.
</short>
</element>

<element name="TFindDialog.DoShowForm">
<short>
Implements the OnShow event handler on the internal form displayed for the 
dialog.
</short>
<descr>
<p>
<var>DoShowForm</var> is a method which implements the event handler 
signalled when the internal form instance for the dialog is displayed. No 
actions are performed in the method at design-time (csDesigning is in 
ComponentState property).
</p>
<p>
DoShowForm signals the OnShow event handler (when assigned) in TFindDialog to 
notify the dialog when the form calls its Show method.
</p>
<p>
DoShowForm is assigned to the OnShow event handler for the internal TForm 
instance when the Execute method is called.
</p>
</descr>
<seealso>
<link id="TFindDialog.Execute"/>
<link id="TCommonDialog.OnShow"/>
<link id="#lcl.forms.TForm.OnShow">TForm.OnShow</link>
<link id="#lcl.forms.TCustomForm.Show">TCustomForm.Show</link>
</seealso>
</element>
<element name="TFindDialog.DoShowForm.Sender">
<short>Object (TFindDialog) for the event notification.</short>
</element>

<element name="TFindDialog.Find">
<short>
Signals the OnFind event handler when the Find button is clicked on the 
dialog form.
</short>
<descr>
<p>
Find is called from the <var>FindClick</var> method, and occurs when the 
dialog is executed. An application must assign a TNotifyEvent routine to 
<var>OnFind</var> to perform the actions needed for the dialog. No actions 
are performed in the method if an event handler routine has not been assigned 
to OnFind.
</p>
</descr>
<seealso>
<link id="TFindDialog.Execute"/>
<link id="TFindDialog.FindClick"/>
<link id="TFindDialog.OnFind"/>
<link id="#rtl.classes.TNotifyEvent">TNotifyEvent</link>
</seealso>
</element>

<element name="TFindDialog.Help">
<short>
Signals the OnHelpClicked event handler when the Help button on the dialog 
form is clicked.
</short>
<descr>
<p>
<var>Help</var> is a method used to perform actions needed when the Help 
button on the dialog form is clicked. Help signals the 
<var>OnHelpClicked</var> event handler (when assigned) to perform the 
required actions. An application must assign a <var>TNotifyEvent</var> 
handler routine to OnHelpClicked. No actions are performed in the method when 
OnHelpClicked has not been assigned.
</p>
<p>
Help is called from the HelpClick method, and occurs when the dialog is 
Executed.
</p>
</descr>
<seealso>
<link id="TFindDialog.Execute"/>
<link id="TFindDialog.HelpClick"/>
<link id="TFindDialog.OnHelpClicked"/>
<link id="#rtl.classes.TNotifyEvent">TNotifyEvent</link>
</seealso>
</element>

<element name="TFindDialog.Replace">
<short>
Signals the OnReplace event handler when the Replace button is clicked on the 
dialog form.
</short>
<descr>
<p>
Replace is introduced in TFindDialog, but it is used in the implementation of 
the TReplaceDialog descendant.
</p>
</descr>
<seealso>
<link id="TFindDialog.OnReplace"/>
<link id="TFindDialog.ReplaceText"/>
<link id="TReplaceDialog.ReplaceText"/>
<link id="TReplaceDialog.OnReplace"/>
<link id="TReplaceDialog.ReplaceClick"/>
<link id="TReplaceDialog.ReplaceAllClick"/>
<link id="TReplaceDialog.CreateForm"/>
</seealso>
</element>

<element name="TFindDialog.CreateForm">
<short>
Creates and configures the internal form displayed for the dialog.
</short>
<descr>
<p>
<var>CreateForm</var> is a <var>TForm</var> function used to create the form 
displayed for the dialog. The form class is defined in the implementation 
section. It contains the controls needed for the edits, labels, buttons, 
radio buttons, and check boxes displayed for the dialog. It includes the 
controls needed to represent the TFindOption values in the Options property.
</p>
<p>
CreateForm ensures that translated/localized resource strings are assigned to 
the captions for the form controls. OnClick event handlers are assigned for 
the Find, Help, and Cancel buttons on the form. The initial Left and Top 
coordinate are also assigned to the form.
</p>
<p>
Use the OnFind, OnHelpClicked, OnShow, and OnClose event handlers to 
implement the specific actions performed when the dialog is executed.
</p>
<p>
CreateForm is called from the Execute method when the form instance has not 
already been assigned.
</p>
</descr>
<seealso/>
</element>
<element name="TFindDialog.CreateForm.Result">
<short>TForm instance created and configured for the dialog.</short>
</element>

<element name="TFindDialog.SetFormValues">
<short>
Stores property values in the class instance to the controls on the dialog 
form.
</short>
<descr>
<p>
<var>SetFormValues</var> copies values from the properties in the class 
instance to the controls displayed on the dialog form. This includes the 
values in <var>FindText</var> and <var>Options</var>.
</p>
<p>
Enumeration values in Options are examined and applied to the radio button or 
check box used to represent a specific value. The Help button on the dialog 
form is made visible when frShowHelp is included in Options. The Scope check 
box is made visible when frHideEntireScope is <b>not</b> present in Options.
</p>
<p>
SetFormValues ensures that the edit control for FindText is the active 
control on the form and its text content is selected.
</p>
<p>
SetFormValues is called from the Execute method, and occurs after the form 
instance has been created and positioned. It is called before the form is 
displayed and executed using its buttons.
</p>
<p>
See GetFormValues for the actions performed when the Find button is clicked 
on the dialog form.
</p>
</descr>
<seealso>
<link id="TFindDialog.FindText"/>
<link id="TFindDialog.Options"/>
<link id="TFindDialog.GetFormValues"/>
<link id="TFindOptions"/>
<link id="TFindOption"/>
</seealso>
</element>

<element name="TFindDialog.GetFormValues">
<short>
Retrieves values from the dialog form and stores them in the properties for 
the class instance.
</short>
<descr>
<p>
<var>GetFormValue</var> is used to update the dialog class instance with the 
values entered on the dialog form at run-time.
</p>
<p>
GetFormValue is called from the FindClick method which is used as the OnClick 
event handler for the Find button on the dialog form. It is called before the 
values in Options are sanitized and the Find method is called to perform the 
search.
</p>
<p>
See SetFormValues for the actions performed to load properties to the dialog 
form.
</p>
</descr>
<seealso>
<link id="TFindDialog.FindText"/>
<link id="TFindDialog.Options"/>
<link id="TFindDialog.Execute"/>
<link id="TFindDialog.FindClick"/>
<link id="TFindDialog.Find"/>
<link id="TFindDialog.OnFind"/>
<link id="TFindDialog.SetFormValues"/>
</seealso>
</element>

<element name="TFindDialog.CalcPosition">
<short>
Determines the position for the dialog form and captures its coordinates.
</short>
<descr>
<p>
<var>CalcPosition</var> ensures that both the form and the class instance are 
updated with the location where the form is displayed. The Position property 
in the form instance is updated to display the form in the correct relative 
location.
</p>
<p>
At design-time, the dialog form is aligned to the center of the Screen 
(poScreenCenter).
</p>
<p>
At run-time, the dialog form is aligned to the center of the main form in the 
application (poMainFormCenter) when the Left and Top coordinates in the 
dialog are set to their unassigned values. The Left and Top coordinates are 
stored in the class instance for subsequent use in the CreateForm method.
</p>
</descr>
<seealso>
<link id="TFindDialog.CreateForm"/>
<link id="TFindDialog.Left"/>
<link id="TFindDialog.Top"/>
<link id="#lcl.forms.TForm.Position">TForm.Position</link>
<link id="#lcl.controls.TControl.Left">TControl.Left</link>
<link id="#lcl.controls.TControl.Top">TControl.Top</link>
</seealso>
</element>
<element name="TFindDialog.CalcPosition.AForm">
<short>
TForm instance examined in the method.
</short>
</element>

<element name="TFindDialog.ReplaceText">
<short>
String with the value used to replace the value in FindText.
</short>
<descr>
<p>
<var>ReplaceText</var> is introduced in <var>TFindDialog</var>, but it is 
used in the implementation of the TReplaceDialog descendant.
</p>
</descr>
<seealso>
<link id="TFindDialog.FindText"/>
<link id="TFindDialog.OnReplace"/>
<link id="TReplaceDialog.ReplaceText"/>
<link id="TReplaceDialog.OnReplace"/>
</seealso>
</element>

<element name="TFindDialog.OnReplace">
<short>
Event handler signalled to replace occurrence(s) of FindText with the value 
in ReplaceText.
</short>
<descr>
<p>
An application must implement and assign a TNotifyEvent handler routine to 
OnReplace which responds to the event notification.
</p>
<p>
The <var>Sender</var> argument contains the object instance with the 
<var>TFindDialog</var> or descendant for the event notification. It can be 
cast to a <var>TFindDialog</var> or a <var>TReplaceDialog</var> type to 
access properties and methods in the dialog class, including: FindText, 
ReplaceText, and Options.
</p>
<p>
OnReplace is introduced in TFindDialog, but it is used in the implementation 
of the TReplaceDialog descendant. Use TReplaceDialog when the additional 
controls and buttons implemented in the replace dialog are needed.
</p>
</descr>
<seealso>
<link id="TFindDialog.FindText"/>
<link id="TFindDialog.ReplaceText"/>
<link id="TFindDialog.OnReplace"/>
<link id="TReplaceDialog.ReplaceText"/>
<link id="TReplaceDialog.OnReplace"/>
<link id="TReplaceDialog.CreateForm"/>
</seealso>
</element>

<element name="TFindDialog.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the constructor for <var>TFindDialog</var>, and calls 
the inherited <var>Create</var> method. It sets the initial value in Options 
to [frDown]. It also stores the unassigned value (-1) for both the Left and 
Top properties in the class instance.
</p>
</descr>
<seealso>
<link id="TFindDialog.Options"/>
<link id="TFindDialog.Left"/>
<link id="TFindDialog.Top"/>
<link id="TFindOptions"/>
<link id="TFindOption"/>
<link id="TCommonDialog.Create"/>
</seealso>
</element>
<element name="TFindDialog.Create.AOwner">
<short>Owner of the class instance.</short>
</element>

<element name="TFindDialog.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. It 
ensures that the internal <var>TForm</var> instance for the dialog form is 
freed (when assigned). Destroy calls the inherited destructor to perform and 
remove free notifications for the referenced counted component.
</p>
</descr>
<seealso/>
</element>

<element name="TFindDialog.CloseDialog">
<short>
Closes the dialog form when its Cancel button is clicked.
</short>
<descr>
<p>
CloseDialog is called from the CancelClick method (the OnClick handler for 
the Cancel button on the dialog form). CloseDialog ensures that the internal 
TForm instance for the dialog class has been assigned, and calls its Close 
method. This initiates a series of method calls and event handler 
notifications needed to close the form.
</p>
<pre>
TCustomForm.Close ->
  TCustomForm.OnClose ->
    TFindDialog.DoCloseForm ->
      TCommonDialog.OnClose
</pre>
</descr>
<seealso>
<link id="TFindDialog.CancelClick"/>
<link id="TFindDialog.DoCloseForm"/>
<link id="TFindDialog.CreateForm"/>
<link id="TFindDialog.Execute"/>
<link id="TCommonDialog.OnClose"/>
<link id="TCommonDialog.OnCanClose"/>
<link id="#lcl.forms.TCustomForm.Close">TCustomForm.Close</link>
<link id="#lcl.forms.TCustomForm.OnClose">TCustomForm.OnClose</link>
</seealso>
</element>

<element name="TFindDialog.Execute">
<short>
Displays the dialog form and responds to button clicks.
</short>
<descr>
<p>
<var>Execute</var> is an overridden <var>Boolean</var> function used to 
display the internal dialog form and respond to button clicks on the form. 
Execute reimplements the method defined in the ancestor class, and does 
<b>not</b> call the inherited method.
</p>
<p>
If a TForm instance already exists in the dialog class, it is reused. If not, 
CreateForm is called to create and configure the TForm instance displayed for 
the dialog. The return value is <b>False</b> if a TForm instance was not 
successfully created in CreateForm.
</p>
<p>
When a valid form exists for the dialog, it is positioned on the screen by 
calling CalcPosition. SetFormValues is called to transfer property values in 
the class instance to the dialog form. The Title, HelpContext, OnClose and 
OnShow properties in the form are updated and its Show method is called to 
display and execute the form. Values from the Height and Width properties in 
the form are stored in the dialog class for use as the default size.
</p>
<p>
The return value is <b>True</b> if the form was successfully configured and 
displayed in the method.
</p>
<p>
Use the OnFind, OnHelpClicked event handlers to perform actions needed when 
either the Find or the Help button on the dialog form is clicked. The Cancel 
button calls CloseDialog when the button is clicked.
</p>
</descr>
<seealso>
<link id="TFindDialog.CreateForm"/>
<link id="TFindDialog.CalcPosition"/>
<link id="TFindDialog.SetFormValues"/>
<link id="TFindDialog.OnFind"/>
<link id="TFindDialog.OnHelpClicked"/>
<link id="TFindDialog.CloseDialog"/>
<link id="TFindDialog.Left"/>
<link id="TFindDialog.Top"/>
<link id="TCommonDialog.Title"/>
<link id="TCommonDialog.HelpContext"/>
<link id="TCommonDialog.OnClose"/>
<link id="TCommonDialog.OnShow"/>
<link id="TCommonDialog.Height"/>
<link id="TCommonDialog.Width"/>
<link id="#lcl.dialogs.TCommonDialog.Execute">TCommonDialog.Execute</link>
</seealso>
</element>
<element name="TFindDialog.Execute.Result">
<short>
<b>True</b> if the dialog was successfully configured and displayed in the 
method.
</short>
</element>

<element name="TFindDialog.Left">
<short>Coordinate for the <var>Left</var> side of the dialog form.</short>
<descr>
<p>
<var>Left</var> is an <var>Integer</var> property which contains the 
horizontal coordinate where the left edge of the dialog form is located. The 
default value for the property is -1 and represents the unassigned value.
</p>
<p>
The property value is read from the Left property in the internal TForm 
instance for the dialog (when assigned). Changing the value in the property 
causes the Left property in the dialog form to be updated with the new 
coordinate value. The value for the property is updated in the CalcPosition 
method when the dialog is executed.
</p>
<p>
Left and Top are used in the CreateForm method to set the default coordinates 
for the dialog form.
</p>
</descr>
<seealso>
<link id="TFindDialog.Top"/>
<link id="TFindDialog.CalcPosition"/>
<link id="TFindDialog.Execute"/>
<link id="TFindDialog.CreateForm"/>
</seealso>
</element>

<element name="TFindDialog.Position">
<short>The position for the dialog form.</short>
<descr>
<p>
<var>Position</var> is a <var>TPoint</var> property with the coordinates 
where the dialog is displayed. The X and Y members in the TPoint instance 
contain the values from the Left and Top properties (respectively). Changing 
the value for the property causes the Left and Top properties to be updated 
with the new member values.
</p>
</descr>
<seealso>
<link id="TFindDialog.Left"/>
<link id="TFindDialog.Top"/>
<link id="#rtl.classes.TPoint">TPoint</link>
</seealso>
</element>

<element name="TFindDialog.Top">
<short>Coordinate for the <var>Top</var> edge of the dialog form.</short>
<descr>
<p>
<var>Top</var> is an <var>Integer</var> property which contains the vertical 
coordinate where the top edge of the dialog form is located. The default 
value for the property is -1 and represents the unassigned value.
</p>
<p>
The property value is read from the Top property in the internal TForm 
instance for the dialog (when assigned). Changing the value in the property 
causes the Top property in the dialog form to be updated with the new 
coordinate value. The value for the property is updated in the CalcPosition 
method when the dialog is executed.
</p>
<p>
Left and Top are used in the CreateForm method to set the default coordinates 
for the dialog form.
</p>
</descr>
<seealso>
<link id="TFindDialog.Left"/>
<link id="TFindDialog.CalcPosition"/>
<link id="TFindDialog.Execute"/>
<link id="TFindDialog.CreateForm"/>
</seealso>
</element>

<element name="TFindDialog.FindText">
<short>
Contains the text to locate when the Find button is clicked on the dialog 
form.
</short>
<descr>
<p>
<var>FindText</var> is a <var>String</var> property with the value to locate 
when Find button is clicked on the dialog form. Changing the value for the 
property causes the corresponding edit control on the dialog form to be 
updated (when assigned) with the new value.
</p>
<p>
Use the OnFind event handler to perform the actions needed to located the 
value in FindText using the Options enabled for the dialog.
</p>
</descr>
<seealso>
<link id="TFindDialog.OnFind"/>
<link id="TFindDialog.Options"/>
</seealso>
</element>

<element name="TFindDialog.Options">
<short>
Contains the find / replace options enabled for the dialog.
</short>
<descr>
<p>
<var>Options</var> is a <var>TFindOptions</var> property which contains the 
set of find / replace options enabled for the dialog. The set type contains 
zero (0) or more values from the TFindOption enumeration. The default value 
for the property is [frDown] and indicates the search direction in the dialog.
</p>
<p>
Changing the values in the property causes the controls on the dialog form to 
be updated (when assigned). For example:
</p>
<dl>
<dt>frEntireScope</dt>
<dd>Causes the EntireScope check box to become checked.</dd>
<dt>frWholeWord</dt>
<dd>Causes the WholeWordsOnly check box to become checked.</dd>
<dt>frMatchCase</dt>
<dd>Causes the CaseSensitive check box to become checked.</dd>
</dl>
<p>
Other values in Options control whether controls on the dialog form are 
visible or enabled, and are applied when the SetFormValues method is called. 
These include:
</p>
<dl>
<dt>frDown</dt>
<dd>Causes the DirectionRadioGroup box to be set to the Down radio 
button.</dd>
<dt>frDisableWholeWord</dt>
<dd>
Causes the WholeWordsOnly check box to be disabled (Enabled = False) when 
present.
</dd>
<dt>frDisableMatchCase</dt>
<dd>
Causes the CaseSensitive check box to be disabled (Enabled = False) when 
present.
</dd>
<dt>frDisableUpDown</dt>
<dd>
Causes the Direction radio group be disabled (Enabled = False) when present.
</dd>
<dt>frHideWholeWord</dt>
<dd>
Causes the WholeWordsOnly check box be hidden (Visible = False) when present.
</dd>
<dt>frHideMatchCase</dt>
<dd>
Causes the CaseSensitive check box be hidden (Visible = False) when present.
</dd>
<dt>frHideUpDown</dt>
<dd>
Causes the Direction radio group to be hidden (Visible = False) when present.
</dd>
<dt>frShowHelp</dt>
<dd>
Causes the Help button to be displayed (Visible = True) when present.
</dd>
<dt>frHideEntireScope</dt>
<dd>
Causes the EntireScope check box to be hidden (Visible = False) when present.
</dd>
</dl>
<p>
Values in Options are updated in the GetFormValues method, which is called 
when the Find button is clicked on the dialog form. The Option values 
affected include:
</p>
<dl>
<dt>frDown</dt>
<dd>
Added or removed based the radio button select in the Direction radio group.
</dd>
<dt>frWholeWord</dt>
<dd>
Added or removed based on the checked state for the WholeWordsOnly check box.
</dd>
<dt>frMatchCase</dt>
<dd>
Added or removed based on the checked state for the CaseSensitive check box.
</dd>
<dt>frEntireScope</dt>
<dd>
Added or removed based on the checked state for the EntireScope check box.
</dd>
</dl>
</descr>
<seealso>
<link id="TFindDialog.SetFormValues"/>
<link id="TFindDialog.GetFormValues"/>
<link id="TFindDialog.Execute"/>
<link id="TFindDialog.FindClick"/>
<link id="TFindOptions"/>
<link id="TFindOption"/>
</seealso>
</element>

<element name="TFindDialog.OnFind">
<short>
Event handler signalled when the Find button is clicked on the dialog form.
</short>
<descr>
<p>
<var>OnFind</var> is a <var>TNotifyEvent</var> property with the event 
handler signalled to perform the find operation for the dialog. OnFind is 
signalled (when assigned) from the Find method, and occurs when the Find 
button is clicked on the dialog form.
</p>
<p>
An application must implement and assign a handler routine to the property to 
respond to the event notification.
</p>
<p>
The <var>Sender</var> argument is the object instance for the event 
notification. It can be cast to TFindDialog (or TReplaceDialog in the 
descendent class) to access the properties and methods in the dialog class 
instance. Use its FindText and Options properties to perform the actions 
needed in the handler routine.
</p>
</descr>
<seealso>
<link id="TFindDialog.FindText"/>
<link id="TFindDialog.Options"/>
<link id="TFindDialog.Find"/>
<link id="TFindDialog.FindClick"/>
<link id="TReplaceDialog.ReplaceText"/>
</seealso>
</element>

<element name="TFindDialog.OnHelpClicked">
<short>
Event handler signalled when the Help button is clicked on the dialog form.
</short>
<descr>
<p>
<var>OnHelpClicked</var> is a <var>TNotifyEvent</var> property with the event 
handler signalled to display context help for the find dialog. It can be used 
to locate, format, and display the help associated with the dialog. 
OnHelpClicked is signalled from the Help method (when assigned), and occurs 
when the Help button is clicked on the dialog form.
</p>
<p>
An application can implement and assign a handler routine to the property to 
respond to the event notification. The Sender argument contains the object 
instance for the event notification. It can be cast to TFindDialog (or 
TReplaceDialog for the descendent class) to access properties and methods 
specific to the dialog class instance. The handler routine is responsible for 
all aspects of the context help display.
</p>
<p>
Include frShowHelp in the Options property to enable the Help button on the 
dialog form.
</p>
</descr>
<seealso>
<link id="TFindDialog.Help"/>
<link id="TFindDialog.HelpClick"/>
<link id="TFindDialog.Options"/>
<link id="TFindOptions"/>
<link id="TFindOption"/>
</seealso>
</element>

<element name="TReplaceDialog">
<short>
Implements a find and replace dialog.
</short>
<descr>
<p>
The dialog appears and offers boxes for the user to enter text for searching 
and text to replace it, for example while editing a file or large piece of 
text.
</p>
<p>
A number of buttons appear, offering the choice to replace this instance, 
find next, replace all.
</p>
</descr>
<seealso>
<link id="TFindDialog"/>
</seealso>
</element>

<element name="TReplaceDialog.DefaultTitle">
<short>
Default value for the Title property used on the replace dialog.
</short>
<descr/>
<seealso>
<link id="TCommonDialog.Title"/>
</seealso>
</element>
<element name="TReplaceDialog.DefaultTitle.Result">
<short>
Returns the value in the rsReplace constant.
</short>
</element>

<element name="TReplaceDialog.ReplaceClick">
<short>
<var>ReplaceClick</var> - code to execute when the Replace button is clicked 
(replace just the current instance).
</short>
<descr/>
<seealso/>
</element>
<element name="TReplaceDialog.ReplaceClick.Sender">
<short>
Object for the event notification.
</short>
</element>

<element name="TReplaceDialog.ReplaceAllClick">
<short>
<var>ReplaceAllClick</var> - code to execute when the Replace All button is 
clicked (replace all remaining instances).
</short>
<descr/>
<seealso/>
</element>
<element name="TReplaceDialog.ReplaceAllClick.Sender">
<short>
Object for the event notification.
</short>
</element>

<element name="TReplaceDialog.CreateForm">
<short>
Gets the form instance displayed when dialog is executed.
</short>
<descr/>
<seealso>
<link id="#lcl.dialogs.TFindDialog.CreateForm">TFindDialog.CreateForm</link>
</seealso>
</element>
<element name="TReplaceDialog.CreateForm.Result">
<short>
Form instance with the editing controls and buttons used on the dialog form.
</short>
</element>

<element name="TReplaceDialog.SetFormValues">
<short>
Copies property values from the class instance to the controls on the dialog 
form.
</short>
<descr/>
<seealso>
<link id="TFindDialog.SetFormValues"/>
</seealso>
</element>

<element name="TReplaceDialog.GetFormValues">
<short>
Copies property values from the dialog form to class instance after the 
dialog has been executed.
</short>
<descr/>
<seealso>
<link id="TFindDialog.GetFormValues"/>
</seealso>
</element>

<element name="TReplaceDialog.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the constructor for <var>TReplaceDialog</var>, and calls 
the inherited <var>Create</var> method. It sets the initial option values for 
find and replace.
</p>
</descr>
<seealso>
<link id="#LCL.Dialogs.TFindDialog.Create">TFindDialog.Create</link>
</seealso>
</element>
<element name="TReplaceDialog.Create.AOwner">
<short>Owner of the class instance.</short>
</element>

<element name="TReplaceDialog.ReplaceText" link="#lcl.dialogs.TFindDialog.ReplaceText"/>
<element name="TReplaceDialog.OnReplace" link="#lcl.dialogs.TFindDialog.OnReplace"/>

<element name="TCustomPrinterSetupDialog">
<short>
Base class for <var>TPrinterSetupDialog</var> and <var>TPageSetupDialog</var>.
</short>
<descr/>
<seealso/>
</element>

<element name="TPrintRange">
<short>
Enumerated type which represents page ranges used in a print dialog.
</short>
<descr/>
<seealso/>
</element>
<element name="TPrintRange.prAllPages">
<short>Print all pages.</short>
</element>
<element name="TPrintRange.prSelection">
<short>Print the selected range of pages.</short>
</element>
<element name="TPrintRange.prPageNums">
<short>Print the selection of individual pages.</short>
</element>
<element name="TPrintRange.prCurrentPage">
<short>Print the current page.</short>
</element>

<element name="TPrintDialogOption">
<short>Enumerated type with available options for a print dialog.</short>
<descr/>
<seealso>
<link id="TPrintDialogOptions"/>
</seealso>
</element>
<element name="TPrintDialogOption.poPrintToFile">
<short>Enables and checks the print to a file check box.</short>
</element>
<element name="TPrintDialogOption.poPageNums">
<short>Selects the Pages radio button in the dialog.</short>
</element>
<element name="TPrintDialogOption.poSelection">
<short>Selects the Selection radio button in a print dialog.</short>
</element>
<element name="TPrintDialogOption.poWarning">
<short>Displays a warning message for a print error.</short>
</element>
<element name="TPrintDialogOption.poHelp">
<short>Displays a Help button in a print dialog.</short>
</element>
<element name="TPrintDialogOption.poDisablePrintToFile">
<short>Disables the print to file check box in a print dialog.</short>
</element>

<element name="TPrintDialogOptions">
<short>
A set type used for the options in a print dialog.
</short>
<descr/>
<seealso>
<link id="TPrintDialogOption"/>
</seealso>
</element>

<element name="TCustomPrintDialog">
<short>
Implements the base class for <var>TPrintDialog</var>.
</short>
<descr>
<p>
<var>TCustomPrintDialog</var> provides properties needed to configure print 
jobs in the TPrintDialog descendant.
</p>
<p>
Use the Options property to enable or disable use of specific properties on 
the dialog.
</p>
<p>
Use the Execute method to display the dialog and capture the values entered 
using the dialog. Use UserChoice to determine the button clicked or action 
taken to close the dialog.
</p>
<p>
The TPrintDialog descendant is defined in the <file>printer4lazarus</file> 
package.
</p>
</descr>
</element>

<element name="TCustomPrintDialog.FFromPage"/>
<element name="TCustomPrintDialog.FToPage"/>
<element name="TCustomPrintDialog.FCollate"/>
<element name="TCustomPrintDialog.FOptions"/>
<element name="TCustomPrintDialog.FPrintToFile"/>
<element name="TCustomPrintDialog.FPrintRange"/>
<element name="TCustomPrintDialog.FMinPage"/>
<element name="TCustomPrintDialog.FMaxPage"/>
<element name="TCustomPrintDialog.FCopies"/>

<element name="TCustomPrintDialog.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<p>
<var>Create</var> is the overridden constructor for the class instance, and 
calls the inherited method on entry. Create sets the default values for the 
PrintRange and Copies properties.
</p>
</descr>
<seealso>
<link id="TCommonDialog.Create"/>
<link id="TCustomPrintDialog.Copies"/>
<link id="TCustomPrintDialog.PrintRange"/>
</seealso>
</element>
<element name="TCustomPrintDialog.Create.TheOwner">
<short>
Owner of the class instance.
</short>
</element>

<element name="TCustomPrintDialog.Collate">
<short>
Enables or disables page collation when multiple copies are produced.
</short>
<descr/>
<seealso/>
</element>

<element name="TCustomPrintDialog.Copies">
<short>
Number of <var>Copies</var> requested for the document.
</short>
<descr/>
<seealso/>
</element>

<element name="TCustomPrintDialog.FromPage">
<short>
First page number to include in the print request.
</short>
<descr/>
<seealso/>
</element>

<element name="TCustomPrintDialog.MinPage">
<short>Smallest value allowed in the page number for a print range.</short>
<descr/>
<seealso/>
</element>

<element name="TCustomPrintDialog.MaxPage">
<short>Largest value allowed in the page number for a print range.</short>
<descr/>
<seealso/>
</element>

<element name="TCustomPrintDialog.Options">
<short>
Set of options enabled when the print dialog is executed.
</short>
<descr>
<p>
<var>Options</var> is a <var>TPrintDialogOptions</var> property with the 
options enabled for the print dialog. It can contain 0 (zero) or more values 
from the <var>TPrintDialogOption</var> enumeration. When a value is included 
in the set, the corresponding option is enabled when the Execute method is 
called. 
</p>
<p>
Values in the property are used to configure the TPrintDialog descendant 
before it is displayed and executed. The values control both the properties 
and printer flags used in the print dialog.
</p>
<p>
See <link id="TPrintDialogOption">TPrintDialogOption</link> for the values 
allowed in the set and their meanings.
</p>
<p>
The default value for the property is an empty set ([]).
</p>
</descr>
<seealso>
<link id="TPrintDialogOptions"/>
<link id="TPrintDialogOption"/>
<link id="TCommonDialog.Execute"/>
</seealso>
</element>

<element name="TCustomPrintDialog.PrintToFile">
<short>
When <b>True</b>, printing is spooled to a file instead of directly to the 
printer.
</short>
<descr/>
<seealso/>
</element>

<element name="TCustomPrintDialog.PrintRange">
<short>
Determines which values are used to represent the page range.
</short>
<descr>
<p>
<var>PrintRange</var> is a <var>TPrintRange</var> property which indicates 
which values on the dialog are used for the page range in a print job.
</p>
<dl>
<dt>prAllPages</dt>
<dd>
Selects all pages in a document for the print job. This is the default value for the property.
</dd>
<dt>prSelection</dt>
<dd>
Causes the pages selected on the dialog to be used.
</dd>
<dt>prPageNums</dt>
<dd>
Causes the page range in the FromPage and ToPage properties to be used on the 
print dialog.
</dd>
<dt>prCurrentPage</dt>
<dd>
Causes the current page only to be printed.
</dd>
</dl>
</descr>
<seealso/>
</element>

<element name="TCustomPrintDialog.ToPage">
<short>
<var>ToPage</var> - the final page number in the range for printing.
</short>
<descr/>
<seealso/>
</element>

<element name="TTaskDialogFlag">
<short>
Represents options that can be enabled for TTaskDialog.
</short>
<descr>
<p>
TTaskDialogFlag values are stored in the TTaskDialogFlags type, as used in 
the TCustomTaskDialog.Flags property.
</p>
</descr>
<version>
<p>
Modified in LCL 3.0 to include tfEmulateClassicStyle in the enumeration.
</p>
<p>
Modified in LCL 4.0 to include additional flag values in the enumeration.
</p>
</version>
<seealso>
<link id="TTaskDialogFlags"/>
<link id="TCustomTaskDialog.Flags"/>
</seealso>
</element>
<element name="TTaskDialogFlag.tfEnableHyperlinks">
<short>
Allows HTML-like hyperlinks in the dialog (in Text, FooterText, and 
ExpandedText) using the <b>'&lt;a href="target"&gt;Target&lt;/a&gt;'</b> 
notation. For platforms that use an emulated (non-native) task dialog form, 
the markup text is displayed instead of a formatted hyperlink.
</short>
</element>
<element name="TTaskDialogFlag.tfUseHiconMain">
<short>
Uses the handle to the image in MainIcon as the primary image for the Task 
dialog. Disables hyperlinks and expanded text areas. Not used in the current 
implementation.
</short>
</element>
<element name="TTaskDialogFlag.tfUseHiconFooter">
<short>
Uses the handle to the image in FooterIcon as the footer icon in the Task 
dialog. Disables hyperlinks and expanded text areas. Not used in the current 
implementation.
</short>
</element>
<element name="TTaskDialogFlag.tfAllowDialogCancellation">
<short>
Allow cancelling the dialog using the Esc key or Alt+F4 (i.e. OS default 
hotkey).
</short>
</element>
<element name="TTaskDialogFlag.tfUseCommandLinks">
<short>
Custom buttons will be shown as larger buttons with an icon in the text 
content area on the dialog. On native task dialog forms, the CommandLinkHint 
for buttons is included on a separate line (using a slightly smaller font) on 
the buttons. On emulated task dialog forms, the text in the CommandLinkHint 
for the buton is omitted.
</short>
</element>
<element name="TTaskDialogFlag.tfUseCommandLinksNoIcon">
<short>
Like tfUseCommandLinks, but hides glyphs for custom buttons in the "command 
links" mode.
</short>
</element>
<element name="TTaskDialogFlag.tfExpandFooterArea">
<short>
Show ExpandedText in the footer, instead of immediately after the main text.
</short>
</element>
<element name="TTaskDialogFlag.tfExpandedByDefault">
<short>
Displays the dialog with the content in ExpandedText in the expanded state.
</short>
</element>
<element name="TTaskDialogFlag.tfVerificationFlagChecked">
<short>
Displays the verification check-box using the checked state on entry.
</short>
</element>
<element name="TTaskDialogFlag.tfShowProgressBar">
<short>
Shows a progress bar on the dialog form. Implemented for native Windows Vista 
or later platforms.
</short>
</element>
<element name="TTaskDialogFlag.tfShowMarqueeProgressBar">
<short>
Shows a progress bar on the dialog form using the marquee style. Implemented 
for native Windows Vista or later platforms.
</short>
</element>
<element name="TTaskDialogFlag.tfCallbackTimer">
<short>
Execute the timer callback event every 200 milliseconds. Enables the timer event on the dialog form.
</short>
</element>
<element name="TTaskDialogFlag.tfPositionRelativeToWindow">
<short>
Position for the dialog form is set to poOwnerFormCenter instead of 
poScreenCenter.
</short>
</element>
<element name="TTaskDialogFlag.tfRtlLayout">
<short>
Use Right-to-Left layout for texts. Implemented for native Windows Vista 
or later platforms.
</short>
</element>
<element name="TTaskDialogFlag.tfNoDefaultRadioButton">
<short>
Does not pre-select a default radio button.
</short>
</element>
<element name="TTaskDialogFlag.tfCanBeMinimized">
<short>
Allows the dialog form to be minimized.
</short>
</element>
<element name="TTaskDialogFlag.tfNoSetForeGround">
<short>
Prevents bringing the dialog to the foreground when the dialog is activated. 
Implemented for native Windows Vista or later platforms.
</short>
</element>
<element name="TTaskDialogFlag.tfSizeToContent">
<short>
Indicates the width for the dialog is determined by the caption, title, or 
lines of text in the content areas areas. The flag is ignored if the 
dialog width is not set to 0 (zero). Implemented for native Windows Vista 
or later platforms.
</short>
</element>
<element name="TTaskDialogFlag.tfForceNonNative">
<short>Forces use of an emulated task dialog form.</short>
</element>
<element name="TTaskDialogFlag.tfEmulateClassicStyle">
<short>
Causes the dialog form to be displayed using a classic style where the content 
areas use clForm as the background color instead of clWindow. Applies to 
platforms which use an emulated task dialog only.
</short>
</element>
<element name="TTaskDialogFlag.tfQuery">
<short>
Causes a query input control to be displayed on the task dialog using an 
editable (non-fixed) combo-box control.
</short>
</element>
<element name="TTaskDialogFlag.tfSimpleQuery">
<short>
Causes a query input control to be displayed on the task dialog using a simple 
TEdit control instance with optional password character-style obfuscation. 
tfQuery takes precedence if both values are included in the flags for a task 
dialog.
</short>
</element>
<element name="TTaskDialogFlag.tfQueryFixedChoices">
<short>
Causes a query input control to be displayed on the task dialog using a 
combo-box to select from non-editable predefined values. tfQuery must also be 
included to enable a query control on the dialog form.
</short>
</element>
<element name="TTaskDialogFlag.tfQueryFocused">
<short>
Causes the query input control to be focused when the task dialog is executed. 
Requires tfQuery or tfSimpleQuery in the flags for a task dialog.
</short>
</element>

<element name="TTaskDialogFlags">
<short>
Set type used to store values from the TTaskDialogFlag enumeration.
</short>
<descr>
<p>
TTaskDialogFlags is the type used for the TCustomTaskDialog.Flags property.
</p>
</descr>
<seealso>
<link id="TTaskDialogFlag"/>
<link id="TCustomTaskDialog.Flags"/>
</seealso>
</element>

<element name="TTaskDialogCommonButton">
<short>Identifier used for common buttons visible on a Task dialog.</short>
<descr>
<p>
Values from <var>TTaskDialogCommonButton</var> are stored in the 
<var>TTaskDialogCommonButtons</var> set type, as used in the 
<var>TCustomTaskDialog.CommonButtons</var> property. When a value is included 
in the set, the corresponding button is visible on the task dialog.
</p>
</descr>
<seealso>
<link id="TTaskDialogCommonButtons"/>
<link id="TCustomTaskDialog.CommonButtons"/>
</seealso>
</element>
<element name="TTaskDialogCommonButton.tcbOk">
<short>The Ok button.</short>
</element>
<element name="TTaskDialogCommonButton.tcbYes">
<short>The Yes button.</short>
</element>
<element name="TTaskDialogCommonButton.tcbNo">
<short>The No button.</short>
</element>
<element name="TTaskDialogCommonButton.tcbCancel">
<short>The Cancel button.</short>
</element>
<element name="TTaskDialogCommonButton.tcbRetry">
<short>The Retry button.</short>
</element>
<element name="TTaskDialogCommonButton.tcbClose">
<short>The Close button.</short>
</element>

<element name="TTaskDialogCommonButtons">
<short>Set type used to store values from TTaskDialogCommonButton.</short>
<descr>
<p>
<var>TTaskDialogCommonButtons</var> is the type used for the 
<var>CommonButtons</var> property in <var>TCustomTaskDialog</var>.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.CommonButtons"/>
</seealso>
</element>

<element name="TTaskDlgClickEvent">
<short>
Specifies an event handler signalled when a button is clicked in 
TCustomTaskDialog / TTaskDialog.
</short>
<descr>
<p>
TTaskDlgClickEvent is the type used for the OnButtonClicked event handler in 
TCustomTaskDialog.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.OnButtonClicked"/>
</seealso>
</element>
<element name="TTaskDlgClickEvent.Sender">
<short>Task dialog for the event notification.</short>
</element>
<element name="TTaskDlgClickEvent.AModalResult">
<short>Modal result for the clicked button.</short>
</element>
<element name="TTaskDlgClickEvent.ACanClose">
<short><b>True</b> if the dialog can close.</short>
</element>

<element name="TTaskDlgTimerEvent">
<short>
Specifies an event handler signalled when the timer callback is enabled in a 
task dialog.
</short>
<descr>
<p>
<var>TTaskDlgTimerEvent</var> is an object procedure type which defines an 
event handler signalled when the timer internal in a task dialog has elapsed. 
Applications can implement and assign a routine using the signature for the 
type to the OnTimer event handler in TTaskDialog.
</p>
<p>
The routine is signalled from the DoOnTimer method in TCustomTaskDialog and is 
called periodically from the widgetset class when the callback timer is 
enabled in the task dialog. Arguments passed to the routine indicate the 
dialog form for the event notification, the number of ticks (milliseconds) 
since the timer was started, and an updatable value to indicate that the time 
should be reset.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.OnTimer"/>
</seealso>
</element>
<element name="TTaskDlgTimerEvent.Sender">
<short>
Task dialog for the event notification.
</short>
</element>
<element name="TTaskDlgTimerEvent.TickCount">
<short>
Number of ticks (milliseconds) since the timer was started.
</short>
</element>
<element name="TTaskDlgTimerEvent.Reset">
<short>
Set to <b>True</b> to reset the timer. Set to <b>False</b> to continue 
execution of the timer callback.
</short>
</element>

<element name="TTaskDialogIcon">
<short>Identifier for an icon displayed on a Task dialog.</short>
<descr>
<p>
TTaskDialogIcon is the type used for the FooterIcon and MainIcon properties 
in TCustomTaskDialog.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.FooterIcon"/>
<link id="TCustomTaskDialog.MainIcon"/>
</seealso>
</element>
<element name="TTaskDialogIcon.tdiNone">
<short>No icon is displayed.</short>
</element>
<element name="TTaskDialogIcon.tdiWarning">
<short>
Displays the Warning icon (Amber triangle with an Exclamation mark).
</short>
</element>
<element name="TTaskDialogIcon.tdiError">
<short>Displays the Error icon (Red circle with an X).</short>
</element>
<element name="TTaskDialogIcon.tdiInformation">
<short>
Displays the Information icon (Blue circle with a Question Mark).
</short>
</element>
<element name="TTaskDialogIcon.tdiShield">
<short>Displays the Shield icon.</short>
</element>
<element name="TTaskDialogIcon.tdiQuestion">
<short>Displays the Question icon (Blue circle with a Question Mark).</short>
</element>

<element name="TTaskDialogBaseButtonItem">
<short>
Defines the base class for a custom button displayed on a Task dialog.
</short>
<descr>
<p>
<var>TTaskDialogBaseButtonItem</var> is a <var>TCollectionItem</var> 
descendant which defines a custom button that can be displayed on a Task 
dialog. It provides properties that indicate the <var>Caption</var> for the 
button, its use as the <var>Default</var> button on a dialog, and its 
<var>ModalResult</var> value.
</p>
<p>
TTaskDialogBaseButtonItem is the ancestor class for 
<var>TTaskDialogBaseButtonItem</var>.
</p>
</descr>
<seealso>
<link id="TTaskDialogBaseButtonItem"/>
</seealso>
</element>

<!-- private -->
<element name="TTaskDialogBaseButtonItem.FCaption"/>
<element name="TTaskDialogBaseButtonItem.FClient"/>
<element name="TTaskDialogBaseButtonItem.FCommandLinkHint"/>
<element name="TTaskDialogBaseButtonItem.FModalResult"/>

<element name="TTaskDialogBaseButtonItem.GetDefault"/>
<element name="TTaskDialogBaseButtonItem.GetDefault.Result"/>
<element name="TTaskDialogBaseButtonItem.SetCaption"/>
<element name="TTaskDialogBaseButtonItem.SetCaption.ACaption"/>
<element name="TTaskDialogBaseButtonItem.SetDefault"/>
<element name="TTaskDialogBaseButtonItem.SetDefault.Value"/>

<element name="TTaskDialogBaseButtonItem.Client">
<short>TCustomTaskDialog where the button is used.</short>
<descr>
<p>
<var>Client</var> is a read-only <var>TCustomTaskDialog</var> property with 
the dialog where the button is used. Its value is set to the Task dialog that 
is the owner of the collection where the button definition is stored.
</p>
</descr>
<seealso>
<link id="TTaskDialogBaseButtonItem.Create"/>
<link id="#rtl.classes.TCollection.Owner">TCollection.Owner</link>
</seealso>
</element>

<element name="TTaskDialogBaseButtonItem.GetDisplayName">
<short>Gets the value for the DisplayName property.</short>
<descr>
<p>
<var>GetDisplayName</var> is an overridden method used to get the value for 
the
<var>DisplayName</var> property. In TTaskDialogBaseButtonItem, the value in 
<var>Caption</var> is used (when assigned) for the property value. When 
Caption is empty, the inherited method is called to get the property value.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TCollectionItem">TCollectionItem</link>
</seealso>
</element>
<element name="TTaskDialogBaseButtonItem.GetDisplayName.Result">
<short>Value for the DisplayName property.</short>
</element>

<element name="TTaskDialogBaseButtonItem.TaskButtonCollection">
<short>
Gets the collection where the button definition is stored.
</short>
<descr>
<p>
TaskButtonCollection is a TTaskDialogButtons function which retrieves the 
Collection where the button definition is stored. It allows the button 
definition to access properties and methods in the collection.
</p>
</descr>
<seealso/>
</element>
<element name="TTaskDialogBaseButtonItem.TaskButtonCollection.Result">
<short>
Collection which owns the button cast to a TTaskDialogButtons type.
</short>
</element>

<element name="TTaskDialogBaseButtonItem.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the overridden constructor for the class instance. It 
calls the inherited method on entry, and sets the value in the 
<var>Client</var> property to the dialog which is the owner for the 
Collection. The value in <var>ModalResult</var> is set to the <var>ID</var> 
value for the collection item + 100.
</p>
</descr>
<seealso>
<link id="TTaskDialogBaseButtonItem.Client"/>
<link id="TTaskDialogBaseButtonItem.ModalResult"/>
<link id="#rtl.classes.TCollectionItem.Collection">TCollectionItem.Collection</link>
<link id="#rtl.classes.TCollectionItem.ID">TCollectionItem.ID</link>
</seealso>
</element>
<element name="TTaskDialogBaseButtonItem.Create.ACollection">
<short>Collection which owns the button item.</short>
</element>

<element name="TTaskDialogBaseButtonItem.ModalResult">
<short>Modal result value returned when the button is clicked.</short>
<descr>
<p>
The default value for the property is assigned when the button item is 
created and is based in its ID value + 100. The value can be changed to any 
reasonable value that is unique for the context.
</p>
<p>
ModalResult is used when a Task dialog is executed and a button is clicked on 
the dialog. Its value for the clicked button is assigned to the ModalResult 
property in the TCustomTaskDialog instance.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.Execute"/>
<link id="TCustomTaskDialog.ModalResult"/>
<link id="TCustomTaskDialog.Buttons"/>
<link id="TCustomTaskDialog.CommonButtons"/>
</seealso>
</element>

<element name="TTaskDialogBaseButtonItem.CommandLinkHint">
<short>
Provides additional information about the button when command links are 
enabled in a task dialog.
</short>
<descr>
<p>
CommandLinkHint is a TTranslateString property which contains additional 
information about the button. The translatable content is used as second line 
of text for the button when command links are enabled in a native TTaskDialog 
instance. The value is not displayed as an additional line on platforms where 
an emulated task dialog is used; this includes all platforms other Windows 
(Vista or later).
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso/>
</element>


<element name="TTaskDialogBaseButtonItem.Caption">
<short>Caption text displayed on the button surface.</short>
<descr>
<p>
<var>Caption</var> is a <var>TTranslateString</var> property with the caption 
text displayed on the button surface. It can be localized using the built-in 
translation facilities available in the LCL. When assigned, Caption also 
provides the DisplayName for the collection item in the object inspector.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TCollectionItem.DisplayName">TCollectionItem.DisplayName</link>
</seealso>
</element>

<element name="TTaskDialogBaseButtonItem.Default">
<short>Indicates if the button is the default button on a Task dialog.</short>
<descr>
<p>
<var>Default</var> is a <var>Boolean</var> property which indicates if the 
button is the default button for a Task dialog. The default value for the 
property is <b>False</b>.
</p>
<p>
Changing the value in the property causes the <var>DefaultButton</var> 
property in the Collection to be updated. When set to <b>True</b>, the button 
instance is assigned to the DefaultButton property in the collection. When 
set to <b>False</b>, the DefaultButton in the collection is set to <b>Nil</b>.
</p>
</descr>
<seealso>
<link id="TTaskDialogBaseButtonItem.TaskButtonCollection"/>
<link id="TTaskDialogButtons.DefaultButton"/>
<link id="#rtl.classes.TCollectionItem.Collection">TCollectionItem.Collection</link>
</seealso>
</element>

<element name="TTaskDialogButtonItem">
<short>
Implements a button definition used for a button in TCustomTaskDialog.
</short>
<descr>
<p>
<var>TTaskDialogButtonItem</var> is a <var>TTaskDialogBaseButtonItem</var> 
descendant used to define and store buttons created in 
<var>TCustomTaskDialog</var> / <var>TTaskDialog</var>. It provides an 
overridden constructor which creates an object inspector-friendly name for 
the button item. It also sets the visibility for the <var>ModalResult</var> 
property to published.
</p>
<p>
TTaskDialogButtonItem is the type used for the <var>Button</var> property in 
TCustomTaskDialog, and maintained in its <var>Buttons</var> collection.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.Button"/>
<link id="TCustomTaskDialog.Buttons"/>
<link id="TTaskDialogBaseButtonItem"/>
</seealso>
</element>

<element name="TTaskDialogButtonItem.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the overridden constructor for the class instance, and 
calls the inherited method on entry. It assigns an object inspector-friendly 
value to the <var>Caption</var> property, such as 'Button3'. The Caption is 
also used as the <var>DisplayName</var> for the collection item when assigned.
</p>
</descr>
<seealso>
<link id="TTaskDialogBaseButtonItem.Caption"/>
<link id="#rtl.classes.TCollectionItem.DisplayName">TCollectionItem.DisplayName</link>
</seealso>
</element>
<element name="TTaskDialogButtonItem.Create.ACollection">
<short>Collection which owns the button item.</short>
</element>

<element name="TTaskDialogButtonItem.CommandLinkHint" link="#lcl.dialogs.TTaskDialogBaseButtonItem.CommandLinkHint"/>

<element name="TTaskDialogButtonItem.ModalResult" link="#lcl.dialogs.TTaskDialogBaseButtonItem.ModalResult"/>

<element name="TTaskDialogRadioButtonItem">
<short>Implements a radio button displayed on a Task dialog.</short>
<descr>
<p>
<var>TTaskDialogRadioButtonItem</var> is a 
<var>TTaskDialogBaseButtonItem</var> descendant which implements a radio 
button displayed on a Task dialog. TTaskDialogRadioButtonItem is the type 
used for the <var>RadioButton</var> property in <var>TCustomTaskDialog</var>, 
and maintained in its <var>RadioButtons</var> collection.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.RadioButton"/>
<link id="TCustomTaskDialog.RadioButtons"/>
</seealso>
</element>

<element name="TTaskDialogRadioButtonItem.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the overridden constructor for the class instance, and 
calls the inherited method on entry. Creates assign an object 
inspector-friendly value for the Caption property, such as 'RadioButton2'.
</p>
</descr>
<seealso>
<link id="TTaskDialogBaseButtonItem.Create"/>
</seealso>
</element>
<element name="TTaskDialogRadioButtonItem.Create.ACollection">
<short>Collection which owns the radio button item.</short>
</element>

<element name="TTaskDialogButtonsEnumerator">
<short>Implements an enumerator for buttons defined in a Task dialog.</short>
<descr/>
<seealso/>
</element>

<element name="TTaskDialogButtonsEnumerator.FIndex"/>
<element name="TTaskDialogButtonsEnumerator.FCollection"/>

<element name="TTaskDialogButtonsEnumerator.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
Sets the internal position for the enumerator to -1 to indicate that a button 
is not available. Use <var>MoveNext</var> to position the enumerator at the 
first button in the collection.
</p>
</descr>
<seealso>
<link id="TTaskDialogButtonsEnumerator.MoveNext"/>
</seealso>
</element>
<element name="TTaskDialogButtonsEnumerator.Create.ACollection">
<short>Collection which owns the buttons for the enumerator.</short>
</element>

<element name="TTaskDialogButtonsEnumerator.GetCurrent">
<short>Gets the value for the Current property.</short>
<descr/>
<seealso>
<link id="TTaskDialogButtonsEnumerator.Current"/>
</seealso>
</element>
<element name="TTaskDialogButtonsEnumerator.GetCurrent.Result">
<short>Value for the Current property.</short>
</element>

<element name="TTaskDialogButtonsEnumerator.MoveNext">
<short>Positions the enumerator on the next button in the collection.</short>
<descr>
<p>
<var>MoveNext</var> is a <var>Boolean</var> function used to move the 
position for the enumeration to the next button in the collection. When the 
enumerator is created, its position is undefined (-1) by default. Use 
MoveNext to move the position to the first button when the enumerator is 
created.
</p>
<p>
The return value is <b>True</b> when another value was found in the 
collection. It is set to <var>False</var> if the position reaches the value 
in <var>Count</var>.
</p>
</descr>
<seealso>
<link id="TTaskDialogButtonsEnumerator.Current"/>
<link id="#rtl.classes.TCollection.Count">TCollection.Count</link>
</seealso>
</element>
<element name="TTaskDialogButtonsEnumerator.MoveNext.Result">
<short><b>True</b> if another button was available in the collection.</short>
</element>

<element name="TTaskDialogButtonsEnumerator.Current">
<short>Button at the current position for the enumerator.</short>
<descr>
<p>
<var>Current</var> is a read-only <var>TTaskDialogBaseButtonItem</var> 
property with the button at the current position for the enumerator. It uses 
the ordinal position in the collection for the button item as set when the 
<var>MoveNext</var> method was called.
</p>
</descr>
<seealso>
<link id="TTaskDialogButtonsEnumerator.MoveNext"/>
<link id="TTaskDialogButtons"/>
</seealso>
</element>

<element name="TTaskDialogButtons">
<short>
Collection type used to access and maintain buttons defined for a Task dialog.
</short>
<descr>
<p>
<var>TTaskDialogButtons</var> is a <var>TOwnedCollection</var> descendant 
which implements the collection used for the buttons on a Task dialog. 
TTaskDialogButtons provides properties and methods used to access and 
maintain the buttons in the collection, such as: <var>Add</var>, 
<var>FindButton</var>, <var>DefaultButton</var>, <var>Items</var>, and 
<var>GetEnumerator</var>.
</p>
<p>
TTaskDialogButtons is the type used for the <var>Buttons</var> and 
<var>RadioButtons</var> properties in <var>TCustomTaskDialog</var> / 
<var>TTaskDialog</var>.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.Buttons"/>
<link id="TCustomTaskDialog.RadioButtons"/>
</seealso>
</element>

<!-- private -->
<element name="TTaskDialogButtons.FDefaultButton"/>
<element name="TTaskDialogButtons.GetItem"/>
<element name="TTaskDialogButtons.GetItem.Result"/>
<element name="TTaskDialogButtons.GetItem.Index"/>
<element name="TTaskDialogButtons.SetDefaultButton"/>
<element name="TTaskDialogButtons.SetDefaultButton.Value"/>
<element name="TTaskDialogButtons.SetItem"/>
<element name="TTaskDialogButtons.SetItem.Index"/>
<element name="TTaskDialogButtons.SetItem.Value"/>

<element name="TTaskDialogButtons.Add">
<short>
Adds a new collection item using the ItemClass for the collection.
</short>
<descr>
<p>
Calls the inherited <var>Add</var> method to create the new collection item, 
and casts the return value to the <var>TTaskDialogBaseButtonItem</var> type 
used as the <var>ItemClass</var>. The inherited method uses the Collection as 
the Owner for the new collection item.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TCollection.Add">TCollection.Add</link>
<link id="#rtl.classes.TCollection.Owner">TCollection.Owner</link>
<link id="#rtl.classes.TCollection.ItemClass">TCollection.ItemClass</link>
</seealso>
</element>
<element name="TTaskDialogButtons.Add.Result">
<short>Collection item created in the method.</short>
</element>

<element name="TTaskDialogButtons.FindButton">
<short>
Gets the button item in the collection with the specified modal result value.
</short>
<descr>
<p>
<var>FindButton</var> enumerates values in the <var>Items</var> property to 
find the first button using the modal result value in AModalResult. The 
return value is Nil if a button using the modal result value is not found.
</p>
</descr>
<seealso>
<link id="TTaskDialogButtons.Items"/>
<link id="TTaskDialogBaseButtonItem"/>
</seealso>
</element>
<element name="TTaskDialogButtons.FindButton.Result">
<short>
TTaskDialogBaseButtonItem instance with the specified modal result value.
</short>
</element>
<element name="TTaskDialogButtons.FindButton.AModalResult">
<short>
Modal result value to locate in the button items for the collection.
</short>
</element>

<element name="TTaskDialogButtons.GetEnumerator">
<short>Gets an enumerator for the buttons in the Items property.</short>
<descr/>
<seealso>
<link id="TTaskDialogButtons.Items"/>
</seealso>
</element>
<element name="TTaskDialogButtons.GetEnumerator.Result">
<short>
TTaskDialogButtonsEnumerator instance for the buttons in the collection.
</short>
</element>

<element name="TTaskDialogButtons.DefaultButton">
<short>
Contains the collection item that is the default button for a Task dialog.
</short>
<descr>
<p>
<var>DefaultButton</var> is a <var>TTaskDialogBaseButtonItem</var> property 
with the button that is the default button for a Task dialog. The value for 
the property is updated when the <var>Default</var> property in a button item 
is changed.
</p>
</descr>
<seealso>
<link id="TTaskDialogBaseButtonItem.Default"/>
</seealso>
</element>

<element name="TTaskDialogButtons.Items">
<short>Provides indexed access to buttons defined in the collection.</short>
<descr>
<p>
<var>Items</var> is an indexed <var>TTaskDialogBaseButtonItem</var> property 
with the buttons defined for the collection. It re-implements the property 
introduced in the ancestor class to use the 
<var>TTaskDialogBaseButtonItem</var> type when reading or writing values in 
the collection. Values in the property are accessed by their ordinal position 
in the collection.
</p>
<p>
Items is the default property, and the target for an enumerator created for 
the class instance.
</p>
</descr>
<seealso>
<link id="TTaskDialogBaseButtonItem"/>
<link id="TTaskDialogButtons.GetEnumerator"/>
<link id="#rtl.classes.TCollection.Items">TCollection.Items</link>
<link id="#rtl.classes.TCollection.ItemClass">TCollection.ItemClass</link>
</seealso>
</element>
<element name="TTaskDialogButtons.Items.Index">
<short>Ordinal position in the collection for the property value.</short>
</element>

<element name="TProgressBarState">
<short>
Alias to the TProgressBarState type in <file>comctrls.pp</file>.
</short>
<descr/>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="#lcl.comctrls.TProgressBarState"/>
</seealso>
</element>

<element name="PBST_NORMAL">
<short>
Numeric constant used in the Task Dialog API to represent pbsNormal from the 
TProgressBarState enumeration.
</short>
<descr/>
<seealso>
<link id="TProgressBarState"/>
</seealso>
</element>

<element name="PBST_ERROR">
<short>
Numeric constant used in the Task Dialog API to represent pbsError from the 
TProgressBarState enumeration.
</short>
<descr/>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TProgressBarState"/>
</seealso></element>

<element name="PBST_PAUSED">
<short>
Numeric constant used in the Task Dialog API to represent pbsPaused from the 
TProgressBarState enumeration.
</short>
<descr/>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TProgressBarState"/>
</seealso></element>

<element name="PB_DEFMIN">
<short>
Numeric constant which defines the default value for the Min property in a 
progress bar.
</short>
<descr/>
<version>
Added in LCL version 4.0.
</version>
<seealso/>
</element>

<element name="PB_DEFMAX">
<short>
Numeric constant which defines the default value for the Max property in a 
progress bar.
</short>
<descr/>
<version>
Added in LCL version 4.0.
</version>
<seealso/>
</element>

<element name="TDE_CONTENT">
<short>
Numeric constant which identifies the text in the main content area on a task 
dialog.
</short>
<descr/>
<version>
Added in LCL version 4.0.
</version>
<seealso/>
</element>

<element name="TDE_EXPANDED_INFORMATION">
<short>
Numeric constant which identifies the expandable text for a task dialog.
</short>
<descr/>
<version>
Added in LCL version 4.0.
</version>
<seealso/>
</element>

<element name="TDE_FOOTER">
<short>
Numeric constant which identifies the footer text for a task dialog.
</short>
<descr/>
<version>
Added in LCL version 4.0.
</version>
<seealso/>
</element>

<element name="TDE_MAIN_INSTRUCTION">
<short>
Numeric constant which identifies the title in the main content areas on a task 
dialog.
</short>
<descr/>
<version>
Added in LCL version 4.0.
</version>
<seealso/>
</element>

<element name="TTaskDialogProgressBar">
<short>
Provides information about a progress bar displayed on a TTaskDialog instance.
</short>
<descr>
<p>
<var>TTaskDialogProgressBar</var> is a <var>TPersistent</var> descendant used 
to represent information about a progress bar displayed on a task dialog. It 
provides properties used to configure or update the progress bar, like: Min, 
Max, Position, MarqueeSpeed, and State. It includes methods used to create the 
progress bar on the task dialog, and to send its settings to the widgetset 
class including its drawing state. It is not the actual progress bar control, 
however.
</p>
<p>
TTaskDialogProgressBar is the type used to implement the ProgressBar property 
in TTaskDialog.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TTaskDialog.ProgressBar"/>
</seealso>
</element>

<!-- private -->
<element name="TTaskDialogProgressBar.ProgressBarStateValues"/>
<element name="TTaskDialogProgressBar.Dlg"/>
<element name="TTaskDialogProgressBar.FMarqueeSpeed"/>
<element name="TTaskDialogProgressBar.FMax"/>
<element name="TTaskDialogProgressBar.FMin"/>
<element name="TTaskDialogProgressBar.FPosition"/>
<element name="TTaskDialogProgressBar.FState"/>

<!-- private -->
<element name="TTaskDialogProgressBar.SetMarqueeSpeed"/>
<element name="TTaskDialogProgressBar.SetMarqueeSpeed.AValue"/>
<element name="TTaskDialogProgressBar.SetMax"/>
<element name="TTaskDialogProgressBar.SetMax.AValue"/>
<element name="TTaskDialogProgressBar.SetMin"/>
<element name="TTaskDialogProgressBar.SetMin.AValue"/>
<element name="TTaskDialogProgressBar.SetPosition"/>
<element name="TTaskDialogProgressBar.SetPosition.AValue"/>
<element name="TTaskDialogProgressBar.SetState"/>
<element name="TTaskDialogProgressBar.SetState.AValue"/>

<!-- public -->
<element name="TTaskDialogProgressBar.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<p>
<var>Create</var> is the constructor for the class instance. It extends the 
constructor to specify the task dialog where the progress bar information is 
used in the <var>ADialog</var> argument. It sets the default values for 
properties in the class instance, including: Min (PB_DEFMIN), Max (PB_DEFMAX), 
and MarqueeSpeed (0 milliseconds).
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TTaskDialogProgressBar.Max"/>
<link id="TTaskDialogProgressBar.Min"/>
<link id="TTaskDialogProgressBar.MarqueeSpeed"/>
<link id="PB_DEFMIN"/>
<link id="PB_DEFMAX"/>
<link id="TCustomTaskDialog"/>
</seealso>

</element>
<element name="TTaskDialogProgressBar.Create.ADialog">
<short>
Task dialog where the progress bar is hosted.
</short>
</element>

<element name="TTaskDialogProgressBar.Initialize">
<short>
Sends the initial values for the progress bar to the task dialog where it is 
hosted.
</short>
<descr>
<p>
<var>Initialize</var> is a method used to apply the values in the progress bar 
by notifying the task dialog and its widget. This includes setting the progress 
bar display style, its minimum and maximum range values, the current position, 
the drawing state, and the update frequency for a progress bar drawn using the 
marquee style.
</p>
<p>
Initialize is called from the DoOnDialogConstructed method in the task dialog 
when the Handle for the task dialog has been assigned. No actions are performed 
in the method if the Handle in the task dialog has not been assigned, or when a 
progress bar has not been enabled using the flags for the task dialog.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.Handle"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TCustomTaskDialog.DoOnDialogConstructed"/>
</seealso>
</element>

<element name="TTaskDialogProgressBar.SetRange">
<short>
Applies the values in the Min and Max properties to the progress bar control on 
a task dialog.
</short>
<descr>
<p>
<var>SetRange</var> is a method used to apply the values in the <var>AMin</var> 
and <var>AMax</var> arguments to the progress bar control on a task dialog. 
SetRange is called when the value for the Min or Max property has been updated 
in the class instance. No actions are performed in the method if the argument 
values are the same as the existing property values in the class instance.
</p>
<p>
SetRange ensures that values in the AMin and AMax are in the range 0..High(
Word) (32767). This is done to ensure that the values are valid for the 
platforms and APIs where the value is used. If a valid is too small, it is set 
to 0. If a value is too large, it is set to High(Word). If AMin is larger than 
AMax, AMin is set to the value in the upper limit.
</p>
<p>
SetRange also ensures that the value in Position is within the range specified 
by Min..Max.
</p>
<p>
SetRange updates the task dialog where the progress bar is displayed when the 
Flags property in the dialog includes the value tfShowProgressBar and the 
Handle for the dialog has been assigned. A TDM_SET_PROGRESS_BAR_RANGE message 
is sent using the Handle for the dialog and the newly assigned values for Min 
and Max.
</p>
<p>
Use the Min and Max properties to set the lower and upper limits for the value 
in Position.
</p>
<p>
Set the value in Position to cause the completion percentage to be 
recalculated and the progress bar control to be redrawn.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TTaskDialogProgressBar.Min"/>
<link id="TTaskDialogProgressBar.Max"/>
<link id="TTaskDialog.ProgressBar"/>
<link id="TCustomTaskDialog.Handle"/>
<link id="TTaskDialog.Flags"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
</seealso>
</element>
<element name="TTaskDialogProgressBar.SetRange.AMin">
<short>
Lower limit for the value in Position.
</short>
</element>
<element name="TTaskDialogProgressBar.SetRange.AMax">
<short>
Upper limit for the value in Position.
</short>
</element>

<!-- published -->
<element name="TTaskDialogProgressBar.MarqueeSpeed">
<short>
Contains the number of milliseconds between updates for a progress bar using 
the marquee display style.
</short>
<descr>
<p>
<var>MarqueeSpeed</var> is a <var>Cardinal</var> property which sets the update 
interval for the progress bar. It specifies, in milliseconds, often a progress 
bar using the marquee display style is updated. The default value for the 
property is 0.
</p>
<p>
Changing the value for the property causes a TDM_SET_PROGRESS_BAR_RANGE message 
to be sent using the Handle for the task dialog. It allows the widgetset class 
to be notified when the marquee progress bar style is enabled, or when its 
update interval has been changed. The update is sent when 
tfShowMarqueeProgressBar has been included in the Flags for the task dialog and 
its Handle has been assigned.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.Handle"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
</seealso>
</element>

<element name="TTaskDialogProgressBar.Max">
<short>
Upper limit for the Position on the progress bar.
</short>
<descr>
<p>
<var>Max</var> is an <var>Integer</var> property which contains the upper limit 
for the position on the progress bar; the value in Position must be in the 
range Min..Max inclusive. The default value for the property is 100.
</p>
<p>
Changing the property value causes the SetRange method to be called. This 
allows the task dialog and the widgetset class to be notified when the range 
for the progress bar has been updated.
</p>
<p>
Use Min to set the lower limit for the value in Position.
</p>
<p>
Use Position to set the current position for the progress bar.
</p>
<p>
Position, Min, and Max are not used when the task dialog is configured to use 
the marquee drawing style for its progress bar.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TTaskDialogProgressBar.Min"/>
<link id="TTaskDialogProgressBar.Position"/>
<link id="TTaskDialogProgressBar.SetRange"/>
</seealso>
</element>

<element name="TTaskDialogProgressBar.Min">
<short>
Lower limit for the Position on the progress bar.
</short>
<descr>
<p>
<var>Min</var> is an <var>Integer</var> property which contains the lower limit 
for the position on the progress bar; the value in Position must be in the 
range Min..Max inclusive. The default value for the property is 0.
</p>
<p>
Changing the property value causes the SetRange method to be called. This 
allows the task dialog and the widgetset class to be notified when the range 
for the progress bar has been updated.
</p>
<p>
Use Max to set the upper limit for the value in Position.
</p>
<p>
Use Position to set the current position for the progress bar.
</p>
<p>
Position, Min, and Max are not used when the task dialog is configured to use 
the marquee drawing style for its progress bar.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TTaskDialogProgressBar.Max"/>
<link id="TTaskDialogProgressBar.Position"/>
<link id="TTaskDialogProgressBar.SetRange"/>
</seealso>
</element>

<element name="TTaskDialogProgressBar.Position">
<short>
Contains the current position for the progress bar.
</short>
<descr>
<p>
<var>Position</var> is an <var>Integer</var> property which indicates the 
current position on the progress bar. Position and Max are used to calculate 
the completion percentage for the progress bar. The default value for the 
property is 0 (zero).
</p>
<p>
The value in Position must be in the range Min..Max inclusive. If Position is 
set to a value which exceeds the allowed range, it is normalized to the Min 
or Max value as needed.
</p>
<p>
Changing the value in the property causes a TDM_SET_PROGRESS_BAR_POS message to 
be sent using the Handle for the task dialog. This allows the widgetset class 
to be notified when the progress bar needs to be redrawn. The message is not 
sent to the dialog if tfShowProgressBar has not been included in its Flags 
property or the Handle for the dialog has not been assigned.
</p>
<p>
Use Min to set the lower limit for the value in Position.
</p>
<p>
Use Max to set the upper limit for the value in Position.
</p>
<p>
Position, Min, and Max are not used when the task dialog is configured to use 
the marquee drawing style for its progress bar.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<notes>
<note>
Does Delphi raise an exception if Position is out of range?
</note>
</notes>
<seealso>
<link id="TTaskDialogProgressBar.Max"/>
<link id="TTaskDialogProgressBar.Min"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
</seealso>
</element>

<element name="TTaskDialogProgressBar.State">
<short>
Contains the current drawing state for the progress bar.
</short>
<descr>
<p>
<var>State</var> is a <var>TProgressBarState</var> property which indicates the 
drawing style used to render the progress bar. The default value for the 
property is pbsNormal. Values in the property affect the drawing style used for 
the completion indicator on the progress bar as follows:
</p>
<dl>
<dt>pbsNormal</dt>
<dd>
Causes the default drawing style for the platform to be applied to the 
completion indicator.
</dd>
<dt>pbsError</dt>
<dd>
Causes the completion bar to be drawn with a red fill color to indicate an 
error condition.
</dd>
<dt>pbsPaused</dt>
<dd>
Causes the completion bar to be drawn with an amber fill color to indicate 
that the progress bar has been paused.
</dd>
</dl>
<p>
Changing the value for the property causes the TDM_SET_PROGRESS_BAR_STATE 
message to be sent to the task dialog instance. This allows the task dialog and 
its widget to be updated with the mew state for the progress bar. This action 
is not performed if tfShowProgressBar has not been included in the flags for 
the task dialog or its Handle has not been assigned.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso/>
</element>

<element name="TCustomTaskDialog">
<short>
Defines a configurable, modal task dialog at run-time.
</short>
<descr>
<p>
<var>TCustomTaskDialog</var> is a <var>TLCLComponent</var> 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:
</p>
<ul>
<li>
A Title for the dialog.
</li>
<li>
A Caption for the dialog.
</li>
<li>
A main Icon for the dialog.
</li>
<li>
Text to describe the task dialog.
</li>
<li>
A footer to display additional information on the dialog.
</li>
<li>
An expandable / collapsible text area which can be displayed in the main 
content area or the footer for the dialog.
</li>
<li>
Standard buttons used to return a modal result value.
</li>
<li>
Custom command buttons for task-specific actions.
</li>
<li>
Radio buttons to select dialog options.
</li>
<li>
A progress bar using either the standard or marquee display styles.
</li>
<li>
A query field to capture user input as text or by selecting a value from a list 
of values in a combo-box control.
</li>
<li>
A verification message and check box.
</li>
<li>
Support for hyperlinks in text areas.
</li>
</ul>
<p>
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 <var>Execute</var> method handles converting 
properties and calling routines and methods in the widgetset which implement 
the task dialog for a given platform.
</p>
<p>
<b>Platform Support</b>
</p>
<p>
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 <file>taskdlgemulation.pp</file> unit. It can be forced by 
including a value in the Flags property for the class instance.
</p>
</descr>
<version>
Modified in LCL version 4.0. The implementation for the most part is rewritten, 
and includes additional features not found in previous versions.
</version>
<seealso>
<link id="TTaskDialog"/>
<link id="#lcl.taskdlgemulation.TLCLTaskDialog">TLCLTaskDialog</link>
<link id="#lcl.lclclasses.TLCLComponent">TLCLComponent</link>
</seealso>
</element>

<!-- private -->
<element name="TCustomTaskDialog.FButton"/>
<element name="TCustomTaskDialog.FButtons"/>
<element name="TCustomTaskDialog.FCaption"/>
<element name="TCustomTaskDialog.FCollapseButtonCaption"/>
<element name="TCustomTaskDialog.FCommonButtons"/>
<element name="TCustomTaskDialog.FCustomFooterIcon"/>
<element name="TCustomTaskDialog.FCustomMainIcon"/>
<element name="TCustomTaskDialog.FDefaultButton"/>
<element name="TCustomTaskDialog.FExpandButtonCaption"/>
<element name="TCustomTaskDialog.FExpanded"/>
<element name="TCustomTaskDialog.FExpandedText"/>
<element name="TCustomTaskDialog.FFlags"/>
<element name="TCustomTaskDialog.FFooterIcon"/>
<element name="TCustomTaskDialog.FFooterText"/>
<element name="TCustomTaskDialog.FHandle"/>
<element name="TCustomTaskDialog.FMainIcon"/>
<element name="TCustomTaskDialog.FModalResult"/>
<element name="TCustomTaskDialog.FOnDialogConstructed"/>
<element name="TCustomTaskDialog.FOnDialogCreated"/>
<element name="TCustomTaskDialog.FOnDialogDestroyed"/>
<element name="TCustomTaskDialog.FOnExpanded"/>
<element name="TCustomTaskDialog.FOnHelp"/>
<element name="TCustomTaskDialog.FOnHyperlinkClicked"/>
<element name="TCustomTaskDialog.FOnNavigated"/>
<element name="TCustomTaskDialog.FOnRadioButtonClicked"/>
<element name="TCustomTaskDialog.FOnTimer"/>
<element name="TCustomTaskDialog.FOnVerificationClicked"/>
<element name="TCustomTaskDialog.FProgressBar"/>
<element name="TCustomTaskDialog.FQueryChoices"/>
<element name="TCustomTaskDialog.FQueryResult"/>
<element name="TCustomTaskDialog.FQueryItemIndex"/>
<element name="TCustomTaskDialog.FRadioButton"/>
<element name="TCustomTaskDialog.FRadioButtons"/>
<element name="TCustomTaskDialog.FTask"/>
<element name="TCustomTaskDialog.FTitle"/>
<element name="TCustomTaskDialog.FURL"/>
<element name="TCustomTaskDialog.FVerificationText"/>
<element name="TCustomTaskDialog.FWidth"/>
<element name="TCustomTaskDialog.FOnButtonClicked"/>

<element name="TCustomTaskDialog.IsCustomFooterIconStored"/>
<element name="TCustomTaskDialog.IsCustomFooterIconStored.Result"/>
<element name="TCustomTaskDialog.IsCustomMainIconStored"/>
<element name="TCustomTaskDialog.IsCustomMainIconStored.Result"/>
<element name="TCustomTaskDialog.SetButtons"/>
<element name="TCustomTaskDialog.SetButtons.Value"/>
<element name="TCustomTaskDialog.SetCustomFooterIcon"/>
<element name="TCustomTaskDialog.SetCustomFooterIcon.AValue"/>
<element name="TCustomTaskDialog.SetCustomMainIcon"/>
<element name="TCustomTaskDialog.SetCustomMainIcon.AValue"/>
<element name="TCustomTaskDialog.SetFlags"/>
<element name="TCustomTaskDialog.SetFlags.AValue"/>
<element name="TCustomTaskDialog.SetQueryChoices"/>
<element name="TCustomTaskDialog.SetQueryChoices.AValue"/>
<element name="TCustomTaskDialog.SetRadioButtons"/>
<element name="TCustomTaskDialog.SetRadioButtons.Value"/>

<!-- protected -->
<element name="TCustomTaskDialog.WSRegisterClass">
<short>
Registers the task dialog class in the widgetset when needed.
</short>
<descr>
<p>
Calls the factory routine in the widgetset implementation if it has not already been registered.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso/>
</element>

<element name="TCustomTaskDialog.DoExecute">
<short>
Performs actions to configure and execute the dialog.
</short>
<descr>
<p>
<var>DoExecute</var> is a <var>Boolean</var> function used to initialize and 
execute the task dialog form. It is called from the Execute method and uses the 
handle in ParentWnd as the parent form for the task dialog.
</p>
<p>
DoExecute sets the default values for properties used as return values for the 
dialog like ModalResult (mrNone) and QueryResult (''). It calls the Execute 
method in the widgetset class instance to perform the actions needed for the 
platform. On Windows Vista and later versions, this causes the native routines 
in the Win32 Task Dialog API to be called. For other platforms, including 
Windows versions prior to Vista, the emulated task dialog in TLCLTaskDialog is 
used in the widget.
</p>
<p>
Use the Flags property to specify which features or behaviors are enabled on 
the task dialog form.
</p>
<p>
DoExecute captures various return values from the widgetset class. These 
include:
</p>
<ul>
<li>
The button identifier used to close the dialog form.
</li>
<li>
The modal result value for the button identifier used to close the form.
</li>
<li>
The optional radio button selected on the dialog.
</li>
<li>
The value from a query control on the dialog and its index position in the 
query choices.
</li>
</ul>
<p>
The return value is <b>False</b> if the button identifier returned from the 
widget is a negative value. The return value is <b>True</b> if the dialog form 
was successfully displayed, and a valid button identifier was used to close the 
form - including when Esc, Alt+F4 or the Cancel button is used.
</p>
<remark>
This behavior is different than other LCL dialogs where a ModalResult of 
mrCancel would cause Execute / DoExecute to return <b>False</b>. This is 
consistent with the task dialog behavior in the Delphi VCL; the Delphi 
documentation states otherwise but it is incorrect.
</remark>
</descr>
<seealso>
<link id="TCustomTaskDialog.Execute"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TCustomTaskDialog.ModalResult"/>
<link id="TCustomTaskDialog.QueryResult"/>
<link id="TCustomTaskDialog.QueryItemIndex"/>
<link id="TCustomTaskDialog.Button"/>
<link id="TCustomTaskDialog.RadioButton"/>
<link id="#lcl.taskdlgemulation.TLCLTaskDialog">TLCLTaskDialog</link>
</seealso>
</element>
<version>
<p>
Modified in version 3.0 to use the tfForceNonNative flag to determine whether 
an emulated dialog is displayed.
</p>
<p>
Implementation modified in LCL 4.0.
</p>
</version>
<element name="TCustomTaskDialog.DoExecute.Result">
<short>
<b>True</b> if a valid button identifier was clicked in the dialog.
</short>
</element>
<element name="TCustomTaskDialog.DoExecute.ParentWnd">
<short>Handle for the Parent Window of the dialog.</short>
</element>

<element name="TCustomTaskDialog.DoOnButtonClicked">
<short>
Signals the OnButtonClicked event handler (when assigned) for the button with 
the specified modal result value.
</short>
<descr>
<p>
DoOnButtonClicked is called from the callback routine passed to the wrapper 
in LCLTaskDialog.
</p>
</descr>
<seealso/>
</element>
<element name="TCustomTaskDialog.DoOnButtonClicked.AModalResult">
<short>Modal result value signalled for the button click notification.</short>
</element>
<element name="TCustomTaskDialog.DoOnButtonClicked.ACanClose">
<short>
<b>True</b> if the dialog should be closed, or <b>False</b> to continue 
execution.
</short>
</element>

<element name="TCustomTaskDialog.DoOnRadioButtonClicked">
<short>
Sets the active radio button and signals the OnRadioButtonClicked event handler 
(when assigned).
</short>
<descr>
<p>
No actions are performed in the method if <var>OnRadioButtonClicked</var> has 
not been assigned.
</p>
<p>
Calls SetRadioButtonFromRadioIndex to set RadioButton to the control at the 
position specified in the <var>ButtonID</var> argument. RadioButton is set to 
<b>Nil</b> if ButtonID is not a valid position in RadioButtons.
</p>
<p>
DoOnRadioButtonClicked is called from the private OnRadioButtonClicked method 
in the TLCLTaskDialog class when an emulated task dialog is used for the 
platform.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.RadioButton"/>
<link id="TCustomTaskDialog.RadioButtons"/>
<link id="TCustomTaskDialog.SetRadioButtonFromRadioIndex"/>
<link id="TCustomTaskDialog.OnRadioButtonClicked"/>
<link id="#lcl.taskdlgemulation.TLCLTaskDialog">TLCLTaskDialog.OnRadioButtonClicked</link>
</seealso>
<notes>
<note>
OnRadioButtonClicked is a property in TCustomTaskDialog and a method in 
TLCLTaskDIalog. Confusing...
</note>
</notes>
</element>
<element name="TCustomTaskDialog.DoOnRadioButtonClicked.ButtonID">
<short>
Index value for the radio button locates and signalled in the method.
</short>
</element>

<element name="TCustomTaskDialog.DoOnDialogConstructed">
<short>
Signals the OnDialogConstructed event handler (when assigned).
</short>
<descr/>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.OnDialogConstructed"/>
<link id="TTaskDialogProgressBar.Initialize"/>
</seealso>
</element>

<element name="TCustomTaskDialog.DoOnDialogCreated">
<short>
Signals the OnDialogCreated event handler (when assigned).
</short>
<descr/>
<version>
Added in LCL version 4.0.
</version>
<seealso/>
</element>

<element name="TCustomTaskDialog.DoOnDialogDestroyed">
<short>
Signals the OnDialogDestroyed event handler (when assigned).
</short>
<descr/>
<version>
Added in LCL version 4.0.
</version>
<seealso/>
</element>

<element name="TCustomTaskDialog.DoOnExpandButtonClicked">
<short>
Updates the value in the Expanded property and signals the OnExpanded event 
handler (when assigned).
</short>
<descr/>
<version>
Added in LCL version 4.0.
</version>
<seealso/>
</element>
<element name="TCustomTaskDialog.DoOnExpandButtonClicked.Expanded">
<short>
New value for the Expanded property.
</short>
</element>

<element name="TCustomTaskDialog.DoOnTimer">
<short>
Signals the OnTimer event handler (when assigned) using the specified parameter 
values.
</short>
<descr/>
<version>
Added in LCL version 4.0.
</version>
<seealso/>
</element>
<element name="TCustomTaskDialog.DoOnTimer.TickCount">
<short>
Elapsed number of milliseconds since the timer was started.
</short>
</element>
<element name="TCustomTaskDialog.DoOnTimer.Reset">
<short>
Set to <b>True</b> to reset (cancel) the timer for the task dialog. 
<b>False</b> allows the timer to continue executing.
</short>
</element>

<element name="TCustomTaskDialog.DoOnVerificationClicked">
<short>
Updates Flags to reflect the checked state for the verification control and 
signals the OnVerificationClicked event handler (when assigned).
</short>
<descr/>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.Flags"/>
<link id="TCustomTaskDialog.OnVerificationClicked"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
</seealso>
</element>
<element name="TCustomTaskDialog.DoOnVerificationClicked.Checked">
<short>
State for the verification check box control on the dialog.
</short>
</element>

<element name="TCustomTaskDialog.DoOnHelp">
<short>
Signals the OnHelp event handler (when assigned).
</short>
<descr>
<p>
<var>DoOnHelp</var> is a method called to perform actions needed when the Help 
command is executed for the task dialog. It signals the OnHelp event handler 
(when assigned) to respond to the help request.
</p>
<p>
DoOnHelp is called when the widgetset handles a TDN_HELP task dialog 
notification message which occurs when the Help button is clicked. For 
platforms where an emulated task dialog form is used, it is called from the 
KeyDown method in the TLCLTaskDialog instance when the F1 key is pressed.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.OnHelp"/>
<link id="TCustomTaskDialog.Buttons"/>
<link id="#lcl.taskdlgemulation.TLCLTaskDialog.KeyDown">TLCLTaskDialog.KeyDown</link>
</seealso>
</element>

<element name="TCustomTaskDialog.DoOnHyperlinkClicked">
<short>
Updates the value in URL and signals the OnHyperlinkClicked event handler (when 
assigned).
</short>
<descr>
<p>
Called from the widgetset class instance when a hyperlink in Text, 
ExpandedText, or FooterText is clicked. Use Flags to enable hyperlinks in the 
text areas by including tfEnableHyperlinks in the property.
</p>
<p>
Use OnHyperlinkClicked to perform actions needed to handle the URL in the 
hyperlink.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.URL"/>
<link id="TCustomTaskDialog.OnHyperlinkClicked"/>
</seealso>
</element>
<element name="TCustomTaskDialog.DoOnHyperlinkClicked.AURL">
<short>
New value for the URL property, and the target for the hyperlink.
</short>
</element>

<element name="TCustomTaskDialog.DoOnNavigated">
<short>
Signals the OnNavigated event handler (when assigned).
</short>
<descr>
<p>
Requires use of pages in the Task Dialog; see
<url href="https://learn.microsoft.com/en-us/dotnet/api/system.windows.forms.taskdialogpage.navigate?view=windowsdesktop-7.0)">
TaskDialogPage.Navigate Method
</url>
which might be implemented in a derived class. The event handler must be in 
base class for Delphi compatibility.
</p>
</descr>
<seealso/>
</element>

<element name="TCustomTaskDialog.InternalSetDialogHandle">
<short>
Sets the value for the Handle property.
</short>
<descr>
<p>
<var>InternalSetDialogHandle</var> is called when the form instance for the 
dialog is created. For platforms using a native task dialog (Windows Vista or 
later), it is called from the callback routine in the widgetset when the 
TDN_DIALOG_CONSTRUCTED is handled for the widget. For platforms using an 
emulated task dialog, it is called when the TLCLTaskDialog instance executes 
the AfterConstruction method in the form instance. It updates the value in 
Handle before the OnDialogConstructed event is signalled for the class instance.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.Handle"/>
<link id="TCustomTaskDialog.OnDialogConstructed"/>
<link id="#lcl.taskdlgemulation.TLCLTaskDialog.AfterConstruction">TLCLTaskDialog.AfterConstruction</link>
</seealso>
</element>
<element name="TCustomTaskDialog.InternalSetDialogHandle.AHandle">
<short>
New value for the Handle property.
</short>
</element>

<element name="TCustomTaskDialog.SetRadioButtonFromRadioIndex">
<short>
Makes the radio button with the specified identifier the active RadioButton on 
the task dialog.
</short>
<descr>
<p>
<var>SetRadioButtonFromRadioIndex</var> is a method used to make the radio 
button specified in <var>AIndex</var> the active (or default) RadioButton on 
the task dialog.
</p>
<p>
<var>AIndex</var> is an Integer value which contains the button identifier for 
the radio button (not its ordinal position) selected from the RadioButtons on 
the dialog. The TTaskDialogButtons instance with the specified identifier is 
stored in the RadioButton property. RadioButton may be set to <b>Nil</b> if 
AIndex is not in the valid range for radio buttons starting at 
TaskDialogFirstRadioButtonIndex, or RadioButtons does not contain the 
identifier.
</p>
<p>
SetRadioButtonFromRadioIndex is called from methods like DoExecute and 
DoOnRadioButtonClicked.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.RadioButton"/>
<link id="TCustomTaskDialog.RadioButtons"/>
<link id="TCustomTaskDialog.DoExecute"/>
<link id="TCustomTaskDialog.DoOnRadioButtonClicked"/>
<link id="TTaskDialogButtons"/>
<link id="TTaskDialogBaseButtonItem"/>
<link id="TaskDialogFirstRadioButtonIndex"/>
</seealso>
</element>
<element name="TCustomTaskDialog.SetRadioButtonFromRadioIndex.AIndex">
<short/>
</element>

<element name="TCustomTaskDialog.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the overridden constructor for the class instance, and 
calls the inherited method on entry. Create allocates resources needed for 
properties like:
</p>
<ul>
<li>Buttons</li>
<li>RadioButtons</li>
<li>QueryChoices</li>
<li>CustomMainIcon</li>
<li>CustomFooterIcon</li>
<li>ProgressBar</li>
</ul>
<p>
Create sets the default values for the following properties:
</p>
<dl>
<dt>CommonButtons</dt>
<dd>Set to the value [tcbOk, tcbCancel].</dd>
<dt>DefaultButton</dt>
<dd>Set to tcbOK.</dd>
<dt>Flags</dt>
<dd>Set to [tfAllowDialogCancellation].</dd>
<dt>FooterIcon</dt>
<dd>Set to tdiNone.</dd>
<dt>MainIcon</dt>
<dd>Set to tdiInformation.</dd>
<dt>Handle</dt>
<dd>Set to the unassigned handle value (0).</dd>
</dl>
</descr>
<seealso>
<link id="TCustomTaskDialog.Buttons"/>
<link id="TCustomTaskDialog.CommonButtons"/>
<link id="TCustomTaskDialog.DefaultButton"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TCustomTaskDialog.FooterIcon"/>
<link id="TCustomTaskDialog.MainIcon"/>
<link id="TCustomTaskDialog.QueryChoices"/>
<link id="TCustomTaskDialog.RadioButtons"/>
<link id="TCustomTaskDialog.ProgressBar"/>
</seealso>
</element>
<element name="TCustomTaskDialog.Create.AOwner">
<short>Owner of the class instance.</short>
</element>

<element name="TCustomTaskDialog.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. It 
frees resources allocated for the Buttons, RadioButtons, QueryChoices, 
CustomFooterIcon, CustomMainIcon, and ProgressBar properties. It calls the 
inherited method prior to exit.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.Buttons"/>
<link id="TCustomTaskDialog.RadioButtons"/>
<link id="TCustomTaskDialog.QueryChoices"/>
<link id="TCustomTaskDialog.CustomFooterIcon"/>
<link id="TCustomTaskDialog.CustomMainIcon"/>
<link id="TCustomTaskDialog.ProgressBar"/>
</seealso>
</element>

<element name="TCustomTaskDialog.ButtonIDToModalResult">
<short>
Gets the modal result value for the button with the specified identifier.
</short>
<descr>
<p>
<var>ButtonIDToModalResult</var> is a <var>TModalResult</var> function used to 
get the modal result value for the button with the identifier specified in the 
<var>AButtonID</var> argument.
</p>
<p>
AButtonID contains one of the button identifier constants which correspond to 
the standard Buttons used on the task dialog, including:
</p>
<ul>
<li>IDOK</li>
<li>IDCANCEL</li>
<li>IDABORT</li>
<li>IDRETRY</li>
<li>IDIGNORE</li>
<li>IDYES</li>
<li>IDNO</li>
<li>IDCLOSE</li>
</ul>
<p>
If AButtonID is in the range of button identifiers starting at 
TaskDialogFirstButtonIndex, but is not found in Buttons, the value in AButtonID 
is used in the return value. If the identifier is valid for and found in 
Buttons, the return value is set to one the modal result constants like:
</p>
<ul>
<li>mrOK</li>
<li>mrCancel</li>
<li>mrAbort</li>
<li>mrRetry</li>
<li>mrIgnore</li>
<li>mrYes</li>
<li>mrNo</li>
<li>mrClose</li>
<li>mrNone</li>
</ul>
<p>
The return value is set to mrNone if AButtonID is not valid for or not found in 
the Buttons collection.
</p>
<p>
ButtonIDToModalResult is called from the DoExecute method using the button 
identifier returned from the Execute method in the widgetset class instance.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.Buttons"/>
<link id="TaskDialogFirstButtonIndex"/>
<link id="TTaskDialogButtons"/>
<link id="TTaskDialogBaseButtonItem.ModalResult"/>
<link id="#lcl.forms.TModalResult">TModalResult</link>
</seealso>
</element>
<element name="TCustomTaskDialog.ButtonIDToModalResult.Result">
<short>
Modal result value for the button with the specified identifier.
</short>
</element>
<element name="TCustomTaskDialog.ButtonIDToModalResult.AButtonID">
<short>
Numeric identifier for the button with the modal result value returned in the 
method.
</short>
</element>

<element name="TCustomTaskDialog.Execute">
<short>Displays the task dialog and captures the modal result value.</short>
<descr>
<p>
<var>Execute</var> is an overloaded <var>Boolean</var> function used to 
display the dialog and capture the value for the ModalResult property. The 
parameterless variant is normally called to display and execute the dialog 
form. It gets the handle for the active form which is used as the parent for 
the task dialog form from the Screen singleton. If a TCustomForm has not been 
assigned in Screen, the unassigned handle value (0) is used. The overloaded 
variant is called using the handle value as an argument.
</p>
<p>
Execute calls the <var>DoExecute</var> method to perform actions needed to 
initialize and display the dialog form. It also processes return values used in 
properties like ModalResult, QueryResult, QueryItemIndex, Button, and 
RadioButton.
</p>
<p>
The return value is <b>True</b> if the dialog was successfully displayed and a 
valid button identifier was clicked to close the dialog - including when Esc, 
Alt+F4 or the Cancel button is used.
</p>
<remark>
This behavior is different than other LCL dialogs where a ModalResult of 
mrCancel would cause Execute / DoExecute to return <b>False</b>. This is 
consistent with the task dialog behavior in the Delphi VCL; the Delphi 
documentation states otherwise but it is incorrect.
</remark>
</descr>
<seealso>
<link id="TCustomTaskDialog.DoExecute"/>
<link id="TCustomTaskDialog.ModalResult"/>
<link id="TCustomTaskDialog.Button"/>
<link id="TCustomTaskDialog.RadioButton"/>
<link id="TCustomTaskDialog.QueryResult"/>
<link id="TCustomTaskDialog.QueryItemIndex"/>
</seealso>
</element>
<element name="TCustomTaskDialog.Execute.Result">
<short>
<b>True</b> if a valid button identifier was selected in the dialog.
</short>
</element>
<element name="TCustomTaskDialog.Execute.ParentWnd">
<short>
Parent window handle used to position the dialog in the LCLTaskDialog wrapper.
</short>
</element>

<element name="TCustomTaskDialog.Button">
<short>Not used in the current LCL version.</short>
<descr>
<p>
<var>Button</var> is a <var>TTaskDialogButtonItem</var> property. It is not 
used in the current LCL version.
</p>
</descr>
<seealso/>
</element>

<element name="TCustomTaskDialog.Buttons">
<short>
Collection with the buttons for the Task dialog.
</short>
<descr>
<p>
<var>Buttons</var> is a <var>TTaskDialogButtons</var> property with the 
collection that contains the buttons for the Task dialog. Values in Buttons 
and <var>CommonButtons</var> are used in the <var>DoExecute</var> method to 
define the button identifiers and modal result values available in the 
<file>LCLTaskDialog</file> wrapper.
</p>
</descr>
<seealso/>
</element>

<element name="TCustomTaskDialog.Caption">
<short>Caption text displayed on the title bar for the Task dialog.</short>
<descr>
<p>
<var>Caption</var> is a <var>TTranslateString</var> property with the text 
displayed on the title bar for the Task dialog. Caption can be localized 
using the LCL translation facilities.
</p>
<p>
Use <var>Title</var> to set the text displayed as the title in the main 
content area. Use <var>Text</var> to set the text displayed beneath the Title 
in the main content area. Use <var>ExpandedText</var> to set the text 
displayed in the expandable content area for the dialog. Use 
<var>FooterText</var> to set the text displayed in the footer aread for the 
dialog.
</p>
</descr>
<seealso/>
</element>

<element name="TCustomTaskDialog.CustomFooterIcon">
<short>
Contains a custom icon displayed in the footer area on the dialog.
</short>
<descr>
<p>
<var>CustomFooterIcon</var> is a <var>TIcon</var> property which contains the 
custom icon used in the footer area on the task dialog. It allows an icon other 
than one of the built-in resources in FooterIcon to be used in the content 
area. The image content can be loaded at design-time using the property editor 
in the Object Inspector, or assigned at run-time prior to calling Execute for 
the task dialog.
</p>
<p>
The property value is stored during component streaming when an icon has been 
assigned to the property and its image data is not empty. Otherwise, it is 
omitted from the LFM resource.
</p>
<p>
The handle for the custom icon image is used when the execute method in the 
widgetset class instance is called. Include the value tfUseHIconFooter in the 
Flags property to enable use of the handle in the widget instance instead of a 
handle for one of the built-in icon resources.
</p>
<p>
Use FooterIcon to select one the standard built-in icons for use in the footer 
the content area.
</p>
<p>
Use MainIcon or CustomMainIcon to specify the icon displayed in the main 
content area on the task dialog.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.FooterIcon"/>
<link id="TCustomTaskDialog.MainIcon"/>
<link id="TCustomTaskDialog.CustomMainIcon"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
<link id="#lcl.graphics.TIcon">TIcon</link>
</seealso>
</element>

<element name="TCustomTaskDialog.CustomMainIcon">
<short>
Contains a custom icon displayed in the main content area on the dialog.
</short>
<descr>
<p>
<var>CustomMainIcon</var> is a <var>TIcon</var> property which contains the 
custom icon used in the main content area on the task dialog. It allows an icon 
other than one of the built-in resources in MainIcon to be used in the content 
area. The image content can be loaded at design-time using the property editor 
in the Object Inspector, or assigned at run-time prior to calling Execute for 
the task dialog.
</p>
<p>
The property value is stored during component streaming when an icon has been 
assigned to the property and its image data is not empty. Otherwise, it is 
omitted from the LFM resource.
</p>
<p>
The handle for the custom icon image is used when the Execute method in the 
widgetset class instance is called. Include the value tfUseHIconMain in the 
Flags property to enable use of the handle in the widget instance instead of a 
handle for one of the built-in icon resources.
</p>
<p>
Use MainIcon to select one the standard built-in icons for use in the main 
content area.
</p>
<p>
Use FooterIcon or CustomFooterIcon to specify the icon displayed in the footer 
content area on the task dialog.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.MainIcon"/>
<link id="TCustomTaskDialog.FooterIcon"/>
<link id="TCustomTaskDialog.CustomFooterIcon"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
<link id="#lcl.graphics.TIcon">TIcon</link>
</seealso>
</element>

<element name="TCustomTaskDialog.CommonButtons">
<short>Set of common buttons displayed on the Task dialog.</short>
<descr>
<p>
<var>CommonButtons</var> is a <var>TTaskDialogCommonButtons</var> property 
with the set of common buttons displayed on the Task dialog. Values from the 
<var>TTaskDialogCommonButton</var> enumeration are included in the set to 
make buttons visible. Values are excluded from the set to remove the buttons. 
The default value for the property is <var>[tcbOk, tcbCancel]</var>, and 
enables the <b>OK</b> and <b>Cancel</b> buttons for the Task dialog.
</p>
<p>
CommonButtons is used in conjunction with the <var>Buttons</var> collection, 
which contains custom button definitions that do not fit the common button 
definitions. Both CommonButtons and Buttons are used in <var>DoExecute</var>, 
and passed as arguments to the wrapper in <file>LCLTaskDialog</file>.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.Buttons"/>
<link id="TCustomTaskDialog.DoExecute"/>
<link id="TCustomTaskDialog.Execute"/>
<link id="TTaskDialogCommonButtons"/>
<link id="TTaskDialogCommonButton"/>
</seealso>
</element>

<element name="TCustomTaskDialog.CollapseButtonCaption">
<short>
Caption text for the "expando" button on the task dialog.
</short>
<descr>
<p>
<var>CollapseButtonCaption</var> is a <var>TTranslateString</var> property with 
the text displayed next to the "expando" button for the dialog when Expanded is 
set to <b>True</b>. It describes the action performed the next time the button 
is clicked. When omitted (or set to an empty string), the value 'Hide details' 
is used.
</p>
<p>
The property value can be localized using the translation facilities provided 
in the Lazarus IDE when enabled for a project, or by manually calling the 
translation routines in LazUtils.
</p>
<p>
Use ExpandButtonCaption to specify the caption displayed when the content in 
ExpandedText is collapsed (Expanded is set to <b>False</b>).
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.ExpandButtonCaption"/>
<link id="TCustomTaskDialog.Expanded"/>
<link id="TCustomTaskDialog.ExpandedText"/>
<link id="#lcl.lcltype.TTranslateString">TTranslateString</link>
</seealso>
</element>

<element name="TCustomTaskDialog.DefaultButton">
<short>
Index of the default button, from the set in the CommonButtons property.
</short>
<descr>
<p>
<var>DefaultButton</var> is <var>TTaskDialogCommonButton</var> property which 
indicates the default button for the Task dialog. It represents the button 
that is clicked if the user presses the Space or Enter key when the Task 
dialog is initially displayed.
</p>
<p>
The property contains one of the values from the <var>CommonButtons</var> 
property. The default value for the property is <var>tcbOK</var>, and 
represents the <b>OK</b> button.
</p>
<p>
It is used to set the default modal result value returned during execution 
when a <var>DefaultButton</var> has not been specified in the 
<var>Buttons</var> collection.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.CommonButtons"/>
<link id="TCustomTaskDialog.Buttons"/>
<link id="TTaskDialogButtons.DefaultButton"/>
<link id="TTaskDialogCommonButton"/>
</seealso>
</element>

<element name="TCustomTaskDialog.ExpandButtonCaption">
<short>Caption displayed for the expand/collapse button on the dialog.</short>
<descr>
<p>
<var>ExpandButtonCaption</var> is a TTranslateString property with the 
caption text displayed beside the button used to expand or collapse the 
ExpandedText on the Task dialog. The property value can be localized using 
the standard LCL translation facilities.
</p>
<p>
The default value for the property is an empty String (''), and cause the 
values "See details" or "Hide details" to be used on the Task dialog (when 
the language is English).
</p>
<p>
Use CollapseButtonCaption to assign the caption displayed when ExpandedText is 
Expanded.
</p>
<p>
Use the Flags property to control the position (tfExpandFooterArea) or the 
expanded / collapsed state (tfExpandedByDefault) for the ExpandedText on the 
Task dialog.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.ExpandedText"/>
<link id="TCustomTaskDialog.CollapseButtonCaption"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
<link id="#lcl.lcltype.TTranslateString">TTranslateString</link>
</seealso>
</element>

<element name="TCustomTaskDialog.ExpandedText">
<short>
Text that is displayed in the expandable / collapsible area on the Task 
dialog.
</short>
<descr>
<p>
ExpandedText is a TTranslateString property with the text displayed in the 
expandable / collapsible area on the Task dialog. Its value can be localized 
using the standard LCL translation facilities. It can contain multi-line text 
when line ending characters (#13,#10) are embedded in the String value. For 
example:
</p>
<code>
ADialog.ExpandedText := 'Please read the Terms of Service.'+#10+
  'Available on our Website.';
</code>
<p>
Or, the multi-line value can be entered in the object inspector using the 
property editor at design-time.
</p>
<p>
Text, ExpandedText, and FooterText allow an HTML-like hyperlinking capability 
(as seen in the previous code example). The feature must be enabled by 
including tfEnableHyperlinks in the Flags property. Use tfExpandFooterArea to 
control the position for the expanded text, or tfExpandedByDefault to expand 
or collapse the text area.
</p>
</descr>
<version>
Multi-line property editors in the object inspector were enabled in Lazarus 
version 2.2.0.
</version>
<seealso>
<link id="TCustomTaskDialog.Flags"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
<link id="#lcl.lcltype.TTranslateString">TTranslateString</link>
</seealso>
</element>

<element name="TCustomTaskDialog.Flags">
<short>
Set of options enabled for the Task dialog.
</short>
<descr>
<p>
<var>Flags</var> is a <var>TTaskDialogFlags</var> property with the set of 
options enabled for the Task dialog. It contains zero or more values from the 
TTaskDialogFlag enumeration, which when included, enable the corresponding 
features in the Task Dialog. The default value for the property is 
[tfAllowDialogCancellation] and allows the dialog to be cancelled using the 
Esc key or Alt+F4 key combination.
</p>
<p>
Changing the property value causes validation and normalization of the flag 
values to be performed. tfQuery and tfSimpleQuery are mutually exclusive 
values; if both are specified in the property value, then tfSimpleQuery is 
excluded from the new property value. In addition, tfQuery and tfSimpleQuery 
causes other flag values to be ignored, and certain features are disabled. 
They cause the expando control (expand or collapse indicator) to be hidden and
ExpandedText is displayed in the expanded state (tfExpandedByDefault). 
Hyperlinks (tfEnableHyperlinks) are disabled when tfQuery or tfSimpleQuery is 
included in the property; the markup for the hyperlink is still displayed in 
the text areas though.
</p>
<p>
See <link id="TTaskDialogFlag">TTaskDialogFlag</link> for the complete list of 
enumeration values allowed in the property and their meanings.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.ExpandedText"/>
<link id="TCustomTaskDialog.FooterText"/>
<link id="TCustomTaskDialog.Text"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
</seealso>
</element>

<element name="TCustomTaskDialog.FooterIcon">
<short>Icon for the footer area displayed at the bottom of the dialog.</short>
<descr>
<p>
<var>FooterIcon</var> is a <var>TTaskDialogIcon</var> property with a value 
which identifies the icon displayed in the footer area for the Task dialog. 
The footer icon is displayed beside the optional text in 
<var>FooterText</var>. The default value for the property is 
<var>tdiNone</var>, and causes the icon to be omitted. See 
<var>TTaskDialogIcon</var> for information about the values in the 
enumeration and their meanings.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.FooterText"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TTaskDialogIcon"/>
</seealso>
</element>

<element name="TCustomTaskDialog.FooterText">
<short>
Text that is displayed in the footer area on the Task dialog.
</short>
<descr>
<p>
<var>FooterText</var> is a <var>TTranslateString</var> property with the text 
displayed in the footer area on the Task dialog. Its value can be localized 
using the standard LCL translation facilities. It can contain multi-line text 
when line ending characters (#13,#10) are embedded in the String value. For 
example:
</p>
<code>
ADialog.FooterText := '(c) Copyright 1960-2021, Acme Corporation LLC.' + 
  #10 + 'All rights reserved.';
</code>
<p>
Or, the multi-line value can be entered in the object inspector using the 
property editor at design-time.
</p>
<p>
Text, ExpandedText, and FooterText allow an HTML-like hyperlinking capability 
using the &lt;a href=""&gt;Link Text&lt;/a&gt; notation. The feature must be 
enabled by including tfEnableHyperlinks in the Flags property. Use 
tfExpandFooterArea to position the expanded text in the footer area.
</p>
</descr>
<version>
Multi-line property editors in the object inspector were enabled in Lazarus 
version 2.2.0.
</version>
<seealso>
<link id="TCustomTaskDialog.FooterIcon"/>
<link id="TCustomTaskDialog.Text"/>
<link id="TCustomTaskDialog.ExpandedText"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
<link id="#lcl.lcltype.TTranslateString">TTranslateString</link>
</seealso>
</element>

<element name="TCustomTaskDialog.MainIcon">
<short>Icon displayed beside the Title for the dialog.</short>
<descr>
<p>
<var>MainIcon</var> is a <var>TTaskDialogIcon</var> with a value that 
identifies the icon displayed beside the <var>Title</var> for the Task 
dialog. The default value is <var>tdiInformation</var>, and causes a blue 
circle with a Question Mark to be displayed as the icon. See 
<var>TTaskDialogIcon</var> for more information about the values in the 
enumeration and their meanings.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.Title"/>
<link id="TCustomTaskDialog.Text"/>
<link id="TCustomTaskDialog.ExpandedText"/>
<link id="TCustomTaskDialog.FooterText"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TTaskDialogIcon"/>
</seealso>
</element>

<element name="TCustomTaskDialog.Handle">
<short>
Handle for the form displayed for the task dialog.
</short>
<descr>
<p>
<var>Handle</var> is a read-only <var>THandle</var> property which contains the 
handle for the dialog form displayed for the task dialog. The value for the 
property is assigned when the form has been created in the widgetset class 
instance. For platforms using a native task dialog (Windows Vista or later), it 
is assigned when the TDN_DIALOG_CONSTRUCTED notification is handled in the 
callback routine for the widget. For platforms using an emulated task dialog, 
it is assigned when the AfterConstruction method for the TLCLTaskDialog instance
is called.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<notes>
<note>Should this use the TLCLHandle type?</note>
</notes>
<seealso>
<link id="TCustomTaskDialog.InternalSetDialogHandle"/>
<link id="TCustomTaskDialog.OnDialogConstructed"/>
<link id="#lcl.taskdlgemulation.TLCLTaskDialog.AfterConstruction">TLCLTaskDialog.AfterConstruction</link>
</seealso>
</element>

<element name="TCustomTaskDialog.ModalResult">
<short>Modal result value returned when the Task dialog was executed.</short>
<descr>
<p>
<var>ModalResult</var> is a <var>TModalResult</var> property with the modal 
result value returned when the Task dialog was executed. It contains the 
corresponding value from the <var>Button</var> used to close the Task dialog, 
<var>DefaultButton</var> if <b>Enter</b> or <b>Space</b> was pressed when the 
dialog was displayed, or <var>mrNone</var> if the dialog was cancelled.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.Buttons"/>
<link id="TCustomTaskDialog.Button"/>
<link id="TCustomTaskDialog.DefaultButton"/>
<link id="TCustomTaskDialog.Execute"/>
</seealso>
</element>

<element name="TCustomTaskDialog.ProgressBar">
<short>
Contains information used to configure and update a progress bar enabled on the 
task dialog.
</short>
<descr>
<p>
<var>ProgressBar</var> is a <var>TTaskDialogProgressBar</var> property which 
contains range, position, and state information for a progress bar enabled on 
the task dialog. Changes to property values in ProgressBar cause the widgetset 
class to be updated and redrawn. The Handle for the dialog is used to send task 
dialog messages to the widget with the new values for the members.
</p>
<p>
Use the Flags property to enable a progress bar on the task dialog. 
tfShowProgressBar enables a conventional progress bar which displays completion 
percentage. tfShowMarqueeProgressBar enables the scrolling marquee-style 
progress bar.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TTaskDialogProgressBar"/>
</seealso>
</element>

<element name="TCustomTaskDialog.QueryChoices">
<short>
Predefined values for the query control on the task dialog.
</short>
<descr>
<p>
<var>QueryChoices</var> is a <var>TStrings</var> property with a list of 
predefined values that can be selected in the query control on the task 
dialog. Values in QueryChoices are displayed in a TComboBox control created for 
the task dialog when tfQuery has been included in the Flags property. Include 
tfQueryFixedChoices in Flags to make the values in QueryChoices read-only in 
the combo-box control.
</p>
<p>
Use QueryItemIndex to determine which value is initially selected in 
QueryChoices, or returned when the task dialog was executed. Use QueryResult to 
access the string value returned in the query control.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.Flags"/>
<link id="TCustomTaskDialog.QueryItemIndex"/>
<link id="TCustomTaskDialog.QueryResult"/>
<link id="TCustomTaskDialog.Execute"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
</seealso>
</element>

<element name="TCustomTaskDialog.QueryItemIndex">
<short>
Ordinal position for the value in QueryChoices selected when the task dialog 
is executed.
</short>
<descr>
<p>
<var>QueryItemIndex</var> is an <var>Integer</var> property which contains the 
ordinal position for the selected value in the QueryChoices on the dialog. It 
contains the initial item in QueryChoices selected when the Execute method is 
called. It is updated with the option selected during execution of the dialog 
form.
</p>
<p>
Use QueryResult to access the string value for the selected item in 
QueryChoices.
</p>
<p>
QueryItem and QueryResult are relevant when tfQuery has been included in the 
Flags for the task dialog.
</p>
<p>
Use ModalResult to determine the button or key combination used to complete 
execution of the dialog form.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.QueryChoices"/>
<link id="TCustomTaskDialog.QueryResult"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TCustomTaskDialog.Execute"/>
<link id="TCustomTaskDialog.ModalResult"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
</seealso>
</element>

<element name="TCustomTaskDialog.QueryResult">
<short>
String representation for the query entered or selected on the dialog form.
</short>
<descr>
<p>
<var>QueryResult</var> is a <var>String</var> property with the value for the 
query control dialog form. The content may reflect either the SimpleQuery or 
the selected value in QueryChoices for the class instance.
</p>
<p>
Use Flags to specify which editing control and mode are used to capture the 
query value (tfSimpleQuery for SimpleQuery and tfQuery for QueryChoices).
</p>
<p>
QueryResult is set to an empty string ('') when the Execute method is called, 
and updated prior to exit.
</p>
<p>
Use ModalResult to determine the button or key press used to complete execution 
of the task dialog. The value in QueryResult is set to the respective source 
even when Esc or Alt+F4 is used to cancel the task dialog.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.QueryChoices"/>
<link id="TCustomTaskDialog.QueryItemIndex"/>
<link id="TCustomTaskDialog.SimpleQuery"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TCustomTaskDialog.Execute"/>
<link id="TCustomTaskDialog.DoExecute"/>
<link id="TCustomTaskDialog.ModalResult"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
</seealso>
</element>

<element name="TCustomTaskDialog.RadioButton">
<short>The radio button selected on the Task dialog.</short>
<descr>
<p>
<var>RadioButton</var> is a read-only <var>TTaskDialogRadioButtonItem</var> 
property with the radio button selected when the Task dialog was executed. The 
property value is set in the Execute method, and contains an entry from the 
RadioButtons collection or <b>Nil</b> if a radio button was not selected or 
available.
</p>
<p>
Use the Default property in one of the RadioButtons to indicate the selected 
radio button control when the Execute method is called.
</p>
<p>
Include tfNoDefaultRadioButton in the Flags property to disable automatic 
selection of a default radio button on the dialog form.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.RadioButtons"/>
<link id="TCustomTaskDialog.Execute"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TCustomTaskDialog.DoExecute"/>
<link id="TTaskDialogRadioButtonItem"/>
</seealso>
</element>

<element name="TCustomTaskDialog.RadioButtons">
<short>
Collection with the optional radio buttons defined for the Task dialog.
</short>
<descr>
<p>
<var>RadioButtons</var> is a <var>TTaskDialogButtons</var> property with the 
collection of defined radio buttons for the Task dialog.
</p>
<p>
Radio buttons are displayed in the main content area for the Task dialog, 
below the values in <var>Text</var> and <var>ExpandedText</var>. Use of radio 
buttons is optional. They are displayed when items have been added to the 
collection. The <var>TTaskDialogRadioButtonItem</var> items in the collection 
are passed as an argument when the <var>Execute</var> method is called.
</p>
<p>
Use the <var>RadioButton</var> property to determine the radio button 
selected on the Task dialog.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.Execute"/>
<link id="TCustomTaskDialog.RadioButton"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TTaskDialogButtons"/>
<link id="TTaskDialogRadioButtonItem"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
</seealso>
</element>

<element name="TCustomTaskDialog.SimpleQuery">
<short>
Contains the text displayed and edited using the query control on the task 
dialog.
</short>
<descr>
<p>
<var>SimpleQuery</var> is a <var>String</var> property which contains free-form 
text maintained using the query control for the task dialog. A single-line edit 
control is used to display and edit the value for the property.
</p>
<p>
SimpleQuery is displayed on the dialog when tfSimpleQuery has been included in 
the Flags property. Please note that tfQuery and tfSimpleQuery flag values are 
mutually exclusive with tfQuery taking precedence.
</p>
<p>
Use QueryChoices if predefined choices selected using a combo-box control are 
needed on the task dialog.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.SimpleQueryPasswordChar"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
</seealso>
</element>

<element name="TCustomTaskDialog.SimpleQueryPasswordChar">
<short>
Character value used to obfuscate text in SimpleQuery for the query control.
</short>
<descr>
<p>
The default value for the property is #0 (NULL character) and indicates that 
obfuscation is not enabled for the simple query control. Another character 
stored in the property is used to obfuscate the characters entered in the 
SimpleQuery property.
</p>
<p>
SimpleQueryPasswordChar is used when tfSimpleQuery has been included in the 
Flags for the task dialog.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.SimpleQuery"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
</seealso>
</element>

<element name="TCustomTaskDialog.Text">
<short>
Text displayed as main content for the Task dialog.
</short>
<descr>
<p>
<var>Text</var> is a <var>TTranslateString</var> property with the text 
displayed in the main content area on the Task dialog. Its value can be 
localized using the standard LCL translation facilities. It can contain 
multi-line text when line ending characters (#13,#10) are embedded in the 
String value. For example:
</p>
<code>
ADialog.Text := 'Please read and accept the Terms of Service. ' + #10 + 
'You must agree before the application can be installed.';
</code>
<p>
Or, the multi-line value can be entered in the object inspector using the 
property editor at design-time.
</p>
<p>
Text, ExpandedText, and FooterText allow an HTML-like hyperlinking capability 
using the &lt;a href="linktarget"&gt;Link Text&lt;/a&gt; notation. The 
feature must be enabled by including tfEnableHyperlinks in the Flags property.
</p>
<p>
Use ExpandedText to set the content in the collapsible area on the Task 
dialog. Use tfExpandFooterArea in the Flags property to position the expanded 
text in the footer area.
</p>
</descr>
<version>
Multi-line property editors in the object inspector were enabled in Lazarus 
version 2.2.0.
</version>
<seealso>
<link id="TCustomTaskDialog.ExpandedText"/>
<link id="TCustomTaskDialog.FooterText"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
<link id="#lcl.lcltype.TTranslateString">TTranslateString</link>
</seealso>
</element>

<element name="TCustomTaskDialog.Title">
<short>
Text displayed at the top of dialog adjacent to the main icon.
</short>
<descr>
<p>
<var>Title</var> is a <var>TTranslateString</var> property which contains text 
displayed at the top of dialog using a larger font size and a highlighted, bold 
font style. Title is displayed adjacent to the MainIcon for the dialog (when 
used).
</p>
<p>
Title can be localized using the Lazarus IDE translation facilities when 
enabled in the project, or by calling translation routines in LazUtils.
</p>
<p>
Use Caption to assigned the value displayed on the window header for the task 
dialog form.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.MainIcon"/>
<link id="TCustomTaskDialog.Caption"/>
<link id="TCustomTaskDialog.Text"/>
<link id="TCustomTaskDialog.ExpandedText"/>
<link id="TCustomTaskDialog.FooterText"/>
<link id="TCustomTaskDialog.ExpandButtonCaption"/>
</seealso>
</element>

<element name="TCustomTaskDialog.VerificationText">
<short>
Optional caption for the verification check box displayed near the bottom of 
the Task dialog.
</short>
<descr>
<p>
<var>VerificationText</var> is a <var>TTranslateString</var> property with the 
text displayed next to a verification check box enabled on the dialog. The 
verification check box is omitted from the task dialog (even when 
tfVerificationFlagChecked is enabled in Flags) if VerificationText is an empty 
string ('').
</p>
<p>
VerificationText can be localized using the Lazarus IDE translation facilities 
when enabled in the project, or by calling translation routines in LazUtils.
</p>
<p>
Use OnVerificationClicked to perform actions needed when the verification check 
box is clicked on the dialog.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.Flags"/>
<link id="TCustomTaskDialog.OnVerificationClicked"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
</seealso>
</element>

<element name="TCustomTaskDialog.Width">
<short>
Sets the width in pixels for the task dialog form.
</short>
<descr>
<p>
<var>Width</var> is an <var>Integer</var> property which sets the width (in 
pixels) for the task dialog form. The default value for the property is 0 
(zero), and causes the width for the dialog form to be calculated when the 
dialog is executed using the length of its textual content and controls.
</p>
<p>
Width is passed as an argument to the Execute method in the TTaskDialog 
instance used in the class.
</p>
<p>
Please note that an emulated task dialog form imposes a lower limit (120 
pixels) or an upper limit (480 pixels) on the auto-calculated width.
</p>
</descr>
<seealso>
<link id="TCustomTaskDialog.Text"/>
<link id="TCustomTaskDialog.ExpandedText"/>
<link id="TCustomTaskDialog.Execute"/>
</seealso>
</element>

<element name="TCustomTaskDialog.URL">
<short>
Universal Resource Locator (or identifier) for a hyperlink clicked on the task 
dialog.
</short>
<descr>
<p>
<var>URL</var> is a read-only <var>String</var> property which contains the 
resource identifier for a hyperlink clicked in one of the text areas for the 
task dialog.
</p>
<p>
Include tfEnableHyperlinks in the Flags property to enable hyperlinks in text 
areas on the task dialog like Text, ExpandedText, and FooterText.
</p>
<p>
Hyperlinks are written using the common HTML Anchor notation:
</p>
<code>
&lt;a href="https://forum.lazarus.freepascal.org/"&gt;Lazarus Forum&lt;/a&gt;
</code>
<p>
Use the OnHyperlinkClicked event handler to perform any actions needed to 
locate, open, or display content represented by the value in URL. Please note 
that URL can contain any valid URI.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.Flags"/>
<link id="TCustomTaskDialog.Text"/>
<link id="TCustomTaskDialog.ExpandedText"/>
<link id="TCustomTaskDialog.FooterText"/>
<link id="TCustomTaskDialog.OnHyperlinkClicked"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
</seealso>
</element>

<element name="TCustomTaskDialog.Expanded">
<short>
Indicates the expanded or collapsed state for the ExpandedText on the task 
dialog form.
</short>
<descr>
<p>
<var>Expanded</var> is a read-only <var>Boolean</var> property which indicates 
whether the content in ExpandedText is currently displayed in the expanded or 
collapsed state. The property value is updated each time the expando control 
(expand / collapse indicator) is clicked.
</p>
<p>
When set to <b>True</b>b>, the values in ExpandedText ar displayed in the 
expanded state on its text area. Otherwise the values in ExpandText are not 
visible on the dialog.
</p>
<remark>
Expanded is always <b>True</b> when tfquery or tfSimpleQuery is included in the 
Flags for the dialog. In addition, the expando control is not displayed on the 
dialog.
</remark>
<p>
Use the OnExpanded event handler to perform actions needed after the property 
value has been updated in the task dialog.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.ExpandedText"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TCustomTaskDialog.OnExpanded"/>
<link id="TTaskDialogFlag"/>
<link id="TTaskDialogFlags"/>
</seealso>
</element>

<element name="TCustomTaskDialog.OnButtonClicked">
<short>
Event handler signalled for the button clicked when the Task dialog was 
executed.
</short>
<descr>
<p>
<var>OnButtonClicked</var> is a <var>TTaskDlgClickEvent</var> property with the 
event handler signalled (when assigned) after a button is clicked on the task 
dialog during execution. It is signalled from the DoOnButtonClicked method.
</p>
<p>
Arguments passed to the TTaskDlgClickEvent event handler include the 
TTaskDialog instance, the modal result value, and a Boolean flag which 
indicates if the dialog can be closed. Setting the CanClose argument to 
<b>False</b> in the handler routine causes the dialog to continue its Execute 
processing loop.
</p>
</descr>
<seealso/>
</element>

<element name="TCustomTaskDialog.OnDialogConstructed">
<short>
Event handler signalled when the constructor for the dialog form instance has 
completed.
</short>
<descr>
<p>
<var>OnDialogConstructed</var> is a <var>TNotifyEvent</var> property with the 
event handler signalled when the constructor for the task dialog has completed. 
It is signalled (when assigned) from the DoOnDialogConstructed method.
</p>
<p>
For native implementations using the Task Dialog API (supported Windows 
versions), it occurs when the TDN_DIALOG_CONSTRUCTED notification is handled in 
the callback routine for the class instance. For emulated task dialog forms, it 
occurs when the overridden AfterConstruction method is called.
</p>
<p>
Applications can implement a handler routine to perform actions needed when the 
dialog form has been allocated but not yet displayed or executed for the
class instance.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.DoOnDialogConstructed"/>
<link id="#lcl.taskdlgemulation.TLCLTaskDialog.CreateNew">TLCLTaskDialog.CreateNew</link>
</seealso>
</element>

<element name="TCustomTaskDialog.OnDialogCreated">
<short>
Event handler signalled when a form instance has been created for the dialog.
</short>
<descr>
<p>
<var>OnDialogCreated</var> is a <var>TNotifyEvent</var> property with the
event handler signalled after a new dialog form instance has been created for 
the class. It is signalled (when assigned) in the DoOnDialogCreated method, and 
occurs when the dialog form is created for the class instance. 
</p>
<p>
For native implementations using the Task Dialog API (supported Windows 
versions), it occurs when the TDN_CREATED notification is handled in the 
callback routine for the class instance. For emulated task dialog forms, it 
occurs when the TLCLTaskDialog.CreateNew method is called. It is the last 
action performed in the method, and allows the caller to be notified when the 
LCL form instance is valid and available to the TTaskDialog owner.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.DoOnDialogCreated"/>
<link id="#lcl.taskdlgemulation.TLCLTaskDialog.CreateNew">TLCLTaskDialog.CreateNew</link>
</seealso>
</element>

<element name="TCustomTaskDialog.OnDialogDestroyed">
<short>
Event handler signalled when the task dialog form has been freed for the class 
instance.
</short>
<descr>
<p>
<var>OnDialogDestroyed</var> is a <var>TNotifyEvent</var> property with the 
event handler signalled when the dialog form for the class instance has been 
freed. It is signalled (when assigned) from the DoOnDialogDestroyed method.
</p>
<p>
For native implementations using the Task Dialog API (supported Windows 
versions), it occurs when the TDN_DESTROYED notification is handled in the 
callback routine for the class instance. For emulated task dialog forms, it 
occurs when the TLCLTaskDialog.Destroy method is called. It is the first action 
performed in the method, and occurs before the inherited destructor is called 
for the LCL form instance.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.DoOnDialogDestroyed"/>
<link id="#lcl.taskdlgemulation.TLCLTaskDialog.Destroy">TLCLTaskDialog.Destroy</link>
</seealso>
</element>

<element name="TCustomTaskDialog.OnVerificationClicked">
<short>
Event handler signalled when the verification check box has been clicked on the 
task dialog.
</short>
<descr>
<p>
<var>OnVerificationClicked</var> is a <var>TNotifyEvent</var> property with the 
event handler signalled when the verification check box for the task dialog is 
clicked. It is signalled (when assigned) from the DoOnVerificationClicked 
method, and occurs after the checked state for the check box control has been 
applied to the Flags in the task dialog.
</p>
<p>
Use OnVerificationClicked to perform actions needed when the checked state has 
been changed.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.DoOnVerificationClicked"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
</seealso>
</element>

<element name="TCustomTaskDialog.OnExpanded">
<short>
Event handler signalled when the ExpandedText on the dialog has been expanded 
or collapsed.
</short>
<descr>
<p>
<var>OnExpanded</var> is a <var>TNotifyEvent</var> property with the event 
handler signalled when the expanded or collapsed state for the 
<var>ExpandedText</var> area on the task dialog has been changed. OnExpanded is 
signalled (when assigned) from the DoOnExpandButtonClicked method, and occurs 
after the member for the read-only Expanded property has been updated with the 
new value.
</p>
<p>
Use Flags to specify the content area on the dialog where the values in 
ExpandedText are displayed (tfExpandFooterArea).
</p>
<p>
Use ExpandButtonCaption and CollapseButtonCaption to set the text displayed 
next to the expando button on the task dialog.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.Expanded"/>
<link id="TCustomTaskDialog.DoOnExpandButtonClicked"/>
<link id="TCustomTaskDialog.ExpandButtonCaption"/>
<link id="TCustomTaskDialog.CollapseButtonCaption"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
<link id="#rtl.classes.TNotifyEvent">TNotifyEvent</link>
</seealso>
</element>

<element name="TCustomTaskDialog.OnTimer">
<short>
Event handler signalled when the interval for the timer on the dialog has 
elapsed.
</short>
<descr>
<p>
<var>OnTimer</var> is a <var>TTaskDlgTimerEvent</var> property with the event 
handler signalled when the interval for the timer in the task dialog has 
elapsed. It is signalled (when assigned) from the DoOnTimer method and receives 
values for the object instance, tick count since the timer was started, and a 
reset flag.
</p>
<p>
For the native Windows Task Dialog API, it occurs when the TDN_TIMER 
notification is handled in the callback procedure for the dialog. For platforms 
which use an emulated task dialog, it occurs when the handler routine for the 
internal TTimer instance in TLCLTaskDialog has elapsed. The timer interval is 
200ms.
</p>
<p>
An application can implement and assign a handler using the signature in 
TTaskDlgTimerEvent to perform actions needed when the notification occurs in 
the class instance.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso/>
<notes>
<note>
There are no mechanisms to set the progress bar range (min, max) or update the 
progress bar position on the widget.
</note>
</notes>
</element>

<element name="TCustomTaskDialog.OnRadioButtonClicked">
<short>
Event handler signalled when a radio button on the dialog has been clicked.
</short>
<descr>
<p>
<var>OnRadioButtonClicked</var> is a <var>TNotifyEvent</var> property with the 
event handler signalled when a radio button on the task dialog has been clicked. It is signalled (when assigned) from the DoOnRadioButtonClicked method, and occurs after the value in RadioButton has been updated to reflect the button identifier clicked on the dialog form.
</p>

<p>
For native implementations using the Task Dialog API (supported Windows 
versions), it occurs when the TDN_RADIO_BUTTON_CLICKED notification is handled 
in the callback routine for the class instance. For emulated task dialog forms, 
it occurs when the corresponding event handler implementation for the LCL form 
instance is called. 
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.DoOnRadioButtonClicked"/>
<link id="#lcl.taskdlgemulation.TLCLTaskDialog">TLCLTaskDialog</link>
</seealso>
</element>

<element name="TCustomTaskDialog.OnHyperlinkClicked">
<short>
Event handler signalled when a hyperlink in one of the text areas has been 
clicked.
</short>
<descr>
<p>
<var>OnHyperlinkClicked</var> is a <var>TNotifyEvent</var> property with the 
event handler signalled when a hyperlink in one of the text areas on the task 
dialog has been clicked. The URL property contains the target for the hyperlink in the event notification.
</p>
<p>
Hyperlinks may appear in the Text, ExpandedText, and FooterText properties. 
They use the common HTML Anchor notation like:
</p>
<code>
&lt;a href="https://www.lazarus-ide.org/"&gt;Lazarus website&lt;/a&gt;
</code>
<p>
Include tfEnableHyperlinks in the Flags property to enable display and handling 
for hyperlinks in the text areas on the dialog.
</p>
<remark>
Hyperlinks are automatically disabled when tfQuery or tfSimpleQuery are included in Flags. The textual content for hyperlinks is still displayed - but without formatting and event handler notifications.
</remark>
</descr>
<seealso>
<link id="TCustomTaskDialog.Text"/>
<link id="TCustomTaskDialog.ExpandedText"/>
<link id="TCustomTaskDialog.FooterText"/>
<link id="TCustomTaskDialog.URL"/>
<link id="TCustomTaskDialog.Flags"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
</seealso>
</element>

<element name="TCustomTaskDialog.OnNavigated">
<short/>
<descr>
<p>
<var>OnNavigated</var> is a <var>TNotifyEvent</var> property with the event 
handler signalled when a page of content is needed for the task dialog. It is 
signalled (when assigned) from the DoOnNavigated method.
</p>
<p>
See <url href="https://learn.microsoft.com/en-us/dotnet/api/system.windows.forms.taskdialogpage.navigate?view=windowsdesktop-7.0">
TaskDialogPage.Navigate
</url> for more information about the API implementation.
</p>
<p>
Please note that the page instance used in the native Task Dialog API is not 
available in the event handler. It might be implemented in a derived class, but 
the event handler must be in base class for Delphi compatibility.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso/>
</element>

<element name="TCustomTaskDialog.OnHelp">
<short>
Event handler signalled to display help for the task dialog.
</short>
<descr>
<p>
<var>OnHelp</var> is a <var>TNotifyEvent</var> property with the event handler 
signalled to display help for the task dialog. It is signalled (when assigned) 
from the DoOnHelp method.
</p>
<p>
For native implementations using the Task Dialog API (supported Windows 
versions), it occurs when the TDN_HELP notification is handled in 
the callback routine for the class instance. For emulated task dialog forms, it 
occurs when the F1 key is processed in the KeyDown handler for the LCL form 
instance.
</p>
<p>
Applications can implement and assign a routine to the handler to perform the 
actions needed to display context or keyword help for the dialog.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.DoOnHelp"/>
<link id="#lcl.taskdlgemulation.TLCLTaskDialog.KeyDown">TLCLTaskDialog.KeyDown</link>
</seealso>
</element>

<element name="TTaskDialog">
<short>
Implements a configurable modal task dialog.
</short>
<descr>
<p>
<var>TTaskDialog</var> is a <var>TCustomTaskDialog</var> 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.
</p>
<p>
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 <var>Execute</var> method handles 
converting properties and calling routines and methods in the widgetset which 
implement the task dialog for a given platform.
</p>
<p>
<b>Platform Support</b>
</p>
<p>
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 
<file>taskdlgemulation.pp</file> unit. It can be forced by including a value in 
the Flags property for the class instance.
</p>
<p>
<b>Using TTaskDialog at Run-time.</b>
</p>
<code>
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 &lt;a href="#terminus"&gt;final&lt;/a&gt; warning.';

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

    if Execute then ; // do something based on ModalResult
    Free;
  end;
end;
</code>
</descr>
<version>
Modified in LCL version 4.0. The implementation for the most part is rewritten, 
and includes additional features not found in previous versions.
</version>
<seealso>
<link id="TCustomTaskDialog"/>
<link id="#lcl.taskdlgemulation.TLCLTaskDialog">TLCLTaskDialog</link>
</seealso>
</element>

<element name="TTaskDialog.Buttons" link="#lcl.dialogs.TCustomTaskDialog.Buttons"/>
<element name="TTaskDialog.Caption" link="#lcl.dialogs.TCustomTaskDialog.Caption"/>
<element name="TTaskDialog.CommonButtons" link="#lcl.dialogs.TCustomTaskDialog.CommonButtons"/>
<element name="TTaskDialog.CollapseButtonCaption" link="#lcl.dialogs.TCustomTaskDialog.CollapseButtonCaption"/>
<element name="TTaskDialog.CustomFooterIcon" link="#lcl.dialogs.TCustomTaskDialog.CustomFooterIcon"/>
<element name="TTaskDialog.CustomMainIcon" link="#lcl.dialogs.TCustomTaskDialog.CustomMainIcon"/>
<element name="TTaskDialog.DefaultButton" link="#lcl.dialogs.TCustomTaskDialog.DefaultButton"/>
<element name="TTaskDialog.ExpandButtonCaption" link="#lcl.dialogs.TCustomTaskDialog.ExpandButtonCaption"/>
<element name="TTaskDialog.ExpandedText" link="#lcl.dialogs.TCustomTaskDialog.ExpandedText"/>
<element name="TTaskDialog.Flags" link="#lcl.dialogs.TCustomTaskDialog.Flags"/>
<element name="TTaskDialog.FooterIcon" link="#lcl.dialogs.TCustomTaskDialog.FooterIcon"/>
<element name="TTaskDialog.FooterText" link="#lcl.dialogs.TCustomTaskDialog.FooterText"/>
<element name="TTaskDialog.MainIcon" link="#lcl.dialogs.TCustomTaskDialog.MainIcon"/>
<element name="TTaskDialog.ProgressBar" link="#lcl.dialogs.TCustomTaskDialog.ProgressBar"/>
<element name="TTaskDialog.RadioButtons" link="#lcl.dialogs.TCustomTaskDialog.RadioButtons"/>
<element name="TTaskDialog.QueryChoices" link="#lcl.dialogs.TCustomTaskDialog.QueryChoices"/>
<element name="TTaskDialog.QueryItemIndex" link="#lcl.dialogs.TCustomTaskDialog.QueryItemIndex"/>
<element name="TTaskDialog.SimpleQuery" link="#lcl.dialogs.TCustomTaskDialog.SimpleQuery"/>
<element name="TTaskDialog.SimpleQueryPasswordChar" link="#lcl.dialogs.TCustomTaskDialog.SimpleQueryPasswordChar"/>
<element name="TTaskDialog.Text" link="#lcl.dialogs.TCustomTaskDialog.Text"/>
<element name="TTaskDialog.Title" link="#lcl.dialogs.TCustomTaskDialog.Title"/>
<element name="TTaskDialog.VerificationText" link="#lcl.dialogs.TCustomTaskDialog.VerificationText"/>
<element name="TTaskDialog.Width" link="#lcl.dialogs.TCustomTaskDialog.Width"/>
<element name="TTaskDialog.OnButtonClicked" link="#lcl.dialogs.TCustomTaskDialog.OnButtonClicked"/>
<element name="TTaskDialog.OnDialogConstructed" link="#lcl.dialogs.TCustomTaskDialog.OnDialogConstructed"/>
<element name="TTaskDialog.OnDialogCreated" link="#lcl.dialogs.TCustomTaskDialog.OnDialogCreated"/>
<element name="TTaskDialog.OnDialogDestroyed" link="#lcl.dialogs.TCustomTaskDialog.OnDialogDestroyed"/>
<element name="TTaskDialog.OnVerificationClicked" link="#lcl.dialogs.TCustomTaskDialog.OnVerificationClicked"/>
<element name="TTaskDialog.OnExpanded" link="#lcl.dialogs.TCustomTaskDialog.OnExpanded"/>
<element name="TTaskDialog.OnTimer" link="#lcl.dialogs.TCustomTaskDialog.OnTimer"/>
<element name="TTaskDialog.OnRadioButtonClicked" link="#lcl.dialogs.TCustomTaskDialog.OnRadioButtonClicked"/>
<element name="TTaskDialog.OnHyperlinkClicked" link="#lcl.dialogs.TCustomTaskDialog.OnHyperlinkClicked"/>

<element name="TaskDialogFirstButtonIndex">
<short>
Lowest index value for a button identifier used on a task dialog instance.
</short>
<descr>
<p>
<var>TaskDialogFirstButtonIndex</var> is a constant which sets the lowest value 
for a button identifier used on a task dialog instance. The value is used to 
assign the modal result value for a new button when its identifier is added to 
the Buttons collection in TTaskDialog.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.Buttons"/>
<link id="TCustomTaskDialog.ButtonIDToModalResult"/>
<link id="TTaskDialogButtonItem.ModalResult"/>
<link id="TTaskDialogBaseButtonItem.Create"/>
<link id="TaskDialogFirstRadioButtonIndex"/>
<link id="#rtl.classes.TCollectionItem.ID">TCollectionItem.ID</link>
</seealso>
</element>

<element name="TaskDialogFirstRadioButtonIndex">
<short>
Lowest index value for a radio button used on a TTaskDialog instance.
</short>
<descr>
<p>
<var>TaskDialogFirstRadioButtonIndex</var> is a constant with the initial value 
for a radio button identifier used on a task dialog instance.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomTaskDialog.RadioButton"/>
<link id="TCustomTaskDialog.SetRadioButtonFromRadioIndex"/>
<link id="TCustomTaskDialog.Execute"/>
<link id="TCustomTaskDialog.DoExecute"/>
<link id="TTaskDialogRadioButtonItem"/>
<link id="TTaskDialogBaseButtonItem.Create"/>
<link id="TaskDialogFirstButtonIndex"/>
<link id="#rtl.classes.TCollectionItem.ID">TCollectionItem.ID</link>
</seealso>
</element>

<element name="MinimumDialogButtonWidth">
<short>Minimum width for a button on a dialog.</short>
<descr/>
<seealso/>
</element>

<element name="MinimumDialogButtonHeight">
<short>Minimum height for a button on a dialog.</short>
<descr/>
<seealso/>
</element>

<element name="MessageDlg">
<short>Shows a message to the user and gets the response.</short>
<descr>
<p>
There are four versions of this function.
</p>
<p>
The first version displays a dialog with the standard caption. The second, 
third and fourth versions enable you to set the caption.
</p>
<p>
The third version allows for a Default button.
</p>
<p>
The fourth version contains a help keyword instead of using context-based 
help.
</p>
<p>
If the first Caption argument is missing, no caption is shown on the box.
</p>
<p>
This is the most complete and elaborate of the message dialogs, and allows 
the programmer considerable control over the appearance of the dialog box.
</p>
<p>
The arguments defining the kind of box and its icon are types rather than 
integer constants, and the buttons can be specified as a set in square 
brackets e.g. [mbRetry, mbIgnore, mbAbort, mbCancel].
</p>
<p>
The HelpCtx argument allows the use of Context Help
</p>
<p>
The return value from the Function is the identity of the button pressed, 
expressed as an integer (see the constant definitions in <link 
id="Controls.TControl">TControl</link> , [mrNone..mrAll]).
</p>
<p>
If the user clicks the [X]-bordericon, the return value will be mrCancel.
</p>
<p>
If the user presses the escape key, the result depends on the widgetset:
</p>
<ul>
<li>If the widgetset has implemented a native dialog, the result will be 
mrCancel.</li>
<li>Otherwise the result will be mrCancel, mrNo or mrOk (in that order) when 
mbCancel, mbNo or mbOk is present. The dialog will not close when the Escape 
key is pressed if none of these buttons are present.</li>
</ul>
</descr>
<seealso/>
<example file="dialogs/trymessagedlg.pas"/>
</element>
<element name="MessageDlg.Result">
<short>
The result of this function is either the button the user pressed to close 
the dialog, or mrCancel.
</short>
<descr>
<p>
The result of this function is the button the user pressed to close the 
dialog expressed as an integer.
</p>
<p>
If the user clicks the [X]-bordericon, the return value will be mrCancel.
</p>
<p>
If the user presses the escape key, the result depends on the widgetset:
</p>
<ul>
<li>If the widgetset has implemented a native dialog, the result will be 
mrCancel.</li>
<li>
Otherwise the result will be mrCancel, mrNo or mrOk (in that order) if 
mbCancel, mbNo or mbOk is present. The dialog will not close when the Escape 
key is pressed if none of these buttons are present.
</li>
</ul>
</descr>
</element>
<element name="MessageDlg.aMsg">
<short>The message to be shown.</short>
<descr>The message shown to the user.</descr>
</element>
<element name="MessageDlg.DlgType">
<short>The type of dialog to be shown.</short>
<descr>
<p>
The DlgType parameter indicates the type of dialog to show. You can choose 
from mtWarning, mtError, mtInformation, mtConfirmation or mtCustom.
</p>
</descr>
</element>
<element name="MessageDlg.Buttons">
<short>Determines the buttons shown on the message dialog.</short>
<descr>
<p>
Buttons indicate which set of button captions have to be shown on the dialog. 
You can choose from predefined sets:
</p>
<ul>
<li>mbAbortRetryIgnore</li>
<li>mbOKCancel</li>
<li>mbYesNo</li>
<li>mbYesNoCancel</li>
</ul>
<p>
Or, you can make your own set.
</p>
</descr>
</element>
<element name="MessageDlg.HelpCtx">
<short>
HelpCtx is used to specify which topic from the help should be shown.
</short>
<descr>HelpCtx is used to specify which topic from the help should be 
shown.</descr>
</element>
<element name="MessageDlg.aCaption">
<short>Used to set the caption of the message dialog.</short>
<descr>Sets the caption of the message dialog shown by this function.</descr>
</element>
<element name="MessageDlg.DefaultButton">
<short>
The default button when the message dialog is executed.
</short>
</element>
<element name="MessageDlg.HelpKeyword">
<short>
Help keyword for the message dialog.
</short>
</element>

<element name="MessageDlgPos">
<short>An extended MessageDlg function.</short>
<descr>
<p>
This function performs the same function as the <link 
id="MessageDlg">MessageDlg</link> function. It has been extended with 
parameters to place the dialog on a certain position on the screen instead of 
in the center of the screen.
</p>
<p>
The MessageDlgPos function does not enable you to choose the caption of the 
dialog.
</p>
</descr>
<seealso/>
</element>
<element name="MessageDlgPos.Result">
<short>
The result of this function is either the button the user pressed to close 
the dialog, or mrCancel.
</short>
<descr>
<p>
The result of this function is the button the user pressed to close the 
dialog expressed as an integer.
</p>
<p>
If the user clicks the [X]-bordericon, the return value will be mrCancel.
</p>
<p>
If the user presses the escape key, the result depends on the widgetset:
</p>
<ul>
<li>If the widgetset has implemented a native dialog, the result will be 
mrCancel.</li>
<li>Otherwise the result will be mrCancel, mrNo or mrOk (in that order) if 
mbCancel, mbNo or mbOk is present. The dialog will not close when the Escape 
key is pressed if none of these buttons are present.</li>
</ul>
</descr>
</element>
<element name="MessageDlgPos.aMsg">
<short>The message to be shown.</short>
<descr>The message shown to the user.</descr>
</element>
<element name="MessageDlgPos.DlgType">
<short>The type of dialog to be shown.</short>
<descr>
<p>
The DlgType parameter indicates the type of dialog to show. You can choose 
from mtWarning, mtError, mtInformation, mtConfirmation or mtCustom.
</p>
</descr>
</element>
<element name="MessageDlgPos.Buttons">
<short>Determines the buttons shown on the message dialog.</short>
<descr>
<p>
Buttons indicate which buttons have to be shown on the dialog. You can choose 
from predefined sets:
</p>
<ul>
<li>mbAbortRetryIgnore</li>
<li>mbOKCancel</li>
<li>mbYesNo</li>
<li>mbYesNoCancel</li>
</ul>
<p>
Or, you can make your own set.
</p>
</descr>
</element>
<element name="MessageDlgPos.HelpCtx">
<short>
HelpCtx is used to specify which topic from the help should be shown.
</short>
<descr>HelpCtx is used to specify which topic from the help should be 
shown.</descr>
</element>
<element name="MessageDlgPos.X">
<short>X specifies the position of the left side of the dialog.</short>
<descr>X specifies the position of the left side of the dialog.</descr>
</element>
<element name="MessageDlgPos.Y">
<short>Y specifies the position of the top side of the dialog.</short>
<descr>Y specifies the position of the top side of the dialog</descr>
</element>

<element name="MessageDlgPosHelp">
<short>An extended MessageDlgPos function.</short>
<descr>
<p>
This function enables you to specify a Helpfile which has to be shown when 
the user presses F1.
</p>
</descr>
<seealso/>
</element>
<element name="MessageDlgPosHelp.Result">
<short>
The result of this function is either the button the user pressed to close 
the dialog, or mrCancel.
</short>
<descr>
<p>
The result of this function is the button the user pressed to close the 
dialog expressed as an integer.
</p>
<p>
If the user clicks the [X]-bordericon, the return value will be mrCancel.
</p>
<p>
If the user presses the escape key, the result depends on the widgetset:
</p>
<ul>
<li>If the widgetset has implemented a native dialog, the result will be 
mrCancel.</li>
<li>Otherwise the result will be mrCancel, mrNo or mrOk (in that order) if 
mbCancel, mbNo or mbOk is present. The dialog will not close when the Escape 
key is pressed if none of these buttons are present.</li>
</ul>
</descr>
</element>
<element name="MessageDlgPosHelp.aMsg">
<short>The message to be shown.</short>
<descr>The message shown to the user.</descr>
</element>
<element name="MessageDlgPosHelp.DlgType">
<short>The type of dialog to be shown.</short>
<descr>
<p>
The DlgType parameter indicates the type of dialog to show. You can choose 
from mtWarning, mtError, mtInformation, mtConfirmation or mtCustom.
</p>
</descr>
</element>
<element name="MessageDlgPosHelp.Buttons">
<short>Determines the buttons shown on the message dialog.</short>
<descr>
<p>
Buttons indicate which buttons have to be shown on the dialog. You can choose 
from predefined sets:
</p>
<ul>
<li>mbAbortRetryIgnore</li>
<li>mbOKCancel</li>
<li>mbYesNo</li>
<li>mbYesNoCancel</li>
</ul>
<p>
Or, you can make your own set.
</p>
</descr>
</element>
<element name="MessageDlgPosHelp.HelpCtx">
<short>
HelpCtx is used to specify which topic from the help should be shown.
</short>
<descr>HelpCtx is used to specify which topic from the help should be 
shown.</descr>
</element>
<element name="MessageDlgPosHelp.X">
<short>X specifies the position of the left side of the dialog.</short>
<descr>X specifies the position of the left side of the dialog</descr>
</element>
<element name="MessageDlgPosHelp.Y">
<short>Y specifies the position of the top side of the dialog.</short>
<descr>Y specifies the position of the top side of the dialog</descr>
</element>
<element name="MessageDlgPosHelp.HelpFileName">
<short>The Helpfile that has to be shown when the user presses F1</short>
<descr>
The name of the helpfile to be shown when the user presses F1 in the dialog.
</descr>
</element>

<element name="CreateMessageDialog">
<short>
Creates a dialog form type with the specified caption, message, and buttons.
</short>
<descr/>
<seealso/>
</element>
<element name="CreateMessageDialog.Result">
<short>
TForm instance with the content representing the specified parameters.
</short>
</element>
<element name="CreateMessageDialog.AMsg">
<short>Message text for the dialog.</short>
</element>
<element name="CreateMessageDialog.ACaption">
<short>Caption displayed as the title for the dialog.</short>
</element>
<element name="CreateMessageDialog.DlgType">
<short>Identifies the dialog type and the image for the dialog.</short>
</element>
<element name="CreateMessageDialog.Buttons">
<short>Set of TMsgDlgBtn buttons displayed on the dialog.</short>
</element>

<element name="DefaultPromptDialog">
<short>Widgetset-independent implementation of a prompt dialog.</short>
<descr>
<p>
<var>DefaultPromptDialog</var> is a <var>LongInt</var> function which 
implements a widgetset-independent prompt dialog. It is uses a LCL TForm 
instance instead of relying on dialogs provided by the operating system. The 
content displayed on the dialog form is specified using the arguments passed 
to the routine, including:
</p>
<dl>
<dt>
DialogCaption
</dt>
<dd>
The caption for the dialog, displayed in the title bar for the dialog form. 
If Caption is an empty string (''), GetDialogCaption is called to get the 
default caption for the value in DialogType. The caption can be set to the 
Application title if DialogType is not one of the idDialogBase values.
</dd>
<dt>
DialogMessage
</dt>
<dd>
The text displayed inside the dialog as a prompt or message.
</dd>
<dt>
DialogType
</dt>
<dd>
A LongInt value which indicates the icon and default caption displayed for 
the dialog. It contains one of the constant values defined in the LCLType 
unit like: idDialogWarning, idDialogError, idDialogInfo, idDialogConfirm, or 
idDialogShield.
</dd>
<dt>
Buttons
</dt>
<dd>
Contains a pointer to an array of LongInt values which define the buttons 
displayed for the dialog. The values correspond to idButtonBase values 
defined in the LCLType unit like: idButtonOk, idButtonCancel, idButtonHelp, 
idButtonYes, idButtonNo, idButtonClose, idButtonAbort, idButtonRetry, 
idButtonIgnore, idButtonAll, idButtonYesToAll, or idButtonNoToAll. Buttons 
using the identifiers idButtonOpen, idButtonSave, and idButtonShield are not 
implemented in the current LCL version. The values for each of the buttons 
indicate the default icon and text for the button, as well as its modal 
result value.
</dd>
<dt>
ButtonCount
</dt>
<dd>
Contains the number of elements for the Buttons array.
</dd>
<dt>
DefaultIndex
</dt>
<dd>
Contains the ordinal position for the default button on the dialog. This is 
the button clicked when the Enter or the Space key is pressed during modal 
display of the dialog.
</dd>
<dt>
EscapeIndex
</dt>
<dd>
Contains the ordinal position for the button clicked when the Escape key is 
pressed during modal display of the dialog.
</dd>
<dt>
UseDefaultPos
</dt>
<dd>
Indicates if the dialog is displayed using the default position for the 
dialog form. When set to <b>True</b>, the value poDesigned is used in the 
Position property for the dialog form. When set to <b>False</b>, the values 
in the X and Y parameters are used in the Left and Top properties for the 
dialog form.
</dd>
</dl>
<p>
The return value contains the LongInt value returned for the button clicked 
on the dialog. It corresponds to the values passed in the Buttons argument, 
but may be changed to the value in EscapeIndex if the Escape key was pressed 
during dialog display.
</p>
<p>
The size and layout for elements on the dialog are calculated when the dialog 
form is created. The maximum width and height for the dialog is the largest 
space needed for the icon, message text and buttons on the dialog. For 
small-format devices (width is 300 pixel or less), a width of 200 pixels is 
used on the dialog form.
</p>
<p>
<b>Example</b>:
</p>
<code>
uses
  LCLType;

procedure TForm1.Button1Click(Sender: TObject);
var
  btns: array[0..2] of LongInt = (idButtonOK, idButtonCancel, idButtonHelp);
  res: LongInt;
begin
  res := DefaultPromptDialog('This is the caption',
    'This is the message of this dialog', idDialogInfo, @btns,
    3, 0, 1, true, 0, 0);
  Caption := 'Dialog result is ' + IntToStr(res);
end;
</code>
</descr>
<seealso>
<link id="#lcl.forms.TCustomForm.ShowModal">TCustomForm.ShowModal</link>
<link id="#lcl.forms.TCustomForm.ModalResult">TCustomForm.ModalResult</link>
<link id="#lcl.interfacebase.PromptDialogFunction">PromptDialogFunction</link>
</seealso>
</element>
<element name="DefaultPromptDialog.Result">
<short>
LongInt value for the button clicked on the prompt dialog.
</short>
</element>
<element name="DefaultPromptDialog.DialogCaption">
<short>Caption displayed on the dialog form.</short>
</element>
<element name="DefaultPromptDialog.DialogMessage">
<short>Text displayed as a prompt or message on the dialog form.</short>
</element>
<element name="DefaultPromptDialog.DialogType">
<short>Identifies the icon and default caption for the dialog.</short>
</element>
<element name="DefaultPromptDialog.Buttons">
<short>Contains the button identifiers displayed on the dialog form.</short>
</element>
<element name="DefaultPromptDialog.ButtonCount">
<short>Number of values in the Buttons argument.</short>
</element>
<element name="DefaultPromptDialog.DefaultIndex">
<short>Position for the default button on the dialog form.</short>
</element>
<element name="DefaultPromptDialog.EscapeResult">
<short>Value returned when the Escape key is pressed for the dialog.</short>
</element>
<element name="DefaultPromptDialog.UseDefaultPos">
<short>
<b>True</b> to use the default position for the dialog form, <b>False</b> to 
use the values in X and Y as the Top and Left coordinates.
</short>
</element>
<element name="DefaultPromptDialog.X">
<short>Horizontal coordinate where the dialog form is displayed.</short>
</element>
<element name="DefaultPromptDialog.Y">
<short>Vertical coordinate where the dialog form is displayed.</short>
</element>

<element name="QuestionDlg">
<short>
Shows a question to the user and gets a response. Similar to MessageDlg, but 
allows to use custom button captions and user-specified response values.
</short>
<descr>
<p>
<var>QuestionDlg</var> has the same functionality as MessageDlg except for 
the <var>Buttons</var> parameter which is of a different type. You can define 
your own captions, return values, and optional flags in Buttons using this 
function.
</p>
<p>
<var>ACaption</var> contains the text displayed as the title for the dialog 
form.
</p>
<p>
<var>AMsg</var> contains the text displayed within the content area for the 
dialog form. It represents the question to be answered using the dialog.
</p>
<p>
<var>DlgType</var> contains a value from the TMsgDlgType enumeration, and 
determines the icon displayed on the dialog form. See <link 
id="TMsgDlgType">TMsgDlgType</link> for the values in the enumeration and 
their meanings.
</p>
<p>
<var>Buttons</var> is defined as an array of const values, and contains the 
numeric identifiers and optional captions and flags for the buttons displayed 
on the dialog. QuestionDlg examines the values in Buttons, and creates a 
button instance for each numeric identifier in the array. Usually, the button 
identifiers are specified using <var>TModalResult</var> constants like mrOk 
or mrCancel (defined in <link id="Controls"/>); these buttons will be 
decorated with an icon associated with the modal result value. Other integer 
values can be used as well, but their buttons will not have an icon. The 
order of the buttons on the dialog form will be the same as the order of the 
numeric values in the array elements.
</p>
<p>
Each string following a numeric button identifier denotes the caption for the 
button. When the button identifier is one of the default 
<var>TModalResult</var> values defined in controls.pp 
(<var>mrNone..mrLast</var>), the caption can be omitted and the default 
caption will be used. For non-<var>TModalResult</var> identifiers, the 
caption <b>MUST</b> be specified. An empty string is not allowed as a 
caption; it will raise a run-time error.
</p>
<p>
You can mark one button as the default button by adding the 'IsDefault' 
option after the caption string. When the user presses the Return key, this 
button is triggered. An exception is raised if more than one button has the 
'IsDefault' designation.
</p>
<p>
Some widgetsets provide an Escape key and/or a close button for the dialog. 
This results in <var>mrCancel</var> in the return value, even if it is not in 
the given button list. Use the 'IsCancel' option after the caption string to 
cause the button to close the dialog. An exception is raised if more than one 
button has the 'IsCancel' designation.
</p>
<p>
You can use both 'IsDefault' and 'IsCancel' flags values for a given button 
by including both strings as arguments following the caption value. Values in 
button flags are case-insensitive; 'IsDefault' is considered the same as 
'isdefault'.
</p>
<p>
The numeric identifier for the button clicked on the dialog is returned by 
the <var>QuestionDlg()</var> function.
</p>
<p>
The overloaded routines allow a help topic to be displayed when the F1 key is 
pressed. <var>HelpCtx</var> is the numeric identifier for the help topic 
passed as an argument to the AskUser routine in the widgetset. 
<var>HelpKeyword</var> is a string value that identifies the help topic. 
Please note that HelpKeyword is not implemented in the current LCL version; 
the numeric help context 0 is always used in the overloaded routine.
</p>
<p>
<b>Examples:</b>
</p>
<code>
var
  res: TModalResult;
//...

// OK, Cancel dialog using default button captions
res := QuestionDlg('Confirm', 'Delete all files and directories?', mtConfirmation,
  [mrOK, mrCancel], 0);
//...


// OK, Cancel dialog with custom button captions and accelerator keys
res := QuestionDlg('Confirm', 'Delete all files and directories?', mtConfirmation,
  [mrOK, '&amp;Do it!', mrCancel, '&amp;Nope'], 0);
//...

// custom modal result values and captions
res := QuestionDlg('Question', 'Is it Okay?', mtConfirmation,
 [400, 'Yes!!!', 401, 'Not cool', 402, 'My mistake'], 0);  
//...

// Yes, No, Cancel with custom captions and button flags
res := QuestionDlg('COPYING', 'Abort?', mtConfirmation,
  [mrNo,'&amp;No', mrYes,'&amp;Yes', mrCancel, '&amp;Cancel', 'IsDefault', 'IsCancel'], 0);

case res of
  mrYes: ShowMessage('You clicked Yes');
  mrNo: ShowMessage('You clicked No');
else
  // mrCancel
  ShowMessage('You cancelled the dialog.');
end;
</code>
</descr>
<seealso>
<link id="MessageDlg"/>
<link id="InputQuery"/>
<link id="DefaultQuestionDialog"/>
</seealso>
</element>
<element name="QuestionDlg.Result">
<short>
The result of this function is the identifier number for the button that the 
user pressed to close the dialog.
</short>
</element>
<element name="QuestionDlg.aCaption">
<short>Caption displayed as the title for the question dialog.</short>
</element>
<element name="QuestionDlg.aMsg">
<short>Contains the question the user has to answer using the dialog.</short>
</element>
<element name="QuestionDlg.DlgType">
<short>
The type of dialog. It determines which icon is displayed on the dialog.
</short>
</element>
<element name="QuestionDlg.Buttons">
<short>
An array of return values, captions and optional flags for the buttons on the 
question dialog.
</short>
</element>
<element name="QuestionDlg.HelpCtx">
<short>
HelpCtx specifies the numeric identifier for the help topic shown when F1 is 
pressed.
</short>
</element>
<element name="QuestionDlg.HelpKeyword">
<short>
HelpKeyword specifies the help topic shown when F1 is pressed. The string 
argument is not used in the current LCL version, and the numeric HelpContext 
is always 0.
</short>
</element>

<element name="DefaultQuestionDialog">
<short>
Implements a widgetset-independent dialog similar to QuestionDlg.
</short>
<descr>
<p>DefaultQuestionDialog displays a message dialog, similar to QuestionDlg, 
but it uses a LCL <var>TForm</var> instance instead of relying on dialogs 
provided by the operating system. The content displayed on the dialog form is 
specified by the arguments passed to the routine, including:
</p>
<dl>
<dt>aCaption</dt>
<dd>
The title of the dialog, displayed in the title bar of the dialog form. In 
case of an empty string (''), the default caption of the dialog type 
(<var>DlgType</var> parameter) is selected, or, when the <var>DlgType</var> 
is not one of the <var>idDialogXXX</var> values the application title is used 
instead.
</dd>
<dt>aMsg</dt>
<dd>The text of the message or question displayed in the dialog</dd>
<dt>DlgType</dt>
<dd>
A LongInt value which defines the icon and default caption displayed for the 
dialog. It contains one of the constant values defined in the 
<var>LCLType</var> unit like: <var>idDialogWarning</var>, 
<var>idDialogError</var>, <var>idDialogInfo</var>, 
<var>idDialogConfirm</var>, or <var>idDialogShield</var>. Do not use the 
<var>mtXXXX</var> values used by other dialogs, they will produce the wrong 
icon.
</dd>
<dt>Buttons</dt>
<dd>A collection of items representing the buttons shown in the dialog. Each 
item describes the button by its caption, an integer value which is returned 
by the function when this button is clicked, as well as boolean flags to 
identify the "Default" or "Cancel" button. The return value is typed 
<var>TModalResult</var>, but any other integers can be used as well. Be 
careful if you plan to use the <var>idButtonXXX</var> constants declared in 
the <var>LCLType</var> unit because they will assign the icons to the buttons 
differently. An empty caption string is NOT replaced by a default string here.
</dd>
<dt>HelpCtx</dt>
<dd>Help context value for the help text to be displayed when the user 
presses F1.</dd>
</dl>
<p>
<b>Example</b>
</p>
<p>
Since <var>Buttons</var> is a <var>TCollection</var> each item must be added 
individually:
</p>
<code>
var
  btns: TDialogButtons;  // requires "uses InterfaceBase"
  res: Integer;
...
  btns := TDialogButtons.Create(TDialogButton);
  with btns.Add do
  begin
    Caption := 'OK';
    ModalResult := mrOK;
  end;
  with btns.Add do
  begin
    Caption := 'Cancel now';
    ModalResult := mrCancel;
  end;
  with btns.Add do
  begin
    Caption := 'Ignore';
    ModalResult := mrIgnore;
  end;
  with btns.Add do
  begin
    Caption := 'Do it';
    ModalResult := 300;
    Default := true;
  end;

  res := DefaultQuestionDialog('This is the caption', 'This is the title', idDialogError, btns, 0);
</code>
<p>
This code will display a dialog box with the following four buttons:
</p>
<ul>
<li>'Ok' returning mrOk</li>
<li>'Cancel now' returning mrCancel</li>
<li>'Ignore' returning mrIgnore</li>
<li>'Do it' returning 300. This will be the default button (focused)</li>
</ul>
</descr>
<seealso/>
</element>
<element name="DefaultQuestionDialog.Result">
<short>
Returns the number value associated with each button.
</short>
</element>
<element name="DefaultQuestionDialog.ACaption">
<short>
Title text of the dialog form
</short>
</element>
<element name="DefaultQuestionDialog.AMsg">
<short>
Message text displayed in the dialog form.
</short>
</element>
<element name="DefaultQuestionDialog.DlgType">
<short>
A number to select the icon shown in the dialog. Select one of the 
<var>idDialogXXXX</var> constants declared in the unit LCLType 
(<var>idDialogWarning</var>, <var>idDialogError</var>, 
<var>idDialogInfo</var>, <var>idDialogConfirm</var> or 
<var>idDialogShield</var>). Do not use the TMsgDlgType values which are used 
by other dialogs!
</short>
</element>
<element name="DefaultQuestionDialog.Buttons">
<short>
A collection of button definitions with caption, return value when clicked, 
and boolean flags to identify the default and cancel button.
</short>
</element>
<element name="DefaultQuestionDialog.HelpCtx">
<short>
HelpCtx specifies the help topic that should be shown when F1 is pressed.
</short>
</element>

<element name="ShowMessage">
<short>Displays the specified message text.</short>
<descr>
<p>
The simplest message dialog: takes a simple string as argument, displays it 
in a box, and waits for a mouse-click or enter-key event before returning to 
the calling routine or program.
</p>
<p>
This is a modal procedure call; the box is displayed, receives focus, and 
does not relinquish focus until the OK box is clicked or otherwise selected.
</p>
</descr>
<seealso>
<link id="#lcl.forms.TApplication.MessageBox">TApplication.MessageBox</link>
</seealso>
<example file="dialogs/tryshowmessage.pas"/>
</element>
<element name="ShowMessage.aMsg">
<short>A string constant containing the message to be shown.</short>
<descr>A string constant containing the message to be shown.</descr>
</element>

<element name="ShowMessageFmt">
<short>
Shows a message assembled from a format string and an array of arguments.
</short>
<descr>
<p>
This procedure is an extension to the <link 
id="ShowMessage">ShowMessage</link> procedure. The parameters it takes are 
the same as the <link id="#rtl.sysutils.Format">Format</link> function.
</p>
</descr>
<seealso>
<link id="ShowMessage"/>
</seealso>
</element>
<element name="ShowMessageFmt.aMsg">
<short>The format string.</short>
</element>
<element name="ShowMessageFmt.Params">
<short>The parameters to be inserted in the message.</short>
</element>

<element name="ShowMessagePos">
<short>Shows a message box at a given screen position.</short>
<descr>Shows a message box at a given screen position.</descr>
<seealso>
<link id="ShowMessage"/>
</seealso>
</element>
<element name="ShowMessagePos.aMsg">
<short>A string constant which is the message to be shown.</short>
</element>
<element name="ShowMessagePos.X">
<short>The horizontal position of the messagebox.</short>
</element>
<element name="ShowMessagePos.Y">
<short>The vertical position of the messagebox.</short>
</element>

<element name="DefaultMessageBox">
<short>
Widgetset-independent implementation of a message box routine.
</short>
<descr/>
<seealso>
<link id="MessageDlg">MessageDlg</link>
</seealso>
</element>
<element name="DefaultMessageBox.Result">
<short>
Modal result value for the dialog which indicates the key pressed to close 
the message box.
</short>
</element>
<element name="DefaultMessageBox.Text">
<short>
The message displayed in the message box.
</short>
</element>
<element name="DefaultMessageBox.Caption">
<short>
The caption or title for the message box.
</short>
</element>
<element name="DefaultMessageBox.Flags">
<short>
Indicates the buttons and icon displayed on the message box. Includes the 
combined values for message box button and icon constants defined in 
<file>lcltype.pp</file>.
</short>
</element>

<element name="InputBox">
<short>
Displays a box with specified title and prompt, and accepts user input in a 
text box.
</short>
<descr>
<p>
A default string can optionally be displayed in the text box. The 
user-entered or default string is returned as the function result.
</p>
<p>
If the user selects the OK button, the text in the text box is returned. If 
the user selects the Cancel button, the default string is returned.
</p>
</descr>
<seealso>
<link id="ShowMessage"/>
</seealso>
<example file="dialogs/inputbox.pas"/>
</element>
<element name="InputBox.Result">
<short>
The result of this function is the string the user entered in the editbox or 
the default string.
</short>
</element>
<element name="InputBox.ACaption">
<short>The caption for the dialog box.</short>
</element>
<element name="InputBox.APrompt">
<short>The text asking the user for his input.</short>
</element>
<element name="InputBox.ADefault">
<short>Default value for dialog box.</short>
<descr>The value of the editbox in the dialog will have this value.</descr>
</element>

<element name="PasswordBox">
<short>Displays a Password prompt with input masking.</short>
<descr>
<p>
PasswordBox is a specialized form of InputQuery. The editbox on the dialog 
box will mask the input. The only parameters are aCaption and aPrompt.
</p>
<p>
Behaves very similarly to the InputQuery function with MaskInput set to 
<b>True</b>; the difference is that the password that was typed in is 
returned as the result of the function (like InputBox).
</p>
</descr>
<seealso>
<link id="InputQuery"/>
<link id="InputBox"/>
</seealso>
</element>
<element name="PasswordBox.Result">
<short>The string the user entered.</short>
</element>
<element name="PasswordBox.ACaption">
<short>The caption for the dialog.</short>
</element>
<element name="PasswordBox.APrompt">
<short>A prompt to ask for the users input.</short>
</element>

<element name="PromptForFileName">
<short>
Displays a file open or save dialog to select a file name for the operation.
</short>
<descr>
<p>
PromptForFileName is a Boolean function used to display an Open or Save 
dialog using the values passed as arguments to the routine. It creates a 
<var>TOpenDialog</var> or a <var>TSaveDialog</var> instance for use in the 
routine. The <var>AIsSaveDialog</var> argument determines which dialog class 
is used in the routine.
</p>
<p>
Argument values are assigned to the corresponding properties in the dialog 
class. The Execute method in the dialog class is called to perform file 
selection or creation as needed, and its return value is used as the return 
value for the routine. The return value is <b>True</b> when the Execute 
method for the dialog class returns <b>True</b>.
</p>
<p>
<var>AFilename</var> contains the initially selected file name in the dialog, 
and is updated with the value selected using the dialog. A default value is 
not provided for the argument. If the dialog returns <b>True</b>, the 
FileName property in the dialog class is assigned to the AFileName argument.
</p>
<p>
<var>AFilter</var> contains file masks that can be selected in the dialog. 
The default value is an empty string ('') and causes the all files mask 
('*.*' or '*') to be used. See TFileDialog.Filter for more information about 
the notation allowed in the argument.
</p>
<p>
<var>ADefaultExt</var> contains the file extension used for the file name 
selected in the routine. The default value for the argument is an empty 
string ('') and indicates that a default file extension is not used. See 
TFileDialog.DefaultExt for more information about default extensions.
</p>
<p>
<var>ATitle</var> contains the caption displayed on the dialog. The default 
value is an empty string ('') and allows the default value provided by the 
dialog class to be used.
</p>
<p>
<var>AInitialDir</var> indicates the initial directory when the dialog is 
displayed. The default value is an empty string ('') and causes the current 
directory in the application to be used as the initial directory in the 
dialog.
</p>
</descr>
<seealso>
<link id="TFileDialog.FileName"/>
<link id="TFileDialog.DefaultExt"/>
<link id="TFileDialog.Filter"/>
<link id="TFileDialog.FilterIndex"/>
<link id="TFileDialog.InitialDir"/>
<link id="TFileDialog.Title"/>
<link id="TOpenDialog"/>
<link id="TSaveDialog"/>
<link id="TCommonDialog.Execute"/>
</seealso>
</element>
<element name="PromptForFileName.Result">
<short>
<b>True</b> if a file name was selected using the dialog.
</short>
</element>
<element name="PromptForFileName.AFileName">
<short>
Updated to contain the file name selected in open or save dialog.
</short>
</element>
<element name="PromptForFileName.AFilter">
<short>
File masks used in the dialog.
</short>
</element>
<element name="PromptForFileName.ADefaultExt">
<short>
Default file extension for the file name selected in the dialog.
</short>
</element>
<element name="PromptForFileName.ATitle">
<short>
Title displayed on the dialog.
</short>
</element>
<element name="PromptForFileName.AInitialDir">
<short>
Initial directory displayed in the dialog.
</short>
</element>
<element name="PromptForFileName.AIsSaveDialog">
<short>
<b>True</b> to create a save dialog, <b>False</b> to create an open dialog.
</short>
</element>

<element name="TaskDlg">
<short>
Provides a wrapper function used to configure and execute a TTaskDialog 
instance.
</short>
<descr>
<p>
<var>TaskDlg</var> is an overloaded function which implements a wrapper used to 
execute a TTaskDialog with the specified parameter values. TaskDlg is a 
convenience routine that allows a task dialog to be used in a manner similar to 
the MessageDlg routine. The overloaded variants allow different features / 
behaviors to be enabled when the task dialog is executed.
</p>
<p>
The parameter values are copied to the corresponding properties in the 
TTaskDialog instance created (and freed after execution) in the routine. The 
Execute method in the dialog is called to display the dialog form and to 
capture the result.
</p>
<p>
The return value is the <var>TModalResult</var> enumeration value returned in 
the ModalResult property for the TTaskdialog instance. The default value is 
<var>mrCancel</var>.
</p>
<p>
Use the Flags argument to indicate whether specific features are enabled (or 
disabled) when the task dialog is executed. See TTaskDialogFlag for the values 
allows in the Flags argument and their usage.
</p>
<p>
See TTaskDialog for more information about the features and behaviors supported 
in the dialog type.
</p>
<p>
For example:
</p>
<code>
var
  IsChecked: boolean;
  RadioResult: integer;
begin
  TaskDlg('I am the caption', 'I am the message', 
    'Some text as information. Lorem ipsum foo bar.',
    tdiInformation, [mbOk, mbCancel], ['Custom', 'Button', 'first'], 500,
    'Checkbox text', IsChecked, ['radio 1', 'radio 2', 'radio default'], 
    RadioResult, 2 {0-based}, 'Example footer text',
    { Can be in body or footer }
    'If there is need for more DETAILS, then the can be added here. ' + 
    'And can be controlled by tfExpandedByDefault, tfExpandFooterArea', 
    { These have default text, rarely need to be changed }
    'Click to see details', 'Click to hide details', 
    [tfAllowDialogCancellation {, tfExpandedByDefault, tfExpandFooterArea}]
    );
end;    
</code>
<p>
Please note that the TaskDlg wrapper does not provide access to all of the 
features / behaviors available in TTaskDialog. You must use a TTaskDialog 
instance to configure and enable those features when parameters are not 
provided in TaskDlg.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TTaskDialog"/>
<link id="TTaskDialogIcon"/>
<link id="TMsgDlgButtons"/>
<link id="TMsgDlgBtn"/>
<link id="TTaskDialogFlags"/>
<link id="TTaskDialogFlag"/>
<link id="MessageDlg"/>
<link id="#lcl.forms.TModalResult">TModalResult</link>
</seealso>
</element>
<element name="TaskDlg.Result">
<short>
TModalResult value returned when the task dialog is executed. The default value is mrCancel.
</short>
</element>
<element name="TaskDlg.aCaption">
<short>
Text displayed as the title bar caption on the task dialog form.
</short>
</element>
<element name="TaskDlg.aMsg">
<short>
Text displayed as the header-like text in the body of the task dialog.
</short>
</element>
<element name="TaskDlg.aInfo">
<short>
Text displayed in the main content area on the task dialog immediately after 
the header text in aMsg.
</short>
</element>
<element name="TaskDlg.DlgIcon">
<short>
Indicates the icon displayed on the task dialog.
</short>
</element>
<element name="TaskDlg.AButtons">
<short>
Set with the common buttons displayed on the task dialog. These buttons have a 
modal result value associated with the button, and can include values like 
mbOK, mbCancel, mbYes, mbNo, mbRetry, and mbClose.
</short>
</element>
<element name="TaskDlg.aFooter">
<short>
Text displayed as the caption in the footer area on the task dialog.
</short>
</element>
<element name="TaskDlg.aDetails">
<short>
Text displayed in an expandable text area on the task dialog. Include 
tfExpandedByDefault in Flags to automatically expand the text area in the main 
body of the task dialog. Include tfExpandFooterArea in Flags to place the 
detail text in the expandable footer area.
</short>
</element>
<element name="TaskDlg.AFlags">
<short>
Set of features or behaviors enabled in task dialog. The default value is 
[tfAllowDialogCancellation] and allows the task dialog to be cancelled.
</short>
</element>
<element name="TaskDlg.ADefaultButton">
<short>
Indicates the default button on the task dialog. Button identifiers start at 
500 for the task dialog.
</short>
</element>
<element name="TaskDlg.ARadioButtons">
<short>
Array of string values used as the captions for radio buttons displayed on the 
task dialog.
</short>
</element>
<element name="TaskDlg.RadioIndex">
<short>
Output parameter used to return the ordinal position for the radio button 
selected on the task dialog during execution.
</short>
</element>
<element name="TaskDlg.ADefaultRadio">
<short>
Ordinal position for the default radio button selected when the task dialog is 
executed. The default value is -1 and indicates that a default radio button has 
not been specified. The task dialog will default at run-time to the first radio 
button unless tfNoDefaultRadioButton has been included in Flags.
</short>
</element>
<element name="TaskDlg.ACheckBoxText">
<short>
Text displayed as the verification text on the task dialog.
</short>
</element>
<element name="TaskDlg.Checked">
<short>
Output parameter used to return the checked state for the verification check 
box on the task dialog.
</short>
</element>
<element name="TaskDlg.ACustomButtons">
<short>
Array of string values with the captions for custom buttons displayed on the task dialog.
</short>
</element>
<element name="TaskDlg.AShowDetails">
<short>
Text displayed as the caption for the expand/collapse button when the text area 
is enabled and collapsed.
</short>
</element>
<element name="TaskDlg.AHideDetails">
<short>
Text displayed as the caption for the expand/collapse button when the text area 
is enabled and expanded.
</short>
</element>

<element name="TCustomCopyToClipboardDialog">
<short>
Base class for a dialog form used during copy to clipboard operations.
</short>
<descr/>
<seealso/>
</element>

<element name="TCustomCopyToClipboardDialog.DoCreate">
<short>
Performs actions needed when a new instance of the form is created.
</short>
<descr>
<p>
<var>DoCreate</var> is an overridden method in 
<var>TCustomCopyToClipboardDialog</var>. It calls the inherited method on 
entry to signal <var>OnCreate</var> or other create handler(s) (when 
assigned). DoCreate calls the <var>RegisterDialogForCopyToClipboard</var> 
routine to enable key preview and set the <var>OnKeyDown</var> handler for 
the form instance.
</p>
</descr>
<seealso>
<link id="RegisterDialogForCopyToClipboard"/>
<link id="#lcl.forms.TCustomForm.OnCreate">TCustomForm.OnCreate</link>
<link id="#lcl.forms.TCustomForm.DoCreate">TCustomForm.DoCreate</link>
</seealso>
</element>

<element name="TCustomCopyToClipboardDialog.GetMessageText">
<short>
Specifies the method used to get the text for the message displayed on the 
dialog form.
</short>
<descr>
<p>
<var>GetMessageText</var> is an abstract virtual method in 
TCustomCopyToClipboardDialog. It must be implemented in a descendent class to 
return the correct value for the dialog form implementation.
</p>
</descr>
<seealso/>
</element>
<element name="TCustomCopyToClipboardDialog.GetMessageText.Result">
<short>Text for the message displayed on the dialog form.</short>
</element>

<element name="RegisterDialogForCopyToClipboard">
<short>
Enables key preview and adds the OnKeyDown handler for the specified dialog.
</short>
<descr/>
<seealso>
<link id="TCustomCopyToClipboardDialog.DoCreate"/>
</seealso>
</element>
<element name="RegisterDialogForCopyToClipboard.ADlg">
<short>Dialog form instance updated in the routine.</short>
</element>

<element name="DialogCopyToClipboard">
<short>Copies the content from the specified dialog to the clipboard.</short>
<descr>
<p>
Content from the dialog is stored as text in the clipboard. No actions are 
performed in the routine if Key and Shift contain values for keys other than 
Ctrl+C or Ctrl+Ins. The clipboard will contain lines with the Caption and 
Message text for the dialog, as well as the captions (sans accelerator keys) 
for controls displayed on the dialog.
</p>
</descr>
<seealso/>
</element>
<element name="DialogCopyToClipboard.Self">
<short>Dialog form instance examined in the routine.</short>
</element>
<element name="DialogCopyToClipboard.Sender">
<short>Not used in the routine.</short>
</element>
<element name="DialogCopyToClipboard.Key">
<short>Virtual key code which initiated the operation.</short>
</element>
<element name="DialogCopyToClipboard.Shift">
<short>Shift, Ctrl, or Alt modifier for the key code.</short>
</element>

<element name="cInputQueryEditSizePixels">
<short>Input Query Edit size in pixels.</short>
<descr/>
<seealso/>
</element>

<element name="cInputQueryEditSizePercents">
<short>Input Query Edit size as a percentage of the monitor width.</short>
<descr/>
<seealso/>
</element>

<element name="cInputQuerySpacingSize">
<short>Spacing between the controls on an Input Query dialog.</short>
<descr/>
<seealso/>
</element>

<element name="TSelectDirOpt">
<short>List of options available when selecting a directory.</short>
</element>
<element name="TSelectDirOpt.sdAllowCreate">
<short>
Allows a new directory to be created in a select directory dialog.
</short>
</element>
<element name="TSelectDirOpt.sdPerformCreate">
<short>
Indicates a directory that does not already exist should be created following 
execution of the dialog.
</short>
</element>
<element name="TSelectDirOpt.sdPrompt">
<short>
Indicates the dialog should prompt the user for confirmation of the selected 
action.
</short>
</element>

<element name="TSelectDirOpts">
<short>Set type used to store directory selection options.</short>
<descr>
<p>
<var>TSelectDirOpts</var> is a set type used to store zero or more values 
from the TSelectDirOpt enumeration. Values added to the set indicate the 
options enabled for a directory selection dialog. A TSelectDirOpts argument 
is passed to the <var>SelectDirectory</var> routine.
</p>
</descr>
<seealso>
<link id="TSelectDirOpt"/>
<link id="SelectDirectory"/>
</seealso>
</element>

<element name="TInputCloseQueryEvent">
<short>
Specifies an event handler signalled when an InputQuery dialog is about to 
close.
</short>
<descr/>
<seealso/>
</element>
<element name="TInputCloseQueryEvent.Sender">
<short>Object for the event notification.</short>
</element>
<element name="TInputCloseQueryEvent.AValues">
<short>Array of values which can be displayed in the event handler.</short>
</element>
<element name="TInputCloseQueryEvent.ACanClose">
<short>
<b>True</b> if the InputQuery can be closed, <b>False</b> to continue 
execution of the dialog.
</short>
</element>

<element name="SelectDirectory">
<short>A function that allows a user to select a directory.</short>
<descr>
<p>
This function will show a dialog which allows the user to select the required 
directory when the directory structure is displayed as a tree.
</p>
<p>
Under Windows the caption from the resulting dialog cannot be set, but the 
label above the directory tree will have this value.
</p>
<p>
There are two version of this function, the second one having the ability to 
indicate whether hidden folders should be shown as well.
</p>
</descr>
<seealso/>
</element>
<element name="SelectDirectory.Result">
<short>A boolean indicating if the user pressed OK.</short>
<descr>A boolean indicating if the user selected a directory and pressed 
OK.</descr>
</element>
<element name="SelectDirectory.Caption">
<short>A constant which sets the caption of the shown dialog.</short>
</element>
<element name="SelectDirectory.InitialDirectory">
<short>The directory the dialog should start in.</short>
<descr>
<p>
The directory the dialog should start in. If a valid directory is given, the 
selected directory in the tree will be set to this directory.
</p>
</descr>
</element>
<element name="SelectDirectory.Directory">
<short>A variable which on exit contains the selected directory.</short>
</element>
<element name="SelectDirectory.ShowHidden">
<short>
A boolean constant indicating whether hidden folders should be shown too.
</short>
</element>
<element name="SelectDirectory.HelpCtx">
<short>Help context for the dialog.</short>
</element>
<element name="SelectDirectory.Options">
<short>Set of options enabled for the dialog.</short>
</element>

<element name="InputQuery">
<short>Use InputQuery to show a dialog box to get input from the user.</short>
<descr>
<p>
Two versions of this function which displays a prompt and expects user input 
of textual data.
</p>
<p>
The first includes a <var>MaskInput</var> boolean argument which determines 
whether the user input is masked out by asterisks in the text-input box (like 
during entry of a password). The second variant omits this argument. Omitting 
the MaskInput argument is equivalent to setting it to <b>False</b>.
</p>
<p>
<var>Value</var> contains the initial text displayed in the edit control for 
the dialog. The text entered by the user is also returned in the variable 
argument Value.
</p>
<p>
The function result is a boolean which returns <b>True</b> if the OK button 
was pressed, or <var>False</var> if the box was closed by any other mechanism 
(such as clicking the 'Close' icon on the top title bar).
</p>
<p>
Another overloaded variant allows Arrays with String values to be passed in 
the APrompts and AValues arguments. They are used to create labels and edit 
controls on the dialog form, where the user can supply multiple values. The 
number of labels and edit controls on the dialog is determined by the length 
of the AValues array. An exception is raised when the APrompts and AValues 
arrays do not have the same length.
</p>
<p>
An event handler routine can be provided in the ACloseEvent argument to 
validate the input values, and determine if the dialog can be closed. It is 
signalled when the input dialog is closed by clicking the Cancel button or 
the Close icon on the dialog form. The handler returns an Array of String 
values input using the dialog.
</p>
</descr>
<seealso>
<link id="InputBox"/>
<link id="PasswordBox"/>
</seealso>
<example file="dialogs/inputquery.pas"/>
</element>
<element name="InputQuery.Result">
<short>
Returns <b>True</b> of OK button was pressed, <b>False</b> if Cancel was 
pressed or abnormal exit.
</short>
<descr>
Result is <b>True</b> if the user pressed OK or hit RETURN in the dialog box. 
If the user pressed Cancel or the dialog was closed without pressing a button 
the result will be <b>False</b>.
</descr>
</element>
<element name="InputQuery.ACaption">
<short>The caption for the dialog box.</short>
</element>
<element name="InputQuery.APrompt">
<short>
The text label displayed for the edit control on the dialog box.
</short>
</element>
<element name="InputQuery.MaskInput">
<short>
Determines if the dialog shows * characters instead of the actual input.
</short>
<descr>
Set MaskInput to <b>True</b> if you want to hide the input and display 
asterisks.
</descr>
</element>
<element name="InputQuery.Value">
<short>
The initial value(s) displayed, and the modified value(s) returned from the 
dialog box.
</short>
<descr>
<p>
<var>Value</var> is a variable parameter used to pass the initial value(s) 
displayed in the dialog box. The overloaded variants allow Value to be 
specified using either a <var>String</var> or an <var>Array of String</var> 
type. Value is where the modified content from the dialog box is returned 
when the <b>ENTER</b> key is pressed or the <b>OK</b> button is clicked.
</p>
</descr>
</element>
<element name="InputQuery.APrompts">
<short>Array with strings values used as labels on the input dialog.</short>
</element>
<element name="InputQuery.AValues">
<short>
Arrays with string values used in edit controls for the associated labels.
</short>
</element>

<element name="DefaultInputDialog">
<short>Widgetset-independent implementation of an input dialog.</short>
<descr/>
<seealso>
<link id="#lcl.interfacebase.InputDialogFunction">InputDialogFunction</link>
</seealso>
</element>
<element name="DefaultInputDialog.Result">
<short>
<b>True</b> if the Ok button was clicked during execution of the dialog.
</short>
</element>
<element name="DefaultInputDialog.InputCaption">
<short>Caption displayed as the title for the dialog.</short>
</element>
<element name="DefaultInputDialog.InputPrompt">
<short>Label displayed on the dialog form.</short>
</element>
<element name="DefaultInputDialog.MaskInput">
<short>
<b>True</b> if the edit control displays '*' characters to mask the input 
value.
</short>
</element>
<element name="DefaultInputDialog.Value">
<short>
Default value for the edit control on the dialog, and the value entered at 
run-time.
</short>
</element>

<element name="InputCombo">
<short>
Creates and executes a combo-box dialog with the specified Caption, Prompt, 
and list of selectable values.
</short>
<descr>
<p>
<var>InputCombo</var> is an Integer function used to create and display an 
input dialog with the values specified in the arguments to the routine.
</p>
<p>
The dialog form is constructed at run-time, and includes the controls needed 
to display the prompt (<var>TLabel</var>) and list of selectable items 
(<var>TComboBox</var>). It also includes a button panel 
(<var>TButtonPanel</var>) with <b>Ok</b> and <b>Cancel</b> buttons. The 
<var>Caption</var> for the dialog form is set to the <var>ACaption</var> 
argument.
</p>
<p>
The dimensions for the dialog form are determined by the maximum length of 
the string values passed in the function parameters. The form uses 
auto-scaling when enabled for the <var>Application</var>. Scaled size values 
are applied to the font for the form and its controls, as well the margins 
and separators used for control alignment. <var>Anchors</var> and 
<var>BorderSpacing</var> are used for control alignment to preserve their 
layout during auto-sizing and scaling operations. The display 
<var>Position</var> for the form is set to <var>poScreenCenter</var>.
</p>
<p>
InputCombo calls the <var>ShowModal</var> method for the <var>TForm</var> 
instance to display the dialog and capture the modal result value. When the 
modal result is <var>mrOk</var> (the OK button was pressed), the return value 
contains the ordinal position for the item in AList that was selected in the 
combo-box control. The return value is <b>-1</b> when the Cancel button or 
the Close border decoration is clicked.
</p>
<p>
Use <var>InputComboEx</var> to display a dialog form that allows custom text 
to be entered in its combo-box control. Use <var>InputQuery</var> to display 
a dialog form which allows entry of a text value using an edit mask.
</p>
</descr>
<seealso>
<link id="InputComboEx"/>
<link id="InputQuery"/>
</seealso>
</element>
<element name="InputCombo.Result">
<short>
Ordinal position for the value selected in AList, or -1 if an option was not 
selected.
</short>
</element>
<element name="InputCombo.ACaption">
<short>Caption or title for the dialog.</short>
</element>
<element name="InputCombo.APrompt">
<short>Label displayed for the combo-box control on the dialog.</short>
</element>
<element name="InputCombo.AList">
<short>
List of values which can be displayed and selected using the combo-box.
</short>
</element>

<element name="InputComboEx">
<short>
Displays an extended input combo-box dialog that allows entry of custom text 
values in its Items.
</short>
<descr>
<p>
<var>InputComboEx</var> is an overloaded <var>String</var> function used to 
create and display a dialog form that can select a value specified in the 
<var>AList</var> argument. The overloaded variants allow the AList argument 
to be specified as a <var>TStrings</var> instance or an array of 
<var>String</var> values.
</p>
<p>
<var>ACaption</var> contains the caption displayed as the title for the 
dialog form.
</p>
<p>
<var>APrompt</var> contains a string displayed as the label for the combo-box 
control.
</p>
<p>
<var>AllowCustomText</var> is a <var>Boolean</var> argument which indicates 
if text values can be added to the combo-box control at run-time. When set to 
<b>True</b>, text can be added to the TComboBox control. This is enabled by 
setting its <var>Style</var> property to <var>csDropDown</var> instead of 
<var>csDropDownList</var> (the default). The default value for the argument 
is <b>False</b> and prevents adding custom text to the combo-box control.
</p>
<p>
The dialog form is constructed at run-time, and includes the controls needed 
to display the prompt (<var>TLabel</var>) and list of selectable items 
(<var>TComboBox</var>). It also includes a button panel 
(<var>TButtonPanel</var>) with <b>Ok</b> and <b>Cancel</b> buttons. The 
<var>Caption</var> for the dialog form is set to the <var>ACaption</var> 
argument.
</p>
<p>
The dimensions for the dialog form are determined by the maximum length of 
the string values passed in the function parameters. The form uses 
auto-scaling when enabled for the <var>Application</var>. Scaled size values 
are applied to the font for the form and its controls, as well the margins 
and separators used for control alignment. <var>Anchors</var> and 
<var>BorderSpacing</var> are used for control alignment to preserve their 
layout during auto-sizing and scaling operations. The display 
<var>Position</var> for the form is set to <var>poScreenCenter</var>.
</p>
<p>
InputComboEx calls the <var>ShowModal</var> method for the <var>TForm</var> 
instance to display the dialog and capture the modal result value. When the 
modal result is <var>mrOk</var> (the OK button was pressed), the return value 
contains the value for the selected item in the combo-box control. The return 
value is an empty string ('') when the Cancel button or the Close border 
decoration is clicked.
</p>
</descr>
<seealso>
<link id="InputCombo"/>
<link id="InputQuery"/>
</seealso>
</element>
<element name="InputComboEx.Result">
<short>
String with the item selected in the combo-box, or an empty string if the 
dialog is cancelled.
</short>
</element>
<element name="InputComboEx.ACaption">
<short>Caption for the dialog.</short>
</element>
<element name="InputComboEx.APrompt">
<short>Prompt or label for the combo-box control.</short>
</element>
<element name="InputComboEx.AList">
<short>List of values displayed in the combo-box control.</short>
</element>
<element name="InputComboEx.AllowCustomText">
<short>
<b>True</b> to allow new values to be added to the combo-box control.
</short>
</element>

<element name="ExtractColorIndexAndColor">
<short>
Extracts the color index and color value for the specified position in a 
color list.
</short>
<descr/>
<seealso/>
</element>
<element name="ExtractColorIndexAndColor.Result">
<short>
<b>True</b> on success, <b>False</b> if the list does not use the correct 
format.
</short>
</element>
<element name="ExtractColorIndexAndColor.AColorList">
<short>List of colors in COLORID=VALUE format.</short>
</element>
<element name="ExtractColorIndexAndColor.AIndex">
<short>Position in the list for the extracted color index and value.</short>
</element>
<element name="ExtractColorIndexAndColor.ColorIndex">
<short>Color index (ColorA=0, ColorB=1, etc.)</short>
</element>
<element name="ExtractColorIndexAndColor.ColorValue">
<short>TColor for the hexadecimal value in the list.</short>
</element>

<element name="GetDialogCaption">
<short>
Gets the resource string used as the caption for the specified dialog 
identifier.
</short>
<descr>
<p>
The following dialog identifiers and return values are used in the routine:
</p>
<dl>
<dt>idDialogWarning</dt>
<dd>Return value is rsMtWarning.</dd>
<dt>idDialogError</dt>
<dd>Return value is rsMtError.</dd>
<dt>idDialogInfo</dt>
<dd>Return value is rsMtInformation.</dd>
<dt>idDialogConfirm</dt>
<dd>Return value is rsMtConfirmation.</dd>
<dt>idDialogShield</dt>
<dd>Return value is rsMtAuthentication.</dd>
</dl>
<p>
The return value is '?' when an unknown value is used in the idDiag argument.
</p>
</descr>
<seealso/>
</element>
<element name="GetDialogCaption.Result">
<short>Default caption for the dialog identifier.</short>
</element>
<element name="GetDialogCaption.idDiag">
<short>
Identifier for the dialog type, i. e. idDialogWarning or idDialogError.
</short>
</element>

<element name="GetDialogIcon">
<short>
Gets a bitmap with the icon for the specified dialog identifier.
</short>
<descr>
<p>
The bitmap may contain a stock image provided by theme services (when 
available), or a PNG image image loaded from a Lazarus resource in the 
application.
</p>
</descr>
<seealso/>
</element>
<element name="GetDialogIcon.Result">
<short>Bitmap with the icon for the dialog identifier.</short>
</element>
<element name="GetDialogIcon.idDiag">
<short>
Identifier for the dialog type, i. e. idDialogWarning or idDialogShield.
</short>
</element>

<element name="dbgs">
<short>
Creates a formatted debugger message for one or more TOpenOption values.
</short>
<descr/>
<version>
Modified in LCL version 4.0 to add additional overloads using TTaskDialogFlag 
and TTaskDialogFlags arguments.
</version>
<seealso/>
</element>
<element name="dbgs.Result">
<short>
Formatted message with enumeration value name(s) for the option or options 
argument.
</short>
</element>
<element name="dbgs.Option">
<short>
TOpenOption enumeration value used to generate the formatted message.
</short>
</element>
<element name="dbgs.Options">
<short>
TOpenOptions set type with the options used to generate the formatted message.
</short>
</element>
<element name="DbgS.AFlag">
<short>
TTaskDIalogFlag value converted to a string in the formatted message.
</short>
</element>
<element name="DbgS.Flags">
<short>
TTaskDialogFlags value converted to a string in the formatted message.
</short>
</element>

<element name="Register">
<short>Registers components for use in the Lazarus IDE.</short>
<descr>
<p>
Register is the procedure used to register components for use in the Lazarus 
IDE.
</p>
<p>
The following components are added to the Component Palette in the Lazarus 
IDE:
</p>
<p>
<b>Dialogs</b> Tab
</p>
<ul>
<li>TOpenDialog</li>
<li>TSaveDialog</li>
<li>TSelectDirectoryDialog</li>
<li>TColorDialog</li>
<li>TFontDialog</li>
<li>TFindDialog</li>
<li>TReplaceDialog</li>
<li>TTaskDialog</li>
</ul>
<p>
<b>Misc</b> Tab
</p>
<ul>
<li>TColorButton</li>
</ul>
</descr>
<seealso>
<link id="#rtl.classes.RegisterComponents">RegisterComponents</link>
</seealso>
</element>

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