<?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="lcl">
<!--
====================================================================
ShellCtrls
====================================================================
-->
<module name="ShellCtrls">
<short>Contains controls which display files and directories.</short>
<descr>
<p>
<file>shellctrls.pas</file> contains tree view and list view controls used to 
access files and directories on the local file system. The following 
components are added to the Lazarus IDE component palette:
</p>
<p>
<b>Misc</b> Tab
</p>
<ul>
<li>TShellTreeView</li>
<li>TShellListView</li>
</ul>
<p>
<file>ShellCtrls.pas</file> is part of the Lazarus Component Library (LCL).
</p>
</descr>

<!-- unresolved references -->
<element name="Classes"/>
<element name="SysUtils"/>
<element name="Math"/>
<element name="Laz_AVL_Tree"/>
<element name="Forms"/>
<element name="Graphics"/>
<element name="ComCtrls"/>
<element name="LCLProc"/>
<element name="LCLType"/>
<element name="LCLStrConsts"/>
<element name="Types"/>
<element name="FileUtil"/>
<element name="LazFileUtils"/>
<element name="LazUTF8"/>
<element name="Masks"/>

<element name="TObjectType">
<short>Indicates which objects should be visible in a Shell control.</short>
<descr>
<p>
<var>TObjectType</var> is an enumerated type with values that indicate which 
file system objects are visible in a Shell control. Values from the 
enumeration are stored in the <var>TObjectTypes</var> set type.
</p>
</descr>
<seealso>
<link id="TObjectTypes"/>
<link id="TCustomShellTreeView.ObjectTypes"/>
<link id="TCustomShellListView.ObjectTypes"/>
</seealso>
</element>
<element name="TObjectType.otFolders">
<short>
Indicates that folders (directories) should be visible. This includes folders 
which represent virtual objects such as disk devices. Hidden folders are 
shown only if otHidden is also present.
</short>
</element>
<element name="TObjectType.otNonFolders">
<short>
Indicates that non-folder objects should be shown, which are usually files. 
Hidden files will be shown if otHidden is also present.
</short>
</element>
<element name="TObjectType.otHidden">
<short>
Indicates that hidden objects should be shown. This value is meaningful when 
used along with one of the other values.
</short>
</element>

<element name="TObjectTypes">
<short>
Set type with values that indicate the visible objects in a Shell control.
</short>
<descr></descr>
<seealso>
<link id="TObjectType"/>
<link id="TCustomShellTreeView.ObjectTypes"/>
<link id="TCustomShellListView.ObjectTypes"/>
</seealso>
</element>

<element name="TFileSortType">
<short>Represents sorting options for the items in a shell control.</short>
<descr>
<p>
<var>TFileSortType</var> is an enumerated type with values that control the 
sort order for the items in a shell control. TFileSortType is the type used 
to implement the <var>TCustomShellTreeView.FileSortType</var> property.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.FileSortType"/>
<link id="TCustomShellTreeView.OnSortCompare"/>
<link id="TFileItemCompareEvent"/>
</seealso>
</element>
<element name="TFileSortType.fstNone">
<short>
No special sorting is done; items will appear in the order provided by the 
file system.
</short>
</element>
<element name="TFileSortType.fstAlphabet">
<short>Items are sorted alphabetically with folders and files mixed.</short>
</element>
<element name="TFileSortType.fstFoldersFirst">
<short>
Items are sorted alphabetically with folders placed at the beginning of the 
list.
</short>
</element>
<element name="TFileSortType.fstCustom">
<short>
Items are sorted using a user-defined compare function for files and 
directories. The sort routine should return a negative value if the first item 
comes before the second item, a positive value when the first item comes after 
the second item, or 0 (zero) when both items have the same value.
</short>
</element>

<element name="TMaskCaseSensitivity">
<short>Represents case sensitivity options for file masks.</short>
<descr>
<p>
<var>TMaskCaseSensitivity</var> is an enumeration type with values that 
represent case sensitivity options for the platform or OS where shell 
controls are implemented. TMaskCaseSensitivity is the type used for the 
<var>MaskCaseSensitivity</var> property in <var>TCustomShellListView</var>. 
It is also passed as an argument to methods in 
<var>TCustomShellTreeView</var>.
</p>
</descr>
<seealso>
<link id="TCustomShellListView.MaskCaseSensitivity"/>
</seealso>
</element>
<element name="TMaskCaseSensitivity.mcsPlatformDefault">
<short>File masks used the default for the platform or OS.</short>
</element>
<element name="TMaskCaseSensitivity.mcsCaseInsensitive">
<short>File masks are case insensitive.</short>
</element>
<element name="TMaskCaseSensitivity.mcsCaseSensitive">
<short>File masks are case sensitive.</short>
</element>

<element name="TExpandCollapseMode">
<short>
Indicates actions performed for child nodes when a shell tree node is expanded or collapsed.
</short>
<descr>
<p>
<var>TExpandCollapseMode</var> is an enumerated type with values that indicate 
the actions performed for child nodes when a shell tree node is expanded or 
collapsed. TExpandCollapseMode is the type used to implement the 
ExpandCollapseMode property in TCustomShellTreeView.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.ExpandCollapseMode"/>
<link id="TCustomShellTreeView.CanExpand"/>
<link id="TCustomShellTreeView.Collapse"/>
</seealso>
<version>
Added in LCL version 3.0.
</version>
</element>
<element name="TExpandCollapseMode.ecmRefreshedExpanding">
<short>
Clear existing children before expanding.
</short>
</element>
<element name="TExpandCollapseMode.ecmKeepChildren">
<short>
Do not clear children of previously expanded tree nodes when they are 
collapsed.
</short>
</element>
<element name="TExpandCollapseMode.ecmCollapseAndClear">
<short>
Clear children when a node is collapsed.
</short>
</element>

<element name="TFileItem">
<short>
Provides information about a file or directory on the local file system for 
use in file sort comparison routines.
</short>
<descr>
<p>
<var>TFileItem</var> is a utility class used to represent a file or directory. 
It contains BasePath with the path to the directory where the item is located 
on the local file system, and FileInfo with the TSearchRec values for the item.
</p>
<p>
TFileItem is the type used to represent the items passed as arguments to a 
TFileItemCompareEvent handler routine. TFileItem instances are created and 
used in the implementation of file listing and sort routines as well.
</p>
</descr>
<version>
Modified in LCL version 3.0. It was moved from the implementation section to 
the interface section, and used to implement TFileItemCompareEvent routines.
</version>
<seealso>
<link id="TCustomShellTreeView.PopulateTreeNodeWithFiles"/>
<link id="TCustomShellTreeView.OnAddItem"/>
<link id="TCustomShellTreeView.OnSortCompare"/>
<link id="TCustomShellTreeView.FileSortType"/>
<link id="TFileItemCompareEvent"/>
</seealso>
</element>

<!-- private -->
<element name="TFileItem.FFileInfo"/>
<element name="TFileItem.FBasePath"/>

<!-- public -->
<element name="TFileItem.isFolder">
<short>
<b>True</b> when the item represents a folder on the local file system.
</short>
<descr>
<p>
<var>isFolder</var> is a <var>Boolean</var> member which indicates if the item 
represents a folder or directory on the local file system. Its value is 
assigned in the Create constructor, and is set to True if the TSearchRec 
instance in the DirInfo argument includes faDirectory in its Attr member.
</p>
</descr>
<seealso>
<link id="TFileItem.Create"/>
<link id="TFileItem.FileInfo"/>
<link id="TFileItem.BasePath"/>
<link id="#rtl.sysutils.TSearchRec">TSearchRec</link>
</seealso>
</element>
<element name="TFileItem.isFolder.Result">
<short>
<b>True</b> when the file item represents a folder on the local file system.
</short>
</element>

<element name="TFileItem.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<p>
<var>Create</var> stores values in the DirInfo and ABasePath arguments to the 
FileInfo and BasePath properties in the class instance. isFolder is updated to 
indicate whether the file item is a directory on the local file system.
</p>
</descr>
<seealso>
<link id="TFileItem.isFolder"/>
<link id="TFileItem.BasePath"/>
<link id="TFileItem.FileInfo"/>
</seealso>
</element>
<element name="TFileItem.Create.DirInfo">
<short>
TSearchRec instance with the directory information for the file item.
</short>
</element>
<element name="TFileItem.Create.ABasePath">
<short>
Contains the path on the local file system where the file item is stored.
</short>
</element>

<element name="TFileItem.BasePath">
<short>
Path to the directory where the file item is stored on the local file system.
</short>
<descr>
<p>
<var>BasePath</var> is assigned in the Create constructor using the value 
passed in the ABasePath argument.
</p>
</descr>
<seealso>
<link id="TFileItem.Create"/>
<link id="TFileItem.FileInfo"/>
<link id="TFileItem.isFolder"/>
</seealso>
</element>

<element name="TFileItem.FileInfo">
<short>
TSearchRec instance with information about the file or directory in the item.
</short>
<descr>
<p>
<var>FileInfo</var> is assigned in the Create constructor using the value 
passed in the DirInfo argument.
</p>
</descr>
<seealso>
<link id="TFileItem.Create"/>
<link id="TFileItem.BasePath"/>
<link id="TFileItem.isFolder"/>
</seealso></element>

<element name="TFileItemCompareEvent">
<short>
Implements a handler routine used to compare values in a custom file sort 
for TCustomShellTreeView.
</short>
<descr>
<p>
<var>TFileItemCompareEvent</var> is the type used to implement the 
OnSortCompare event handler in TCustomShellTreeView. TFileItemCompareEvent 
compares the file items specified in the Item1 and Item2 arguments to 
determine which value occurs first in the sort order.
</p>
<p>
The return value is an <var>Integer</var> with the relative sort order for the 
compared values:
</p>
<dl>
<dt>A negative value (&lt;0)</dt>
<dd>Indicates that Item1 occurs before Item2 in the sort order.</dd>
<dt>A positive value (&gt;0)</dt>
<dd>Indicates that Item1 occurs after Item2 in the sort order.</dd>
<dt>0 (zero)</dt>
<dd>Indicates that Item1 and Item2 have the same value in the sort order.</dd>
</dl>
<p>
An application can implement and assign a routine using the signature to the 
OnSortCompare event handler in TCustomShellTreeView. Set its FileSortType 
property to fstCustom to enable the handler routine.
</p>
<p>
The following is an item compare function, as implemented by forum member 
d7_2_laz, used to order items with leading Underscore characters:
</p>
<code>
function TForm1.SortCompareUnderscore(Item1, Item2: TFileItem): integer;
begin
  // Make sure that folders are moved to the top
  Result := ord(Item2.isFolder) - ord(Item1.isFolder);
  if Result = 0 then
    if (pos('_', Item1.FileInfo.Name) = 1) or 
      (pos('_', Item2.FileInfo.Name) = 1) then
      Result := AnsiCompareText(Item1.FileInfo.Name, Item2.FileInfo.Name)
    else
      Result := CompareText(Item1.FileInfo.Name, Item2.FileInfo.Name);
end;
</code>
<p>
<b>Sort File Items by Date</b>
</p>
<code>
function TForm1.SortCompareByDate(Item1, Item2: TFileItem): integer;
begin
  // Folders first ...
  Result := ord(Item2.isFolder) - ord(Item1.isFolder);
  if Result = 0 then
  begin
    // then file date ...
    Result := CompareValue(Item1.FileInfo.TimeStamp, Item2.FileInfo.TimeStamp);
    if Result = 0 then
      // then file name
      Result := CompareText(Item1.FileInfo.Name, Item2.FileInfo.Name);
  end;
end;
</code>
<p>
<b>Sort File Items by Size</b>
</p>
<code>
function TForm1.SortCompareBySize(Item1, Item2: TFileItem): integer;
begin
  // Folders first
  Result := ord(Item2.isFolder) - ord(Item1.isFolder);
  if Result = 0 then
  begin
    // then file size ...
    Result := Item1.FileInfo.Size - Item2.FileInfo.Size;
    if Result = 0 then
      // then file name
      Result := CompareText(Item1.FileInfo.Name, Item2.FileInfo.Name);
  end;
end;
</code>
</descr>
<seealso>
<link id="TCustomShellTreeView.OnSortCompare"/>
<link id="TCustomShellTreeView.FileSortType"/>
<link id="TFileItem"/>
</seealso>
</element>
<element name="TFileItemCompareEvent.Item1">
<short>
First file item for the comparison routine.
</short>
</element>
<element name="TFileItemCompareEvent.Item2">
<short>
Second file item for the comparison routine.
</short></element>
<element name="TFileItemCompareEvent.Result">
<short>
Integer with the relative sort order for the compared file items.
</short>
</element>

<element name="TAddItemEvent">
<short>
Specifies an event handler signalled when an item is added to a shell control.
</short>
<descr>
<p>
<var>TAddItemEvent</var> specifies an event handler signalled when an item is 
added to a shell control. TAddItemEvent is the type used to implement the 
<var>OnAddItem</var> event handler in <var>TCustomShellListView</var> and 
<var>TCustomShellTreeView</var>.
</p>
<p>
Applications must implement and assign an object procedure using the 
signature for the event to respond to the notification. The <var>Sender</var> 
argument must be cast to the correct class type to access properties and 
method in the control. Set the value in the <var>CanAdd</var> variable 
parameter to <b>False</b> to prevent the item from being added in the calling 
procedure.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.PopulateTreeNodeWithFiles"/>
<link id="TCustomShellTreeView.OnAddItem"/>
</seealso>
</element>
<element name="TAddItemEvent.Sender">
<short>Object (control) generating the event notification.</short>
</element>
<element name="TAddItemEvent.ABasePath">
<short>Base path for the item added to the shell control.</short>
</element>
<element name="TAddItemEvent.AFileInfo">
<short>
Search record with information for the item added to the shell control.
</short>
</element>
<element name="TAddItemEvent.CanAdd">
<short><b>True</b> if the item can be added.</short>
</element>

<element name="TCustomShellTreeView">
<short>
The base class for a tree view control used to display files, directories and 
other objects (such as devices) from the local file system.
</short>
<descr>
<p>
<var>TCustomShellTreeView</var> is a <var>TCustomTreeView</var> descendant 
that defines the base class used to display files, directories, and other 
objects (such as devices) from the local file system. TCustomShellTreeView 
provides a hierarchical tree view for the file system objects, and is used to 
navigate between items in the control.
</p>
<p>
TCustomShellTreeView extends the ancestor class with properties, methods, and 
events needed to access, maintain, and navigate file system objects in the 
control. Applications should not create instances of TCustomShellTreeView; 
use the <var>TShellTreeView</var> class instead.
</p>
<remark>
Event handlers inherited from TCustomTreeView may include arguments which use 
TCustomTreeView or TTreeNode types. When they are implemented in 
TCustomShellTreeView, it is often necessary to cast these arguments to the 
TShellTreeNode or TCustomShellTreeView types to access properties and/or 
methods implemented in the descendent classes.
</remark>
</descr>
<seealso>
<link id="TShellTreeView"/>
<link id="#lcl.comctrls.TCustomTreeView">TCustomTreeView</link>
</seealso>
</element>

<element name="TCustomShellTreeView.FObjectTypes"/>
<element name="TCustomShellTreeView.FPopulateDelayed"/>
<element name="TCustomShellTreeView.FRoot"/>
<element name="TCustomShellTreeView.FShellListView"/>
<element name="TCustomShellTreeView.FExpandCollapseMode"/>
<element name="TCustomShellTreeView.FFileSortType"/>
<element name="TCustomShellTreeView.FInitialRoot"/>
<element name="TCustomShellTreeView.FUpdateLock"/>
<element name="TCustomShellTreeView.FUseBuiltinIcons"/>
<element name="TCustomShellTreeView.FOnAddItem"/>

<element name="TCustomShellTreeView.FOnSortCompare">
<short>
Member with the event handler for the OnSortCompare property.
</short>
</element>

<element name="TCustomShellTreeView.CreateRootNode">
<short>
(Re-)creates the root node for the tree view using the specified path.
</short>
</element>
<element name="TCustomShellTreeView.CreateRootNode.APath">
<short>
Path to the root node for the tree view.
</short>
</element>
<element name="TCustomShellTreeView.CreateRootNode.Result">
<short>
TTreeNode instance for the new root node, with updated TShellTreeNode 
properties as well.
</short>
</element>

<element name="TCustomShellTreeView.GetPath">
<short>Gets the value for the Path property.</short>
<descr></descr>
<seealso>
<link id="TCustomShellTreeView.Path"/>
</seealso>
</element>
<element name="TCustomShellTreeView.GetPath.Result">
<short>Value for the property.</short>
</element>

<element name="TCustomShellTreeView.SetFileSortType">
<short>Sets the value for the FileSortType property.</short>
<descr></descr>
<seealso>
<link id="TShellTreeView.FileSortType"/>
</seealso>
</element>
<element name="TCustomShellTreeView.SetFileSortType.AValue">
<short>New value for the property.</short>
</element>

