Contains controls which display files and directories.

shellctrls.pas 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:

Misc Tab

TShellTreeView
TShellListView

ShellCtrls.pas is part of the Lazarus Component Library (LCL).

Indicates which objects should be visible in a Shell control.

TObjectType 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 TObjectTypes set type.

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. Indicates that non-folder objects should be shown, which are usually files. Hidden files will be shown if otHidden is also present. Indicates that hidden objects should be shown. This value is meaningful when used along with one of the other values. Set type with values that indicate the visible objects in a Shell control. Represents sorting options for the items in a shell control.

TFileSortType 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 TCustomShellTreeView.FileSortType property.

No special sorting is done; items will appear in the order provided by the file system. Items are sorted alphabetically with folders and files mixed. Items are sorted alphabetically with folders placed at the beginning of the list. 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. Represents case sensitivity options for file masks.

TMaskCaseSensitivity 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 MaskCaseSensitivity property in TCustomShellListView. It is also passed as an argument to methods in TCustomShellTreeView.

File masks used the default for the platform or OS. File masks are case insensitive. File masks are case sensitive. Indicates actions performed for child nodes when a shell tree node is expanded or collapsed.

TExpandCollapseMode 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.

Added in LCL version 3.0. Clear existing children before expanding. Do not clear children of previously expanded tree nodes when they are collapsed. Clear children when a node is collapsed. Provides information about a file or directory on the local file system for use in file sort comparison routines.

TFileItem 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.

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.

Modified in LCL version 3.0. It was moved from the implementation section to the interface section, and used to implement TFileItemCompareEvent routines. True when the item represents a folder on the local file system.

isFolder is a Boolean 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.

TSearchRec True when the file item represents a folder on the local file system. Constructor for the class instance.

Create 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.

TSearchRec instance with the directory information for the file item. Contains the path on the local file system where the file item is stored. Path to the directory where the file item is stored on the local file system.

BasePath is assigned in the Create constructor using the value passed in the ABasePath argument.

TSearchRec instance with information about the file or directory in the item.

FileInfo is assigned in the Create constructor using the value passed in the DirInfo argument.

Implements a handler routine used to compare values in a custom file sort for TCustomShellTreeView.

TFileItemCompareEvent 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.

The return value is an Integer with the relative sort order for the compared values:

A negative value (<0): Indicates that Item1 occurs before Item2 in the sort order.
A positive value (>0): Indicates that Item1 occurs after Item2 in the sort order.
0 (zero): Indicates that Item1 and Item2 have the same value in the sort order.

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.

The following is an item compare function, as implemented by forum member d7_2_laz, used to order items with leading Underscore characters:


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;

Sort File Items by Date


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;

Sort File Items by Size


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;

First file item for the comparison routine. Second file item for the comparison routine. Integer with the relative sort order for the compared file items. Specifies an event handler signalled when an item is added to a shell control.

TAddItemEvent specifies an event handler signalled when an item is added to a shell control. TAddItemEvent is the type used to implement the OnAddItem event handler in TCustomShellListView and TCustomShellTreeView.

Applications must implement and assign an object procedure using the signature for the event to respond to the notification. The Sender argument must be cast to the correct class type to access properties and method in the control. Set the value in the CanAdd variable parameter to False to prevent the item from being added in the calling procedure.

Object (control) generating the event notification. Base path for the item added to the shell control. Search record with information for the item added to the shell control. True if the item can be added. The base class for a tree view control used to display files, directories and other objects (such as devices) from the local file system.

TCustomShellTreeView is a TCustomTreeView 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.

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 TShellTreeView class instead.

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. TCustomTreeView Member with the event handler for the OnSortCompare property. (Re-)creates the root node for the tree view using the specified path. Path to the root node for the tree view. TTreeNode instance for the new root node, with updated TShellTreeNode properties as well. Gets the value for the Path property. Value for the property. Sets the value for the FileSortType property. New value for the property. Sets the value for the ObjectTypes property. New value for the property. Sets the value for the OnSortCompare property. Added in LCL version 3.0. New value for the OnSortCompare property. Sets the value for the Path property. New value for the property. Sets the value for the Root property. New value for the property. Sets the value for the ShellListView property. New value for the property. Sets the value for the UseBuiltinIcons property. New value for the property. Performs actions needed to create a new tree node in the shell control.

DoCreateNodeClass is an overridden method used to perform actions needed to create a new tree node in the Items for the shell control. DoCreateNodeClass sets NewNodeClass to the TShellTreeNode class type used in TCustomShellTreeView. DoCreateNodeClass calls the inherited method using NewNodeClass as an argument.

