lazarus/components/lazcontrols/docs/shortpathedit.xml

<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
<package name="LazControls">

<module name="ShortPathEdit">
<short>Implements the TShortPathEdit control.</short>
<descr>
<p>
<file>ShortPathEdit.pas</file> implements the TShortPathEdit control, a 
directory edit control with a directory selection dialog.
</p>
<p>
This file is part of the <file>LazControls</file> package.
</p>
</descr>

<!-- unresolved external references -->
<element name="Classes"/>
<element name="SysUtils"/>
<element name="EditBtn"/>
<element name="Dialogs"/>
<element name="LazFileUtils"/>

<element name="TShortPathEdit">
<short>Control used to select a directory on the local file system.</short>
<descr>
<p>
<var>TShortPathEdit</var> is a <var>TDirectoryEdit</var> descendant which 
allows selecting a directory on the local file system.
</p>
<p>
TShortPathEdit provides a <var>Directory</var> property to specify the 
starting directory for its path selection dialog. If Directory is not 
assigned, the RootDirectory property is used instead. It differs from the 
ancestor class in its implementation of the <var>CreateDialog</var> and 
<var>RunDialog</var> methods.
</p>
<p>
An <var>OnAcceptDirectory</var> event handler is provided and allows the 
application to determine how the selected directory name is handled. The 
event handler can be used to process and store the value for the directory 
selected in the dialog.
</p>
<p>
TShortPathEdit is used in the implementation of the path editor dialog in the 
Lazarus IDE.
</p>
</descr>
<seealso>
<link id="#lcl.editbtn.TDirectoryEdit"/>
</seealso>
</element>

<!-- private -->
<element name="TShortPathEdit.FDirectory"/>
<element name="TShortPathEdit.FOnAcceptDir"/>

<!-- protected -->
<element name="TShortPathEdit.CreateDialog">
<short>Creates and configures the dialog used to select a directory.</short>
<descr>
<p>
<var>CreateDialog</var> is an overridden method in <var>TShortPathEdit</var> 
used to create and configure the directory selection dialog for the control.  
The return value contains the <var>TCommonDialog</var> descendant created and 
configured in the method. It is actually a <var>TSelectDirectoryDialog</var> 
instance.
</p>
<p>
CreateDialog uses the value in the <var>Directory</var> property as the 
initial directory for the dialog. Directory must contain a path which exists 
on the local file system. If Directory is unassigned, or does not exist, the 
value in <var>RootDir</var> is used as the initial directory for the dialog.
</p>
<p>
CreateDialog assigns the value in <var>DialogTitle</var> as the title for the 
dialog.
</p>
<p>
CreateDialog is called when the <var>RunDialog</var> method is called after 
clicking on the speed button for the control.
</p>
</descr>
<seealso/>
</element>
<element name="TShortPathEdit.CreateDialog.Result">
<short>
Directory selection dialog created and configured in the method.
</short>
</element>

<!-- published -->
<element name="TShortPathEdit.RunDialog">
<short>Executes the directory selection dialog for the control.</short>
<descr>
<p>
<var>RunDialog</var> is an overridden method in <var>TShortPathEdit</var>. It 
is an alternate implementation, and does not call the inherited method.
</p>
<p>
RunDialog calls <var>CreateDialog</var> to create and configure the directory 
selection dialog used in the control. The <var>Execute</var> method in the 
dialog is called, and the String returned as the dialog result is captured. 
The <var>OnAcceptDirectory</var> event handler is signalled (when assigned) 
using the dialog result as an argument. If the dialog return value is not an 
empty string (''), it is assigned to the <var>Directory</var> property.
</p>
</descr>
<seealso/>
</element>

<element name="TShortPathEdit.Directory">
<short>Initial directory used in the directory selection dialog.</short>
<descr>
<p>
<var>Directory</var> is a <var>String</var> property used to specify the 
initial directory on the local file system used to select a directory in the 
control. It is used as the initial directory for the directory selection 
dialog executed in the RunDialog method. It is also used to store a valid 
path name returned from the directory selection dialog.
</p>
<p>
A value assigned to Directory is not automatically reflected in the text for 
the control. Use the OnAcceptDirectory event handler to update the value in 
Text if desired.
</p>
</descr>
<seealso/>
</element>

<element name="TShortPathEdit.OnAcceptDirectory">
<short>
Event handler signalled when a directory is selected in the directory 
selection dialog.
</short>
<descr>
<p>
<var>OnAcceptDirectory</var> is <var>TAcceptFileNameEvent</var> property 
with the event handler signalled when a directory path has been selected in 
the <var>RunDialog</var> method. Arguments to the event handler include the 
directory name selected in the dialog, or an empty string when the Cancel 
button is pressed in the dialog.
</p>
<p>
OnAcceptDirectory can be used to performed actions needed when the selected 
directory has been changed. Value is a variable parameter, so it can be 
modified in the event handler prior to its storage in the 
<var>Directory</var> property. For instance, the selected directory could be 
converted to a path relative to the RootDir for the control. Or, the selected 
directory could shortened and assigned to the <var>Text</var> for the control.
</p>
<p>
Applications must implement and assign an object procedure to allow 
responding to the event notification.
</p>
</descr>
<seealso/>
</element>

</module>

</package>
</fpdoc-descriptions>