<element name="TCustomShellTreeView.SetObjectTypes">
<short>Sets the value for the ObjectTypes property.</short>
<descr></descr>
<seealso>
<link id="TCustomShellTreeView.ObjectTypes"/>
</seealso>
</element>
<element name="TCustomShellTreeView.SetObjectTypes.AValue">
<short>New value for the property.</short>
</element>

<element name="TCustomShellTreeView.SetOnSortCompare">
<short>
Sets the value for the OnSortCompare property.
</short>
<descr/>
<version>
Added in LCL version 3.0.
</version>
<seealso>
<link id="TCustomShellTreeView.OnSortCompare"/>
<link id="TFileItemCompareEvent"/>
</seealso>
</element>
<element name="TCustomShellTreeView.SetOnSortCompare.AValue">
<short>
New value for the OnSortCompare property.
</short>
</element>

<element name="TCustomShellTreeView.SetPath">
<short>Sets the value for the Path property.</short>
<descr></descr>
<seealso>
<link id="TCustomShellTreeView.Path"/>
</seealso>
</element>
<element name="TCustomShellTreeView.SetPath.AValue">
<short>New value for the property.</short>
</element>

<element name="TCustomShellTreeView.SetRoot">
<short>Sets the value for the Root property.</short>
<descr></descr>
<seealso>
<link id="TCustomShellTreeView.Root"/>
</seealso>
</element>
<element name="TCustomShellTreeView.SetRoot.AValue">
<short>New value for the property.</short>
</element>

<element name="TCustomShellTreeView.SetShellListView">
<short>Sets the value for the ShellListView property.</short>
<descr></descr>
<seealso>
<link id="TCustomShellTreeView.ShellListView"/>
<link id="TCustomShellListView"/>
</seealso>
</element>
<element name="TCustomShellTreeView.SetShellListView.Value">
<short>New value for the property.</short>
</element>

<element name="TCustomShellTreeView.SetUseBuiltinIcons">
<short>Sets the value for the UseBuiltinIcons property.</short>
<descr/>
<seealso>
<link id="TCustomShellTreeView.UseBuiltinIcons"/>
</seealso>
</element>
<element name="TCustomShellTreeView.SetUseBuiltinIcons.AValue">
<short>New value for the property.</short>
</element>

<element name="TCustomShellTreeView.DoCreateNodeClass">
<short>
Performs actions needed to create a new tree node in the shell control.
</short>
<descr>
<p>
<var>DoCreateNodeClass</var> is an overridden method used to perform actions 
needed to create a new tree node in the Items for the shell control. 
DoCreateNodeClass sets <var>NewNodeClass</var> to the 
<var>TShellTreeNode</var> class type used in <var>TCustomShellTreeView</var>. 
DoCreateNodeClass calls the inherited method using NewNodeClass as an 
argument.
</p>
</descr>
<seealso>
<link id="TShellTreeNode"/>
</seealso>
</element>
<element name="TCustomShellTreeView.DoCreateNodeClass.NewNodeClass">
<short>Class reference used to create tree nodes in the shell control.</short>
</element>

<element name="TCustomShellTreeView.Loaded">
<short>
Performs actions needed when LCL component streaming has been completed.
</short>
<descr>
<p>
<var>Loaded</var> is an overridden procedure used to perform actions needed 
when LCL component streaming has been completed. In 
<var>TCustomShellTreeView</var>, this includes calling the inherited method 
and setting the initial value for the root directory. If the initial root 
directory was assigned at design-time, <var>PopulateWithBaseFiles</var> is 
called to load files in the shell control.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.Root"/>
<link id="TCustomShellTreeView.PopulateWithBaseFiles"/>
</seealso>
</element>

<element name="TCustomShellTreeView.CreateNode">
<short>Creates a new tree node for the shell control.</short>
<descr>
<p>
<var>CreateNode</var> is an overridden method used to create an new 
<var>TTreeNode</var> instance for the shell control. CreateNode calls the 
inherited method to create the class instance used as the return value for 
the method.
</p>
<p>
CreateNode ensures that the tree node is a <var>TShellTreeNode</var> class 
instance; the class type can be overridden in the 
<var>OnCreateNodeClass</var> event handler. If the new tree node is not 
derived from <var>TShellTreeNode</var>, an <var>EShellCtrl</var> exception is 
raised to indicate the invalid node type.
</p>
</descr>
<errors>
Raises an <var>EShellCtrl</var> exception if the new tree node is not derived 
from <var>TShellTreeNode</var>.
</errors>
<seealso>
<link id="TShellTreeNode"/>
<link id="EShellCtrl"/>
<link id="#lcl.comctrls.TTreeNodeClass">TTreeNodeClass</link>
<link id="#lcl.comctrls.TCustomTreeView.OnCreateNodeClass">TCustomTreeView.OnCreateNodeClass</link>
</seealso>
</element>
<element name="TCustomShellTreeView.CreateNode.Result">
<short>New tree node created in the method.</short>
</element>

<element name="TCustomShellTreeView.PopulateTreeNodeWithFiles">
<short>
Adds tree nodes for file system objects found starting at the specified node 
/ path.
</short>
<descr>
<p>
<var>PopulateTreeNodeWithFiles</var> is a <var>Boolean</var> function used to 
fill the <var>Items</var> property with the file system objects for a given 
tree node. <var>ANode</var> contains the initial tree node examined in the 
method. <var>ANodePath</var> contains the path on the local file system to 
the tree node in <var>ANode</var>. The return value is <b>True</b> if at 
least one node was added to Items in the method.
</p>
<p>
No actions are performed in the method at design-time, and the return value 
is set to <b>False</b>.
</p>
<p>
<var>PopulateTreeNodeWithFiles</var> fills a list with <var>TFileItem</var> 
instances for file system objects matching the <var>ObjectTypes</var> for the 
shell control. <var>DoAddItem</var> is called for each <var>TFileItem</var> 
instance, which signals the <var>OnAddItem</var> event handler (when 
assigned). The event handler is used to selectively filter file system 
objects added to the <var>Items</var> in the control. If the 
<var>TAddItemEvent</var> handler sets its <var>CanAdd</var> argument to 
<b>False</b>, the file system object is not added to Items.
</p>
<p>
On exit, Items contains the <var>TShellTreeNode</var> instances where ANode 
is the parent. If an entry is a directory which has sub-directories, its 
<var>HasChildren</var> property is set to <b>True</b>.
</p>
<p>
<var>PopulateTreeNodeWithFiles</var> is used in the implementation of the 
<var>PopulateWithBaseFiles</var> and <var>CanExpand</var> methods in 
<var>TCustomShellTreeView</var>.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.ObjectTypes"/>
<link id="TCustomShellTreeView.Items"/>
<link id="TCustomShellTreeView.DoAddItem"/>
<link id="TCustomShellTreeView.CanExpand"/>
<link id="TCustomShellTreeView.PopulateWithBaseFiles"/>
<link id="TShellTreeNode"/>
</seealso>
</element>
<element name="TCustomShellTreeView.PopulateTreeNodeWithFiles.Result">
<short>
Returns <b>True</b> if at least one item was added to the shell control.
</short>
</element>
<element name="TCustomShellTreeView.PopulateTreeNodeWithFiles.ANode">
<short>
Initial tree node used when filling the Items for the shell control.
</short>
</element>
<element name="TCustomShellTreeView.PopulateTreeNodeWithFiles.ANodePath">
<short>Path to the initial tree node used in the method.</short>
</element>

<element name="TCustomShellTreeView.DoSelectionChanged">
<short>
Performs actions needed when a new item is selected in the shell control.
</short>
<descr>
<p>
<var>DoSelectionChanged</var> is an overridden method used to perform actions 
needed when a new item is selected in the shell control. DoSelectionChanged 
calls the inherited DoSelectionChanged method, and ensures that a 
<var>TCustomShellListView</var> control assigned to <var>ShellListView</var> 
is synchronized to the current selection in the class.
</p>
<p>
No actions are performed in the method if values for either 
<var>ShellListView</var> or <var>Selected</var> have not been assigned 
(contain <b>Nil</b>).
</p>
<p>
<var>Selected</var> contains the current tree node selected in the shell 
control, and is used to determine if the selection is a file, directory, or 
other device. When it is a directory, its path is assigned to the 
<var>Root</var> property in <var>ShellListView</var>.
</p>
<p>
If <var>Selected</var> does not represent a directory, the path refers to a 
file name that must exist on the local file system. An <var>EShellCtrl</var> 
exception is raised if the selected item does not exist. If 
<var>Selected</var> has a parent tree node, its path is assigned to the 
<var>Root</var> property in <var>ShellListView</var>. If no parent is 
available, the <var>Root</var> property in <var>ShellListView</var> is set to 
an empty string (<b>''</b>).
</p>
</descr>
<errors>
Raises an <var>EShellCtrl</var> exception if Selected refers to a file name 
that no longer exists on the local file system.
</errors>
<seealso>
<link id="TCustomShellTreeView.ShellListView"/>
<link id="TCustomShellListView"/>
<link id="TCustomShellListView.Root"/>
<link id="TShellTreeNode"/>
<link id="EShellCtrl"/>
<link id="#lcl.comctrls.TCustomTreeView.Selected">TCustomTreeView.Selected</link>
</seealso>
</element>

<element name="TCustomShellTreeView.DoAddItem">
<short>
Performs actions needed to add a new tree node to the shell control.
</short>
<descr>
<p>
<var>DoAddItem</var> is a procedure used to perform actions needed when a new 
tree node is added to the shell control. DoAddItem signals the 
<var>OnAddItem</var> event handler (when assigned) to examine and process the 
arguments passed to the method.
</p>
<p>
<var>ABasePath</var> contains the path on the local file system where the 
file system object exists.
</p>
<p>
<var>AFileInfo</var> is a <var>TSearchRec</var> instance with the details for 
the file system object.
</p>
<p>
<var>CanAdd</var> is a variable Boolean parameter used to indicate if the new 
tree node can be added to the shell control.
</p>
<p>
No actions are performed in the method when <var>OnAddItem</var> has not been 
assigned (contains <b>Nil</b>). Applications must implement and assign an 
object procedure to the event handler which responds to the event 
notification.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.OnAddItem"/>
</seealso>
</element>
<element name="TCustomShellTreeView.DoAddItem.ABasePath">
<short>Base path for the new tree node.</short>
</element>
<element name="TCustomShellTreeView.DoAddItem.AFileInfo">
<short>TSearchRec with information about the file system object.</short>
</element>
<element name="TCustomShellTreeView.DoAddItem.CanAdd">
<short>Indicates if the tree node can be added for the specified path.</short>
</element>

<element name="TCustomShellTreeView.CanExpand">
<short>
Determines if the specified tree node can be expanded in the shell tree view 
control.
</short>
<descr>
<p>
<var>CanExpand</var> is an overridden <var>Boolean</var> function used to 
determine if the specified tree node can be expanded in the shell tree view 
control. CanExpand ensures that the shell control reflects the current content 
in the local file system during execution of the method.
</p>
<p>
<var>Node</var> contains the <var>TTreeNode</var> examined and updated in the 
method.
</p>
<p>
CanExpand calls the inherited method to signal the OnExpanding event handler 
(when assigned). No additional actions are performed if the inherited method 
returns <b>False</b>.
</p>
<p>
<var>CanExpand</var> temporarily disables the <var>AutoExpand</var> 
functionality in the shell tree view control, and updates the child nodes in 
Node when needed. The value in ExpandCollapseMode is used to determine whether 
child nodes are created or recreated. The following actions are performed for 
the ExpandCollapseMode property values:
</p>
<dl>
<dt>ecmRefreshedExpanding</dt>
<dd>
Deletes existing child nodes and calls PopulateTreeNodeWithFiles to reload 
entries for the path in Node.
</dd>
<dt>ecmKeepChildren</dt>
<dd>
Keeps existing child nodes. Calls PopulateTreeNodeWithFiles if the existing 
child node count is 0 (zero).
</dd>
<dt>ecmCollapseAndClear</dt>
<dd>
Calls PopulateTreeNodeWithFiles to load files for the path in Node.
</dd>
</dl>
<p>
The value in <var>AutoExpand</var> is restored to its original value prior to 
exiting from the method.
</p>
<p>
The entire update process is done in a BeginUpdate / EndUpdate block to reduce 
the number of screen refreshes in the method.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.ExpandCollapseMode"/>
<link id="TCustomShellTreeView.PopulateTreeNodeWithFiles"/>
<link id="TShellTreeView.AutoExpand"/>
<link id="TShellTreeNode"/>
<link id="TTreeNode"/>
<link id="#lcl.comctrls.TCustomTreeView.AutoExpand">TCustomTreeView.AutoExpand</link>
</seealso>
<version>
Modified in LCL version 3.0 to use ExpandCollapseMode to control actions 
performed for child nodes.
</version>
</element>
<element name="TCustomShellTreeView.CanExpand.Result">
<short>
<b>True</b> when the tree node can be expanded to display child nodes.
</short>
</element>
<element name="TCustomShellTreeView.CanExpand.Node">
<short>Tree node examined in the method.</short>
</element>

<element name="TCustomShellTreeView.Collapse">
<short>
Removes child nodes (if needed) when the specified tree node is collapsed.
</short>
<descr>
<p>
<var>Collapse</var> is an overridden method in <var>TCustomShellTreeView</var> 
used to update the tree node specified in <var>Node</var> when it changes from 
the expanded to the collapsed state. It uses the value in the 
ExpandCollapseMode property to determine whether existing child nodes are 
removed from the collapsed tree node.
</p>
<p>
When ExpandCollapseMode is set to ecmCollapseAndClear, the DeleteChildren 
method in Node is called to free its child nodes. The operation is performed 
in a BeginUpdate / EndUpdate block to prevent updates to the control while the 
child nodes are deleted.
</p>
<p>
Collapse calls the inherited method prior to exit to update scroll bars on the control and to signal the OnCollapsed event handler (when assigned).
</p>
<p>
No actions are performed in the method when ComponentState is set to 
csDestroying.
</p>
<p>
Collapse is called when a tree node has executed its Collapse method.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.ExpandCollapseMode"/>
<link id="#lcl.comctrls.TCustomTreeView.Collapse">TCustomTreeView.Collapse</link>
<link id="#lcl.comctrls.TCustomTreeView.OnCollapsed">TCustomTreeView.OnCollapsed</link>
<link id="#lcl.comctrls.TTreeNode.Collapse">TTreeNode.Collapse</link>
<link id="#lcl.comctrls.TTreeNode.HasChildren">TTreeNode.HasChildren</link>
<link id="#lcl.comctrls.TTreeNode.DeleteChildren">TTreeNode.DeleteChildren</link>
<link id="#rtl.classes.TComponent.ComponentState">TComponent.ComponentState</link>
</seealso>
<version>
Added in LCL version 3.0.
</version>
</element>
<element name="TCustomShellTreeView.Collapse.Node">
<short>
Tree node affected in the method.
</short>
</element>

<element name="TCustomShellTreeView.DrawBuiltInIcon">
<short>Draws the Shell Icon for the specified tree node.</short>
<descr>
<p>
<var>DrawBuiltInIcon</var> is an overridden <var>TSize</var> function used to 
draw an icon on the tree using the Shell icon for the file or folder name in 
<var>ANode</var>. It re-implements the method in the 
<var>TCustomTreeView</var> ancestor, and does <b>not</b> call the inherited 
method.
</p>
<p>
When <var>UseBuiltinIcons</var> is <b>True</b>, the internal 
<var>GetShellIcon</var> routine is called to get the icon used for the entry. 
The icon is drawn on the control <var>Canvas</var> using the rectangle in 
<var>ARect</var>. The icon is centered vertically in the specified rectangle.
</p>
<p>
The return value contains the dimensions for the icon as a <var>TSize</var> 
instance. When UseBuiltinIcons is <b>False</b>, the return value always 
contains a TSize instance with both the <var>Width</var> (<var>CX</var>) and 
<var>Height</var> (<var>CY</var>) set to <b>0</b> (<b>zero</b>). The size may 
also be empty (0, 0) if an icon was not found or returned for the file system 
entry by the widgetset class instance. This can occur when the entry 
represented by ANode has been removed from the file system.
</p>
<remark>
DrawBuiltInIcon is defined for the Windows platform only; it requires use of 
the <var>SHGetFileInfoW</var> routine in the FPC <file>ShellApi.pp</file> 
unit.
</remark>
</descr>
<seealso>
<link id="TCustomShellTreeView.UseBuiltinIcons"/>
<link id="TCustomShellTreeView.GetBuiltinIconSize"/>
<link id="#lcl.comctrls.TCustomTreeView.DrawBuiltinIcon">TCustomTreeView.DrawBuiltinIcon</link>
</seealso>
</element>
<element name="TCustomShellTreeView.DrawBuiltInIcon.Result">
<short>TSize instance with the dimension for the icon.</short>
</element>
<element name="TCustomShellTreeView.DrawBuiltInIcon.ANode">
<short>Tree node with the name for the file system entry.</short>
</element>
<element name="TCustomShellTreeView.DrawBuiltInIcon.ARect">
<short>Rectangle where the icon is drawn.</short>
</element>