Class reference used to create tree nodes in the shell control. Performs actions needed when LCL component streaming has been completed.

Loaded is an overridden procedure used to perform actions needed when LCL component streaming has been completed. In TCustomShellTreeView, 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, PopulateWithBaseFiles is called to load files in the shell control.

Creates a new tree node for the shell control.

CreateNode is an overridden method used to create an new TTreeNode instance for the shell control. CreateNode calls the inherited method to create the class instance used as the return value for the method.

CreateNode ensures that the tree node is a TShellTreeNode class instance; the class type can be overridden in the OnCreateNodeClass event handler. If the new tree node is not derived from TShellTreeNode, an EShellCtrl exception is raised to indicate the invalid node type.

Raises an EShellCtrl exception if the new tree node is not derived from TShellTreeNode. TTreeNodeClass TCustomTreeView.OnCreateNodeClass New tree node created in the method. Adds tree nodes for file system objects found starting at the specified node / path.

PopulateTreeNodeWithFiles is a Boolean function used to fill the Items property with the file system objects for a given tree node. ANode contains the initial tree node examined in the method. ANodePath contains the path on the local file system to the tree node in ANode. The return value is True if at least one node was added to Items in the method.

No actions are performed in the method at design-time, and the return value is set to False.

PopulateTreeNodeWithFiles fills a list with TFileItem instances for file system objects matching the ObjectTypes for the shell control. DoAddItem is called for each TFileItem instance, which signals the OnAddItem event handler (when assigned). The event handler is used to selectively filter file system objects added to the Items in the control. If the TAddItemEvent handler sets its CanAdd argument to False, the file system object is not added to Items.

On exit, Items contains the TShellTreeNode instances where ANode is the parent. If an entry is a directory which has sub-directories, its HasChildren property is set to True.

PopulateTreeNodeWithFiles is used in the implementation of the PopulateWithBaseFiles and CanExpand methods in TCustomShellTreeView.

Returns True if at least one item was added to the shell control. Initial tree node used when filling the Items for the shell control. Path to the initial tree node used in the method. Performs actions needed when a new item is selected in the shell control.

DoSelectionChanged 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 TCustomShellListView control assigned to ShellListView is synchronized to the current selection in the class.

No actions are performed in the method if values for either ShellListView or Selected have not been assigned (contain Nil).

Selected 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 Root property in ShellListView.

If Selected does not represent a directory, the path refers to a file name that must exist on the local file system. An EShellCtrl exception is raised if the selected item does not exist. If Selected has a parent tree node, its path is assigned to the Root property in ShellListView. If no parent is available, the Root property in ShellListView is set to an empty string ('').

Raises an EShellCtrl exception if Selected refers to a file name that no longer exists on the local file system. TCustomTreeView.Selected Performs actions needed to add a new tree node to the shell control.

DoAddItem is a procedure used to perform actions needed when a new tree node is added to the shell control. DoAddItem signals the OnAddItem event handler (when assigned) to examine and process the arguments passed to the method.

ABasePath contains the path on the local file system where the file system object exists.

AFileInfo is a TSearchRec instance with the details for the file system object.

CanAdd is a variable Boolean parameter used to indicate if the new tree node can be added to the shell control.

No actions are performed in the method when OnAddItem has not been assigned (contains Nil). Applications must implement and assign an object procedure to the event handler which responds to the event notification.

Base path for the new tree node. TSearchRec with information about the file system object. Indicates if the tree node can be added for the specified path. Determines if the specified tree node can be expanded in the shell tree view control.

CanExpand is an overridden Boolean 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.

Node contains the TTreeNode examined and updated in the method.

CanExpand calls the inherited method to signal the OnExpanding event handler (when assigned). No additional actions are performed if the inherited method returns False.

CanExpand temporarily disables the AutoExpand 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:

ecmRefreshedExpanding: Deletes existing child nodes and calls PopulateTreeNodeWithFiles to reload entries for the path in Node.
ecmKeepChildren: Keeps existing child nodes. Calls PopulateTreeNodeWithFiles if the existing child node count is 0 (zero).
ecmCollapseAndClear: Calls PopulateTreeNodeWithFiles to load files for the path in Node.

The value in AutoExpand is restored to its original value prior to exiting from the method.

The entire update process is done in a BeginUpdate / EndUpdate block to reduce the number of screen refreshes in the method.

