From 6c528d9822e687001bf9d07aa4241c274eb72db7 Mon Sep 17 00:00:00 2001
From: dsiders <dsiders@lazarus-ide.org>
Date: Sun, 2 Feb 2025 18:42:55 -0500
Subject: [PATCH] Docs: LCL/shellctrls. Clarifies content in the
 TCustomShellTreeView.FileSortType topic.

---
 docs/xml/lcl/shellctrls.xml | 27 +++++++++++++++++----------
 1 file changed, 17 insertions(+), 10 deletions(-)

diff --git a/docs/xml/lcl/shellctrls.xml b/docs/xml/lcl/shellctrls.xml
index 6d9b3e2ca6..2fb8ef2a6e 100644
--- a/docs/xml/lcl/shellctrls.xml
+++ b/docs/xml/lcl/shellctrls.xml
@@ -1725,14 +1725,15 @@ enumeration values and their meanings.
 </p>
 <p>
 Changing the value in <var>FileSortType</var> causes the <var>Items</var> 
-property to be cleared, and tree nodes to be reloaded. If Root has not been 
-assigned, PopulateWithBaseFiles is used to fill the Items property. 
-If Root has a non-empty value, an internal routine is called to recreate the 
-root node using the required path. The value in Root is expanded and used to 
-create the remaining nodes for the tree. This includes filling 
-TShellTreeNode-specific information for the TTreeNode instances in Items. If 
-the path to the Selected tree node is still valid for the file system, it is 
-restored to the Path property.
+property to be cleared, and tree nodes to be reloaded using the sort order  
+needed for the property value. If Root has not been assigned, 
+PopulateWithBaseFiles is used to fill the Items property. If Root has a 
+non-empty value, an internal routine is called to recreate the root node using 
+the required path. The value in Root is expanded and used to create the 
+remaining nodes for the tree. This includes filling TShellTreeNode-specific 
+information for the TTreeNode instances in Items. If the path to the Selected 
+tree node is still valid for the file system, it is restored to the Path 
+property.
 </p>
 <p>
 No action other than setting the property value is performed in the method at 
@@ -1743,6 +1744,10 @@ The value in FileSortType is used in the PopulateTreeNodeWithFiles method and
 passed as an argument to an internal method used to load the files in a given 
 path name.
 </p>
+<p>
+Use the OnSortCompare event handler to implement the sort / compare routine 
+needed when FileSortType is set to fstCustom.
+</p>
 <remark>
 The value in FileSortType is not used in <var>PopulateWithBaseFiles</var> on 
 Windows platforms. The entries are logical drive letters processed in the 
@@ -1750,14 +1755,15 @@ order provided by the file system.
 </remark>
 </descr>
 <seealso>
-<link id="TFileSortType"/>
-<link id="EInvalidPath"/>
 <link id="TCustomShellTreeView.Items"/>
 <link id="TCustomShellTreeView.Root"/>
 <link id="TCustomShellTreeView.Path"/>
 <link id="TCustomShellTreeView.ExistsAndIsValid"/>
+<link id="TCustomShellTreeView.OnSortCompare"/>
 <link id="TCustomShellTreeView.PopulateWithBaseFiles"/>
 <link id="TCustomShellTreeView.PopulateTreeNodeWithFiles"/>
+<link id="TFileSortType"/>
+<link id="EInvalidPath"/>
 </seealso>
 </element>
 
@@ -1997,6 +2003,7 @@ Added in LCL version 3.0.
 <link id="TCustomShellTreeView.ExistsAndIsValid"/>
 <link id="TCustomShellTreeView.PopulateTreeNodeWithFiles"/>
 <link id="TCustomShellTreeView.PopulateWithBaseFiles"/>
+<link id="TFileSortType"/>
 </seealso>
 </element>