<element name="TCustomShellTreeView.ExistsAndIsValid">
<short>
Checks whether the specified path is a valid file system object and type for 
the tree view control.
</short>
<descr>
<p>
<var>ExistsAndIsValid</var> is a <var>Boolean</var> function used to determine 
whether a file system object at the path specified in <var>APath</var> can be 
displayed on the tree view control.
</p>
<p>
APath is a UTF-8-encoded fully-qualified path name. File attributes for the 
argument are retrieved to check whether it exists on the local file system. 
ObjectTypes is checked to determine whether the item is one of the object types 
displayed on the tree view control; this includes checking whether the otHidden 
object type setting matches the file system attributes for the path.
</p>
<p>
The return value is <b>False</b> if both conditions are <b>not</b> satisfied. 
The return value is <b>True</b> if APath a valid file (or directory) on the 
local file system.
</p>
<p>
ExistsAndIsValid is used in the UpdateView method when the Path and expanded 
state for a Selected node are updated.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomShellTreeView.ObjectTypes"/>
<link id="TCustomShellTreeView.Path"/>
<link id="TCustomShellTreeView.UpdateView"/>
</seealso>
</element>
<element name="TCustomShellTreeView.ExistsAndIsValid.Result">
<short>
Returns <b>True</b> if the specified path exists and is valid for the object 
types displayed on the control. 
</short>
</element>
<element name="TCustomShellTreeView.ExistsAndIsValid.APath">
<short>
Path name examined in the method.
</short>
</element>

<element name="TCustomShellTreeView.GetBuiltinIconSize">
<short>Gets the size for a shell icon used in the control.</short>
<descr>
<p>
<var>GetBuiltinIconSize</var> is an overridden <var>TSize</var> function used 
to get the dimensions for a shell icon displayed for a file system entry in 
the control. GetBuiltinIconSize re-implements the method from the 
<var>TCustomTreeView</var> ancestor, and does <b>not</b> call the inherited 
method.
</p>
<p>
The return value is a <var>TSize</var> instance with the <var>Width</var> 
(<var>CX</var>) and <var>Height</var> (<var>CY</var>) for the shell icon.
</p>
<p>
When <var>UseBuiltinIcons</var> is <b>True</b>, the internal member used for 
the icon size is checked. It is used when explicit values have been set for 
the Width and Height in the TSize instance. If the default values (0) are in 
Width and Height, the internal GetShellIcon routine is called to get the icon 
size used for Drive letter designations. It is assigned as the return value 
for the method, and stored in the internal member.
</p>
<p>
When UseBuiltinIcons is <b>False</b>, the return value always contains a 
TSize instance with both the <var>Width</var> (<var>CX</var>) and 
<var>Height</var> (<var>CY</var>) set to <b>0</b> (<b>zero</b>). The size may 
also be empty (0, 0) if an icon was not found or returned for the file system 
entry by the widgetset class instance. This can occur when the entry 
represented by ANode has been removed from the file system.
</p>
<remark>
GetBuiltinIconSize is defined for the Windows platform only; it requires use 
of the <var>SHGetFileInfoW</var> routine in the FPC <file>ShellApi.pp</file> 
unit.
</remark>
</descr>
<seealso>
<link id="TCustomShellTreeView.UseBuiltinIcons"/>
<link id="#lcl.comctrls.TCustomTreeView.DrawBuiltinIcon">TCustomTreeView.GetBuiltinIconSize</link>
</seealso>
</element>
<element name="TCustomShellTreeView.GetBuiltinIconSize.Result">
<short>TSize instance with the dimensions for the shell icon.</short>
</element>

<element name="TCustomShellTreeView.NodeHasChildren">
<short>
Determines whether the specified tree view Node has child nodes.
</short>
<descr>
<p>
NodeHasChildren is an overridden Boolean function used to determine whether 
the specified tree view Node has child nodes. It re-implements the method 
from the TCustomTreeView ancestor class to examine the local file system for 
the path the tree node. It does not call the inherited method.
</p>
<p>
NodeHasChildren signals the OnHasChildren event handler (when assigned) to 
get the return value for the method. The shell tree view class instance and 
the value in Node are passed as arguments to the event handler.
</p>
<p>
When an event handler has not been assigned, the return value is set to 
<b>True</b> if the specified Node is a Directory on the local file system.
</p>
<p>
The return value is also <b>True</b> when the path to the node can be 
accessed as a sub-directory in Node (when ObjectTypes does not include 
otNonFolders objects). Include otHidden in ObjectTypes to include hidden 
directories in the comparison.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.ObjectTypes"/>
<link id="#lcl.comctrls.TCustomTreeView.NodeHasChildren">TCustomTreeView.NodeHasChildren</link>
<link id="#lcl.comctrls.TCustomTreeView.OnHasChildren">TCustomTreeView.OnHasChildren</link>
</seealso>
</element>
<element name="TCustomShellTreeView.NodeHasChildren.Result">
<short>
<b>True</b> when the node is a directory or contains non-folder objects at 
the given path.
</short>
</element>

<element name="TCustomShellTreeView.ExpandCollapseMode">
<short>
Controls the actions performed when a tree node is expanded or collapsed on 
the control.
</short>
<descr>
<p>
<var>ExpandCollapseMode</var> is a <var>TExpandCollapseMode</var> property 
which determines the actions performed when a tree node is expanded or 
collapsed on the tree view control. The default value for the property is 
ecmRefreshedExpanding. This value causes the child nodes for a given tree node 
to be deleted and recreated when the node is expanded.
</p>
<p>
See <link id="TExpandCollapseMode">TExpandCollapseMode</link> for the other 
values allowed in the property, and the corresponding actions performed in the 
tree node.
</p>
<p>
ExpandCollapseMode is used in the CanExpand and Collapse methods.
</p>
</descr>
<version>
Added in LCL version 3.0.
</version>
<seealso>
<link id="TCustomShellTreeView.CanExpand"/>
<link id="TCustomShellTreeView.Collapse"/>
<link id="TCustomShellTreeView.PopulateTreeNodeWithFiles"/>
<link id="TExpandCollapseMode"/>
<link id="#lcl.comctrls.TTreeNode.Collapse">TTreeNode.Collapse</link>
<link id="#lcl.comctrls.TTreeNode.Expand">TTreeNode.Expand</link>
</seealso>
</element>

<element name="TCustomShellTreeView.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<p>
<var>Create</var> is the constructor for the class instance. Create calls the 
inherited method using the value in <var>AOwner</var> as the owner for the 
class instance. 
</p>
<p>
Create sets the default values for properties, including:
</p>
<dl>
<dt>UseBuiltinIcons</dt>
<dd>Set to True top enable the built-in icons in the widgetset class.</dd>
<dt>PathDelimiter</dt>
<dd>Set to the platform-specific PathDelim from the SysUtils unit.</dd>
<dt>Options</dt>
<dd>
Includes tvoReadOnly in the set to match the default value for the ReadOnly 
property.
</dd>
<dt>ObjectTypes</dt>
<dd>
Set to [otFolders] to display folders (but not files) in the tree view.
</dd>
</dl>
<p>
Create initializes internal members used to monitor the <var>Root</var> 
property for changes to its value, and the find options used to locate nodes in 
the Items for the tree view control. Find options include use of 
case-insensitive comparisons in node values when the CaseInsensitiveFilenames 
compiler define is enabled.
</p>
<p>
Please note: Values in the <var>Items</var> property are populated when the 
<var>Loaded</var> method is called during component streaming.
</p>
</descr>
<version>
Modified in LCL version 3.0 to initialize the PathDelimiter property and 
internal find options. 
Modified in LCL version 4.0 to update the Options property.
</version>
<seealso>
<link id="TCustomShellTreeView.ObjectTypes"/>
<link id="TCustomShellTreeView.UseBuiltinIcons"/>
<link id="TCustomShellTreeView.Root"/>
<link id="TCustomShellTreeView.Items"/>
<link id="TCustomShellTreeView.ShellListView"/>
<link id="TCustomShellTreeView.Loaded"/>
<link id="TCustomTreeView.PathDelimiter"/>
<link id="#rtl.sysutils.PathDelim">SysUtils.PathDelim</link>
</seealso>
</element>
<element name="TCustomShellTreeView.Create.AOwner">
<short>Component that owns the class instance.</short>
</element>

<element name="TCustomShellTreeView.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the destructor for the class instance. Destroy ensures 
that the <var>ShellListView</var> is set to <b>Nil</b> prior to calling the 
inherited destructor.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.ShellListView"/>
</seealso>
</element>

<element name="TCustomShellTreeView.GetBasePath">
<short>
Returns the initial path in the file system hierarchy for the tree structure 
in the control.
</short>
<descr>
<p>
<var>GetBasePath</var> is a <var>String</var> class function used to get the 
notation for the initial path in the file system hierarchy. The return value 
contains the following values for the supported platforms:
</p>
<dl>
<dt>Windows platforms (other than Windows CE)</dt>
<dd>'' (empty string)</dd>
<dt>Windows CE</dt>
<dd>'\'</dd>
<dt>UNIX-like operating systems</dt>
<dd>'/'</dd>
<dt>Amiga</dt>
<dd>'' (empty string)</dd>
</dl>
</descr>
<seealso>
<link id="TCustomShellTreeView.Root"/>
<link id="TCustomShellTreeView.GetRootPath"/>
</seealso>
</element>

<element name="TCustomShellTreeView.GetRootPath">
<short>
Returns the effective value for Root when an explicit value has not been 
assigned.
</short>
<descr>
<p>
If Root has an non-empty string value, it is used as the return value. 
Otherwise, GetBasePath is called to get the root designation for the 
platform. A trailing path delimiter is appended to the return value if it is 
not already present.
</p>
<p>
GetRootPath is called from GetPathFromNode when a relative path is found in 
the fully-qualified path for a node. It is also called from the Refresh 
method to get a path when a tree node is not specified as an argument to the 
method.
</p>
</descr>
<seealso>
</seealso>
</element>

<element name="TCustomShellTreeView.GetFilesInDir">
<short>
Fills a TStrings instance with file system objects which match the specified 
path and mask.
</short>
<descr>
<p>
<var>GetFilesInDir</var> is a class method which can be called without an 
existing instance of a TCustomShellTreeView descendant. For example:
</p>
<code>
TShellTreeView.GetFilesInDir('/path/to/dir', '*.pas;*.pp', 
  [otNonFolders], AStringList, [fstAlphabet], mcsCaseSensitive);
</code>
<p>
It performs actions to gather directories and/or files as in the 
PopulateTreeNodeWithFiles method, but does <b>not</b> store the file system objects to the Items property.
</p>
<p>
GetFilesInDir calls an implementation routine to access the local file system 
and to store matching file system objects in AResult. It calls FindFirstUTF8 / 
FindNextUTF8 / FindCloseUTF8 (in LazUtils) to gather TSearchRec information for 
the folders or files which match the specified criteria. The file system 
information is transferred to TFileItem instances which are stored in the 
Objects property in AResult. The Names property in AResult contains the names 
for the directories or files.
</p>
<p>
Use <var>ABaseDir</var> to specify the folder examined in the method, and the 
base directory used to resolve any relative path references in AMask. A 
trailing path delimiter is not required in ABaseDir; it is appended (when 
needed) in the implementation.
</p>
<p>
Use <var>AMask</var> to specify one or masks for file system items considered a 
match in the method. Use the ';' character to delimit mask values in the 
argument. When omitted (or set to an empty string), the AllFilesMask ('*') is 
used when checking file system objects.
</p>
<p>
Use <var>AObjectTypes</var> to specify the file system objects examined in the 
method. See <link id="TObjectType">TObjectType</link> for the values allowed in 
the set type, and their meanings.
</p>
<p>
<var>AResult</var> is a <var>TStrings</var> instance where folders and/or files 
matching the specified criteria are stored and returned to the caller. Use the 
Names property in AResult to access the names for the file system objects in 
the list. Use the Objects property in AResult to access 
<link id="TFileItem">TFileItem</link> instances with the path and search
record information for the file system objects. A value in Object must be cast 
to a TFileItem type to access the properties specific to the object instance. 
Use the Clear method in AResult to free the Names and Objects in the TStrings 
instance.
</p>
<p>
Use <var>AFileSortType</var> to specify the sort order applied to the values 
stored in AResult. See <link id="TFileSortType">TFileSortType</link> for the 
values allowed in the argument, and their meanings.
</p>
<p>
Use <var>ACaseSensitivity</var> to specify whether case sensitivity is used 
when comparing values in AMask to select matching file system objects. See 
<link id="TMaskCaseSensitivity">TMaskCaseSensitivity</link> for the values 
allowed in the argument, and their meanings. The default value for the argument 
is mcsPlatformDefault in the implementation routine.
</p>
</descr>
<version>
Modified in LCL version 3.0 to have public visibility.
</version>
<seealso>
<link id="TCustomShellTreeView.Items"/>
<link id="TCustomShellTreeView.PopulateTreeNodeWithFiles"/>
<link id="TFileItem"/>
<link id="TFileSortType"/>
<link id="TMaskCaseSensitivity"/>
<link id="TObjectType"/>
<link id="TObjectTypes"/>
<link id="#lazutils.lazfileutils.FindFirstUTF8">FindFirstUTF8</link>
<link id="#lazutils.lazfileutils.FindNextUTF8">FindNextUTF8</link>
<link id="#lazutils.lazfileutils.FindCloseUTF8">FindCloseUTF8</link>
<link id="#lazutils.masks.TMaskList">TMaskList</link>
<link id="#rtl.sysutils.TSearchRec">TSearchRec</link>
</seealso>
</element>
<element name="TCustomShellTreeView.GetFilesInDir.ABaseDir">
<short>
Base directory name used to resolve relative path references in AMask.
</short>
</element>
<element name="TCustomShellTreeView.GetFilesInDir.AMask">
<short>
One or more mask values used to select the matching file system objects  
returned in AResult.
</short>
</element>
<element name="TCustomShellTreeView.GetFilesInDir.AObjectTypes">
<short>
Specifies the file system object types examined and returned in AResult.
</short>
</element>
<element name="TCustomShellTreeView.GetFilesInDir.AResult">
<short>
TStrings instance where file system objects matching the specified criteria 
are stored and returned.
</short>
</element>
<element name="TCustomShellTreeView.GetFilesInDir.AFileSortType">
<short>
Sort type/order applied to the file system objects in AResult.
</short>
</element>
<element name="TCustomShellTreeView.GetFilesInDir.ACaseSensitivity">
<short>
Indicates whether case sensitivity is used when file system objects are 
compared to the selection criteria.
</short>
</element>

<element name="TCustomShellTreeView.GetPathFromNode">
<short>
Returns the path (including the file name) for the file system object 
represented in the specified node.
</short>
<descr>
<p>
GetPathFromNode casts the tree node in ANode to a TShellTreeNode type to 
access the file system-specific properties and methods for the node.
</p>
<p>
When IsDirectory returns <b>True</b>, the return value contains the path to 
the folder with a trailing path delimiter. Otherwise, the return value has 
the fully-qualified path for the file.
</p>
<p>
An absolute path in the return value includes the root directory prepended to 
the value.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.GetRootPath"/>
<link id="TShellTreeNode.IsDirectory"/>
<link id="TShellTreeNode.FullFilename"/>
<link id="TShellTreeNode.BasePath"/>
<link id="#lazutils.lazfileutils.FilenameIsAbsolute">FilenameIsAbsolute</link>
</seealso>
</element>
<element name="TCustomShellTreeView.GetPathFromNode.Result">
<short>
Fully qualified path for the file system object represented in the node.
</short>
</element>
<element name="TCustomShellTreeView.GetPathFromNode.ANode">
<short>Tree node with the path and file name for the node.</short>
</element>

<element name="TCustomShellTreeView.PopulateWithBaseFiles">
<short>Fills the tree view when the Root directory is empty.</short>
<descr>
<remark>
The implementation of PopulateWithBaseFiles is platform-specific.
</remark>
<p>
For Windows platforms other than Windows CE, the tree view is filled with 
<var>TShellTreeNode</var> entries for the logical drive names found on the 
system. The drive information is retrieved using the 
<var>GetLogicalDriveStrings</var> routine in the Windows API.
</p>
<p>
For other platforms, which do not use drive letters, the tree view is 
populated with nodes for the files or directories in the base path for the 
control.
</p>
<p>
PopulateWithBaseFiles is called from the <var>Loaded</var>, 
<var>SetRoot</var>, and <var>SetFileSortType</var> methods when an empty 
string (<b>''</b>) is assigned to the <var>Root</var> property.
</p>
<p>
No actions are performed in the method at design-time, or when the component 
is loaded using the LCL streaming mechanism on platforms other than Windows.
</p>
</descr>
<seealso></seealso>
</element>