TCustomTreeView.AutoExpand Modified in LCL version 3.0 to use ExpandCollapseMode to control actions performed for child nodes. True when the tree node can be expanded to display child nodes. Tree node examined in the method. Removes child nodes (if needed) when the specified tree node is collapsed.

Collapse is an overridden method in TCustomShellTreeView used to update the tree node specified in Node 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.

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.

Collapse calls the inherited method prior to exit to update scroll bars on the control and to signal the OnCollapsed event handler (when assigned).

No actions are performed in the method when ComponentState is set to csDestroying.

Collapse is called when a tree node has executed its Collapse method.

TCustomTreeView.Collapse TCustomTreeView.OnCollapsed TTreeNode.Collapse TTreeNode.HasChildren TTreeNode.DeleteChildren TComponent.ComponentState Added in LCL version 3.0. Tree node affected in the method. Draws the Shell Icon for the specified tree node.

DrawBuiltInIcon is an overridden TSize function used to draw an icon on the tree using the Shell icon for the file or folder name in ANode. It re-implements the method in the TCustomTreeView ancestor, and does not call the inherited method.

When UseBuiltinIcons is True, the internal GetShellIcon routine is called to get the icon used for the entry. The icon is drawn on the control Canvas using the rectangle in ARect. The icon is centered vertically in the specified rectangle.

The return value contains the dimensions for the icon as a TSize instance. When UseBuiltinIcons is False, the return value always contains a TSize instance with both the Width (CX) and Height (CY) set to 0 (zero). 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.

DrawBuiltInIcon is defined for the Windows platform only; it requires use of the SHGetFileInfoW routine in the FPC ShellApi.pp unit. TCustomTreeView.DrawBuiltinIcon TSize instance with the dimension for the icon. Tree node with the name for the file system entry. Rectangle where the icon is drawn. Checks whether the specified path is a valid file system object and type for the tree view control.

ExistsAndIsValid is a Boolean function used to determine whether a file system object at the path specified in APath can be displayed on the tree view control.

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.

The return value is False if both conditions are not satisfied. The return value is True if APath a valid file (or directory) on the local file system.

ExistsAndIsValid is used in the UpdateView method when the Path and expanded state for a Selected node are updated.

Added in LCL version 4.0. Returns True if the specified path exists and is valid for the object types displayed on the control. Path name examined in the method. Gets the size for a shell icon used in the control.

GetBuiltinIconSize is an overridden TSize 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 TCustomTreeView ancestor, and does not call the inherited method.

The return value is a TSize instance with the Width (CX) and Height (CY) for the shell icon.

When UseBuiltinIcons is True, 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.

When UseBuiltinIcons is False, the return value always contains a TSize instance with both the Width (CX) and Height (CY) set to 0 (zero). 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.

GetBuiltinIconSize is defined for the Windows platform only; it requires use of the SHGetFileInfoW routine in the FPC ShellApi.pp unit. TCustomTreeView.GetBuiltinIconSize TSize instance with the dimensions for the shell icon. Determines whether the specified tree view Node has child nodes.

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.

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.

When an event handler has not been assigned, the return value is set to True if the specified Node is a Directory on the local file system.

The return value is also True 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.

TCustomTreeView.NodeHasChildren TCustomTreeView.OnHasChildren True when the node is a directory or contains non-folder objects at the given path. Controls the actions performed when a tree node is expanded or collapsed on the control.

ExpandCollapseMode is a TExpandCollapseMode 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.

See TExpandCollapseMode for the other values allowed in the property, and the corresponding actions performed in the tree node.

ExpandCollapseMode is used in the CanExpand and Collapse methods.

Added in LCL version 3.0. TTreeNode.Collapse TTreeNode.Expand Constructor for the class instance.

Create is the constructor for the class instance. Create calls the inherited method using the value in AOwner as the owner for the class instance.

Create sets the default values for properties, including:

UseBuiltinIcons: Set to True top enable the built-in icons in the widgetset class.
PathDelimiter: Set to the platform-specific PathDelim from the SysUtils unit.
Options: Includes tvoReadOnly in the set to match the default value for the ReadOnly property.
ObjectTypes: Set to [otFolders] to display folders (but not files) in the tree view.

Create initializes internal members used to monitor the Root 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.

Please note: Values in the Items property are populated when the Loaded method is called during component streaming.

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. SysUtils.PathDelim Component that owns the class instance. Destructor for the class instance.

Destroy is the destructor for the class instance. Destroy ensures that the ShellListView is set to Nil prior to calling the inherited destructor.

Returns the initial path in the file system hierarchy for the tree structure in the control.

