<?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>
