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.

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.

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.

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.

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 ('').

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.

CanExpand is an overridden Boolean function used to determine if the specified tree node can be expanded in the shell control. Node contains the TTreeNode examined 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 control, and removes all child tree nodes in Node. The child nodes are re-created using the PopulateTreeNodeWithFiles method. This ensures that the shell control reflects the current content in the local file system during execution of the method. 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.

DrawBuiltInIcon is an overridden TSize function used draw an icon in the tree using the Shell icon for the file 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 file. 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) are set to 0 (zero).

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) are set to 0 (zero).

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

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 initializes an internal member used to monitor the Root property for changes to its value. Create sets the value in ObjectTypes to display folders.

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

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

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)

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.

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.

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.

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.

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.

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.

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.

Changing the values in the property causes the Refresh method to be called to reload the Items for the control starting at the root directory. The currently Selected tree node is saved before the nodes are refreshed, and restored when Items has been reloaded. An exception raised when the path no longer exists in the tree nodes is handled and ignored in the method.

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.

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

Changing the value in FileSortType causes the Items property to be cleared, and the tree nodes to be re-created for the Path when Root has been assigned. If Root contains an empty string (''), the PopulateWithBaseFiles method is called. Otherwise, the Path is updated to force the control to be reloaded.

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 the internal GetFilesInDir procedure.

Root is a String property used to set the directory (or logical device) used to fill the list of items in the tree view control. Changing the value in Root causes the Items in the control to be re-populated.

No actions are performed in the method when a new value is set for the the Root property while the component is being loaded using the LCL streaming mechanism. The actions are performed when the Loaded method is called.

An empty string ('') indicates that the base path for the platform should be used to populate the tree view. This causes the PopulateWithBaseFiles method to be called to determine the Items displayed in the control.

Setting Root to an invalid path name causes an EInvalidPath exception to be raised at run-time. The error is ignored, and an exception is not raised, at design-time to prevent crashing the Lazarus IDE.

TShellTreeNode instances are created and added to the Items property using the expanded fully qualified path name in Root.

If ShellListView has been assigned for the control, its Root property is updated to match the new value for the property.

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 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 when setting Path 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

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.