paweld/lazarus
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/lazarus/lazarus.git synced 2025-04-06 05:38:25 +02:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Lazutils documentation update, includes directories for examples. Issue #38365, patch from Andrey Sobol.

Browse Source 
git-svn-id: trunk@64406 -
This commit is contained in:
juha 2021-01-19 13:54:29 +00:00
parent b092cee8be
commit f3e2fd9696
6 changed files with 304 additions and 231 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.gitattributes vendored
View File

@ -6089,6 +6089,8 @@ docs/xml/lazutils/compwriterpas.xml svneol=native#text/plain
docs/xml/lazutils/dynamicarray.xml svneol=native#text/plain
docs/xml/lazutils/dynhasharray.xml svneol=native#text/plain
docs/xml/lazutils/dynqueue.xml svneol=native#text/plain
docs/xml/lazutils/examples/fileutil.findallfiles.pas svneol=native#text/pascal
docs/xml/lazutils/examples/readme.txt svneol=native#text/plain
docs/xml/lazutils/extendedstrings.xml svneol=native#text/plain
docs/xml/lazutils/filereferencelist.xml svneol=native#text/plain
docs/xml/lazutils/fileutil.xml svneol=native#text/plain
@ -6186,6 +6188,7 @@ docs/xml/lcl/dialogs/trymessagedlg.pas svneol=native#text/pascal
docs/xml/lcl/dialogs/tryshowmessage.pas svneol=native#text/pascal
docs/xml/lcl/dynamicarray/tarrayexample.pas svneol=native#text/plain
docs/xml/lcl/editbtn.xml svneol=LF#text/xml eol=lf
docs/xml/lcl/examples/readme.txt svneol=native#text/plain
docs/xml/lcl/extctrls.xml svneol=LF#text/xml eol=lf
docs/xml/lcl/extctrls/radiobutton.pas svneol=native#text/pascal
docs/xml/lcl/extctrls/statusbar.pas svneol=native#text/plain

23
docs/xml/lazutils/examples/fileutil.findallfiles.pas Normal file
View File

@ -0,0 +1,23 @@
uses
FileUtil;
var
PascalFiles: TStringList;
begin
PascalFiles := TStringList.Create;
try
FindAllFiles(PascalFiles, LazarusDirectory, '*.pas;*.pp;*.p;*.inc', true); //find e.g. all pascal sourcefiles
ShowMessage(Format('Found %d Pascal source files', [PascalFiles.Count]));
finally
PascalFiles.Free;
end;
end;
// or
begin
//No need to create the stringlist; the function does that for you
PascalFiles := FindAllFiles(LazarusDirectory, '*.pas;*.pp;*.p;*.inc', true); //find e.g. all pascal sourcefiles
try
ShowMessage(Format('Found %d Pascal source files', [PascalFiles.Count]));
finally
PascalFiles.Free;
end;
end;

34
docs/xml/lazutils/examples/readme.txt Normal file
View File

@ -0,0 +1,34 @@
This directory is intended for storing examples of Pascal code included in the documentation.
You can include example code in the documentation as follows:
1. Place an example of the code inside this directory as a unit with name UnitName.FunctionName.pas or similar.
Place the link in this example for the documentation <element> tag as follows:
<element name="MyDangerousFunction">
<example file="examples/UnitName.MyDangerousFunction.pas"/>
</element>
The file attribute of the <example> tag is used to specify the filename containing the example. The filename does not require an extension: if it is missing, .pp is assumed.
If you use the fpdoc editor then use the example tab for that.
https://www.freepascal.org/docs-html/current/fpdoc/fpdocsu70.html
2. Place the example code into the <descr><descr/> section inside <code></code> tags.
Note that any text surrounding the code tags should be placed inside <p></p> tags.
For example:
<element name="MyDangerousFunction">
<descr>
<p>
// Any description.
</p>
<code>
// Place example code here.
</code>
</p>
</descr>
</element>
https://www.freepascal.org/docs-html/current/fpdoc/fpdocsu63.html

277
docs/xml/lazutils/fileutil.xml
View File