GetBasePath is a String 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:

Windows platforms (other than Windows CE): '' (empty string)
Windows CE: '\'
UNIX-like operating systems: '/'
Amiga: '' (empty string)

Returns the effective value for Root when an explicit value has not been assigned.

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.

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.

Fills a TStrings instance with file system objects which match the specified path and mask.

GetFilesInDir is a class method which can be called without an existing instance of a TCustomShellTreeView descendant. For example:


TShellTreeView.GetFilesInDir('/path/to/dir', '*.pas;*.pp', 
  [otNonFolders], AStringList, [fstAlphabet], mcsCaseSensitive);

It performs actions to gather directories and/or files as in the PopulateTreeNodeWithFiles method, but does not store the file system objects to the Items property.

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.

Use ABaseDir 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.

Use AMask 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.

Use AObjectTypes to specify the file system objects examined in the method. See TObjectType for the values allowed in the set type, and their meanings.

AResult is a TStrings 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 TFileItem 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.

Use AFileSortType to specify the sort order applied to the values stored in AResult. See TFileSortType for the values allowed in the argument, and their meanings.

Use ACaseSensitivity to specify whether case sensitivity is used when comparing values in AMask to select matching file system objects. See TMaskCaseSensitivity for the values allowed in the argument, and their meanings. The default value for the argument is mcsPlatformDefault in the implementation routine.

Modified in LCL version 3.0 to have public visibility. FindFirstUTF8 FindNextUTF8 FindCloseUTF8 TMaskList TSearchRec Base directory name used to resolve relative path references in AMask. One or more mask values used to select the matching file system objects returned in AResult. Specifies the file system object types examined and returned in AResult. TStrings instance where file system objects matching the specified criteria are stored and returned. Sort type/order applied to the file system objects in AResult. Indicates whether case sensitivity is used when file system objects are compared to the selection criteria. Returns the path (including the file name) for the file system object represented in the specified node.

GetPathFromNode casts the tree node in ANode to a TShellTreeNode type to access the file system-specific properties and methods for the node.

When IsDirectory returns True, 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.

An absolute path in the return value includes the root directory prepended to the value.

FilenameIsAbsolute Fully qualified path for the file system object represented in the node. Tree node with the path and file name for the node. Fills the tree view when the Root directory is empty. The implementation of PopulateWithBaseFiles is platform-specific.

For Windows platforms other than Windows CE, the tree view is filled with TShellTreeNode entries for the logical drive names found on the system. The drive information is retrieved using the GetLogicalDriveStrings routine in the Windows API.

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.

PopulateWithBaseFiles is called from the Loaded, SetRoot, and SetFileSortType methods when an empty string ('') is assigned to the Root property.

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.

Updates the tree view to display file system objects starting at the specified tree node.

Refresh is an overloaded method in TCustomShellTreeView. 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.

Refresh is called when a new value is assigned to the ObjectTypes property.

Tree node with the initial path displayed in the shell control; Nil defaults to the root directory. Reloads the nodes for tree view control and synchronizes an associated ShellListView control.

UpdateView 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.

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.

The Selected property provides the selected tree node on the control.

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.

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.

Added in LCL version 4.0. TCustomTreeView.TopItem TCustomTreeView.Selected TTreeNodes.BeginUpdate TTreeNodes.EndUpdate Path to the first tree node updated in the method. Root is used when omitted. Indicates if OS-provided icons are used for entries in the Shell control.

UseBuiltinIcons is a Boolean property which indicates if OS-provided icons are used for the file system entries in the Shell control.

The default value for the property is True. Setting a new value for the property causes the Invalidate method to be called to redraw the control.

UseBuiltinIcons is used in the DrawBuiltinIcon method, and controls whether the corresponding method is called in the widgetset class. When UseBuiltinIcons is set to False, an icon is not drawn in the DrawBuiltinIcon method.

Indicates the file system objects displayed using the control.

ObjectTypes is a TObjectTypes 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.

otFolders: Enables and displays folders (directories).
otNonFolders: Enables and displays files and other file system entries which are not a folder.
otHidden: Enables and displays hidden directories and/or files on the tree view control.

The default value for the property is [otFolders].

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.

TCustomTreeView.Selected TCustomTreeView.TopItem Connects this ShellTreeView to a ShellListView.

ShellListView is a TCustomShellListView property used to connect the tree view to a list view control.

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 Root or ObjectTypes properties in the list view are propagated to the associated tree view control.

