<?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="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>
<p>
<file>filereferencelist.pas</file> is part of the <file>lazutils</file> 
package.
</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">LUInvalidChangeStamp64</link>
</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>