@ -10,16 +10,10 @@
<short>
Miscellaneous procedures, functions, types, and classes for manipulating files and file names
</short>
<descr>
<p>
This unit contains functions, procedures, types, and classes used to maintain compatibility with the FileUtil unit in Delphi. File routines that deal with UTF-8 file names are located in the LazFileUtils unit.
</p>
<p>
File name handling in the unit is platform- or OS-specific. For the Windows, Darwin (MacOS), and Amiga platforms, file names are <b>NOT</b> case sensitive. In addition, under Darwin, the <b>NotLiteralFilenames</b> define is enabled. This indicates that file names cannot be compared using the <b>=</b>
<descr><p>This unit contains functions, procedures, types, and classes used to maintain compatibility with the FileUtil unit in Delphi. File routines that deal with UTF-8 file names are located in the LazFileUtils unit.
</p><p>File name handling in the unit is platform- or OS-specific. For the Windows, Darwin (MacOS), and Amiga platforms, file names are <b>NOT</b> case sensitive. In addition, under Darwin, the <b>NotLiteralFilenames</b> define is enabled. This indicates that file names cannot be compared using the <b>=</b>
string operator.
</p>
<p>
This unit contains basic functions similar to those in the RTL, but use UTF-8 instead of the defauilt system encoding. Please note that AnsiToUTF8 and UTF8ToAnsi need a widestring manager under Linux, BSD, and MacOSX. Normally these OS's use UTF-8 as system encoding so the WideStringManager is not needed.
</p><p>This unit contains basic functions similar to those in the RTL, but use UTF-8 instead of the defauilt system encoding. Please note that AnsiToUTF8 and UTF8ToAnsi need a widestring manager under Linux, BSD, and MacOSX. Normally these OS's use UTF-8 as system encoding so the WideStringManager is not needed.
</p>
</descr>
@ -33,8 +27,8 @@
<element name="UTF8FileHeader">
<short>Byte Order Mark (BOM) used at the beginning of UTF-8-encoded files</short>
<descr></descr>
<seealso></seealso>
<descr/>
<seealso/>
</element>
<element name="FilenamesCaseSensitive">
@ -44,7 +38,7 @@
<descr>
The value is determined by the presence of the <b>CaseInsensitiveFilenames</b> compiler define.
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="FilenamesLiteral">
@ -55,28 +49,28 @@
<descr>
The value is determined by the presence of the <b>NotLiteralFilenames</b> compiler define.
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="ComparePhysicalFilenames">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="ComparePhysicalFilenames.Filename1">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="ComparePhysicalFilenames.Filename2">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="ComparePhysicalFilenames.Result">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="CompareFilenames">
@ -109,15 +103,15 @@
</element>
<element name="ExtractShortPathNameUTF8">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="ExtractShortPathNameUTF8.FileName">
<short></short>
<short/>
</element>
<element name="ExtractShortPathNameUTF8.Result">
<short></short>
<short/>
</element>
<element name="DeleteDirectory">
@ -150,24 +144,24 @@
</element>
<element name="ProgramDirectoryWithBundle">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="ProgramDirectoryWithBundle.Result">
<short></short>
<short/>
</element>
<element name="ExpandUNCFileNameUTF8">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="ExpandUNCFileNameUTF8.FileName">
<short></short>
<short/>
</element>
<element name="ExpandUNCFileNameUTF8.Result">
<short></short>
<short/>
</element>
<element name="FileSize">
@ -290,16 +284,16 @@
<descr>
Deprecated. Use the function from the LazFileUtils unit.
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="CreateAbsolutePath.Filename">
<short></short>
<short/>
</element>
<element name="CreateAbsolutePath.BaseDirectory">
<short></short>
<short/>
</element>
<element name="CreateAbsolutePath.Result">
<short></short>
<short/>
</element>
<element name="GetAllFilesMask">
@ -375,9 +369,9 @@
</element>
<element name="sffFindProgramInPath">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="SearchFileInPath">
@ -631,12 +625,12 @@
</element>
<element name="TDirectoryEnterEvent">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="TDirectoryEnterEvent.FileIterator">
<short></short>
<short/>
</element>
<element name="TFileSearcher">
@ -665,21 +659,21 @@
</element>
<element name="TFileSearcher.FOnDirectoryEnter">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="TFileSearcher.FFileAttribute">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="TFileSearcher.FDirectoryAttribute">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="TFileSearcher.RaiseSearchingError">
@ -777,42 +771,42 @@
<short>
Character used as a delimiter between file masks in the search critera
</short>
<descr></descr>
<seealso></seealso>
<descr/>
<seealso/>
</element>
<element name="TFileSearcher.PathSeparator">
<short>
Character used as a delimiter between directory paths in the search criteria
</short>
<descr></descr>
<seealso></seealso>
<descr/>
<seealso/>
</element>
<element name="TFileSearcher.FollowSymLink">
<short>
Indicates if a search should follow paths that are symbolic links
</short>
<descr></descr>
<seealso></seealso>
<descr/>
<seealso/>
</element>
<element name="TFileSearcher.FileAttribute">
<short></short>
<short/>
<descr>
FileAttribute is a Word property. The default value for the property is
<var>faAnyfile</var>.
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="TFileSearcher.DirectoryAttribute">
<short></short>
<short/>
<descr>
DirectoryAttribute is a Word property. The default value for the property is
<var>faDirectory</var>.
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="TFileSearcher.OnDirectoryFound">
@ -829,8 +823,8 @@
<element name="TFileSearcher.OnDirectoryEnter">
<short>Event handler signalled when the searcher enters a new directory</short>
<descr></descr>
<seealso></seealso>
<descr/>
<seealso/>
</element>
<element name="TListFileSearcher">
@ -841,7 +835,7 @@
TListFileSearcher is a TFileSearcher descendant used to used store files matching a specified
search criteria in a TStrings class instance.
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="TListFileSearcher.FList">
@ -852,8 +846,8 @@
<short>
Performs actions required to add a file name to the list of matches for the file searcher
</short>
<descr></descr>
<seealso></seealso>
<descr/>
<seealso/>
</element>
<element name="TListFileSearcher.Create">
@ -863,7 +857,7 @@
<descr>
Create is the constructor for the class instance. Create calls the inherited constructor, and stores the TStrings instance in AList to the the internal member used in the class instance.
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="TListFileSearcher.Create.AList">
<short>TStrings class instance used to store matching file names</short>
@ -876,7 +870,7 @@
<descr>
TListDirectoriesSearcher is a TFileSearcher descendant used to store directory names matching the specified search criteria in a TStrings class instance.
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="TListDirectoriesSearcher.FDirectoriesList">
@ -887,8 +881,8 @@
<short>
Performs actions needed to add a directory path to the list of matches for the searcher
</short>
<descr></descr>
<seealso></seealso>
<descr/>
<seealso/>
</element>
<element name="TListDirectoriesSearcher.Create">
@ -898,39 +892,39 @@
<descr>
Create is the constructor for the class instance. Create calls the inherited constructor, and stores the value in AList to the internal member used to capture matching directory names in the class instance.
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="TListDirectoriesSearcher.Create.AList">
<short>
TStrings class instance used to store directory names matching the specified search criteria
</short>
<descr></descr>
<seealso></seealso>
<descr/>
<seealso/>
</element>
<element name="FindAllFiles">
<short>
Returns the list of files in the specified path matching the search criteria
</short>
<descr>
<p>
FindAllFiles is an overloaded method used to populate a TStringList class instance with a list of files match the specified search criteria. The procedure variant uses an existing TStringList class instance to store the matching file names. The function variant creates the TStringList
class instance used as the return value for the method.
</p>
<descr><p>FindAllFiles is an overloaded method used to populate a TStringList class instance with a list of files match the specified search criteria.
The procedure variant uses an existing TStringList class instance to store the matching file names.
The function variant creates the TStringList class instance used as the return value for the method.
</p>
</descr>
<seealso/>
<errors>The function <var>FindAllFiles</var> creates the stringlist internally. This may look very convenient at first sight, but it is very easy to create memory leaks that way.
</errors><example file="examples/fileutil.findallfiles.pas"/>
</element>
<element name="FindAllFiles.Result">
<short>List of file names matching the search criteria</short>
<descr>
The StringList is created in the FindAllFiles function; you should not instantiate it before calling the function.
</descr>
<descr>The StringList is created in the FindAllFiles function; you should not instantiate it before calling the function.
</descr>
</element>
<element name="FindAllFiles.AList">
<short>TStringList used to store file names matching the search criteria</short>
<descr>
AList must be instantiated before it is passed as an argument to the method. The TStringList instance must also be freed by the routine where it was created.
</descr>
<descr>AList must be instantiated before it is passed as an argument to the method. The TStringList instance must also be freed by the routine where it was created.
</descr>
</element>
<element name="FindAllFiles.SearchPath">
<short>Base path for searching files</short>
@ -939,12 +933,13 @@
<short>
A list of masks, separated by a semicolon (;) to which found files should match
</short>
<descr>
A list of masks, separated by a semicolon (;) to which found files should match. The mask can contain wildcards like * and ? and it also supports sets like [a-d,x]. See the Masks unit for more details.
</descr>
<descr>A list of masks, separated by a semicolon (;) to which found files should match. The mask can contain wildcards like * and ? and it also supports sets like [a-d,x]. See the Masks unit for more details.
</descr>
</element>
<element name="FindAllFiles.SearchSubDirs">
<short>If search recursively sub directories</short>
<descr>Parameter DirAttr is int file attribute: if file-system item has this attribute(s), it is considered as a directory. It can be <var>faDirectory</var>, <var>faSymLink</var>, (<var>faDirectory</var>+<var>faSymLink</var>) or maybe another bits can be used.
</descr>
</element>
<element name="FindAllFiles.PathSeparator">
<short>If search recursively sub directories</short>
@ -954,58 +949,56 @@
<short>
Stores directory names matching the search criteria in a TStringList class instance
</short>
<descr>
<p>
FindAllDirectories is an overloaded routine used to store directory path names that match the specified search criteria in a TStringList class instance. The procedure variant uses an existing TStringList class instance to store the matching directory names. The function variant allocates a TStringList class instance used to capture the matching directory names.
<descr><p>FindAllDirectories is an overloaded routine used to store directory path names that match the specified search criteria in a TStringList class instance. The procedure variant uses an existing TStringList class instance to store the matching directory names. The function variant allocates a TStringList class instance used to capture the matching directory names.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="FindAllDirectories.Result">
<short>Stores directory names matching the search criteria</short>
<descr></descr>
<seealso></seealso>
<descr/>
<seealso/>
</element>
<element name="FindAllDirectories.AList">
<short>Stores directory names matching the search criteria</short>
<descr></descr>
<seealso></seealso>
<descr/>
<seealso/>
</element>
<element name="FindAllDirectories.SearchPath">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="FindAllDirectories.SearchSubDirs">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="FindAllDirectories.PathSeparator">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="TCopyFileFlag">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="TCopyFileFlag.cffOverwriteFile">
<short></short>
<short/>
</element>
<element name="TCopyFileFlag.cffCreateDestDirectory">
<short></short>
<short/>
</element>
<element name="TCopyFileFlag.cffPreserveTime">
<short></short>
<short/>
</element>
<element name="TCopyFileFlags">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="CopyFile">
@ -1026,39 +1019,39 @@
<short>The destination filename for the Copy</short>
</element>
<element name="CopyFile.Flags">
<short></short>
<short/>
</element>
<element name="CopyFile.PreserveTime">
<short>If True, the timestamp of the original file is preserved in the copied file</short>
</element>
<element name="CopyFile.ExceptionOnError">
<short></short>
<short/>
</element>
<element name="CopyDirTree">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="CopyDirTree.Result">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="CopyDirTree.SourceDir">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="CopyDirTree.TargetDir">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="CopyDirTree.Flags">
<short></short>
<descr></descr>
<seealso></seealso>
<short/>
<descr/>
<seealso/>
</element>
<element name="PascalFileExt">
@ -1070,14 +1063,14 @@
<element name="PascalSourceExt">
<short>An array of file extensions considered to be Pascal source code</short>
<descr></descr>
<seealso></seealso>
<descr/>
<seealso/>
</element>
<element name="AllDirectoryEntriesMask">
<short>File masked used to match all directories entries</short>
<descr></descr>
<seealso></seealso>
<descr/>
<seealso/>
</element>
</module>

