<?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">
<!--
====================================================================
lazdialogs
====================================================================
-->
<module name="lazdialogs">
<short>
Contains classes, types, and routines needed for Lazarus dialogs in 
custom-drawn and non-desktop environments.
</short>
<descr>
<p>
<file>lazdialogs.pas</file> contains classes, types, and routines needed for 
Lazarus dialogs in custom-drawn and non-desktop environments.
</p>
</descr>

<element name="TLazFileDialogKind">
<short>
Enumerated type which represents the dialog kind in a Lazarus dialog form.
</short>
<descr></descr>
<seealso>
<link id="TLazarusFileDialogForm.Initialize"/>
<link id="TLazOpenDialog.DoInitialize"/>
<link id="TLazSaveDialog.DoInitialize"/>
<link id="TLazSelectDirectoryDialog.DoInitialize"/>
</seealso>
</element>
<element name="TLazFileDialogKind.ldkOpenDesktop">
<short>Dialog is an open dialog for desktop environments.</short>
</element>
<element name="TLazFileDialogKind.ldkSaveDesktop">
<short>Dialog is a save dialog for desktop environments.</short>
</element>
<element name="TLazFileDialogKind.ldkOpenPDA">
<short>Dialog is an open dialog for PDA environments.</short>
</element>
<element name="TLazFileDialogKind.ldkSavePDA">
<short>Dialog is a save dialog for PDA environments.</short>
</element>
<element name="TLazFileDialogKind.ldkSelectDirectory">
<short>Dialog is a directory selection dialog.</short>
</element>

<element name="TLazarusFileDialogForm">
<short>
Implements the form displayed for TLazOpenDialog descendants.  
</short>
<descr>
<p>
<var>TLazarusFileDialogForm</var> is a <var>TForm</var> descendant which 
implements the form displayed for dialogs which are not wrappers for native 
dialogs on a given platform. The form includes public members that are used 
to store input or output values for the dialog, like:
</p>
<ul>
<li>FileName</li>
<li>Filter</li>
<li>InitialDir</li>
<li>Title</li>
</ul>
<p>
It includes public user interface elements needed for the dialog form. The 
active UI elements are determined by the TLazFileDialogKind value passed as 
an argument when a dialog calls the Initialize method for the form. The UI 
elements include:
</p>
<ul>
<li>ShellTreeView (TShellTreeView)</li>
<li>ShellListView (TShellListView)</li>
<li>SaveEdit (TEdit)</li>
<li>FilterComboBox (TFilterComboBox)</li>
<li>ButtonPanel (TButtonPanel)</li>
</ul>
<p>
TLazarusFileDialogForm includes methods that implement routines assigned to 
event handlers in the various UI elements. The routines perform actions like 
setting the ModalResult value when a button is clicked, updating FileName 
from selected nodes in the shell controls, and enabling / disabling controls 
as needed.
</p>
<p>
TLazarusFileDialogForm is used to implement the private form member in the 
TLazOpenDialog component.
</p>
</descr>
<seealso>
<link id="TLazOpenDialog"/>
<link id="TLazFileDialogKind"/>
<link id="#lcl.forms.TForm">TForm</link>
</seealso>
</element>

<element name="TLazarusFileDialogForm.FKind">
<short>
Member used to store the TLazFileDialogKind enumeration value for the dialog 
form.
</short>
</element>

<element name="TLazarusFileDialogForm.SetFilter">
<short>
Sets the value for the file mask used in the Filter for the dialog form.
</short>
<descr>
<p>
<var>SetFilter</var> is a procedure used to set the value in the 
<var>Filter</var> for the dialog form. SetFilter ensures that the new 
property value in <var>AFilter</var> is also applied to the filter for the 
combo box in the dialog form.
</p>
<p>
When AFilter is an empty string (<b>''</b>), the filter in FilterComboBox is 
set to the file mask that matches all files (<var>rsAllFiles</var>). 
Otherwise, the new property value in AFilter is used in the filter for 
FilterComboBox.
</p>
</descr>
<seealso>
<link id="TLazarusFileDialogForm.FilterComboBox"/>
</seealso>
</element>

<element name="TLazarusFileDialogForm.SetFilter.AFilter">
<short>New value for the Filter member.</short>
</element>

<element name="TLazarusFileDialogForm.ButtonPanel">
<short>
Button panel for the Lazarus dialog form.
</short>
<descr>
<p>
<var>ButtonPanel</var> is a <var>TButtonPanel</var> member that contains the 
buttons appropriate for a specific kind of Lazarus dialog. ButtonPanel is 
configured by default to display and respond to Ok and Cancel buttons in the 
Initialize method. Specialized dialog types can alter the default buttons and 
their actions.
</p>
</descr>
<seealso>
<link id="TLazarusFileDialogForm.Initialize"/>
<link id="TLazFileDialogKind"/>
</seealso>
</element>

