<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
  <package name="lazutils">
    <!--
      ====================================================================
        FileReferenceList
      ====================================================================
    -->
    <module name="FileReferenceList">
      <short>Contains types and classes used to implement a list of file references.</short>
      <descr>
        <p>
          Implements the <var>TFileReference</var> and <var>TFileReferenceList</var> classes. Provides a list of file references with reference counters and a search path for files in the list.
        </p>
        <p>
          Author: Mattias Gaertner
        </p>
      </descr>

      <!-- unresolved external references -->
      <element name="Classes"/>
      <element name="SysUtils"/>
      <element name="Laz_AVL_Tree"/>
      <element name="LazFileUtils"/>
      <element name="LazFileCache"/>
      <element name="LazTracer"/>

      <element name="TFileReference">
        <short>Represents a reference-counted file stored in TFileReferenceList.</short>
        <descr>
          <p>
            <var>TFileReference</var> is a class used to represent a reference-counted file stored in the <var>TFileReferenceList</var> class. It provides <var>FileName</var> and <var>ReferenceCount</var> properties which are maintained by methods in TFileReferenceList.
          </p>
        </descr>
        <seealso>
          <link id="TFileReferenceList"/>
        </seealso>
      </element>

      <!-- private -->
      <element name="TFileReference.fFilename"/>
      <element name="TFileReference.fReferenceCount"/>

      <!-- public -->
      <element name="TFileReference.Filename">
        <short>Contains the name for the reference-counted file in the class instance.</short>
        <descr>
          <p>
            <var>FileName</var> is a read-only String property with the name for the reference-counted file. The value in FileName is assigned in the <var>TFileReferenceList.AddFilename</var> method when the class instance is created.
          </p>
          <p>
            Use <var>ReferenceCount</var> to determine the number of times the file is referenced in the AVL Tree for the <var>TFileReferenceList</var> class where the item is stored.
          </p>
        </descr>
        <seealso>
          <link id="TFileReference.ReferenceCount"/>
          <link id="TFileReferenceList.AddFilename"/>
          <link id="TFileReferenceList.RemoveFilename"/>
        </seealso>
      </element>

      <element name="TFileReference.ReferenceCount">
        <short>Contains the number of references for the file.</short>
        <descr/>
        <seealso>
          <link id="TFileReference.FileName"/>
          <link id="TFileReferenceList.AddFilename"/>
          <link id="TFileReferenceList.RemoveFilename"/>
        </seealso>
      </element>

      <element name="TFileReferenceFlag">
        <short>Represents flag values used for file references in TFileReferenceList.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TFileReferenceFlag.frfSearchPathValid">
        <short>
          Included when the search path for a file reference list is valid.
        </short>
      </element>
      <element name="TFileReferenceFlag.frfChanged">
        <short>
          Included when the Timestamp or UpdateLock is changed for a file reference list.
        </short>
      </element>

      <element name="TFileReferenceFlags">
        <short>Set type used to store flag values for TFileReferenceList.</short>
        <descr/>
        <seealso>
          <link id="TFileReferenceList"/>
        </seealso>
      </element>

      <element name="TFileReferenceList">
        <short>Implements a list used to maintain TFileReference instances.</short>
        <descr/>
        <seealso/>
      </element>

      <!-- private -->
      <element name="TFileReferenceList.FOnChanged"/>
      <element name="TFileReferenceList.FTimeStamp"/>

      <element name="TFileReferenceList.FTree">
        <short>Tree of TFileReference instances sorted by file name.</short>
      </element>

      <element name="TFileReferenceList.FFlags"/>
      <element name="TFileReferenceList.FSearchPath"/>
      <element name="TFileReferenceList.FUpdateLock"/>

      <element name="TFileReferenceList.UpdateSearchPath">
        <short>
          Reconstructs the delimited list of search path(s) for the files in the list.
        </short>
      </element>

      <element name="TFileReferenceList.IncreaseTimeStamp">
        <short>Increments the value in the TimeStamp property.</short>
      </element>

      <element name="TFileReferenceList.Invalidate">
        <short>
          Updates the TimeStamp and internal flags for the list, and signal OnChange when needed.
        </short>
      </element>

      <!-- public -->
      <element name="TFileReferenceList.Create">
        <short>Constructor for the class instance.</short>
        <descr>
          <p>
            Sets the default value for the <var>Timestamp</var> property (<var>LUInvalidChangeStamp64</var>).
          </p>
        </descr>
        <seealso>
          <link id="TFileReferenceList.TimeStamp"/>
          <link id="#lazutils.lazfilecache.LUInvalidChangeStamp64"/>
        </seealso>
      </element>

      <element name="TFileReferenceList.Destroy">
        <short>Destructor for the class instance.</short>
        <descr>
          <p>
            <var>Destroy</var> is the overridden destructor for the class instance. It calls <var>Clear</var> to remove nodes in the internal AVL Tree for the class instance. Calls the inherited destructor prior to exiting from the method.
          </p>
        </descr>
        <seealso/>
      </element>

      <element name="TFileReferenceList.Clear">
        <short>Removes any tree nodes in the internal AVL tree.</short>
        <descr>
          Also frees the <var>TFileReference</var> instance for the AVL tree nodes.
        </descr>
        <seealso/>
      </element>

      <element name="TFileReferenceList.BeginUpdate">
        <short>Increments the UpdateLock for the class instance.</short>
        <descr/>
        <seealso/>
      </element>

      <element name="TFileReferenceList.EndUpdate">
        <short>Decrements the UpdateLock and signals OnChange when needed.</short>
        <descr/>
        <seealso/>
      </element>

      <element name="TFileReferenceList.AddFilename">
        <short>Adds a reference-counted file name to the list.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TFileReferenceList.AddFilename.Filename">
        <short>File name added to the list and the internal AVL tree.</short>
      </element>

      <element name="TFileReferenceList.RemoveFilename">
        <short>Remove a reference for the specified file name.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TFileReferenceList.RemoveFilename.Filename">
        <short>
          File name de-referenced in the list and optionally removed from the internal AVL tree.
        </short>
      </element>

      <element name="TFileReferenceList.GetFileReference">
        <short>Gets an existing TFileReference instance for the specified file name.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TFileReferenceList.GetFileReference.Result">
        <short>
          TFileReference instance for the specified file name, or Nil when not found.
        </short>
      </element>
      <element name="TFileReferenceList.GetFileReference.Filename">
        <short>File name to locate in the list.</short>
      </element>

      <element name="TFileReferenceList.CreateSearchPathFromAllFiles">
        <short>
          Gets a delimited list of search paths for the reference-counted files in the list.
        </short>
        <descr/>
        <seealso/>
      </element>
      <element name="TFileReferenceList.CreateSearchPathFromAllFiles.Result">
        <short>Delimited list of search paths for the reference-counted files.</short>
      </element>

      <element name="TFileReferenceList.CreateFileList">
        <short>
          Creates and returns a TStringList instance with the file names in the list.
        </short>
        <descr/>
        <seealso/>
      </element>
      <element name="TFileReferenceList.CreateFileList.Result">
        <short>TStringList instance allocated in the method for the list of file names.</short>
      </element>

      <element name="TFileReferenceList.TimeStamp">
        <short>Contains the timestamp value for the last change to the list.</short>
        <descr/>
        <seealso/>
      </element>

      <element name="TFileReferenceList.OnChanged">
        <short>Event handler signalled when items in the list have been changed.</short>
        <descr/>
        <seealso/>
      </element>

      <element name="TFileReferenceList.UpdateLock">
        <short>Contains the active update counter for the list.</short>
        <descr/>
        <seealso/>
      </element>

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