164
docs/xml/lazutils/lazfileutils.xml
View File

@ -81,7 +81,7 @@
<dd>Filename1 comes after Filename2</dd>
</dl>
</descr>
<errors></errors>
<errors/>
<seealso>
<link id="CompareFilenames"/>
</seealso>
@ -129,8 +129,8 @@
The return is 1 if Filename does not contain a file extension.
</p>
</descr>
<errors></errors>
<seealso></seealso>
<errors/>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -167,7 +167,7 @@
</p>
</descr>
<seealso>
<link id ="CompareFileNames"/>
<link id="CompareFileNames"/>
</seealso>
</element>
@ -302,7 +302,7 @@
<var>ExtractFileNameOnly</var> is a <var>String</var> function used to extract the base file name (without the file extension) from the value in AFilename. Path information, up to the last directory separator ('/' or '\') or device separator (':') character, in AFileName is ignored. The file extension, starting at the '.' character, is also omitted.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -337,7 +337,7 @@
The return value is False if TheFilename (without the optional device identifier) is an empty string (''), or does not start with the directory separator for the environment.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -369,7 +369,7 @@
The return value is False if TheFilename (without the optional device identifier)is an empty string (''), or does not start with the directory separator for the environment.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -395,7 +395,7 @@
In UNIX-like environments, the FilenameIsUnixAbsolute function is used in the implementation of FilenameIsAbsolute. The return value is False if TheFilename is an empty string (''), or does not start with the directory separator for the environment.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -508,7 +508,7 @@
FileIsExecutable is a Boolean function used to determine if the specified file name is executable. For UNIX-like environments, a combination of FpStat, FPS_ISREG, and FpAccess are used to get the return value. For the Windows environment, the value from FileExistsUTF8 is used as the return value. In short, the function is not really useful in a Windows environment.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -523,17 +523,11 @@
<element name="FileIsSymlink">
<short>Indicates if the specified file is a symbolic link in the file system</short>
<descr>
<p>
<var>FileIsSymlink</var> is a <var>Boolean</var> function used to determine if the specified file name is a symbolic link on the local file system.
</p>
<p>
The implementation of FileIsSymlink is platform-specific. For UNIX-like environments, the <var>FpReadLink</var> function is used to determine if the symbolic link can be resolved to a physical file name in the local file system. For the Windows platform, <var>FileGetAttrUTF8</var> is called to get and examine the file attributes for the specified file name. The file attributes must include the value <b>FILE_ATTRIBUTE_REPARSE_POINT</b>, and one of the Windows API values such as <b>IO_REPARSE_TAG_SYMLINK</b> or <b>IO_REPARSE_TAG_MOUNT_POINT</b> for the corresponding file handle. For the Amiga platform, FileIsSymLink always returns <b>False</b>.
<descr><p><var>FileIsSymlink</var> is a <var>Boolean</var> function used to determine if the specified file name is a symbolic link on the local file system.
</p><p>The implementation of FileIsSymlink is platform-specific. For UNIX-like environments, the <var>FpReadLink</var> function is used to determine if the symbolic link can be resolved to a physical file name in the local file system. For the Windows platform, <var>FileGetAttrUTF8</var> is called to get and examine the file attributes for the specified file name. The file attributes must include the value <b>FILE_ATTRIBUTE_REPARSE_POINT</b>, and one of the Windows API values such as <b>IO_REPARSE_TAG_SYMLINK</b> or <b>IO_REPARSE_TAG_MOUNT_POINT</b> for the corresponding file handle. For the Amiga platform, FileIsSymLink always returns <b>False</b>.
</p>
</descr>
<seealso>
<link id="#rtl.System.FpReadLink"/>
<link id="FileGetAttrUTF8"/>
<seealso><link id="#rtl.BaseUnix.FpReadLink"/><link id="FileGetAttrUTF8"/>
</seealso>
</element>
<element name="FileIsSymlink.Result">
@ -547,20 +541,12 @@
<short>
Indicates if the specified file has a descriptor or handle on the local file system
</short>
<descr>
<p>
<var>FileIsHardLink</var> is a <var>Boolean</var> function used to determine if the specified file name is represented by a file descriptor or handle on the local file system.
</p>
<p>
The implementation of FileIsHardLink is platform- or OS-specific. For UNIX-like environments, a file handle is retrieved by calling the <var>FileOpenUTF8</var> function and passed to the <var>FPFStat</var> function to access the file information. For the Windows platform (excluding WinCE and Windows XP), the <var>GetFileInformationByHandle</var> Windows API routine is called to get information for the file handle. For the Amiga platform, FileIsHardLink always returns <b>False</b>.
</p>
<p>
The return value is <b>False</b> if a file handle could not be accessed for the specified file name or it is actually a symbolic link on the local file system.
<descr><p><var>FileIsHardLink</var> is a <var>Boolean</var> function used to determine if the specified file name is represented by a file descriptor or handle on the local file system.
</p><p>The implementation of FileIsHardLink is platform- or OS-specific. For UNIX-like environments, a file handle is retrieved by calling the <var>FileOpenUTF8</var> function and passed to the <var>FPFStat</var> function to access the file information. For the Windows platform (excluding WinCE and Windows XP), the <var>GetFileInformationByHandle</var> Windows API routine is called to get information for the file handle. For the Amiga platform, FileIsHardLink always returns <b>False</b>.
</p><p>The return value is <b>False</b> if a file handle could not be accessed for the specified file name or it is actually a symbolic link on the local file system.
</p>
</descr>
<seealso>
<link id="FileOpenUTF8"/>
<link id="#rtl.System.fpfstat"/>
<seealso><link id="FileOpenUTF8"/><link id="#rtl.BaseUnix.fpfstat"/>
</seealso>
</element>
<element name="FileIsHardLink.Result">
@ -606,7 +592,7 @@
FileIsWritable is a Boolean function which indicates if the specified file name is writable. For UNIX-like environments, FpAccess is used to get the return value. For Windows, FileGetAttrUTF8 is used to determine if faReadOnly is omitted from the attributes for the file.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -643,7 +629,7 @@
Content in the file (up to 1024 characters) is checked to ensure that invalid Null and Control characters are not found in the file. The return value is True when the specified file name exists in the local file system, and does not contain Null or Control characters.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -663,7 +649,7 @@
<!-- function Visibility: default -->
<element name="FilenameIsTrimmed">
<short></short>
<short/>
<descr>
<p>
FilenameIsTrimmed is an overloaded Boolean function used to determine if the specified file name contains characters to remove or resolve before use. The variant which uses PChar values performs the comparison. The return value is False when the file name is a candidate for use of TrimFilename to remove whitespace or special characters.
@ -672,7 +658,7 @@
Use TrimFilename to remove leading or trailing whitespace, duplicate directory separators, or relative path symbols.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -703,7 +689,7 @@
<descr>
<var>TrimFilename</var> is a String function used to remove leading and trailing spaces (Decimal 32) in the specified path and file name. In addition, ResolveDots is called to expand directory characters (like '.' and '..') and to remove duplicate path delimiters (like '//').
</descr>
<errors></errors>
<errors/>
<seealso>
<link id="ResolveDots"/>
<link id="FileNameIsTrimmed"/>
@ -751,7 +737,7 @@
CleanAndExpandFilename is a String function used to remove whitespace and to resolve special characters in the specified file name. CleanAndExpandFilename calls TrimFilename and ExpandFileNameUTF8 to get the return value for the function. The return value is the current directory when Filename contains an empty string ('').
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -805,7 +791,7 @@
The return value is an empty string (<b>''</b>) if Filename contains an empty string (<b>''</b>).
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -873,7 +859,7 @@
CreateRelativePath is thread safe, and therefore, does not guarantee that the current directory is correct for file names like 'D:test.txt'.
</remark>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -920,7 +906,7 @@
This is a logical test; FileIsInPath does not expand or follow symbolic links.
</remark>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -951,7 +937,7 @@
Please note: PathIsInPath ensures that a trailing path delimiter is included in the Path and Directory arguments prior to performing its comparison. On Windows, this results in a Path like 'C:' being treated as if it contains 'C:\'.
</remark>
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="PathIsInPath.Result">
<short>True when Directory exists in Path</short>
@ -978,7 +964,7 @@
The return value is the same as the <var>aFileName</var> argument if the file name did not need to be shortened.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="ShortDisplayFilename.Result">
<short>Shortened version of the specifed file name</short>
@ -991,11 +977,11 @@
</element>
<element name="TPathDelimSwitch">
<short></short>
<short/>
<descr>
<var>TPathDelimSwitch</var> is an enumerated type with values that indicate how path delimiters in file names are handled in routines like SwitchPathDelims, CheckPathDelim, and IsCurrentPathDelim. Values in the enumeration represent the various platform- or OS-specific path delimiters available in the Lazarus LCL at run-time.
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="TPathDelimSwitch.pdsNone">
<short>No path delimiter changes were used</short>
@ -1036,7 +1022,7 @@
For Windows, this means any UNIX path delimiters (<b>/</b>) in FileName are converted into the Windows path delimiter (<b>\</b>). Conversely, for all other platforms and environments, the Windows path delimiter (<b>\</b>) is converted to the UNIX notation (<b>/</b>). All path delimiter substitutions in FileName occur inline.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="ForcePathDelims.FileName">
<short>File name examined in the routine</short>
@ -1070,7 +1056,7 @@
<var>AppendPathDelim</var> is a <var>String</var> function used to ensure that a trailing path delimiter is included in the specified Path. The return value includes the value in Path and the trailing path delimiter (when needed).
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -1093,7 +1079,7 @@
<var>ChompPathDelim</var> is a <var>String</var> function used to remove a trailing path delimiter from the specified value in Path. For environments where UNC paths are allowed, ChompPathDelim ensures that the UNC path delimiters are retained. Windows Device identifiers, such as "D:" are also retained in Path.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -1186,7 +1172,7 @@
<short>Value to compare to the current path delimiter for the system</short>
</element>
<element name="CheckPathDelim.Changed">
<short></short>
<short/>
</element>
<element name="IsCurrentPathDelim">
@ -1219,7 +1205,7 @@
</dd>
</dl>
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="IsCurrentPathDelim.Result">
<short>Boolean result of the path delimiter comparison</short>
@ -1343,7 +1329,7 @@
Compiler defines determine the mechanism used to perform a comparison of the values in APath and SearchPath; i.e. <var>CaseInsensitiveFilenames</var> and <var>NotLiteralFilenames</var>. <var>CompareFilenames</var> is called to perform the comparison when inline comparison of string values in not supported.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="FindPathInSearchPath.Result">
<short>Position or value for the located search path</short>
@ -1371,7 +1357,7 @@
<var>FileExistsUTF8</var> is a <var>Boolean</var> function which indicates if the specified file name exists in the local file system. For the Windows environment, FileExistsUTF8 uses FileGetAttrUTF8 to ensure that Filename does not have the <b>FILE_ATTRIBUTE_DIRECTORY</b> attribute. For UNIX-like environments, the FileExists function in <file>SysUtils</file> is used to get the return value.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -1400,7 +1386,7 @@
The return value is in FileDate format, and can be transformed to a TDateTime value with the FileDateToDateTime function.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -1423,7 +1409,7 @@
<var>DirectoryExistsUTF8</var> is <var>Boolean</var> function used to determine if the specified path exists on the local file system. For the Windows environment, FileGetAttrUTF8 is called to see if <b>FILE_ATTRIBUTE_DIRECTORY</b> is included in the file attributes for the specified Directory. For UNIX-like environments, the DirectoryExists function in the <file>SysUtils</file> unit is used to get the return value.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -1449,7 +1435,7 @@
If an empty string ('') is passed in Filename, it is expanded to the current directory using GetCurrentDirUTF8. When FileName contains the tilde character (<b>~</b>), it is converted to the path to the home directory for the user using the <var>HOME</var> environment variable. Relative paths in FileName are resolved by calling ResolveDots.
</p>
</descr>
<errors></errors>
<errors/>
<seealso>
<link id="GetCurrentDirUTF8"/>
<link id="ResolveDots"/>
@ -1487,7 +1473,7 @@
The return value contains the result from GetLastError; a non-zero value indicates that no files matching the criteria were found.
</p>
</descr>
<errors></errors>
<errors/>
<seealso>
<link id="#rtl.SysUtils.FIndFirst"/>
</seealso>
@ -1529,7 +1515,7 @@
The return value contains the result from GetLastError; a non-zero value indicates that an error was encountered.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -1552,7 +1538,7 @@
<var>FindCloseUTF8</var> is a procedure used to free resources allocated to the search record in F by the <var>FindFirstUTF8</var> routine. FindCloseUTF8 calls the FindClose function in the <file>SysUtils</file> unit.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- argument Visibility: default -->
@ -1576,7 +1562,7 @@
The return value is the value from GetLastError; a non-zero value indicates that an error has occurred.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -1633,7 +1619,7 @@
</dd>
</dl>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -1688,7 +1674,7 @@
The return value contains the result from GetLastError; a non-zero value indicates that an error has occurred.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -1722,7 +1708,7 @@
The return value contains True when Filename is successfully deleted from the local file system.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -1751,8 +1737,8 @@
The return value is True if the file is renamed successfully.
</p>
</descr>
<errors></errors>
<seealso></seealso>
<errors/>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -1789,7 +1775,7 @@
When ImplicitCurrentDir is <b>False</b>, each path in DirList is searched for a file with the specified name. The search is stopped when the first file with the specified file name is found. The return value contains the path in DirList where the file name was located along with the file name, or an empty string ('') if the specified file is not found in the search.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -1817,7 +1803,7 @@
<var>FileIsReadOnlyUTF8</var> is a <var>Boolean</var> function used to determine if the specified file is marked as read-only in the local file system. FileIsReadOnlyUTF8 calls FileGetAttrUTF8 for the specified file name and checks to see if faReadOnly has been included in the file attributes value. The return value is True when faReadOnly has been included in the file attributes.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -1883,7 +1869,7 @@
</dd>
</dl>
</errors>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -1914,7 +1900,7 @@
An error can occur if a directory with the specified name already exists in the local file system.
</p>
</errors>
<seealso></seealso>
<seealso/>
</element>
<!-- function result Visibility: default -->
@ -2148,7 +2134,7 @@ Modified: MM/DD/YYYY hh:mm
The return value can be 'Modified: ?' if an exception is encountered when getting the date/time value for the file.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="GetFileDescription.Result">
<short>String with the file information for the platform or OS</short>
@ -2185,7 +2171,7 @@ Modified: MM/DD/YYYY hh:mm
File attributes not found in Attrib are represented as '-' characters.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="DbgSFileAttr.Result">
<short>String with information about the file attributes</short>
@ -2325,7 +2311,7 @@ Modified: MM/DD/YYYY hh:mm
</element>
<element name="GetAppConfigDirUTF8">
<short></short>
<short/>
<descr>
<p>
<var>GetAppConfigDirUTF8</var> is a <var>String</var> function used to get the directory on the local file system where application configuration and data files are stored.
@ -2449,7 +2435,7 @@ Modified: MM/DD/YYYY hh:mm
GetTempFileNameUTF8 examines the files in the specified directory to determine if a file already exists which starts with the value in Prefix. If a file is located in the directory, a numeric suffix (starting at 0) is appended to the base file name in Prefix to build a temporary file name which does not already exist in the directory.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="GetTempFileNameUTF8.Result">
<short>Temporary file name generated in the routine</short>
@ -2482,7 +2468,7 @@ Modified: MM/DD/YYYY hh:mm
Use ExtractUNCVolume to get host and path information from a file name expressed using UNC notation.
</p>
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="IsUNCPath.Result">
<short>True when the path contains UNC notation</short>
@ -2550,7 +2536,7 @@ Modified: MM/DD/YYYY hh:mm
C:\
</code>
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="ExtractFileRoot.Result">
<short>Root directory on the file system for the specified file name </short>
@ -2560,34 +2546,34 @@ C:\
</element>
<element name="GetDarwinSystemFilename">
<short></short>
<short/>
<descr>
Implemented when the platform or OS includes the <b>darwin</b> compiler define. Used in the implementation of TryCreateRelativePath for the Darwin platform.
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="GetDarwinSystemFilename.Result">
<short></short>
<short/>
</element>
<element name="GetDarwinSystemFilename.Filename">
<short></short>
<short/>
</element>
<element name="GetDarwinNormalizedFilename">
<short></short>
<short/>
<descr>
Implemented when the platform or OS includes the <b>darwin</b> compiler define. Handles canonical string normalization forms for file names on the Darwin platform.
</descr>
<seealso></seealso>
<seealso/>
</element>
<element name="GetDarwinNormalizedFilename.Result">
<short></short>
<short/>
</element>
<element name="GetDarwinNormalizedFilename.Filename">
<short></short>
<short/>
</element>
<element name="GetDarwinNormalizedFilename.nForm">
<short></short>
<short/>
</element>
<element name="SHGetFolderPathUTF8">
@ -2626,8 +2612,8 @@ C:\
<short>
Ensures that whitespace and quoting use the format required for command line parameters
</short>
<descr></descr>
<seealso></seealso>
<descr/>
<seealso/>
</element>
<element name="StrToCmdLineParam.Result">
<short>
@ -2640,8 +2626,8 @@ C:\
<element name="MergeCmdLineParams">
<short>Generates a string with the specified list of parameters</short>
<descr></descr>
<seealso></seealso>
<descr/>
<seealso/>
</element>
<element name="MergeCmdLineParams.Result">
<short>String representation for the list of parameters</short>
@ -2652,8 +2638,8 @@ C:\
<element name="SplitCmdLine">
<short>Splits the specified command line into program and parameter values</short>
<descr></descr>
<seealso></seealso>
<descr/>
<seealso/>
</element>
<element name="SplitCmdLine.CmdLine">
<short>Command line examined in the function</short>
@ -2667,8 +2653,8 @@ C:\
<element name="PrepareCmdLineOption">
<short>Ensures command line options are formatted properly</short>
<descr></descr>
<seealso></seealso>
<descr/>
<seealso/>
</element>
<element name="PrepareCmdLineOption.Result">
<short>Command line option after quoting has been applied</short>

34
docs/xml/lcl/examples/readme.txt Normal file
View File

@ -0,0 +1,34 @@
This directory is intended for storing examples of Pascal code included in the documentation.
You can include example code in the documentation as follows:
1. Place an example of the code inside this directory as a unit with name UnitName.FunctionName.pas or similar.
Place the link in this example for the documentation <element> tag as follows:
<element name="MyDangerousFunction">
<example file="examples/UnitName.MyDangerousFunction.pas"/>
</element>
The file attribute of the <example> tag is used to specify the filename containing the example. The filename does not require an extension: if it is missing, .pp is assumed.
If you use the fpdoc editor then use the example tab for that.
https://www.freepascal.org/docs-html/current/fpdoc/fpdocsu70.html
2. Place the example code into the <descr><descr/> section inside <code></code> tags.
Note that any text surrounding the code tags should be placed inside <p></p> tags.
For example:
<element name="MyDangerousFunction">
<descr>
<p>
// Any description.
</p>
<code>
// Place example code here.
</code>
</p>
</descr>
</element>
https://www.freepascal.org/docs-html/current/fpdoc/fpdocsu63.html