<element name="TLazarusFileDialogForm.ShellTreeView">
<short>
Shell tree view control for the Lazarus dialog form.
</short>
<descr></descr>
<seealso></seealso>
</element>

<element name="TLazarusFileDialogForm.ShellListView">
<short>
Shell list view control for the Lazarus dialog form.
</short>
<descr></descr>
<seealso></seealso>
</element>

<element name="TLazarusFileDialogForm.SaveEdit">
<short>Edit control used for a FileName on the dialog form.</short>
<descr></descr>
<seealso></seealso>
</element>

<element name="TLazarusFileDialogForm.FilterComboBox">
<short>
Combo box control used for the file mask filter in the Lazarus dialog form.
</short>
<descr></descr>
<seealso></seealso>
</element>

<element name="TLazarusFileDialogForm.FileName">
<short>
File name for the selected file in the Lazarus dialog form.
</short>
<descr>
<p>
FileName is a String member which contains the full path and file name for 
the item affected by the Lazarus dialog.
</p>
<p>
For Open dialogs, it contains the path for the Selected item in the 
ShellListView control. For Save dialogs, it contains the path for the 
Selected directory in the ShellTreeView combined with the value from the 
SaveEdit control. For other dialog types, it contains the path information 
for the Selected item in the ShellTreeView control.
</p>
</descr>
<seealso>
<link id="TLazFileDialogKind"/>
<link id="TLazarusFileDialogForm.ShellTreeView"/>
<link id="TLazarusFileDialogForm.ShellListView"/>
<link id="TLazarusFileDialogForm.SaveEdit"/>
</seealso>
</element>

<element name="TLazarusFileDialogForm.Filter">
<short>
File mask filter for the Lazarus dialog form.
</short>
<descr></descr>
<seealso></seealso>
</element>

<element name="TLazarusFileDialogForm.InitialDir">
<short>
Initial directory used in the Lazarus file dialog form.
</short>
<descr></descr>
<seealso></seealso>
</element>

<element name="TLazarusFileDialogForm.Title">
<short>
Title displayed for the Lazarus dialog form.
</short>
<descr></descr>
<seealso></seealso>
</element>

<element name="TLazarusFileDialogForm.CreateNew">
<short>
Alternate constructor for the class instance.
</short>
<descr>
<p>
CreateNew is an overridden constructor for the class instance. CreateNew 
calls the inherited method using values in AOwner and Num as arguments. 
CreateNew ensures that the Lazarus dialog form sets its position to the value 
poScreenCenter.
</p>
<p>
CreateNew allows the form instance to be created without using the associated 
.lfm file. The CreateNew constructor is used (instead of Create) when the 
TCustomForm descendant is not a TForm class instance or not a descendant of 
TForm.
</p>
<p>
See the Initialize method for information about creation and positioning of 
child controls on the Lazarus dialog form.
</p>
</descr>
<seealso>
<link id="TLazarusFileDialogForm.Initialize"/>
<link id="#lcl.forms.TCustomForm.CreateNew">TCustomForm.CreateNew</link>
</seealso>
</element>

<element name="TLazarusFileDialogForm.CreateNew.AOwner">
<short>Owner of the Lazarus dialog form.</short>
</element>

<element name="TLazarusFileDialogForm.CreateNew.Num">
<short>Not used in the current implementation.</short>
</element>

<element name="TLazarusFileDialogForm.Initialize">
<short>
Creates and positions child controls on the Lazarus dialog form.
</short>
<descr>
<p>
Initialize is a procedure used to create and position child controls on the 
Lazarus dialog form appropriate for the dialog type specified in AKind.
</p>
<p>
The value in AKind is stored in an internal member in the class instance, and 
is used to determine the child controls configured and displayed on the 
Lazarus dialog form. It affects the following:
</p>
<ul>
<li>ShellTreeView</li>
<li>ShellListView</li>
<li>SaveEdit</li>
<li>FilterComboBox</li>
<li>ButtonPanel</li>
</ul>
<p>
Initialize creates the ButtonPanel for the Lazarus dialog form, and positions 
it aligned to the bottom of the form instance. ButtonPanel is configured to 
display Ok and Cancel buttons, and uses the HandleOkClick and 
HandleCancelClick methods to respond to the OnClick events for the respective 
buttons.
</p>
<p>
Initialize uses the HandleCloseQuery method as the event handler for the 
OnCloseQuery event.
</p>
</descr>
<seealso>
<link id="TLazarusFileDialogForm.ButtonPanel"/>
<link id="TLazarusFileDialogForm.ShellListView"/>
<link id="TLazarusFileDialogForm.ShellTreeView"/>
<link id="TLazarusFileDialogForm.SaveEdit"/>
<link id="TLazarusFileDialogForm.FilterComboBox"/>
</seealso>
</element>
<element name="TLazarusFileDialogForm.Initialize.AKind">
<short>Dialog kind for the Lazarus dialog form instance.</short>
</element>