In a similar fashion, changes to the Root property or the selected item in the tree view causes the changes to be propagated to the associated list view control.

Indicates the sort type used for items (tree nodes) on the tree view control.

FileSortType is a TFileSortType property used to indicate the sort order for tree nodes in the Items property. The default value for the property is fstNone, and indicates the default sort order is used for tree nodes. See TFileSortType for information about the enumeration values and their meanings.

Changing the value in FileSortType causes the Items 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.

No action other than setting the property value is performed in the method at design-time.

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.

Use the OnSortCompare event handler to implement the sort / compare routine needed when FileSortType is set to fstCustom.

The value in FileSortType is not used in PopulateWithBaseFiles on Windows platforms. The entries are logical drive letters processed in the order provided by the file system. Indicates the directory or path which is the top-level node in the tree view.

Root is a String 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.

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.

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.

Setting Root to an empty string ('') 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.

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.

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.

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.

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.

TTreeNode.Expand Path to the directory displayed in the shell control.

Path is a String property which represents the path on the local file system to the Selected tree node in the control.

Reading the value for the property calls the GetPathFromNode method to derive the value for the property using the Selected tree node. The full path for the TShellTreeNode 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.

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 Root.

An EInvalidPath exception is raised if Path is set to a value that is not valid, including:

The path does not exist on the local file system.
The path cannot be resolved as a directory located under the Root directory.
The path represents an entry not valid for the settings in ObjectTypes.

FilenameIsAbsolute Event handler signalled when an item (tree node) is added to the shell control.

OnAddItem is a TAddItemEvent property which contains the event handler signalled when an item (tree node) is added to the shell control. OnAddItem is signalled from the PopulateTreeNodeWithFiles 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.

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 False in the event handler to omit the file system object in Items.

Event handler signalled to compare file items in a custom sort routine.

OnSortCompare is a TFileItemCompareEvent 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.

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.

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:


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;

Sort File Items by Date


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;

Sort File Items by Size


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;

Added in LCL version 3.0. Contains the tree nodes used to represent the hierarchical tree structure for the tree view control.

Items is a TTreeNodes 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.

Methods which access or maintain the Items in TCustomShellTreeView always cast the node values to TShellTreeNode to access the file system-specific information.

In TCustomShellTreeView, Items is cleared and re-populated at run-time when a new value is assigned to the Root, FileSortType, or OnSortCompare properties.

TCustomTreeView.Items TCustomTreeView.OnCreateNodeClass Implements a tree view control to display the files, directories and other objects (such as devices) from the local file system.

TShellTreeView is a TCustomShellTreeView 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.

TShellTreeView sets the visibility for properties, methods, and events defined in the ancestor class.

Uses the Color from the Parent control, when enabled.

ParentColor determines if the control should use the Color from the Parent control, when enabled. The default value for the property is False in TShellTreeView.

When this property is True, 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 False.

TControl.ParentColor Indicates whether the text (or caption) for tree nodes can be edited in the shell control.

ReadOnly is a Boolean property which indicates whether the text for the TTreeNode instances in Items can be edited in the control. When ReadOnly is set to False, the BeginEditing method is not called when the F2 key is pressed, or when the Left mouse button is double clicked. The default value for the property is True.

The property value is True when tvoReadOnly has been included in the Options 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 False causes the EndEditing method to be called.

The ReadOnly property was changed to True 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.

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 False so that the user can edit items/nodes again.

Modified in LCL version 4.0 to set the default value for the property to True. Enables navigation using the Tab key.

The default value for the properly is True in TShellTreeView.

TWinControl.TabStop Tag value for the component.

Tag 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.

TComponent Specifies an event handler signalled when an item is added to TCustomShellListView.

TCSLVFileAddedEvent specifies the interface for an event handler signalled when a TListItem instance is added to TCustomShellListView. TCSLVFileAddedEvent is the type used to implement the OnAddItem property in TCustomShellListView.

Applications must implement and assign an object procedure using the event signature to respond to the notification. Sender must be cast to the correct class type to access properties and methods in the control for the notification. Or, use the ListView property in the Item argument.

TListItem Object (control) generating the event notification. List item for the event notification. Implements the class used for list items maintained in TShelllListView.

TShellListItem is a TListItem 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.

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.

Added in LCL version 3.0. TListItem TListItems.Add Checks for the directory attribute in the file system information for the list item.

The return value is True if the Attr member in FileInfo includes the faDirectory flag value.

Added in LCL version 3.0. FindFirst FindNext TRawbyteSearchRec TUnicodeSearchRec Returns True if the list item represents a directory on the local file system. File system information about the list item.

