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

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 include folders which represent virtual objects such as disks 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 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 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 an object procedure using the signature for the event to respond to the event notification.

Object 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 action can continue 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 tree. Applications should not create instances of TCustomShellTreeView; use the TShellTreeView class instead.

TCustomTreeView 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 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 for the tree node which used as the return value contains for the method.

CreateNode ensures that the tree node is a TShellTreeNode class instance; it may have been 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. 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 tree nodes for file system objects. 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 on item was added in the method.

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

PopulateTreeNodeWithFiles calls GetFilesInDir to get a list with TFileItem instances for all file system objects matching the ObjectTypes enabled in the shell control. Each of the TFileItem instances are passed to the DoAddItem method to determine if they can be added to the Items in the control. If the new node is for a directory, 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 control

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 using the value in Node as an argument.

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 on entry to the method.

TCustomTreeView.AutoExpand True when the tree node contains child nodes and be expanded Tree node examined in the method Defined for the Windows platform only. Draws the Shell Icon for the specified tree node

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

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

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 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 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: Design-time values in the Items property are populated when the Loaded method is called during component streaming.

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 platform

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 root value, returning the value of GetBasePath() of Root is empty or the Root property value otherwise Finds all files/directories directly inside a directory

Helper routine. Finds all files/directories directly inside a directory. Does not recurse subdirectories found the current directory.

AMask may contain multiple file masks separated by the Semicolon (';') character. Do not add a final delimiter after the last mask in the argument.

The base directory A list of masks used to obtain files which match the mask. The masks should be separated by a Semicolon (';') character. For example: "*.exe;*.txt" The kinds of objects to add to the list An existing TStringList object used to store the list of files found in the method Indicates the sort order for the items in the list Indicates if file names are compared using case sensitivity in the method Returns the path (including the file name) from the file system that a particular node represents 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 Used in the implementation of the SetObjectTypes method. Tree node with the initial path displayed in the shell control; Nil defaults to the root directory

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 internal GetShellIcon routine is used to get the icon drawn in the method. When UseBuiltinIcons is set to False, an icon is not drawn in the DrawBuiltinIcon method.

The DrawBuiltinIcon and GetBuiltinIconSize methods are defined for the Windows platform only; they requires use of the SHGetFileInfoW routine in the FPC ShellApi.pp unit. Indicates which objects should be shown in this control (for example if it should show files and directories or only directories) 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 specic object types. Changes to the Root or ObjectTypes properties in the list view are propogated 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 propogated to the associated list view control.

Indicates how the items should be sorted in the tree

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

Indicates the directory to start showing the list of items

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

Needs review. 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.

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.

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 TCustomShellTreeView. Applications must implement an object procedure using the event signature to respond to the notification.

TListItem Object generating the event notification List item for the event notification 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 Fills the list view with file system information for the root directory

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

No actions are performed in the method at design-time, or when Root contains an empty string ('').

PopulateWithRoot calls GetFilesInDir to get a list of file system items for the path which match the Mask and ObjectTypes specified for the control. Each of file information items in the list are passed to DoAddItem and OnAddItem to determine if they can be added to the Items in the control. 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.

Sets the size for Columns in the list view

Resize is a method used to set the size for Columns in the list view control. Resize calls the inherited method, and checks the Columns defined for the control. The Width property is used to determine the layout sizes applied to the columns for the control.

No actions (other than calling the inherited method) are performed if fewer than 3 (three) columns are defined for the control. This is the number of columns defined in the constructor for the vsReport ViewStyle.

Resize is used in the implementation of the Create constructor, and can be called to adjust the layout for the control when the Width property has been changed.

TCustomListView.ViewStyle TCustomListView.Columns TListColumns TViewStyle TControl.Width 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 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:

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 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 GetFilesInDir method for the ShellTreeView assigned in the 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.

Indicates which objects are visible in the control (files and/or directories, hidden files, etc.) 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 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

Represents tree nodes in 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. TShellTreeNode is the class type reference used to create new nodes in the TCustomShellTreeView.CreateNode method.

Sets the value in the BasePath property New value for the property Gets the short file 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. ShortFilename tries to get the file name from an internal TSearchRec for the tree node. If the file name is an empty string (''), the name in the search record is used as the return value. ShortFilename does not include path information in the return value.

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

Short file name for the item represented in the tree node 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. FullFilename includes the value in BasePath when it is available, and the name from the TSearchRec for the tree node. For directory and/or device nodes, the return value does not include a trailing path delimiter. 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.

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 the tree node is a directory on the local file system. The return value is True when the file attributes in the TSearchRec for the tree node includes the faDirectory attribute.

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

BasePath is a read-only String property which contains the path on the local file system to the object in the tree node. The value for the property is set when the tree node is created in TShellTreeView methods using the SetBasePath method in the class instance.

Exception raised for errors occuring 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