<element name="TCustomShellTreeView.Refresh">
<short>
Updates the tree view to display file system objects starting at the 
specified tree node.
</short>
<descr>
<p>
<var>Refresh</var> is an overloaded method in 
<var>TCustomShellTreeView</var>. It ensures that the tree node specified in 
ANode is selected and expanded to reveal its immediate first-level child 
nodes. When ANode is unassigned (Nil), the value in Root is updated for the 
tree view an associated list view control (when assigned). Setting the value 
in Root also populates the TShellTreeNode instances in the Items property.
</p>
<p>
Refresh is called when a new value is assigned to the ObjectTypes property.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.Items"/>
<link id="TCustomShellTreeView.Root"/>
<link id="TCustomShellTreeView.ShellListView"/>
<link id="TCustomShellTreeView.ObjectTypes"/>
</seealso>
</element>
<element name="TCustomShellTreeView.Refresh.ANode">
<short>
Tree node with the initial path displayed in the shell control; Nil defaults 
to the root directory.
</short>
</element>

<element name="TCustomShellTreeView.UpdateView">
<short>
Reloads the nodes for tree view control and synchronizes an associated 
ShellListView control.
</short>
<descr>
<p>
<var>UpdateView</var> is a method used to repopulate the nodes on a tree view 
control. It ensures that Items contains the entries needed for the current 
state of the local file system in the tree view control.
</p>
<p>
UpdateView ensures that the Selected and expanded tree node(s) are captured, 
and restored when the nodes in Items have been reloaded. If one of the selected 
or expanded nodes no longer exists on the file system, the Path in an existing 
parent node is used for the update. When a node is updated, its HasChildren 
property is changed to reflect whether subdirectories have been added or 
removed for the node.
</p>
<p>
The Selected property provides the selected tree node on the control.
</p>
<p>
Updates to the Items in the control are enclosed by BeginUpdate and EndUpdate 
method calls to reduce the number of updates while the control is reloaded.
</p>
<p>
UpdateView causes an associated ShellListView control to call its UpdateView 
method to synchronize the two controls. This action is omitted if ShellListView 
has not been assigned, or the directory requested does not affect the Selected 
tree node.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomShellTreeView.Items"/>
<link id="TCustomShellTreeView.Refresh"/>
<link id="TCustomShellTreeView.GetPathFromNode"/>
<link id="TCustomShellTreeView.NodeHasChildren"/>
<link id="TCustomShellTreeView.ShellListView"/>
<link id="TCustomShellListView.UpdateView"/>
<link id="TCustomShellTreeView.Root"/>
<link id="TCustomShellTreeView.Path"/>
<link id="TCustomShellTreeView.ExistsAndIsValid"/>
<link id="#lcl.comctrls.TCustomTreeView.TopItem">TCustomTreeView.TopItem</link>
<link id="#lcl.comctrls.TCustomTreeView.Selected">TCustomTreeView.Selected</link>
<link id="#lcl.comctrls.TTreeNodes.BeginUpdate">TTreeNodes.BeginUpdate</link>
<link id="#lcl.comctrls.TTreeNodes.EndUpdate">TTreeNodes.EndUpdate</link>
</seealso>
</element>
<element name="TCustomShellTreeView.UpdateView.AStartDir">
<short>
Path to the first tree node updated in the method. Root is used when omitted.
</short>
</element>

<element name="TCustomShellTreeView.UseBuiltinIcons">
<short>
Indicates if OS-provided icons are used for entries in the Shell control.
</short>
<descr>
<p>
<var>UseBuiltinIcons</var> is a <var>Boolean</var> property which indicates 
if OS-provided icons are used for the file system entries in the Shell 
control.
</p>
<p>
The default value for the property is <b>True</b>. Setting a new value for 
the property causes the <var>Invalidate</var> method to be called to redraw 
the control.
</p>
<p>
UseBuiltinIcons is used in the <var>DrawBuiltinIcon</var> method, and 
controls whether the corresponding method is called in the widgetset class. 
When UseBuiltinIcons is set to <b>False</b>, an icon is not drawn in the 
DrawBuiltinIcon method.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.DrawBuiltinIcon"/>
</seealso>
</element>

<element name="TCustomShellTreeView.ObjectTypes">
<short>
Indicates the file system objects displayed using the control.
</short>
<descr>
<p>
<var>ObjectTypes</var> is a <var>TObjectTypes</var> property with the file 
system objects which can be stored in Items and displayed on the tree view 
control. It is a set type and can contains zero or more values from the 
TObjectType enumeration. When values are included in the set, they are 
enabled and displayed on the control.
</p>
<dl>
<dt>otFolders</dt>
<dd>
Enables and displays folders (directories).
</dd>
<dt>otNonFolders</dt>
<dd>
Enables and displays files and other file system entries which are not a 
folder.
</dd>
<dt>otHidden</dt>
<dd>
Enables and displays hidden directories and/or files on the tree view 
control.
</dd>
</dl>
<p>
The default value for the property is [otFolders].
</p>
<p>
Changing the values in the property causes the UpdateView method to be called 
to reload the Items displayed on the control. The currently Selected tree node 
is saved before the nodes are refreshed, and restored (when able) when Items 
has been reloaded. If the selected path has become invalid after the property 
change, an previous path (or the root node) becomes the Selected item on the 
control.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.Items"/>
<link id="TCustomShellTreeView.ExistsAndIsValid"/>
<link id="TCustomShellTreeView.Path"/>
<link id="TCustomShellTreeView.Root"/>
<link id="TCustomShellTreeView.UpdateView"/>
<link id="TObjectTypes"/>
<link id="TObjectType"/>
<link id="#lcl.comctrls.TCustomTreeView.Selected">TCustomTreeView.Selected</link>
<link id="#lcl.comctrls.TCustomTreeView.TopItem">TCustomTreeView.TopItem</link>
</seealso>
</element>

<element name="TCustomShellTreeView.ShellListView">
<short>
Connects this ShellTreeView to a ShellListView.
</short>
<descr>
<p>
<var>ShellListView</var> is a <var>TCustomShellListView</var> property used 
to connect the tree view to a list view control.
</p>
<p>
Methods and properties in the list view control can be used to change the 
currently selected directory, or to limit its display to specific object 
types. Changes to the <var>Root</var> or <var>ObjectTypes</var> properties in 
the list view are propagated to the associated tree view control.
</p>
<p>
In a similar fashion, changes to the <var>Root</var> property or the selected 
item in the tree view causes the changes to be propagated to the associated 
list view control.
</p>
</descr>
<seealso>
<link id="TShellListView"/>
<link id="TCustomShellListView"/>
<link id="TCustomShellListView.ShellTreeView"/>
</seealso>
</element>

<element name="TCustomShellTreeView.FileSortType">
<short>
Indicates the sort type used for items (tree nodes) on the tree view control.
</short>
<descr>
<p>
<var>FileSortType</var> is a <var>TFileSortType</var> property used to 
indicate the sort order for tree nodes in the <var>Items</var> property. The 
default value for the property is <b>fstNone</b>, and indicates the default 
sort order is used for tree nodes. See 
<link id="TFileSortType">TFileSortType</link> for information about the 
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 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 
design-time.
</p>
<p>
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 
order provided by the file system.
</remark>
</descr>
<seealso>
<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>

<element name="TCustomShellTreeView.Root">
<short>
Indicates the directory or path which is the top-level node in the tree view.
</short>
<descr>
<p>
<var>Root</var> is a <var>String</var> property used to set the directory (or 
logical device) used to fill the list of Items (tree nodes) in the tree view 
control. It represents the top-level node in the tree structure which does not 
have a parent tree node.
</p>
<p>
Changing the value in Root causes the Items in the control to be cleared and 
re-populated at run-time. This action is not performed at design-time; the 
tree node for the specified Root is displayed - but no other tree nodes are 
loaded or displayed.
</p>
<p>
No actions are performed in the method when a new value is set for the 
Root property while the component is being loaded using the LCL streaming 
mechanism. The actions are performed at run-time when the Loaded method for 
the control is called.
</p>
<p>
Setting Root to an empty string (<b>''</b>) indicates that the base path for 
the platform should be used to populate the nodes for the tree view. For 
Windows, this is often an empty string and causes the root directory for the 
current disk device to be used. For UNIX-like platforms, the base path is '/' 
for the root directory on the file system. For WinCE, the base path is '\' 
without a device specifier.
</p>
<p>
Setting Root to a valid path on the file system causes the specified directory 
to become the effective top-level node in the tree view control. Any directory 
above the specified root in the local file system cannot be accessed using the 
tree view control.
</p>
<p>
Setting Root to an invalid path causes an EInvalidPath exception to be raised 
at run-time. The error is ignored, and the exception is not raised, at 
design-time to prevent crashing the Lazarus IDE.
</p>
<p>
Values in Items are cleared and the tree nodes in Items are re-created using 
the effective path (base or specified). For platforms where the base path 
causes Root to be an empty string, the PopulateWithBaseFiles method is called 
to determine the Items displayed on the control. For platforms with a 
non-empty base path, or an explicit path assigned to the property, 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.
</p>
<p>
If ShellListView has been assigned for the control, its Root property is 
updated to match the new value for the property in the tree view control.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.GetBasePath"/>
<link id="TCustomShellTreeView.Items"/>
<link id="TCustomShellTreeView.PopulateWithBaseFiles"/>
<link id="TCustomShellTreeView.PopulateTreeNodeWithFiles"/>
<link id="TShellTreeView.ShellListView"/>
<link id="TShellListView"/>
<link id="TShellListView.Root"/>
<link id="TShellTreeNode"/>
<link id="#lcl.comctrls.TTreeNode.Expand">TTreeNode.Expand</link>
</seealso>
</element>

<element name="TCustomShellTreeView.Path">
<short>
Path to the directory displayed in the shell control.
</short>
<descr>
<p>
<var>Path</var> is a <var>String</var> property which represents the path on 
the local file system to the Selected tree node in the control.
</p>
<p>
Reading the value for the property calls the <var>GetPathFromNode</var> 
method to derive the value for the property using the <var>Selected</var> 
tree node. The full path for the <var>TShellTreeNode</var> is used, with a 
path delimiter appended for a directory entry. If the path is not absolute, 
the base path name is prepended to the path value.
</p>
<p>
Setting the value for the property causes the new value to be resolved to 
a fully-qualified path name when needed. A relative path is expanded into a 
fully-qualified absolute path value resolved relative to the base path in 
<var>Root</var>.
</p>
<p>
An <var>EInvalidPath</var> exception is raised if Path is set to a value 
that is not valid, including:
</p>
<ul>
<li>
The path does not exist on the local file system.
</li>
<li>
The path cannot be resolved as a directory located under the Root directory.
</li>
<li>
The path represents an entry not valid for the settings in ObjectTypes.
</li>
</ul>
</descr>
<seealso>
<link id="TCustomShellTreeView.GetPathFromNode"/>
<link id="TCustomShellTreeView.GetRootPath"/>
<link id="TCustomShellTreeView.ExistsAndIsValid"/>
<link id="TCustomShellTreeView.ObjectTypes"/>
<link id="EInvalidPath"/>
<link id="#lazutils.lazfileutils.FilenameIsAbsolute">FilenameIsAbsolute</link>
</seealso>
</element>

<element name="TCustomShellTreeView.OnAddItem">
<short>
Event handler signalled when an item (tree node) is added to the shell 
control.
</short>
<descr>
<p>
<var>OnAddItem</var> is a <var>TAddItemEvent</var> property which contains 
the event handler signalled when an item (tree node) is added to the shell 
control. OnAddItem is signalled from the <var>PopulateTreeNodeWithFiles</var> 
method, and allows the base path and file information for each file to be 
checked before it is added to the Items for the tree view control.
</p>
<p>
An application must implement and assign an object procedure using the 
signature in TAddItemEvent to the handler. The Sender argument is the tree 
view control for the event notification. ABasePath contains the value from 
BasePath in the tree view control. AFileInfo is a TSearchRec instance with 
the attributes for the file system object represented in the node. CanAdd is 
a variable parameter which indicates whether the file system object should be 
added to the Items property. Set CanAdd to <b>False</b> in the event handler 
to omit the file system object in Items.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.Items"/>
<link id="TCustomShellTreeView.PopulateTreeNodeWithFiles"/>
<link id="TAddItemEvent"/>
</seealso>
</element>

<element name="TCustomShellTreeView.OnSortCompare">
<short>
Event handler signalled to compare file items in a custom sort routine.
</short>
<descr>
<p>
<var>OnSortCompare</var> is a <var>TFileItemCompareEvent</var> property with 
the event handler signalled to implement a custom file sort for the tree view 
control. OnSortCompare is used to order the directories or files displayed in 
the tree view control when the FileSortType property is set to fstCustom.
</p>
<p>
Changing the routine assigned to the property causes the Items in the control 
to be reloaded and ordered at run-time starting at the top-level tree node in 
Root. The Path property is used to to expand and select a tree node after 
the sort operation has been completed if the path still exists and is valid 
for the settings in ObjectTypes.
</p>
<p>
An application can implement and assign a routine using the signature perform 
custom file comparison routines using various attributes. The following is an 
item compare function, as implemented by forum member d7_2_laz, used to order 
items with leading Underscore characters:
</p>
<code>
function TForm1.SortCompareUnderscore(Item1, Item2: TFileItem): integer;
begin
  // Make sure that folders are moved to the top
  Result := ord(Item2.isFolder) - ord(Item1.isFolder);
  if Result = 0 then
    if (pos('_', Item1.FileInfo.Name) = 1) or 
      (pos('_', Item2.FileInfo.Name) = 1) then
      Result := AnsiCompareText(Item1.FileInfo.Name, Item2.FileInfo.Name)
    else
      Result := CompareText(Item1.FileInfo.Name, Item2.FileInfo.Name);
end;
</code>
<p>
<b>Sort File Items by Date</b>
</p>
<code>
function TForm1.SortCompareByDate(Item1, Item2: TFileItem): integer;
begin
  // Folders first ...
  Result := ord(Item2.isFolder) - ord(Item1.isFolder);
  if Result = 0 then
  begin
    // then file date ...
    Result := CompareValue(Item1.FileInfo.TimeStamp, Item2.FileInfo.TimeStamp);
    if Result = 0 then
      // then file name
      Result := CompareText(Item1.FileInfo.Name, Item2.FileInfo.Name);
  end;
end;
</code>
<p>
<b>Sort File Items by Size</b>
</p>
<code>
function TForm1.SortCompareBySize(Item1, Item2: TFileItem): integer;
begin
  // Folders first
  Result := ord(Item2.isFolder) - ord(Item1.isFolder);
  if Result = 0 then
  begin
    // then file size ...
    Result := Item1.FileInfo.Size - Item2.FileInfo.Size;
    if Result = 0 then
      // then file name
      Result := CompareText(Item1.FileInfo.Name, Item2.FileInfo.Name);
  end;
end;
</code>
</descr>
<version>
Added in LCL version 3.0.
</version>
<seealso>
<link id="TCustomShellTreeView.FileSortType"/>
<link id="TCustomShellTreeView.Items"/>
<link id="TCustomShellTreeView.ObjectTypes"/>
<link id="TCustomShellTreeView.Root"/>
<link id="TCustomShellTreeView.Path"/>
<link id="TCustomShellTreeView.ExistsAndIsValid"/>
<link id="TCustomShellTreeView.PopulateTreeNodeWithFiles"/>
<link id="TCustomShellTreeView.PopulateWithBaseFiles"/>
<link id="TFileSortType"/>
</seealso>
</element>