FileInfo is a TSearchRec 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:

Timestamp
Size
Attributes
Excluded Attributes
Find Handle
File Mode (on UNIX-like platforms)
Find Data Structure (or symlink structure on UNIX-like platforms)

Added in LCL version 3.0. FindFirst FindNext TRawbyteSearchRec TUnicodeSearchRec 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.

TCustomShellListView is a TCustomListView descendant which defines a list view control for file system objects on the local file system. TCustomShellListView extends the ancestor class with properties, methods, and events needed to access and maintain items in the control including:

Mask
MaskCaseSensitivity
ObjectTypes
Root
ShellTreeView
Items
GetPathFromItem
OnAddItem
OnFileAdded

Application should not create instance of TCustomShellListView; use the TShellListView descendant which sets the scope for members in the class.

Sets the value for the Mask property. New value for the property. Sets the value for the MaskCaseSensitivity property. New value for the property. Sets the value for the ShellTreeView property. New value for the property. Sets the value for the Root property.

Calls Clear to remove list items in the control. Calls PopulateWithRoot to load file system entries in the new root directory. Raises an EInvalidPath exception at run-time if Value contains an invalid path name. Does not raise an exception at design-time to prevent crashing the IDE.

Raises an EInvalidPath exception at run-time if Value contains an invalid path name. New value for the property. Sets the value for the ObjectTypes property.

Forces the Items property to be cleared and reloaded. Selected is restored if it was assigned on entry.

New value for the ObjectTypes property. Registers an association between the class type and its widgetset class.

WSRegisterClass is an overridden class method in TCustomShellListView. It registers properties that are ignored in the class instance during LCL component streaming, including:

ItemIndex (Used in older LCL versions)
BevelKind (Provided for Delphi compatibility)
TListItem.OverlayIndex (Provided for Delphi compatibility)

It calls the inherited method, and registers the companion widgetset class instance.

TWinControl.WSRegisterClass Adjusts the width of columns in the list view according to the overall width for the control.

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.

No actions are performed in the method when the control has fewer than three (3) columns, or when AutoSizeColumns is False and an explicit value has been assigned to the first column in the control.

An arbitrary width of 400 pixels is used to determine the adjusted width for each of the columns.

Width < 400 pixels: 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.
Width >= 400 pixels: 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.

If the control has more than three columns, the widths for the remaining columns are not altered.

AdjustColWidths calls BeginUpdate prior to updating the column widths, and calls EndUpdate when column layout has been updated.

AdjustColWidths is called from the Create constructor, from the DoOnResize method, and when a new value is assigned to AutoSizeColumns property.

TControl.ClientWidth TCustomListView.Columns Creates the handle for the control and populates the Items property.

CreateHandle is an overridden method in TCustomShellListView. 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.

CreateHandle is called from methods in the ancestor class when HandleNeeded is called for the class instance or its Parent.

TWinControl.CreateHandle TWinControl.HandleNeeded TWinControl.HandleAllocated Create a new entry added to the Items for the shell control.

CreateListItem 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.

The return value contains the new TListItem (or descendent) class instance created for the list item in the method.

Added in LCL version 3.0. TCustomListView.CreatelistItem TListItem TListItems.Add Fills the list view with file system information for the directory in Root.

PopulateWithRoot is a procedure used to fill the Items property with file system entries for the directory specified in Root.

No actions are performed in the method at design-time, or when Root contains an empty string (''). 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.

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.

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.

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.

When UseBuiltInIcons is set to True, 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 vsIcon, 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.

The OnFileAdded event handler is signalled (when assigned) for each new entry added to Items.

The Sort method is called prior to exit to order the Items in the control using the option specified in the FileSortType property.

Updated in LCL version 3.0 to use TShellListItem as the item class for list items. Adjusts column widths when the control is resized.

Calls the inherited method, and calls AdjustColWidths to update the layout for Columns.

TControl.DoOnResize Sets the value for the AutoSizeColumns property. New value for the AutoSizeColumns property. Signals the OnAddItem event handler when an entry is added to the Items in the control. Base path for the list view. TSearchRec with the information for the new entry. Set the argument to True to allow the item to be added; set to False to prevent adding the item. Gets the index position for the built-in icon used for the specified path or file name.

GetBuiltinImageIndex is an Integer function used to get the image index for a built-in icon provided by the operating system or platform.

The return value contains the ordinal position for the image used for the file name or path specified in AFilename. The return value is -1 if an image could not be selected for the value in AFileName.

