TCustomShellTreeView.Root property

Declaration

property Root: string read FRoot write SetRoot;

Description

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.

See also

• GetBasePath
• Items
• PopulateWithBaseFiles
• PopulateTreeNodeWithFiles
• ShellListView
• TShellListView
• Root
• TShellTreeNode
• TTreeNode.Expand