<element name="TCustomShellTreeView.Items">
<short>	
Contains the tree nodes used to represent the hierarchical tree structure for the tree view control.
</short>
<descr>	
<p>
<var>Items</var> is a <var>TTreeNodes</var> property which contains the tree 
nodes which represent the tree structure for the control. In 
TCustomShellTreeView, and the TShellTreeView descendant, it is populated at 
run-time with TShellTreeNode instances instead of the TTreeNode type used in 
the ancestor class. This allows file system information to be included for the 
tree nodes. This occurs when the CreateNode method is called for the control, 
and results in TShellTreeNode being used as the TTreeNodeClass type for the 
derived control. An exception is raised if OnCreateNodeClass is implemented to 
return a type other than TShellTreeNode.
</p>
<p>
Methods which access or maintain the Items in TCustomShellTreeView always cast 
the node values to TShellTreeNode to access the file system-specific 
information.
</p>
<p>
In TCustomShellTreeView, Items is cleared and re-populated at run-time when a 
new value is assigned to the Root, FileSortType, or OnSortCompare properties.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.CreateNode"/>
<link id="TCustomShellTreeView.NodeHasChildren"/>
<link id="TCustomShellTreeView.PopulateTreeNodeWithFiles"/>
<link id="TCustomShellTreeView.DoSelectionChanged"/>
<link id="TCustomShellTreeView.GetPathFromNode"/>
<link id="TShellTreeNode"/>
<link id="#lcl.comctrls.TCustomTreeView.Items">TCustomTreeView.Items</link>
<link id="#lcl.comctrls.TCustomTreeView.OnCreateNodeClass">TCustomTreeView.OnCreateNodeClass</link>
</seealso>
</element>

<element name="TShellTreeView">
<short>
Implements a tree view control to display the files, directories and other 
objects (such as devices) from the local file system.
</short>
<descr>
<p>
<var>TShellTreeView</var> is a <var>TCustomShellTreeView</var> descendant 
that implements a tree view used to display files, directories, and other 
objects (such as devices) from the local file system. TShellTreeView provides 
a hierarchical tree view for the file system objects, and is used to navigate 
between items in the control.
</p>
<p>
TShellTreeView sets the visibility for properties, methods, and events 
defined in the ancestor class.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView"/>
</seealso>
</element>

<element name="TShellTreeView.Align" link="#lcl.controls.TControl.Align"/>
<element name="TShellTreeView.Anchors" link="#lcl.controls.TControl.Anchors"/>
<element name="TShellTreeView.AutoExpand" link="#lcl.comctrls.TCustomTreeView.AutoExpand"/>
<element name="TShellTreeView.BorderSpacing" link="#lcl.controls.TControl.BorderSpacing"/>
<element name="TShellTreeView.BackgroundColor" link="#lcl.comctrls.TCustomTreeView.BackgroundColor"/>
<element name="TShellTreeView.BorderStyle" link="#lcl.controls.TWinControl.BorderStyle"/>
<element name="TShellTreeView.BorderWidth" link="#lcl.controls.TWinControl.BorderWidth"/>
<element name="TShellTreeView.Color" link="#lcl.controls.TControl.Color"/>
<element name="TShellTreeView.Constraints" link="#lcl.controls.TControl.Constraints"/>
<element name="TShellTreeView.Enabled" link="#lcl.controls.TControl.Enabled"/>
<element name="TShellTreeView.ExpandSignType" link="#lcl.comctrls.TCustomTreeView.ExpandSignType"/>
<element name="TShellTreeView.Font" link="#lcl.controls.TControl.Font"/>
<element name="TShellTreeView.FileSortType" link="#lcl.shellctrls.TCustomShellTreeView.FileSortType"/>
<element name="TShellTreeView.HideSelection" link="#lcl.comctrls.TCustomTreeView.HideSelection"/>
<element name="TShellTreeView.HotTrack" link="#lcl.comctrls.TCustomTreeView.HotTrack"/>
<element name="TShellTreeView.Images" link="#lcl.comctrls.TCustomTreeView.Images"/>
<element name="TShellTreeView.Indent" link="#lcl.comctrls.TCustomTreeView.Indent"/>
<element name="TShellTreeView.MultiSelectStyle" link="#lcl.comctrls.TCustomTreeView.MultiSelectStyle"/>

<element name="TShellTreeView.ParentColor">
<short>
Uses the Color from the Parent control, when enabled.
</short>
<descr>
<p>
ParentColor determines if the control should use the Color from the Parent 
control, when enabled. The default value for the property is <b>False</b> in 
TShellTreeView.
</p>
<p>
When this property is <b>True</b>, all changes to the Color of the parent 
will also be applied to the Color of the control, ensuring that they both 
contain same value. If the Color of the control is changed by the 
application, then ParentColor will be automatically set to <b>False</b>.
</p>
</descr>
<seealso>
<link id="#lcl.controls.TControl.ParentColor">TControl.ParentColor</link>
</seealso>
</element>

<element name="TShellTreeView.ParentFont" link="#lcl.controls.TControl.ParentFont"/>
<element name="TShellTreeView.ParentShowHint" link="#lcl.controls.TControl.ParentShowHint"/>
<element name="TShellTreeView.PopupMenu" link="#lcl.controls.TControl.PopupMenu"/>

<element name="TShellTreeView.ReadOnly">
<short>
Indicates whether the text (or caption) for tree nodes can be edited in the 
shell control.
</short>
<descr>
<p>
<var>ReadOnly</var> is a <var>Boolean</var> property which indicates whether 
the text for the <var>TTreeNode</var> instances in Items can be edited in the 
control. When ReadOnly is set to <b>False</b>, the <var>BeginEditing</var> 
method is <b>not</b> called when the <b>F2</b> key is pressed, or when the Left 
mouse button is double clicked. The default value for the property is 
<b>True</b>.
</p>
<p>
The property value is <b>True</b> when <var>tvoReadOnly</var> has been 
included in the <var>Options</var> for the control. Setting a new value for 
the property causes tvoReadOnly to be included in or excluded from the values 
in Options. Changing the value to <b>False</b> causes the 
<var>EndEditing</var> method to be called.
</p>
<p>
The ReadOnly property was changed to <b>True</b> because the shell tree view 
does not automatically propagate changes to a tree node caption to the file 
system. The previous behavior was confusing because the user was able to rename 
a node but had to notice that the change was not persistent without additional 
code.
</p>
<p>
Applications using the shell controls only for selecting files and folders are 
not affected. In "file-manager" application types, however, the ReadOnly 
property must be changed explicitely to <b>False</b> so that the user can edit 
items/nodes again.
</p>
</descr>
<version>
Modified in LCL version 4.0 to set the default value for the property to 
<b>True</b>.
</version>
<seealso>
<link id="#lcl.comctrls.TCustomTreeView.ReadOnly"/>
<link id="#lcl.comctrls.TCustomTreeView.Options"/>
<link id="#lcl.comctrls.TTreeViewOption"/>
<link id="#lcl.comctrls.TTreeViewOptions"/>
</seealso>
</element>

<element name="TShellTreeView.RightClickSelect" link="#lcl.comctrls.TCustomTreeView.RightClickSelect"/>
<element name="TShellTreeView.Root" link="#lcl.shellctrls.TCustomShellTreeView.Root"/>
<element name="TShellTreeView.RowSelect" link="#lcl.comctrls.TCustomTreeView.RowSelect"/>
<element name="TShellTreeView.ScrollBars" link="#lcl.comctrls.TCustomTreeView.ScrollBars"/>
<element name="TShellTreeView.SelectionColor" link="#lcl.comctrls.TCustomTreeView.SelectionColor"/>
<element name="TShellTreeView.ShowButtons" link="#lcl.comctrls.TCustomTreeView.ShowButtons"/>
<element name="TShellTreeView.ShowHint" link="#lcl.controls.TControl.ShowHint"/>
<element name="TShellTreeView.ShowLines" link="#lcl.comctrls.TCustomTreeView.ShowLines"/>
<element name="TShellTreeView.ShowRoot" link="#lcl.comctrls.TCustomTreeView.ShowRoot"/>
<element name="TShellTreeView.StateImages" link="#lcl.comctrls.TCustomTreeView.StateImages"/>

<element name="TShellTreeView.TabStop">
<short>Enables navigation using the Tab key.</short>
<descr>
<p>
The default value for the properly is <b>True</b> in TShellTreeView.
</p>
</descr>
<seealso>
<link id="#lcl.controls.TWinControl.TabStop">TWinControl.TabStop</link>
</seealso>
</element>

<element name="TShellTreeView.TabOrder" link="#lcl.controls.TWinControl.TabOrder"/>

<element name="TShellTreeView.Tag">
<short>Tag value for the component.</short>
<descr>
<p>
<var>Tag</var> can be used to store an integer value in the component. This 
value is streamed together with all other published properties. It can be 
used for instance to quickly identify a component in an event handler.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TComponent">TComponent</link>
</seealso>
</element>

<element name="TShellTreeView.ToolTips" link="#lcl.comctrls.TCustomTreeView.ToolTips"/>
<element name="TShellTreeView.Visible" link="#lcl.controls.TControl.Visible"/>
<element name="TShellTreeView.Options" link="#lcl.comctrls.TCustomTreeView.Options"/>
<element name="TShellTreeView.TreeLineColor" link="#lcl.comctrls.TCustomTreeView.TreeLineColor"/>
<element name="TShellTreeView.TreeLinePenStyle" link="#lcl.comctrls.TCustomTreeView.TreeLinePenStyle"/>
<element name="TShellTreeView.ExpandSignColor" link="#lcl.comctrls.TCustomTreeView.ExpandSignColor"/>
<element name="TShellTreeView.ObjectTypes" link="#lcl.shellctrls.TCustomShellTreeView.ObjectTypes"/>
<element name="TShellTreeView.ShellListView" link="#lcl.shellctrls.TCustomShellTreeView.ShellListView"/>
<element name="TShellTreeView.OnAddItem" link="#lcl.shellctrls.TCustomShellTreeView.OnAddItem"/>
<element name="TShellTreeView.OnAdvancedCustomDraw" link="#lcl.comctrls.TCustomTreeView.OnAdvancedCustomDraw"/>
<element name="TShellTreeView.OnAdvancedCustomDrawItem" link="#lcl.comctrls.TCustomTreeView.OnAdvancedCustomDrawItem"/>
<element name="TShellTreeView.OnChange" link="#lcl.comctrls.TCustomTreeView.OnChange"/>
<element name="TShellTreeView.OnChanging" link="#lcl.comctrls.TCustomTreeView.OnChanging"/>
<element name="TShellTreeView.OnClick" link="#lcl.controls.TControl.OnClick"/>
<element name="TShellTreeView.OnCollapsed" link="#lcl.comctrls.TCustomTreeView.OnCollapsed"/>
<element name="TShellTreeView.OnCollapsing" link="#lcl.comctrls.TCustomTreeView.OnCollapsing"/>
<element name="TShellTreeView.OnCustomDraw" link="#lcl.comctrls.TCustomTreeView.OnCustomDraw"/>
<element name="TShellTreeView.OnCustomDrawItem" link="#lcl.comctrls.TCustomTreeView.OnCustomDrawItem"/>
<element name="TShellTreeView.OnDblClick" link="#lcl.controls.TControl.OnDblClick"/>
<element name="TShellTreeView.OnEdited" link="#lcl.comctrls.TCustomTreeView.OnEdited"/>
<element name="TShellTreeView.OnEditing" link="#lcl.comctrls.TCustomTreeView.OnEditing"/>
<element name="TShellTreeView.OnEnter" link="#lcl.controls.TWinControl.OnEnter"/>
<element name="TShellTreeView.OnExit" link="#lcl.controls.TWinControl.OnExit"/>
<element name="TShellTreeView.OnExpanded" link="#lcl.comctrls.TCustomTreeView.OnExpanded"/>
<element name="TShellTreeView.OnExpanding" link="#lcl.comctrls.TCustomTreeView.OnExpanding"/>
<element name="TShellTreeView.OnGetImageIndex" link="#lcl.comctrls.TCustomTreeView.OnGetImageIndex"/>
<element name="TShellTreeView.OnGetSelectedIndex" link="#lcl.comctrls.TCustomTreeView.OnGetSelectedIndex"/>
<element name="TShellTreeView.OnHasChildren" link="#lcl.comctrls.TCustomTreeView.OnHasChildren"/>
<element name="TShellTreeView.OnKeyDown" link="#lcl.controls.TWinControl.OnKeyDown"/>
<element name="TShellTreeView.OnKeyPress" link="#lcl.controls.TWinControl.OnKeyPress"/>
<element name="TShellTreeView.OnKeyUp" link="#lcl.controls.TWinControl.OnKeyUp"/>
<element name="TShellTreeView.OnMouseDown" link="#lcl.controls.TControl.OnMouseDown"/>
<element name="TShellTreeView.OnMouseEnter" link="#lcl.controls.TControl.OnMouseEnter"/>
<element name="TShellTreeView.OnMouseLeave" link="#lcl.controls.TControl.OnMouseLeave"/>
<element name="TShellTreeView.OnMouseMove" link="#lcl.controls.TControl.OnMouseMove"/>
<element name="TShellTreeView.OnMouseUp" link="#lcl.controls.TControl.OnMouseUp"/>
<element name="TShellTreeView.OnMouseWheel" link="#lcl.controls.TControl.OnMouseWheel"/>
<element name="TShellTreeView.OnMouseWheelDown" link="#lcl.controls.TControl.OnMouseWheelDown"/>
<element name="TShellTreeView.OnMouseWheelUp" link="#lcl.controls.TControl.OnMouseWheelUp"/>
<element name="TShellTreeView.OnMouseWheelHorz" link="#lcl.controls.TControl.OnMouseWheelHorz"/>
<element name="TShellTreeView.OnMouseWheelLeft" link="#lcl.controls.TControl.OnMouseWheelLeft"/>
<element name="TShellTreeView.OnMouseWheelRight" link="#lcl.controls.TControl.OnMouseWheelRight"/>
<element name="TShellTreeView.OnSelectionChanged" link="#lcl.comctrls.TCustomTreeView.OnSelectionChanged"/>
<element name="TShellTreeView.OnShowHint" link="#lcl.controls.TControl.OnShowHint"/>
<element name="TShellTreeView.OnSortCompare" link="#lcl.shellctrls.TCustomShellTreeView.OnSortCompare"/>
<element name="TShellTreeView.OnUTF8KeyPress" link="#lcl.controls.TWinControl.OnUTF8KeyPress"/>

<element name="TCSLVFileAddedEvent">
<short>
Specifies an event handler signalled when an item is added to 
TCustomShellListView.
</short>
<descr>
<p>
<var>TCSLVFileAddedEvent</var> specifies the interface for an event handler 
signalled when a <var>TListItem</var> instance is added to 
<var>TCustomShellListView</var>. TCSLVFileAddedEvent is the type used to 
implement the <var>OnAddItem</var> property in 
<var>TCustomShellListView</var>.
</p>
<p>
Applications must implement and assign an object procedure using the event 
signature to respond to the notification. <var>Sender</var> must be cast to 
the correct class type to access properties and methods in the control for 
the notification. Or, use the <var>ListView</var> property in the 
<var>Item</var> argument.
</p>
</descr>
<seealso>
<link id="TCustomShellListView.OnAddItem"/>
<link id="#lcl.comctrls.TListItem">TListItem</link>
</seealso>
</element>
<element name="TCSLVFileAddedEvent.Sender">
<short>Object (control) generating the event notification.</short>
</element>
<element name="TCSLVFileAddedEvent.Item">
<short>List item for the event notification.</short>
</element>

<element name="TShellListItem">
<short>
Implements the class used for list items maintained in TShelllListView.
</short>
<descr>
<p>
<var>TShellListItem</var> is a <var>TListItem</var> descendant which 
implements the class used for the list items in the TShellListView control. It 
extends the ancestor class with the FileInfo property used for file system 
information about the list item. It also includes the IsFolder method to 
identify whether the list item is a directory on the local file system.
</p>
<p>
TShellListItem is the default class type used to create a new list item in the 
TCustomShellListView.CreateListItem method. It can, however be overridden by 
using an OnCreateItemClass event handler in the shell list view control. It is 
also used in the PopulateWithRoot method in TCustomShellListView to cast a new 
TFileItem instance created when the a file is added to the Items for the 
control.
</p>
</descr>
<version>
Added in LCL version 3.0.
</version>
<seealso>
<link id="TCustomShellListView.CreateListItem"/>
<link id="TCustomShellListView.PopulateWithRoot"/>
<link id="TCustomShellListView.Items"/>
<link id="TCustomListView.OnCreateItemClass"/>
<link id="TFileItem.Create"/>
<link id="#lcl.comctrls.TListItem">TListItem</link>
<link id="#lcl.comctrls.TListItems.Add">TListItems.Add</link>
</seealso>
</element>

<!-- private -->
<element name="TShellListItem.FFileInfo"/>

<!-- public -->
<element name="TShellListItem.isFolder">
<short>
Checks for the directory attribute in the file system information for the list 
item.
</short>
<descr>
<p>
The return value is <b>True</b> if the Attr member in FileInfo includes the 
faDirectory flag value.
</p>
</descr>
<version>
Added in LCL version 3.0.
</version>
<seealso>
<link id="TShellListItem.FileInfo"/>
<link id="TFileItem.Create"/>
<link id="#rtl.sysutils.FindFirst">FindFirst</link>
<link id="#rtl.sysutils.FindNext">FindNext</link>
<link id="#rtl.sysutils.TRawbyteSearchRec">TRawbyteSearchRec</link>
<link id="#rtl.sysutils.TUnicodeSearchRec">TUnicodeSearchRec</link>
</seealso>
</element>
<element name="TShellListItem.isFolder.Result">
<short>
Returns <b>True</b> if the list item represents a directory on the local file 
system.
</short>
</element>