When ALargeImage is True, the index value refers to a large image as used in the vsIcon view style. When set to False, it refers to a small image as used in the other view styles.

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.

GetBuiltinImageIndex is called from the PopulateWithRoot method when UseBuiltInIcons is set to True.

In the current LCL version, GetBuiltinImageIndex is implemented for the Windows platform only. TCustomListView.LargeImages TCustomListView.SmallImages Ordinal position for the built-in image. File name or path used to find the associated image. True if the large image list is used for the image. Event handler signalled when a file is added to the Items in the control.

OnFileAdded is a TCSLVFileAddedEvent property representing the event handler signalled when a file is added to the Items in the control. Applications must implement and assign an object procedure to the event handler to respond to the event notification. See for information about the arguments passed to the event handler.

OnFileAdded is signalled (when assigned) from the PopulateWithRoot method after calling DoAddItem and OnAddItem, and after the list item has been added to the Items property.

Constructor for the class instance.

Create is the overridden constructor for the class instance. Create calls the inherited method using AOwner as the owner of the class instance. Create sets the default values for properties in the class instance, including:

UseBuiltInIcons: True
ViewStyle: vsReport view style
ObjectTypes: [otNonFolders]
MaskCaseSensitivity: mcsPlatformDefault
Columns: Creates three columns for File Name, File Size, and File Type

Create calls the Resize method to adjust the widths for the Columns defined in the method.

TCustomListView.ViewStyle TCustomListView.Columns Owner for the class instance. Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy ensures that a control assigned to the ShellTreeView property is set to Nil. Destroy calls the inherited method.

Gets the path on the local file system for the specified item.

GetPathFromItem is a String function used to get the path on the local file system for the list item specified in ANode. The return value contains the content from the Root property with a trailing path delimiter, joined with the Caption for the TListItem in ANode.

TListItem Complete path to the item. List item examined in the method. Reloads the contents for the list view control and restores the Selected item.

UpdateView 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.

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.

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.

Added in LCL version 4.0. TCustomListView.Clear TCustomListView.Selected Indicates if columns in the control are automatically resized to fill the client display area.

AutoSizeColumns is a Boolean property which indicates if the Columns for the control are automatically resized to fill the client display area for the control. When set to True, 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 True.

Changing the value for the property to True causes the Resize method to be called.

The Resize method will be called at least once, even when AutoSizeColumns is set to False, if an explicit width has not been set for the first column in the control. TCustomListView.Columns TListColumn File mask used to select items displayed in the shell control.

Mask is a String 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 (';') character. For example:

*.exe; br*.com; c??.*

Changing the value in Mask causes the Clear method to be called for the shell control. In addition, the Items property calls its Clear method to remove entries stored in the property. The PopulateWithRoot method is called to re-populate the shell control using the new mask value.

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.

Use MaskCaseSensitivity to specify the case sensitivity option used when matching file masks in the shell control.

TCustomListView.Clear Case Sensitivity option enabled for file masks in the shell control.

MaskCaseSensitivity is a TMaskCaseSensitivity property which represents the case sensitivity option used for file masks in the shell control. The default value for the property is mcsPlatformDefault. See TMaskCaseSensitivity for a description of the enumeration values and their meanings.

Changing the value in MaskCaseSensitivity causes the shell control to re-populate its file Items using the Mask for the control.

Controls which file system objects are visible on the list view control.

ObjectTypes is a TObjectTypes 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.

See TObjectType for the list of enumeration values and their meanings.

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.

TCustomListView.Clear TCustomListView.Selected Indicates the initial directory path whose objects are displayed in the control.

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.

Used to connect the ShellListView to a ShellTreeView.

ShellTreeView is a TCustomShellTreeView 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.

Changing the value in ShellTreeView causes the Clear method to be called to refresh the list view control. The path to the Selected item in the tree view is used as the Root property in the list view. The PopulateWithRoot method is called to fill the Items in the list view control.

TCustomTreeView.Selected TCustomListView.Clear Indicates if icons provided by the OS or platform are used for items in the list.

UseBuiltInIcons is a Boolean property which indicates if icons provided by the OS or platform are used for the Items in the list view control. The default value for the property is True.

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 True, the GetBuiltInImageIndex method is called to get the image index for a TListItem stored in the Items property.

Set UseBuiltInIcons to False to use custom images provided in the LargeImages or SmallImages properties.

UseBuiltInIcons and GetBuiltInImageIndex require support in the widgetset class to use system-provided icons. This support is currently implemented for the Windows platform only. TCustomListView.LargeImages TCustomListView.SmallImages Event handler signalled to determine if the specified file information can be added to the Items for the list view.