<element name="TLazarusFileDialogForm.HandleOkClick">
<short>
Event handler signalled when the OK button is clicked.
</short>
<descr></descr>
<seealso></seealso>
</element>
<element name="TLazarusFileDialogForm.HandleOkClick.ASender">
<short>.
</short>
</element>

<element name="TLazarusFileDialogForm.HandleCancelClick">
<short>
Event handler signalled when the Cancel button is clicked.
</short>
<descr></descr>
<seealso></seealso>
</element>
<element name="TLazarusFileDialogForm.HandleCancelClick.ASender">
<short>
Component generating the event notification.
</short>
</element>

<element name="TLazarusFileDialogForm.HandleCloseQuery">
<short>
Event handler for an OnCloseQuery event notification.
</short>
<descr>
<p>
<var>HandleCloseQuery</var> is a procedure used as the event handler for the 
<var>OnCloseQuery</var> event notification. It is assigned in the Initialize 
method.
</p>
<p>
HandleCloseQuery ensures that the Lazarus dialog form can in fact be closed, 
and updates the value in FileName when needed. It sets the value in the 
CanClose parameter to <b>False</b> when the modal result for the dialog form 
is mrCancel. No additional actions are performed in the method if the dialog 
form cannot be closed.
</p>
<p>
Additional actions are performed in the method to update FileName and 
CanClose based on the TLazFileDialogKind value used in the dialog form. For 
Save dialogs (where Kind is ldkSaveDesktop or ldkSavePDA), the value in the 
SaveEdit control cannot contain be an empty string (<b>''</b>). No additional 
actions are performed in the method when SaveEdit is empty. Otherwise, the 
values from the selected item in ShellTreeView, PathDelimite, and SaveEdit 
are combined and assigned to FileName. CanClose is also set to True.
</p>
<p>
For Open dialogs (where Kind is ldkOpenDesktop or ldkOpenPDA), the selected 
item in ShellListView cannot be unassigned (<b>Nil</b>). No additional 
actions are performed in the method when the selected item in ShellListView 
is unassigned. Otherwise, the value in FileName is set to the path and file 
name for the selected item in ShellListView. CanClose is also set to True.
</p>
<p>
For other dialog kinds, the selected item in ShellTreeView cannot be 
unassigned (<b>Nil</b>). No additional actions are perform when the selected 
item in ShellTreeView is unassigned. Otherwise, the path information for the 
selected item is stored in FileName. CanClose is also set to True.
</p>
</descr>
<seealso>
<link id="TLazarusFileDialogForm.Initialize"/>
<link id="TLazarusFileDialogForm.FileName"/>
<link id="TLazarusFileDialogForm.ShellTreeView"/>
<link id="TLazarusFileDialogForm.ShellListView"/>
</seealso>
</element>
<element name="TLazarusFileDialogForm.HandleCloseQuery.Sender">
<short>Component performing the event notification.</short>
</element>
<element name="TLazarusFileDialogForm.HandleCloseQuery.CanClose">
<short>Indicates if the Lazarus dialog form can be closed.</short>
</element>

<element name="TLazarusFileDialogForm.HandleEditChange">
<short>
Event handler for changes to the value in the SaveEdit control.
</short>
<descr>
<p>
HandleEditChange is a procedure used as the event handler for changes to the 
value in the SaveEdit control. It is assigned to the control in the 
Initialize method.
</p>
<p>
HandleEditChange ensures that the OK button in ButtonPanel is enabled or 
disabled based on the value in SaveEdit; it is enabled when the value for 
SaveEdit is not an empty string (<b>''</b>).
</p>
</descr>
<seealso>
<link id="TLazarusFileDialogForm.SaveEdit"/>
<link id="TLazarusFileDialogForm.ButtonPanel"/>
</seealso>
</element>
<element name="TLazarusFileDialogForm.HandleEditChange.ASender">
<short>Component generating the event notification.</short>
</element>