<element name="TShellListItem.FileInfo">
<short>
File system information about the list item.
</short>
<descr>
<p>
<var>FileInfo</var> is a <var>TSearchRec</var> property which contains file 
system information about the list item. It is a record instance returned from 
the FindFirst or FindNext routines in the RTL, and contains the attributes for 
a file or folder on the local file system. FileInfo includes values like:
</p>
<ul>
<li>Timestamp</li>
<li>Size</li>
<li>Attributes</li>
<li>Excluded Attributes</li>
<li>Find Handle</li>
<li>File Mode (on UNIX-like platforms)</li>
<li>Find Data Structure (or symlink structure on UNIX-like platforms)</li>
</ul>
</descr>
<version>
Added in LCL version 3.0.
</version>
<seealso>
<link id="TCustomShellListView.DoAddItem"/>
<link id="TCustomShellListView.PopulateWithRoot"/>
<link id="TCustomShellTreeView.DoAddItem"/>
<link id="TCustomShellTreeView.PopulateTreeNodeWithFiles"/>
<link id="TAddItemEvent"/>
<link id="#rtl.sysutils.FindFirst">FindFirst</link>
<link id="#rtl.sysutils.FindNext">FindNext</link>
<link id="#rtl.sysutils.TRawbyteSearchRec">TRawbyteSearchRec</link>
<link id="#rtl.sysutils.TUnicodeSearchRec">TUnicodeSearchRec</link>
</seealso>
</element>

<element name="TCustomShellListView">
<short>
The base class that defines a list view control to display the files, 
directories and other objects (such as devices) from the local file system.
</short>
<descr>
<p>
<var>TCustomShellListView</var> is a <var>TCustomListView</var> descendant 
which defines a list view control for file system objects on the local file 
system. <var>TCustomShellListView</var> extends the ancestor class with 
properties, methods, and events needed to access and maintain items in the 
control including:
</p>
<ul>
<li>Mask</li>
<li>MaskCaseSensitivity</li>
<li>ObjectTypes</li>
<li>Root</li>
<li>ShellTreeView</li>
<li>Items</li>
<li>GetPathFromItem</li>
<li>OnAddItem</li>
<li>OnFileAdded</li>
</ul>
<p>
Application should not create instance of <var>TCustomShellListView</var>; 
use the <var>TShellListView</var> descendant which sets the scope for members 
in the class.
</p>
</descr>
<seealso>
<link id="TCustomShellListView.Mask"/>
<link id="TCustomShellListView.MaskCaseSensitivity"/>
<link id="TCustomShellListView.ObjectTypes"/>
<link id="TCustomShellListView.Root"/>
<link id="TCustomShellListView.ShellTreeView"/>
<link id="TCustomShellListView.Items"/>
<link id="TCustomShellListView.GetPathFromItem"/>
<link id="TCustomShellListView.OnAddItem"/>
<link id="TCustomShellListView.OnFileAdded"/>
<link id="TShellListView"/>
</seealso>
</element>

<element name="TCustomShellListView.FMask"/>
<element name="TCustomShellListView.FMaskCaseSensitivity"/>
<element name="TCustomShellListView.FObjectTypes"/>
<element name="TCustomShellListView.FRoot"/>
<element name="TCustomShellListView.FShellTreeView"/>
<element name="TCustomShellListView.FUseBuiltInIcons"/>
<element name="TCustomShellListView.FLockUpdate"/>
<element name="TCustomShellListView.FOnAddItem"/>
<element name="TCustomShellListView.FOnSortCompare"/>
<element name="TCustomShellListView.FOnFileAdded"/>

<element name="TCustomShellListView.SetMask">
<short>Sets the value for the Mask property.</short>
<descr></descr>
<seealso>
<link id="TCustomShellListView.Mask"/>
</seealso>
</element>
<element name="TCustomShellListView.SetMask.AValue">
<short>New value for the property.</short>
</element>

<element name="TCustomShellListView.SetMaskCaseSensitivity">
<short>Sets the value for the MaskCaseSensitivity property.</short>
<descr></descr>
<seealso>
<link id="TCustomShellListView.MaskCaseSensitivity"/>
</seealso>
</element>
<element name="TCustomShellListView.SetMaskCaseSensitivity.AValue">
<short>New value for the property.</short>
</element>

<element name="TCustomShellListView.SetShellTreeView">
<short>Sets the value for the ShellTreeView property.</short>
<descr></descr>
<seealso>
<link id="TCustomShellListView.ShellTreeView"/>
</seealso>
</element>
<element name="TCustomShellListView.SetShellTreeView.Value">
<short>New value for the property.</short>
</element>

<element name="TCustomShellListView.SetRoot">
<short>Sets the value for the Root property.</short>
<descr>
<p>
Calls <var>Clear</var> to remove list items in the control. Calls 
<var>PopulateWithRoot</var> to load file system entries in the new root 
directory. Raises an <var>EInvalidPath</var> exception at run-time if Value 
contains an invalid path name. Does <b>not</b> raise an exception at 
design-time to prevent crashing the IDE.
</p>
</descr>
<errors>
Raises an EInvalidPath exception at run-time if Value contains an invalid 
path name.
</errors>
<seealso>
<link id="TCustomShellListView.Root"/>
</seealso>
</element>
<element name="TCustomShellListView.SetRoot.Value">
<short>New value for the property.</short>
</element>

<element name="TCustomShellListView.SetObjectTypes">
<short>
Sets the value for the ObjectTypes property.
</short>
<descr>
<p>
Forces the Items property to be cleared and reloaded. Selected is restored if 
it was assigned on entry.
</p>
</descr>
<seealso/>
</element>
<element name="TCustomShellListView.SetObjectTypes.Value">
<short>
New value for the ObjectTypes property.
</short>
</element>

<element name="TCustomShellListView.WSRegisterClass">
<short>
Registers an association between the class type and its widgetset class.
</short>
<descr>
<p>
<var>WSRegisterClass</var> is an overridden class method in 
<var>TCustomShellListView</var>. It registers properties that are ignored in 
the class instance during LCL component streaming, including:
</p>
<ul>
<li>ItemIndex (Used in older LCL versions)</li>
<li>BevelKind (Provided for Delphi compatibility)</li>
<li>TListItem.OverlayIndex (Provided for Delphi compatibility)</li>
</ul>
<p>
It calls the inherited method, and registers the companion widgetset class 
instance.
</p>
</descr>
<seealso>
<link id="#lcl.controls.TWinControl.WSRegisterClass">TWinControl.WSRegisterClass</link>
</seealso>
</element>

<element name="TCustomShellListView.AdjustColWidths">
<short>
Adjusts the width of columns in the list view according to the overall width 
for the control.
</short>
<descr>
<p>
AdjustColWidths is a method used to adjust the width of columns according to 
the overall width for the control. It ensures that the columns are 
proportionately sized in the control layout.
</p>
<p>
No actions are performed in the method when the control has fewer than three 
(3) columns, or when AutoSizeColumns is <b>False</b> and an explicit value 
has been assigned to the first column in the control.
</p>
<p>
An arbitrary width of 400 pixels is used to determine the adjusted width for 
each of the columns.
</p>
<dl>
<dt>Width &lt; 400 pixels</dt>
<dd>
The initial column is give 50% of the overall client width, and the second 
column is given 25% of the overall client width.The third column is given the 
remaining client area for the control.
</dd>
<dt>Width &gt;= 400 pixels</dt>
<dd>
The initial column is give 70% of the overall width, and the second column is 
given 15% of the overall width. The third column is given the remaining 
client area for the control, or 0 when no space is available.
</dd>
</dl>
<p>
If the control has more than three columns, the widths for the remaining 
columns are not altered.
</p>
<p>
AdjustColWidths calls BeginUpdate prior to updating the column widths, and 
calls EndUpdate when column layout has been updated.
</p>
<p>
AdjustColWidths is called from the Create constructor, from the DoOnResize 
method, and when a new value is assigned to AutoSizeColumns property.
</p>
</descr>
<seealso>
<link id="TCustomShellListView.AutoSizeColumns"/>
<link id="TCustomShellListView.Create"/>
<link id="TCustomShellListView.DoOnResize"/>
<link id="#lcl.controls.TControl.ClientWidth">TControl.ClientWidth</link>
<link id="#lcl.comctrls.TCustomListVIew.Columns">TCustomListView.Columns</link>
</seealso>
</element>

<element name="TCustomShellListView.CreateHandle">
<short>
Creates the handle for the control and populates the Items property.
</short>
<descr>
<p>
<var>CreateHandle</var> is an overridden method in 
<var>TCustomShellListView</var>. It calls the inherited method on entry to 
allocate the handle for the windowed control with creation parameters and 
window flags as needed. An internal flag is checked to determine if the 
control is waiting for handle creation to finish loading the values in Items. 
When set, PopulateWithRoot is called to load the file system entries in Items 
and the flag is cleared.
</p>
<p>
CreateHandle is called from methods in the ancestor class when HandleNeeded 
is called for the class instance or its Parent.
</p>
</descr>
<seealso>
<link id="TCustomShellListView.Items"/>
<link id="TCustomShellListView.PopulateWithRoot"/>
<link id="TCustomShellListView.Root"/>
<link id="#lcl.controls.TWinControl.CreateHandle">TWinControl.CreateHandle</link>
<link id="#lcl.controls.TWinControl.HandleNeeded">TWinControl.HandleNeeded</link>
<link id="#lcl.controls.TWinControl.HandleAllocated">TWinControl.HandleAllocated</link>
</seealso>
</element>

<element name="TCustomShellListView.CreateListItem">
<short>
Create a new entry added to the Items for the shell control.
</short>
<descr>
<p>
<var>CreateListItem</var> is an overridden TListItem function in 
TCustomShellListView. It ensures that the TShellListItem class type is used 
for new Items added to the shell control. If an OnCreateItemClass event 
handler has been assigned, the inherited method in TCustomListView is called 
to confirm/override the item class used and to create the new instance added 
to Items.
</p>
<p>
The return value contains the new TListItem (or descendent) class instance 
created for the list item in the method.
</p>
</descr>
<version>
Added in LCL version 3.0.
</version>
<seealso>
<link id="#lcl.comctrls.TCustomListView.CreatelistItem">TCustomListView.CreatelistItem</link>
<link id="#lcl.comctrls.TListItem">TListItem</link>
<link id="#lcl.comctrls.TListItems.Add">TListItems.Add</link>
</seealso>
</element>

<element name="TCustomShellListView.PopulateWithRoot">
<short>
Fills the list view with file system information for the directory in Root.
</short>
<descr>
<p>
<var>PopulateWithRoot</var> is a procedure used to fill the <var>Items</var> 
property with file system entries for the directory specified in 
<var>Root</var>.
</p>
<p>
No actions are performed in the method at design-time, or when Root contains 
an empty string (<b>''</b>). In addition, the actions may be delayed if the 
Handle for control has not been allocated. An internal flag is set to 
indicate the condition, and PopulateWithRoot will be called again when the 
Handle is created in CreateHandle.
</p>
<p>
PopulateWithRoot calls the GetFilesInDirectory helper routine in the 
implementation section to get a list of file system items for the path which 
match the Mask and ObjectTypes specified for the control. Each of the files in 
the list are passed to DoAddItem / OnAddItem to determine if they can be added 
to the Items property.
</p>
<p>
The add method in Items is called to create the list items which represent 
each of the files or directories. If a list item is a TShellListItem class 
type, its FileInfo property is updated with the file information from the 
TFileItem created in the GetFilesInDirectory helper.
</p>
<p>
The Caption is used to store the file or directory name in the list item. The 
Data property in the list item is used to store a pointer to the file size. 
Values are added to SubItems in the list item to store the string 
representation for the file size, and the file extension.
</p>
<p>
When UseBuiltInIcons is set to <b>True</b>, the GetBuiltInImageIndex method 
is called to get the ImageIndex for the built-in icon on a list item. This 
action is performed using the path to the current file name when LargeImages 
and/or SmallImages have not been assigned. The value in ViewStyle determines 
the image size requested. When ViewStyle is <var>vsIcon</var>, LargeImages is 
checked (when assigned). Otherwise, SmallImages is checked (when assigned). 
If an image list exists in either LargeImages or SmallImages, the existing 
ImageIndex in the list item is used.
</p>
<p>
The OnFileAdded event handler is signalled (when assigned) for each new entry 
added to Items.
</p>
<p>
The Sort method is called prior to exit to order the Items in the control 
using the option specified in the FileSortType property.
</p>
</descr>
<version>
Updated in LCL version 3.0 to use TShellListItem as the item class for list 
items.
</version>
<seealso>
<link id="TCustomShellListView.Root"/>
<link id="TCustomShellListView.Items"/>
<link id="TCustomShellListView.Mask"/>
<link id="TCustomShellListView.ObjectTypes"/>
<link id="TCustomShellListView.UseBuiltInIcons"/>
<link id="TCustomShellTreeView.FileSortType"/>
<link id="TCustomShellListView.DoAddItem"/>
<link id="TCustomShellListView.OnAddItem"/>
<link id="TCustomShellListView.OnFileAdded"/>
<link id="TCustomShellListView.CreateHandle"/>
<link id="TShellListItem"/>
<link id="TAddItemEvent"/>
<link id="TCSLVFileAddedEvent"/>
</seealso>
</element>

<element name="TCustomShellListView.DoOnResize">
<short>Adjusts column widths when the control is resized.</short>
<descr>
<p>
Calls the inherited method, and calls AdjustColWidths to update the layout 
for Columns.
</p>
</descr>
<seealso>
<link id="TCustomShellListView.AdjustColWidths"/>
<link id="#lcl.controls.TControl.DoOnResize">TControl.DoOnResize</link>
</seealso>
</element>

<element name="TCustomShellListView.SetAutoSizeColumns">
<short>Sets the value for the AutoSizeColumns property.</short>
<descr/>
<seealso>
<link id="TCustomShellListView.AutoSizeColumns"/>
</seealso>
</element>
<element name="TCustomShellListView.SetAutoSizeColumns.Value">
<short>New value for the AutoSizeColumns property.</short>
</element>

<element name="TCustomShellListView.DoAddItem">
<short>
Signals the OnAddItem event handler when an entry is added to the Items in 
the control.
</short>
<descr></descr>
<seealso></seealso>
</element>
<element name="TCustomShellListView.DoAddItem.ABasePath">
<short>Base path for the list view.</short>
</element>
<element name="TCustomShellListView.DoAddItem.AFileInfo">
<short>TSearchRec with the information for the new entry.</short>
</element>
<element name="TCustomShellListView.DoAddItem.CanAdd">
<short>
Set the argument to <b>True</b> to allow the item to be added; set to 
<b>False</b> to prevent adding the item.
</short>
</element>

<element name="TCustomShellListView.GetBuiltinImageIndex">
<short>
Gets the index position for the built-in icon used for the specified path or 
file name.
</short>
<descr>
<p>
<var>GetBuiltinImageIndex</var> is an <var>Integer</var> function used to get 
the image index for a built-in icon provided by the operating system or 
platform.
</p>
<p>
The return value contains the ordinal position for the image used for the 
file name or path specified in <var>AFilename</var>. The return value is 
<b>-1</b> if an image could not be selected for the value in AFileName.
</p>
<p>
When <var>ALargeImage</var> is <b>True</b>, the index value refers to a large 
image as used in the vsIcon view style. When set to <b>False</b>, it refers 
to a small image as used in the other view styles.
</p>
<p>
GetBuiltinImageIndex calls the GetBuiltInImageIndex method in the widgetset 
class to get the return value for the method. The widgetset class handles 
storing the built-in image to the correct image list when the handle for the 
image list has not already been assigned.
</p>
<p>
GetBuiltinImageIndex is called from the <var>PopulateWithRoot</var> method 
when <var>UseBuiltInIcons</var> is set to <b>True</b>.
</p>
<remark>
In the current LCL version, GetBuiltinImageIndex is implemented for the 
Windows platform only.
</remark>
</descr>
<seealso>
<link id="TCustomShellListView.UseBuiltInIcons"/>
<link id="TCustomShellListView.PopulateWithRoot"/>
<link id="#lcl.comctrls.TCustomListView.LargeImages">TCustomListView.LargeImages</link>
<link id="#lcl.comctrls.TCustomListView.SmallImages">TCustomListView.SmallImages</link>
</seealso>
</element>
<element name="TCustomShellListView.GetBuiltinImageIndex.Result">
<short>Ordinal position for the built-in image.</short>
</element>
<element name="TCustomShellListView.GetBuiltinImageIndex.AFileName">
<short>File name or path used to find the associated image.</short>
</element>
<element name="TCustomShellListView.GetBuiltinImageIndex.ALargeImage">
<short><b>True</b> if the large image list is used for the image.</short>
</element>