OnAddItem is a TAddItemEvent property used to implement the event handler. It is signalled to determine if the specified file can be added to the Items for the list view.

Arguments passed to the event handler identify the base path and file information examined in the procedure. Use the CanAdd argument to indicate if the file information can be added in a calling routine. See for more information about the event handler definition.

OnAddItem is signalled from the DoAddItem method (when assigned).

Implements a list view control to display the files, directories and other objects (such as devices) on the local file system.

TShellListView is a TCustomShellListView descendant which implements a list view control for file system objects on the local file system. TShellListView contains properties, methods, and events needed to access and maintain items in the control including:

Mask
MaskCaseSensitivity
ObjectTypes
Root
ShellTreeView
Items
GetPathFromItem
OnAddItem
OnFileAdded

The background color for the control.

The default value for the properly is clWindow in TShellListView.

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.

TControl.Color Uses the Color from the Parent control, when enabled.

ParentColor determines if the control should use the Color from the Parent control, when enabled. The default value for the property is False in TShellListView.

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.

TControl.ParentColor Disables editing of list items on the shell control when set to True.

ReadOnly is a Boolean property used to enable or disable editing of captions for list items at run-time. When ReadOnly is set to True, the editor for the control cannot be activated using a mouse double Click or by pressing the F2 function key.

The default value for the property is True, and indicates that item editing is not allowed.

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.

The ReadOnly property was changed to True 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.

Modified in LCL version 4.0 to set the default value for the property to True. Represents tree nodes in TCustomShellTreeView / TShellTreeView.

TShellTreeNode is a TTreeNode descendant which represents tree nodes in TShellTreeView. 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 TSearchRec instance for the file system object stored when the node is created by a Shell tree view control.

TShellTreeNode is the class type used to create new nodes in the TCustomShellTreeView.CreateNode method.

Member used to store the TSearchRec instance with file or directory information for the tree node. Sets the value in the BasePath property. New value for the BasePath property. Gets the name for the item represented in the tree node.

ShortFilename is a String 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.

Use FullFilename to get the complete name which includes complete path information for the item represented in the tree node.

Modified in LCL version 2.2.2 to remove direct access to the internal TSearchRec instance for the node when getting the property value. TTreeNode.Text Name for the item represented in the tree node without path information. Gets the full file name including path for the item represented in the tree node.

FullFilename is a String function used to get the full path and name for the file system object represented by the tree node. When BasePath is not empty (a root node), it is included in the return value followed by a path delimiter and the value in Text (ShortFilename). For a root node, only the value in Text is used.

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:\').

Use ShortFilename to get the name for the tree node without path information.

Modified in LCL version 2.2.2 to remove direct access to the internal TSearchRec instance when getting the value for the property. TTreeNode.Text The full path and name for the file system object. Indicates if the tree node is a directory on the local file system.

IsDirectory is a Boolean function which indicates if the file system object for the tree node is a directory on the local file system. The return value is True when the file attributes in the internal TSearchRec instance for the tree node includes the faDirectory attribute.

Use HasChildren to determine if the shell tree node has child nodes representing files or sub-directories.

TTreeNode.HasChildren True when the tree node represents a directory on the local file system. Contains the base path to the file system object in the tree node.

BasePath is a read-only String 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.

The value for the property is assigned by calling SetBasePath when the tree node is created in TCustomShellTreeView / TShellTreeView methods.

Use ShortFilename to get the name for the tree node without path information.

Exception raised for errors occurring in shell controls. EShellCtrl is a Exception descendant raised when errors occur in shell controls. Exception raised for an invalid path in shell controls. EInvalidPath is a EShellCtrl descendant raised for an invalid path in shell controls. Provides strings values with details about classes used in shell controls for the debugger.

DbgS is an overloaded String 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 TObjectTypes and TMaskCaseSensitivity class types.

For TObjectTypes, a string is built to represents the set type using the format:

[otFolders,otNonFolders,otHidden]

For TMaskCaseSensitivity, a string version of the enumeration value is used as the return value. For example:


  'mcsPlatformDefault'
  'mcsCaseInsensitive'
  'mcsCaseSensitive'

Formatted values for the debugger. TObjectTypes examined in the routine. TMaskCaseSensitivity examined in the routine. Registers components for use in the Lazarus IDE.

The following components are added to the Lazarus IDE component palette:

Misc Tab

TShellTreeView
TShellListView