<element name="TLazarusFileDialogForm.HandleSelectItem">
<short>
Event handler for changes to the selected item in ShellListView.
</short>
<descr>
<p>
HandleSelectItem is a procedure used as the event handler for a change to the 
selected item in ShellListView. It is assigned to the OnSelectItem property 
in ShellListView in the Initialize method.
</p>
<p>
HandleSelectItem ensures that the value in SaveEdit is updated with the 
Caption for the selected item in Save dialogs (Kind is ldkSaveDesktop or 
ldkSavePDA). For other dialog types, the OK button in ButtonPanel is enabled 
or disabled depending on the selection of an item in ShellListView; the OK 
button is Enabled when the Selected parameter contains True.
</p>
</descr>
<seealso>
<link id="TLazarusFileDialogForm.SaveEdit"/>
<link id="TLazarusFileDialogForm.ShellListView"/>
<link id="TLazarusFileDialogForm.ButtonPanel"/>
</seealso>
</element>
<element name="TLazarusFileDialogForm.HandleSelectItem.Sender">
<short>
Component generating the event notification.
</short>
</element>
<element name="TLazarusFileDialogForm.HandleSelectItem.Item">
<short>
List item selected in the ShellListView control.
</short>
</element>
<element name="TLazarusFileDialogForm.HandleSelectItem.Selected">
<short>
Indicates that Item is selected when True.
</short>
</element>

<element name="TLazarusFileDialogForm.HandleTreeViewSelectionChanged">
<short>
Event handler signalled when the selected item in ShellTreeView is changed.
</short>
<descr>
<p>
HandleTreeViewSelectionChanged is a procedure used as the event handler for a 
change to the selected item in the ShellTreeView control. It is assigned to 
the OnSelectItem property for the ShellListView control in the Initialize 
method.
</p>
<p>
HandleTreeViewSelectionChanged is used in directory selection dialogs (Kind 
contains ldkSelectDirectory). HandleTreeViewSelectionChanged ensures that the 
OK button in ButtonPanel is enabled.
</p>
</descr>
<seealso>
<link id="TLazarusFileDialogForm.ShellTreeView"/>
<link id="TLazarusFileDialogForm.ButtonPanel"/>
<link id="TLazFileDialogKind"/>
</seealso>
</element>
<element name="TLazarusFileDialogForm.HandleTreeViewSelectionChanged.ASender">
<short>Component generating the event notification.</short>
</element>

<element name="TLazOpenDialog">
<short>
Implements a Lazarus file open dialog.
</short>
<descr></descr>
<seealso></seealso>
</element>

<element name="TLazOpenDialog.FForm">
<short>
Member used to store the form instance for the Lazarus dialog.
</short>
</element>

<element name="TLazOpenDialog.WSRegisterClass">
<short>
An empty implementation; dialogs do not require a WS implementation.
</short>
</element>

<element name="TLazOpenDialog.DoExecute">
<short>
Executes the file open dialog.
</short>
<descr>
<p>
<var>DoExecute</var> is an overridden <var>Boolean</var> function used to 
execute the Lazarus File Open dialog. The return value is <b>True</b> when 
the ShowModal method in the dialog form is a value other than 
<var>mrCancel</var>. DoExecute also updates the FileName member to reflect 
the value returned on the dialog form.
</p>
</descr>
<seealso>
<link id="TLazarusFileDialogForm"/>
<link id="TLazarusFileDialogForm.FileName"/>
<link id="#lcl.forms.TCustomForm.ShowModal">TCustomForm.ShowModal</link>
</seealso>
</element>
<element name="TLazOpenDialog.DoExecute.Result">
<short>
<b>True</b> when the file open dialog was not cancelled during execution.
</short>
</element>

<element name="TLazOpenDialog.DoInitialize">
<short>
Performs actions needed to initialize the Lazarus dialog.
</short>
<descr></descr>
</element>
<seealso></seealso>

<element name="TLazOpenDialog.Create">
<short>
Constructor for the class instance.
</short>
<descr></descr>
<seealso></seealso>
</element>
<element name="TLazOpenDialog.Create.TheOwner">
<short>Owner of the Lazarus dialog.</short>
</element>

<element name="TLazSaveDialog">
<short>
Implements a Lazarus File Save dialog.
</short>
<descr></descr>
<seealso></seealso>
</element>

<element name="TLazSaveDialog.DoInitialize">
<short>
Performs actions needed to initialize the Lazarus dialog.
</short>
<descr></descr>
<seealso></seealso>
</element>

<element name="TLazSelectDirectoryDialog">
<short>
Implements a Lazarus directory selection dialog.
</short>
<descr></descr>
<seealso></seealso>
</element>

<element name="TLazSelectDirectoryDialog.DoInitialize">
<short>
Performs actions needed to initialize the Lazarus dialog.
</short>
<descr></descr>
<seealso></seealso>
</element>

</module>
<!-- lazdialogs -->

</package>
</fpdoc-descriptions>