<element name="TCustomShellListView.OnFileAdded">
<short>
Event handler signalled when a file is added to the Items in the control.
</short>
<descr>
<p>
<var>OnFileAdded</var> is a <var>TCSLVFileAddedEvent</var> property 
representing the event handler signalled when a file is added to the 
<var>Items</var> in the control. Applications must implement and assign an 
object procedure to the event handler to respond to the event notification. 
See <link id="TCSLVFileAddedEvent"/> for information about the arguments 
passed to the event handler.
</p>
<p>
<var>OnFileAdded</var> is signalled (when assigned) from the 
<var>PopulateWithRoot</var> method after calling <var>DoAddItem</var> and 
<var>OnAddItem</var>, and after the list item has been added to the 
<var>Items</var> property.
</p>
</descr>
<seealso>
<link id="TCSLVFileAddedEvent"/>
<link id="TCustomShellListView.PopulateWithRoot"/>
<link id="TCustomShellListView.DoAddItem"/>
<link id="TCustomShellListView.OnAddItem"/>
<link id="TCustomShellListView.Items"/>
</seealso>
</element>

<element name="TCustomShellListView.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the overridden constructor for the class instance. 
<var>Create</var> calls the inherited method using <var>AOwner</var> as the 
owner of the class instance. <var>Create</var> sets the default values for 
properties in the class instance, including:
</p>
<dl>
<dt>UseBuiltInIcons</dt>
<dd>True</dd>
<dt>ViewStyle</dt>
<dd>vsReport view style</dd>
<dt>ObjectTypes</dt>
<dd>[otNonFolders]</dd>
<dt>MaskCaseSensitivity</dt>
<dd>mcsPlatformDefault</dd>
<dt>Columns</dt>
<dd>Creates three columns for File Name, File Size, and File Type</dd>
</dl>
<p>
<var>Create</var> calls the <var>Resize</var> method to adjust the widths for 
the <var>Columns</var> defined in the method.
</p>
</descr>
<seealso>
<link id="TCustomShellListView.ObjectTypes"/>
<link id="#lcl.comctrls.TCustomListView.ViewStyle">TCustomListView.ViewStyle</link>
<link id="#lcl.comctrls.TCustomListView.Columns">TCustomListView.Columns</link>
</seealso>
</element>
<element name="TCustomShellListView.Create.AOwner">
<short>Owner for the class instance.</short>
</element>

<element name="TCustomShellListView.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. 
<var>Destroy</var> ensures that a control assigned to the 
<var>ShellTreeView</var> property is set to <b>Nil</b>. <var>Destroy</var> 
calls the inherited method.
</p>
</descr>
<seealso>
<link id="TCustomShellListView.ShellTreeView"/>
</seealso>
</element>

<element name="TCustomShellListView.GetPathFromItem">
<short>Gets the path on the local file system for the specified item.</short>
<descr>
<p>
<var>GetPathFromItem</var> is a <var>String</var> function used to get the 
path on the local file system for the list item specified in 
<var>ANode</var>. The return value contains the content from the 
<var>Root</var> property with a trailing path delimiter, joined with the 
<var>Caption</var> for the <var>TListItem</var> in <var>ANode</var>.
</p>
</descr>
<seealso>
<link id="TCustomShellListView.Root"/>
<link id="#lcl.comctrls.TListItem">TListItem</link>
</seealso>
</element>
<element name="TCustomShellListView.GetPathFromItem.Result">
<short>Complete path to the item.</short>
</element>
<element name="TCustomShellListView.GetPathFromItem.ANode">
<short>List item examined in the method.</short>
</element>

<element name="TCustomShellListView.UpdateView">
<short>
Reloads the contents for the list view control and restores the Selected item.
</short>
<descr>
<p>
<var>UpdateView</var> is a method used to repopulate the Items for the control. 
It ensures that the Selected entry is captured and restored (if assigned and 
still available) when the file system entries have been reloaded in the method.
</p>
<p>
UpdateView calls Clear to discard existing entries in Items, and 
PopulateWithRoot to recreate the entries starting at the path in Root. 
FindCaption is called to locate and restore the value in Selected.
</p>
<p>
UpdateView ensures that an associated ShellTreeView control calls its 
UpdateView method to synchronize the contents for the controls. Root is used as 
the starting directory for the update.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="TCustomShellListView.Root"/>
<link id="TCustomShellListView.PopulateWithRoot"/>
<link id="TCustomShellTreeView.UpdateView"/>
<link id="#lcl.comctrls.TCustomListView.Clear">TCustomListView.Clear</link>
<link id="#lcl.comctrls.TCustomListView.Selected">TCustomListView.Selected</link>
</seealso>
</element>

<element name="TCustomShellListView.AutoSizeColumns">
<short>
Indicates if columns in the control are automatically resized to fill the 
client display area.
</short>
<descr>
<p>
<var>AutoSizeColumns</var> is a <var>Boolean</var> property which indicates 
if the <var>Columns</var> for the control are automatically resized to fill 
the client display area for the control. When set to <b>True</b>, the widths 
for the Columns are adjusted so that they fill the client display area 
without the need for a horizontal scroll bar. The default value for the 
property is <b>True</b>.
</p>
<p>
Changing the value for the property to <b>True</b> causes the 
<var>Resize</var> method to be called.
</p>
<remark>
The Resize method will be called at least once, even when AutoSizeColumns is 
set to <b>False</b>, if an explicit width has not been set for the first 
column in the control.
</remark>
</descr>
<seealso>
<link id="#lcl.comctrls.TCustomListView.Columns">TCustomListView.Columns</link>
<link id="#lcl.comctrls.TListColumn">TListColumn</link>
</seealso>
</element>

<element name="TCustomShellListView.Mask">
<short>File mask used to select items displayed in the shell control.</short>
<descr>
<p>
<var>Mask</var> is a <var>String</var> property used to supply a mask which 
determines the file system objects displayed in the shell control. Mask can 
contain one or more mask values delimited by the Semicolon (<b>';'</b>) 
character. For example:
</p>
<code>*.exe; br*.com; c??.*</code>
<p>
Changing the value in Mask causes the <var>Clear</var> method to be called 
for the shell control. In addition, the <var>Items</var> property calls its 
<var>Clear</var> method to remove entries stored in the property. The 
<var>PopulateWithRoot</var> method is called to re-populate the shell control 
using the new mask value.
</p>
<p>
The value in Mask is passed as an argument to the  GetFilesInDirectory helper 
routine which gets the file system objects displayed in the List View control.
</p>
<p>
Use <var>MaskCaseSensitivity</var> to specify the case sensitivity option 
used when matching file masks in the shell control.
</p>
</descr>
<seealso>
<link id="TCustomShellListView.Items"/>
<link id="TCustomShellListView.PopulateWithRoot"/>
<link id="TCustomShellListView.MaskCaseSensitivity"/>
<link id="#lcl.comctrls.TCustomListView.Clear">TCustomListView.Clear</link>
</seealso>
</element>

<element name="TCustomShellListView.MaskCaseSensitivity">
<short>
Case Sensitivity option enabled for file masks in the shell control.
</short>
<descr>
<p>
<var>MaskCaseSensitivity</var> is a <var>TMaskCaseSensitivity</var> property 
which represents the case sensitivity option used for file masks in the shell 
control. The default value for the property is <var>mcsPlatformDefault</var>. 
See <var>TMaskCaseSensitivity</var> for a description of the enumeration 
values and their meanings.
</p>
<p>
Changing the value in <var>MaskCaseSensitivity</var> causes the shell control 
to re-populate its file Items using the <var>Mask</var> for the control.
</p>
</descr>
<seealso>
<link id="TMaskCaseSensitivity"/>
<link id="TCustomShellListView.Mask"/>
</seealso>
</element>

<element name="TCustomShellListView.ObjectTypes">
<short>
Controls which file system objects are visible on the list view control.
</short>
<descr>
<p>
<var>ObjectTypes</var> is a <var>TObjectTypes</var> property with the set of 
file system objects displayed by the list view control. It allows zero or more 
values from the TObjectType enumeration to be included in the property. The 
default value for the property is [otNonFolders] and allows file system objects 
other than directories to be displayed on the list view control.
</p>
<p>
See <link id="TObjectType">TObjectType</link> for the list of enumeration 
values and their meanings.
</p>
<p>
Changing the value for the property causes the contents of the list view 
control to be cleared and reloaded. If Selected has been assigned, it is 
restored following the update to the list view items.
</p>
</descr>
<seealso>
<link id="TCustomShellListView.PopulateWithRoot"/>
<link id="TCustomShellTreeView.ObjectTypes"/>
<link id="TObjectTypes"/>
<link id="#lcl.comctrls.TCustomListView.Clear">TCustomListView.Clear</link>
<link id="#lcl.comctrls.TCustomListView.Selected">TCustomListView.Selected</link>
</seealso>
</element>

<element name="TCustomShellListView.Root">
<short>
Indicates the initial directory path whose objects are displayed in the 
control.
</short>
<descr>
<p>
The most important property of the ShellListView, indicates the directory 
whose contents will be shown. This property is automatically managed if the 
property ShellTreeView is filled. If this property is empty, nothing will be 
shown.
</p>
</descr>
<seealso>
</seealso>
</element>

<element name="TCustomShellListView.ShellTreeView">
<short>
Used to connect the ShellListView to a ShellTreeView.
</short>
<descr>
<p>
<var>ShellTreeView</var> is a <var>TCustomShellTreeView</var> property used 
to connect the list view control to a shell tree view control. ShellTreeView 
provides access to the currently selected device, file, or directory in the 
local file system.
</p>
<p>
Changing the value in ShellTreeView causes the <var>Clear</var> method to be 
called to refresh the list view control. The path to the <var>Selected</var> 
item in the tree view is used as the <var>Root</var> property in the list 
view. The <var>PopulateWithRoot</var> method is called to fill the 
<var>Items</var> in the list view control.
</p>
</descr>
<seealso>
<link id="TCustomShellListView.Root"/>
<link id="TCustomShellListView.PopulateWithRoot"/>
<link id="TCustomShellTreeView.ShellListView"/>
<link id="TShellTreeView"/>
<link id="TCustomShellTreeView"/>
<link id="#lcl.comctrls.TCustomTreeView.Selected">TCustomTreeView.Selected</link>
<link id="#lcl.comctrls.TCustomListView.Clear">TCustomListView.Clear</link>
</seealso>
</element>

<element name="TCustomShellListView.UseBuiltInIcons">
<short>
Indicates if icons provided by the OS or platform are used for items in the 
list.
</short>
<descr>
<p>
<var>UseBuiltInIcons</var> is a <var>Boolean</var> property which indicates 
if icons provided by the OS or platform are used for the <var>Items</var> in 
the list view control. The default value for the property is <b>True</b>.
</p>
<p>
UseBuiltInIcons is used when the list view control is populated with the 
names for the file and/or directories on the local file system. When set to 
<b>True</b>, the <var>GetBuiltInImageIndex</var> method is called to get the 
image index for a <var>TListItem</var> stored in the <var>Items</var> 
property.
</p>
<p>
Set UseBuiltInIcons to <b>False</b> to use custom images provided in the 
<var>LargeImages</var> or <var>SmallImages</var> properties.
</p>
<remark>
UseBuiltInIcons and GetBuiltInImageIndex require support in the widgetset 
class to use system-provided icons. This support is currently implemented for 
the Windows platform only.
</remark>
</descr>
<seealso>
<link id="TCustomShellListView.Items"/>
<link id="TCustomShellListView.PopulateWithRoot"/>
<link id="TListItem.ImageIndex"/>
<link id="#lcl.comctrls.TCustomListView.LargeImages">TCustomListView.LargeImages</link>
<link id="#lcl.comctrls.TCustomListView.SmallImages">TCustomListView.SmallImages</link>
</seealso>
</element>

<element name="TCustomShellListView.OnAddItem">
<short>
Event handler signalled to determine if the specified file information can be 
added to the Items for the list view.
</short>
<descr>
<p>
<var>OnAddItem</var> is a <var>TAddItemEvent</var> property used to implement 
the event handler. It is signalled to determine if the specified file can be 
added to the <var>Items</var> for the list view.
</p>
<p>
Arguments passed to the event handler identify the base path and file 
information examined in the procedure. Use the <var>CanAdd</var> argument to 
indicate if the file information can be added in a calling routine. See <link 
id="TAddItemEvent"/> for more information about the event handler definition.
</p>
<p>
<var>OnAddItem</var> is signalled from the <var>DoAddItem</var> method (when 
assigned).
</p>
</descr>
<seealso>
<link id="TAddItemEvent"/>
<link id="TCustomShellListView.Items"/>
<link id="TCustomShellListView.DoAddItem"/>
<link id="TCustomShellListView.PopulateWithRoot"/>
</seealso>
</element>

<element name="TCustomShellListView.Items" link="#lcl.comctrls.TCustomListView.Items"/>

<element name="TShellListView">
<short>
Implements a list view control to display the files, directories and other 
objects (such as devices) on the local file system.
</short>
<descr>
<p>
<var>TShellListView</var> is a <var>TCustomShellListView</var> descendant 
which implements a list view control for file system objects on the local 
file system. <var>TShellListView</var> contains properties, methods, and 
events needed to access and maintain items in the control including:
</p>
<ul>
<li>Mask</li>
<li>MaskCaseSensitivity</li>
<li>ObjectTypes</li>
<li>Root</li>
<li>ShellTreeView</li>
<li>Items</li>
<li>GetPathFromItem</li>
<li>OnAddItem</li>
<li>OnFileAdded</li>
</ul>
</descr>
<seealso>
<link id="TCustomShellListView"/>
<link id="TCustomShellListView.Mask"/>
<link id="TCustomShellListView.MaskCaseSensitivity"/>
<link id="TCustomShellListView.ObjectTypes"/>
<link id="TCustomShellListView.Root"/>
<link id="TCustomShellListView.ShellTreeView"/>
<link id="TCustomShellListView.Items"/>
<link id="TCustomShellListView.GetPathFromItem"/>
<link id="TCustomShellListView.OnAddItem"/>
<link id="TCustomShellListView.OnFileAdded"/>
</seealso>
</element>

<element name="TShellListView.Columns" link="#lcl.comctrls.TCustomListView.Columns"/>
<element name="TShellListView.Align" link="#lcl.controls.TControl.Align"/>
<element name="TShellListView.AutoSizeColumns" link="#lcl.shellctrls.TCustomShellListView.AutoSizeColumns"/>
<element name="TShellListView.Anchors" link="#lcl.controls.TControl.Anchors"/>
<element name="TShellListView.BorderSpacing" link="#lcl.controls.TControl.BorderSpacing"/>
<element name="TShellListView.BorderStyle" link="#lcl.comctrls.TCustomListView.BorderStyle"/>
<element name="TShellListView.BorderWidth" link="#lcl.controls.TWinControl.BorderWidth"/>

<element name="TShellListView.Color">
<short>The background color for the control.</short>
<descr>
<p>
The default value for the properly is clWindow in TShellListView.
</p>
<p>
If Color is set to clDefault, it needs to be passed through GetDefaultColor 
to resolve clDefault to a TColor value. Convenience routines which obtain the 
color by resolving clDefault and ParentColor are also provided as 
TControl.GetColorResolvingParent and TControl.GetRGBColorResolvingParent.
</p>
</descr>
<seealso>
<link id="#lcl.controls.TControl.Color">TControl.Color</link>
</seealso>
</element>

<element name="TShellListView.Constraints" link="#lcl.controls.TControl.Constraints"/>
<element name="TShellListView.DragCursor" link="#lcl.controls.TControl.DragCursor"/>
<element name="TShellListView.DragMode" link="#lcl.controls.TControl.DragMode"/>
<element name="TShellListView.Enabled" link="#lcl.controls.TControl.Enabled"/>
<element name="TShellListView.Font" link="#lcl.controls.TControl.Font"/>
<element name="TShellListView.HideSelection" link="#lcl.comctrls.TCustomListView.HideSelection"/>
<element name="TShellListView.LargeImages" link="#lcl.comctrls.TCustomListView.LargeImages"/>
<element name="TShellListView.LargeImagesWidth" link="#lcl.comctrls.TCustomListView.LargeImagesWidth"/>
<element name="TShellListView.Mask" link="#lcl.shellctrls.TCustomShellListView.Mask"/>
<element name="TShellListView.MaskCaseSensitivity" link="#lcl.shellctrls.TCustomShellListView.MaskCaseSensitivity"/>
<element name="TShellListView.MultiSelect" link="#lcl.comctrls.TCustomListView.MultiSelect"/>

<element name="TShellListView.ParentColor">
<short>Uses the Color from the Parent control, when enabled.</short>
<descr>
<p>
ParentColor determines if the control should use the Color from the Parent 
control, when enabled. The default value for the property is <b>False</b> in 
TShellListView.
</p>
<p>
When this property is <b>True</b>, all changes to the Color of the parent 
will also be applied to the Color of the control, ensuring that they both 
contain same value. If the Color of the control is changed by the 
application, then ParentColor will be automatically set to <b>False</b>.
</p>
<p>
Using ParentColor when the Color value is clDefault can cause problems in 
resolving the actual color value. To obtain the Color property of a control 
while taking into account clDefault and ParentColor, use the 
GetColorResolvingParent method. This method might return a non-RGB color, but 
will never return clDefault. To obtain a purely RGB result use the 
GetRGBColorResolvingParent method.
</p>
</descr>
<seealso>
<link id="#lcl.controls.TControl.ParentColor">TControl.ParentColor</link>
</seealso>
</element>

<element name="TShellListView.ParentFont" link="#lcl.controls.TControl.ParentFont"/>
<element name="TShellListView.ParentShowHint" link="#lcl.controls.TControl.ParentShowHint"/>
<element name="TShellListView.PopupMenu" link="#lcl.controls.TControl.PopupMenu"/>

<element name="TShellListView.ReadOnly">
<short>
Disables editing of list items on the shell control when set to <b>True</b>.
</short>
<descr>
<p>
<var>ReadOnly</var> is a <var>Boolean</var> property used to enable or 
disable editing of captions for list items at run-time. When ReadOnly is set 
to <b>True</b>, the editor for the control cannot be activated using a mouse 
double Click or by pressing the F2 function key.
</p>
<p>
The default value for the property is <b>True</b>, and indicates that item 
editing is not allowed.
</p>
<p>
ReadOnly is one of the TListViewProperty values included in the 
TListViewProperties set type and exchanged with the widgetset class. The 
property value is read from and written to the TCustomTreeview widgetset 
class instance when its handle is valid. Changing the value for the property 
causes the widgetset class to be updated with the new value.
</p>
<p>
The ReadOnly property was changed to <b>True</b> because the shell list view 
does not automatically propagate changes in a list item to the file system. The 
previous behavior was confusing because the user was able to modify a list item 
but had to notice that the change was not persistent without additional code.
</p>
<p>
Applications using the shell controls only for selecting files and folders are 
not affected. In "file-manager" application types, however, the ReadOnly 
property must be changed explicitely to <b>False</b> so that the user can edit 
items/nodes again.
</p>
</descr>
<version>
Modified in LCL version 4.0 to set the default value for the property to 
<b>True</b>.
</version>
<seealso>
<link id="#lcl.comctrls.TCustomListView.ReadOnly"/>
<link id="TListViewProperties"/>
<link id="TListViewProperty"/>
</seealso>
</element>

<element name="TShellListView.RowSelect" link="#lcl.comctrls.TCustomListView.RowSelect"/>
<element name="TShellListView.ScrollBars" link="#lcl.comctrls.TCustomListView.ScrollBars"/>
<element name="TShellListView.ShowColumnHeaders" link="#lcl.comctrls.TCustomListView.ShowColumnHeaders"/>
<element name="TShellListView.ShowHint" link="#lcl.controls.TControl.ShowHint"/>
<element name="TShellListView.SmallImages" link="#lcl.comctrls.TCustomListView.SmallImages"/>
<element name="TShellListView.SmallImagesWidth" link="#lcl.comctrls.TCustomListView.SmallImagesWidth"/>
<element name="TShellListView.SortColumn" link="#lcl.comctrls.TCustomListView.SortColumn"/>
<element name="TShellListView.SortType" link="#lcl.comctrls.TCustomListView.SortType"/>
<element name="TShellListView.StateImages" link="#lcl.comctrls.TCustomListView.StateImages"/>
<element name="TShellListView.TabStop" link="#lcl.comctrls.TCustomListVIew.TabStop"/>
<element name="TShellListView.TabOrder" link="#lcl.controls.TWinControl.TabOrder"/>
<element name="TShellListView.ToolTips" link="#lcl.comctrls.TCustomListView.ToolTips"/>
<element name="TShellListView.Visible" link="#lcl.controls.TControl.Visible"/>
<element name="TShellListView.ViewStyle" link="#lcl.comctrls.TCustomListView.ViewStyle"/>
<element name="TShellListView.ObjectTypes" link="#lcl.shellctrls.TCustomShellListView.ObjectTypes"/>
<element name="TShellListView.Root" link="#lcl.shellctrls.TCustomShellListView.Root"/>
<element name="TShellListView.ShellTreeView" link="#lcl.shellctrls.TCustomShellListView.ShellTreeView"/>
<element name="TShellListView.OnChange" link="#lcl.comctrls.TCustomListView.OnChange"/>
<element name="TShellListView.OnClick" link="#lcl.controls.TControl.OnClick"/>
<element name="TShellListView.OnColumnClick" link="#lcl.comctrls.TCustomListView.OnColumnClick"/>
<element name="TShellListView.OnCompare" link="#lcl.comctrls.TCustomListView.OnCompare"/>
<element name="TShellListView.OnContextPopup" link="#lcl.controls.TControl.OnContextPopup"/>
<element name="TShellListView.OnDblClick" link="#lcl.controls.TControl.OnDblClick"/>
<element name="TShellListView.OnDeletion" link="#lcl.comctrls.TCustomListView.OnDeletion"/>
<element name="TShellListView.OnDragDrop" link="#lcl.controls.TControl.OnDragDrop"/>
<element name="TShellListView.OnDragOver" link="#lcl.controls.TControl.OnDragOver"/>
<element name="TShellListView.OnEdited" link="#lcl.comctrls.TCustomListView.OnEdited"/>
<element name="TShellListView.OnEditing" link="#lcl.comctrls.TCustomListView.OnEditing"/>
<element name="TShellListView.OnEndDrag" link="#lcl.controls.TControl.OnEndDrag"/>
<element name="TShellListView.OnKeyDown" link="#lcl.controls.TWinControl.OnKeyDown"/>
<element name="TShellListView.OnKeyPress" link="#lcl.controls.TWinControl.OnKeyPress"/>
<element name="TShellListView.OnKeyUp" link="#lcl.controls.TWinControl.OnKeyUp"/>
<element name="TShellListView.OnMouseDown" link="#lcl.controls.TControl.OnMouseDown"/>
<element name="TShellListView.OnMouseEnter" link="#lcl.controls.TControl.OnMouseEnter"/>
<element name="TShellListView.OnMouseLeave" link="#lcl.controls.TControl.OnMouseLeave"/>
<element name="TShellListView.OnMouseMove" link="#lcl.controls.TControl.OnMouseMove"/>
<element name="TShellListView.OnMouseUp" link="#lcl.controls.TControl.OnMouseUp"/>
<element name="TShellListView.OnMouseWheel" link="#lcl.controls.TControl.OnMouseWheel"/>
<element name="TShellListView.OnMouseWheelDown" link="#lcl.controls.TControl.OnMouseWheelDown"/>
<element name="TShellListView.OnMouseWheelUp" link="#lcl.controls.TControl.OnMouseWheelUp"/>
<element name="TShellListView.OnMouseWheelHorz" link="#lcl.controls.TControl.OnMouseWheelHorz"/>
<element name="TShellListView.OnMouseWheelLeft" link="#lcl.controls.TControl.OnMouseWheelLeft"/>
<element name="TShellListView.OnMouseWheelRight" link="#lcl.controls.TControl.OnMouseWheelRight"/>
<element name="TShellListView.OnResize" link="#lcl.controls.TControl.OnResize"/>
<element name="TShellListView.OnSelectItem" link="#lcl.comctrls.TCustomListView.OnSelectItem"/>
<element name="TShellListView.OnStartDrag" link="#lcl.controls.TControl.OnStartDrag"/>
<element name="TShellListView.OnUTF8KeyPress" link="#lcl.controls.TWinControl.OnUTF8KeyPress"/>
<element name="TShellListView.OnAddItem" link="#lcl.shellctrls.TCustomShellListView.OnAddItem"/>
<element name="TShellListView.OnFileAdded" link="#lcl.shellctrls.TCustomShellListView.OnFileAdded"/>

<element name="TShellTreeNode">
<short>Represents tree nodes in TCustomShellTreeView / TShellTreeView.</short>
<descr>
<p>
<var>TShellTreeNode</var> is a <var>TTreeNode</var> descendant which 
represents tree nodes in <var>TShellTreeView</var>. TShellTreeNode extends 
the ancestor class with properties and methods needed to work with files or 
directories on the local file system. It includes an internal 
<var>TSearchRec</var> instance for the file system object stored when the 
node is created by a Shell tree view control.
</p>
<p>
TShellTreeNode is the class type used to create new nodes in the 
<var>TCustomShellTreeView.CreateNode</var> method.
</p>
</descr>
<seealso>
<link id="TCustomShellTreeView.CreateNode"/>
</seealso>
</element>

<!-- private -->
<element name="TShellTreeNode.FBasePath"/>

<!-- protected -->
<element name="TShellTreeNode.FFileInfo">
<short>
Member used to store the TSearchRec instance with file or directory 
information for the tree node.
</short>
<seealso>
<link id="TShellTreeNode.IsDirectory"/>
<link id="TCustomShellTreeView.Root"/>
<link id="TCustomShellTreeView.PopulateTreeNodeWithFiles"/>
<link id="TCustomShellTreeView.PopulateWithBaseFiles"/>
<link id="TFileItem.FileInfo"/>
</seealso>
</element>

<element name="TShellTreeNode.SetBasePath">
<short>Sets the value in the BasePath property.</short>
<descr></descr>
<seealso>
<link id="TShellTreeNode.BasePath"/>
</seealso>
</element>
<element name="TShellTreeNode.SetBasePath.ABasePath">
<short>New value for the BasePath property.</short>
</element>

<!-- public -->
<element name="TShellTreeNode.ShortFilename">
<short>Gets the name for the item represented in the tree node.</short>
<descr>
<p>
<var>ShortFilename</var> is a <var>String</var> function used to get the 
short file name for the item represented in the tree node. The return value 
contains the value in the Text property for the tree node, and represents the 
name for the file system entry without drive or path information.
</p>
<p>
Use <var>FullFilename</var> to get the complete name which includes complete 
path information for the item represented in the tree node.
</p>
</descr>
<version>
Modified in LCL version 2.2.2 to remove direct access to the internal 
TSearchRec instance for the node when getting the property value.
</version>
<seealso>
<link id="TShellTreeNode.FullFilename"/>
<link id="#lcl.comctrls.TTreeNode.Text">TTreeNode.Text</link>
</seealso>
</element>
<element name="TShellTreeNode.ShortFilename.Result">
<short>
Name for the item represented in the tree node without path information.
</short>
</element>

<element name="TShellTreeNode.FullFilename">
<short>
Gets the full file name including path for the item represented in the tree 
node.
</short>
<descr>
<p>
<var>FullFilename</var> is a <var>String</var> function used to get the full 
path and name for the file system object represented by the tree node. When 
<var>BasePath</var> is not empty (a root node), it is included in the return 
value followed by a path delimiter and the value in <var>Text</var> 
(<var>ShortFilename</var>). For a root node, only the value in 
<var>Text</var> is used.
</p>
<p>
Trailing path delimiters are not included in the property value for directory 
nodes, and are not needed for file nodes. On Windows platforms (other than 
WinCE), device identifiers (like 'C:') are modified to include a trailing 
path delimiter ('C:\').
</p>
<p>
Use ShortFilename to get the name for the tree node without path information.
</p>
</descr>
<version>
Modified in LCL version 2.2.2 to remove direct access to the internal 
TSearchRec instance when getting the value for the property.
</version>
<seealso>
<link id="TShellTreeNode.BasePath"/>
<link id="TShellTreeNode.ShortFilename"/>
<link id="TShellTreeNode.IsDirectory"/>
<link id="#lcl.comctrls.TTreeNode.Text">TTreeNode.Text</link>
</seealso>
</element>
<element name="TShellTreeNode.FullFilename.Result">
<short>The full path and name for the file system object.</short>
</element>

<element name="TShellTreeNode.IsDirectory">
<short>
Indicates if the tree node is a directory on the local file system.
</short>
<descr>
<p>
<var>IsDirectory</var> is a <var>Boolean</var> function which indicates if 
the file system object for the tree node is a directory on the local file 
system. The return value is <b>True</b> when the file attributes in the 
internal <var>TSearchRec</var> instance for the tree node includes the 
<var>faDirectory</var> attribute.
</p>
<p>
Use <var>HasChildren</var> to determine if the shell tree node has child 
nodes representing files or sub-directories.
</p>
</descr>
<seealso>
<link id="TShellTreeNode.SetBasePath"/>
<link id="TCustomShellTreeView.PopulateTreeNodeWithFiles"/>
<link id="TCustomShellTreeView.PopulateWithBaseFiles"/>
<link id="TCustomShellListView.PopulateWithRoot"/>
<link id="#lcl.comctrls.TTreeNode.HasChildren">TTreeNode.HasChildren</link>
</seealso>
</element>
<element name="TShellTreeNode.IsDirectory.Result">
<short>
<b>True</b> when the tree node represents a directory on the local file 
system.
</short>
</element>

<element name="TShellTreeNode.BasePath">
<short>
Contains the base path to the file system object in the tree node.
</short>
<descr>
<p>
<var>BasePath</var> is a read-only <var>String</var> property which contains 
the base path on the local file system to the object in the tree node. It 
contains an empty string ('') when the file system object is located at the 
root of the tree.
</p>
<p>
The value for the property is assigned by calling <var>SetBasePath</var> when 
the tree node is created in TCustomShellTreeView / TShellTreeView methods.
</p>
<p>
Use <var>ShortFilename</var> to get the name for the tree node without path 
information.
</p>
</descr>
<seealso>
<link id="TShellTreeNode.SetBasePath"/>
<link id="TCustomShellTreeView.PopulateTreeNodeWithFiles"/>
<link id="TCustomShellTreeView.PopulateWithBaseFiles"/>
<link id="TCustomShellListView.PopulateWithRoot"/>
</seealso>
</element>

<element name="EShellCtrl">
<short>Exception raised for errors occurring in shell controls.</short>
<descr>
<var>EShellCtrl</var> is a <var>Exception</var> descendant raised when errors 
occur in shell controls.
</descr>
<seealso>
<link id="TCustomShellTreeView.CreateNode"/>
<link id="TCustomShellTreeView.DoSelectionChanged"/>
<link id="EInvalidPath"/>
</seealso>
</element>

<element name="EInvalidPath">
<short>Exception raised for an invalid path in shell controls.</short>
<descr>
<var>EInvalidPath</var> is a <var>EShellCtrl</var> descendant raised for an 
invalid path in shell controls.
</descr>
<seealso>
<link id="EShellCtrl"/>
<link id="TCustomShellTreeView.Root"/>
<link id="TCustomShellTreeView.FileSortType"/>
<link id="TCustomShellTreeView.ObjectTypes"/>
<link id="TCustomShellTreeView.Path"/>
<link id="TCustomShellListView.Root"/>
</seealso>
</element>

<element name="DbgS">
<short>
Provides strings values with details about classes used in shell controls for 
the debugger.
</short>
<descr>
<p>
<var>DbgS</var> is an overloaded <var>String</var> function used to get a 
string value with details about classes used in shell controls. The value is 
intended for use in the debugger. The overloaded variants provide support for 
the <var>TObjectTypes</var> and <var>TMaskCaseSensitivity</var> class types.
</p>
<p>
For <var>TObjectTypes</var>, a string is built to represents the set type 
using the format:
</p>
<code>[otFolders,otNonFolders,otHidden]</code>
<p>
For <var>TMaskCaseSensitivity</var>, a string version of the enumeration 
value is used as the return value. For example:
</p>
<code>
  'mcsPlatformDefault'
  'mcsCaseInsensitive'
  'mcsCaseSensitive'
</code>
</descr>
<seealso>
<link id="TObjectTypes"/>
<link id="TMaskCaseSensitivity"/>
</seealso>
</element>
<element name="DbgS.Result">
<short>Formatted values for the debugger.</short>
</element>
<element name="DbgS.OT">
<short>TObjectTypes examined in the routine.</short>
</element>
<element name="DbgS.CS">
<short>TMaskCaseSensitivity examined in the routine.</short>
</element>

<element name="Register">
<short>Registers components for use in the Lazarus IDE.</short>
<descr>
<p>
The following components are added to the Lazarus IDE component palette:
</p>
<p>
<b>Misc</b> Tab
</p>
<ul>
<li>TShellTreeView</li>
<li>TShellListView</li>
</ul>
</descr>
<seealso/>
</element>

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