Implements list box and combo-box controls used to select files on the local file system

filectrl.pp contains classes, types, and routines used to implement list box and combo-box controls used to select files on the local file system. It adds the following components to the Misc tab in the Lazarus IDE Component Palette:

TFileListBox
TFilterComboBox

Enumerated type with file and directory attributes used in TFileListBox

TFileAttr is an enumerated type with values that represent file and directory attributes for a selection in TFileListBox. Values from TFileAttr are stored in the TFileType set, which is used to implement the FileType property in TFileListBox.

Values in TFileAttr generally correspond to the file attributes used in TSearchRec from the FreePascal RTL (Run-Time Library). The differences are:

ftNormal: This represents a file lacking any other file attributes; represented in TSearchRec with the Integer value 0 (zero).
fsAnyFile: This value from TSearchRec is not represented in TFileAttr; it is a search mask and not an actual file attribute.

TSearchRec FindFirst FindNext FindClose File is read-only. File is hidden. For UNIX-like environments, this means that the file name starts with a '.' (Period) character. File is a system file. For UNIX-like environments, this means that it is a character, block, or FIFO file. Drive Volume label used on the Windows FAT (not FAT32) file system. Volume labels are not used on UNIX-like file systems. File attribute for a directory entry. File is ready to be archived. Not used for UNIX-like file systems. File has no other file attributes. Set type used to store file attributes

TFileType is a set type used to store zero (0) or more enumeration values from TFileAttr. TFileType is the type used to implement the FileType property in TFileListBox.

Implements the base class for a file selection list box

TCustomFileListBox is a TCustomListBox descendant which implements the base type for TFileListBox. TCustomFileListBox extends the ancestor with properties, methods, and events used to select a file or directory on the local file system in a list box control.

Use the Drive and Directory properties to specify the location on the local file system displayed in the list box. Please note that Drive is not used on UNIX-like file systems.

Use FileType to specify the files and/or directories which can be displayed in the control.

Use Mask to specify a file mask (with optional wildcards) used to select the files displayed in the control. Please note that wild cards may be implemented differently for some file systems. For example: '*' is the "all files" mask on UNIX-like file systems instead of "*.*".

Use the Sorted property to control the order of files and directories displayed in the control.

Use Items to access the file and/or directory names matching the FileType and Mask in the current Directory for the control. Directory names are enclosed in square brackets ([]).

Use FileName or ItemIndex to get or set the current selection in the control.

Assign an object procedure to the OnChange event handler to perform actions needed when a new item has been selected in the control.

Do not create instances of TCustomFileListBox. Use the TFileListBox descendant which sets the visibility of properties used in the class instance.

TCustomListBox Storage specifier for the Mask property True when a value other than the all directory entries mask ('*') has been assigned to the property Sets the value for the Directory property New value for the property Sets the value for the Drive property New value for the property Sets the value for the FileName property New value for the property Sets the value for the FileType property New value for the property Sets the value for the Mask property New value for the property Updates the value in FileName when a new item is selected in the list box TCustomListBox.Items Performs actions needed when the selected file has changed in the control

DoChangeFile is a method used to change the file selection in the control. It signals the OnChange event handler (when assigned).

Performs actions needed when the control has finished loading using the LCL component streaming mechanism

Loaded is an overridden method in TCustomFileListBox, and calls the inherited method on entry. Loaded calls the UpdateFileList method to load file and directory names into the Items property.

TComponent.Loaded Gets the ordinal position for the specified file name in Items

IndexOfFile is an Integer function used to get the ordinal position for the specified file name in the list of file names in the control. AFilename contains the file name to locate in the method.

IndexOfFile handles drive and volume entries that may be stored in Items by ignoring the square brackets ([]) used to surround values with the corresponding file attributes. The CompareFileNames routine from LazFileUtils is used to perform file name comparisons.

The return value is -1 when AFilename is not stored in the Items property.

TCustomListBox.Items CompareFileNames Ordinal position in Items for the specified file name, or -1 when not found File name to locate in Items Implements the handler for KeyUp events in the control

Overridden in TCustomFileListBox to update the selected file name prior to calling the inherited method.

TWinControl.KeyUp Virtual key code examined in the method Shift, Alt, or Ctrl modifier for the virtual key Sets the value for the ItemIndex property

SetItemIndex is an overridden method in TCustomFileListBox. Calls the inherited method on entry. Calls UpdateSelectedFileName to set the new value for the FileName property.

TCustomListBox.SetItemIndex TCustomListBox.ItemIndex New value for the property Constructor for the class instance

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create sets the default values for properties in the class instance, including:

Mask: Set to the AllDirectoryEntriesMask ('*')
FileType: Set to [ftNormal]
Directory: Set to the value from GetCurrentDirUTF8
Drive: Contains the value form ExtractFileDrive, or an empty string
MultiSelect: Set to False
Sorted: Set to True after files have been loaded in UpdateFileList

Create calls the UpdateFileList method to load the file and directory names for the current directory into the Items property.

TCustomListBox.Items TCustomListBox.MultiSelect TComponent.Create Owner for the class instance Destructor for the class instance

Destroy is the overridden destructor for the class instance, and calls the inherited destructor on entry.

TComponent.Destroy Performs actions needed when the mouse is clicked on the list box control

Click is an overridden method in TCustomFileListBox used to perform actions needed when the mouse is clicked in the list box control. Click ensures that the value in the FileName property is updated to reflect the selected file name in Items. ItemIndex contains the position for the current selection in the list box.

Click signals the OnChange event handler (when assigned) by calling the DoChangeFile method.

TCustomListBox.ItemIndex TCustomListBox.Items TCustomListBox.MultiSelect TControl.Click Loads the list of files and/or directories for the list box control

UpdateFileList is a method used to load the list of file and/or directory names in the Items for the control. No actions are performed in the method at design-time, or when the component is being loaded using the LCL streaming mechanism.

UpdateFileList calls Clear to remove any existing values in the Items property.

Values in FileType are used to construct file attributes needed for use with TSearchRec. The FindFirstUTF8 and FindNextUTF8 routines from LazFileUtils are used to find matching file or directory names in the Directory for the control. Each value returned for the TSearchRec is compared to the Mask and FileType defined in the control. Acceptable values are added to the Items property.

Please note that Directory names (included when FileType contains ftDirectory) are surrounded by square brackets ('[]') when added to the Items property.

The private UpdateSelectedFileName method is called to include path information in FileName for the selected item in the control.

UpdateFileList is called in the implementation of the Create and Loaded methods. It is also called when a new value is assigned to Drive, Directory, FileType, or Mask.

The Drive on which the file is located (applies to Windows systems)

Drive is a Char property which indicates the current drive letter for the Directory in the list box control. Drive is relevant for file systems which use drive designations (Windows).

The default value for the property is ' ' (space character). Changing the value in Drive causes the UpdateFileList method to be called to fill the list of Items displayed in the list box control.

Use Directory to specify the path on the local file system to the entries displayed in the control.

Setting a new value in Drive does not automatically alter the value in Directory. Always assign an explicit value to Directory when setting the value in Drive. In addition, setting a value in Directory which includes a drive designator like 'd:\config\' does not update the value in Drive. The only time Drive is automatically sync'd to the value in Directory is in the Create constructor. The Directory or Folder in which the file is located

Directory is a String property which contains the path on the local file system to the files or and/or directories displayed in the list box control. The initial value for Directory is assigned in the constructor and defaults to the current directory for the application.

The value in Directory is prepended to the value in Filename when the UpdateSelectedFileName method is called from methods like: Click, KeyUp, SetItemIndex, SetFileName.

Changing the value in Directory causes the UpdateFileList method to be called to reload the file and or directory names stored in the Items property.

Changing the value in Directory does not automatically update the value in Drive. If Directory includes a drive designator like 'D:\config\', the drive portion is not applied to the Drive property. In addition, setting a value in Drive does not update the value in Directory. The only time Drive and Directory are automatically sync'd is in the Create constructor. TCustomListBox.ItemIndex FileName - the name of the selected file

FileName is a String property which contains the file name for the currently selected item in the list box control. The value in FileName is updated when an item in the control is selected, or when a new value is assigned to the ItemIndex property.

Assigning a new value to the property causes the IndexOfFile method to be called to locate the specified value in the Items for the control. The private UpdateSelectedFileName method is called to ensure that the new file name includes the path information in Directory, and to signal the OnChange event handler (when assigned).

TCustomListBox.ItemIndex TCustomListBox.Items FileType - the type or attributes of the selected file

FileType is a TFileType set property which contains zero (0) or more values from the TFileAttr enumeration. FileType determines the file system entries displayed in the list box control. See TFileAttr for more information about the enumeration values and their meanings.

The default value for the property is [ftNormal].

Assigning a new set value for the property causes the UpdateFileList method to be called to reload the file system entries stored in the Items property.

TCustomListBox.Items Contains the mask for files selected for the control

Mask should be filled with one or more file masks separated by semi-colons. For example: '*.pdf;*.svg' will show all files with the extensions pdf and svg. The default value for the property is '*' which is the generic mask meaning any file or directory. Do not use the Windows specific mask '*.*' to attempt to show all files, which is the behavior from Delphi. In the LCL version of the control '*.*' will require the file name to have an extension.

Allowed wildcards include '*.*' which means zero or more characters, and '?' which means exactly 1 character with any value. Other characters represent themselves with one important detail: The file matching algorithm is not case sensitive. So if you set '*.PDF' in the mask, then 'PostScript.pdf' will also be shown, even on Linux which is a case sensitive file system.

This property has exactly the same rules and behavior as the Mask property in TFilterComboBox.

Changing the value in Mask causes the UpdateFileList method to be called to reload the file information for the current Directory in the Items property.

TCustomListBox.Items Event handler signalled when the selected file in the list box control is changed

OnChange is a TNotifyEvent property which contains the event handler signalled when the selected file for the control has been changed. This can occur when clicking on an entry in list box, when assigning a value directly to the FileName property, and when the list of file system entries in the control is reloaded.

OnChange is triggered (when assigned) from the DoChangeFile method. An application must implement and assign an object procedure to the handler to respond to the event notification.

Indicates if values in Items are sort in ascending alphanumeric order

Sorted is a public property in TCustomFileListBox, and indicates if values stored in Items are sorted in ascending alphanumeric order. The default value for the property is True.

TCustomListBox.Sorted TCustomListBox.Items Implements a file selection list box control

TFileListBox is a TCustomFileListBox descendant which implements a file selection list box control. It is used to select a file or directory on the local file system. TFileListBox sets the visibility for properties introduced in an ancestor class, and does not contains any new properties, methods, or events.

Use the Drive and Directory properties to specify the location on the local file system displayed in the list box. Please note that Drive is not used on UNIX-like file systems.

Use FileType to specify the files and/or directories which can be displayed in the control.

Use Mask to specify a file mask (with optional wildcards) used to select the files displayed in the control. Please note that wild cards may be implemented differently for some file systems. For example: '*' is the "all files" mask on UNIX-like file systems instead of '*.*'.

Use the Sorted property to control the order of files and directories displayed in the control.

Use the FileName property to get the current file selection in the control.

Assign an object procedure to the OnChange event handler to perform actions needed when a new item has been selected in the control.

Specifies a combo-box used to select a file filter

TCustomFilterComboBox is a TCustomComboBox descendant which defines a combo-box used to select files which match a selection filter.

Use the Filter property to define the filter names and expressions available in the drop-down for the combo-box. Only the filter name is displayed in the combo-box.

Use AutoComplete to enable or disable case-insensitive automatic text completion in the edit area for the combo-box. When set to True, the Filter which starts the the typed value is located and selected in the control. Please note that AutoComplete works when the text area is empty, or when the entire contents of the editable are are selected.

Use ItemIndex to get the ordinal position in Filter for the selected filter. Use the OnSelect event handler to perform actions needed when a new value is selected in the combo-box.

TCustomFilterComboBox includes a ShellListView property with the TShellListView instance used to display the list of files matching the selected filter. ShellListView is updated (when assigned) in the Select method to use the value in Mask in the list view control. Set the Root property in ShellListView to control the directory displayed in the control.

TCustomFilterComboBox sets the visibility for properties defined in an ancestor class, and does not introduce any new properties, methods, or events. Please note that some properties are not published for the control, so do they do not appear in the Object Inspector at design-time. For example: Mask.

TCustomComboBox TShellListView Sets the value for the Filter property New value for the property Sets the value for the ShellListView property New value for the property Performs actions needed when the selected item (ItemIndex) has been changed

Select is an overridden method in TCustomFilterComboBox. It ensures that the value in Mask is also applied to the ShellListView control (when assigned). This forces the ShellListView to reload the list of matching files displayed in the control.

Select calls the inherited method to signal the OnSelect event handler (when assigned).

TCustomComboBox.OnSelect Handles notification messages for sub-components in the control Component for the notification message Operation for the notification message Constructor for the class instance

Create is the overridden constructor for the class instance, and calls the inherited method on entry. Create sets the value for the Text property to an empty string ('').

TCustomComboBox.Create Owner of the class instance Destructor for the class instance

Destroy calls the inherited destructor.

Parses the file filter(s) in AFilter and stores them in AStrings

ConvertFilterToStrings is a class procedure used to parse the LCL filter string in AFilter, and store the individual filters in AStrings.

AFilter contains a value like: 'Text files (*.txt *.pas)|*.txt;*.pas|Binaries (*.exe)|*.exe'.

Values in AClearStrings, AAddDescription, and AAddFilter control the values stored in the AStrings.

AClearStrings indicates whether existing values in AStrings are cleared before adding values found in the method.

AAddDescription indicates if the descriptive text for file filter(s) are added to the string list.

AAddFilter indicates if the file mask portion of the filter is added to the string list.

When AAddDescription = True and AAddFilter = False, the following values would be stored in AStrings:

Text files (*.txt *.pas)
Binaries (*.exe)

Adapted from the converter initially created for QtWSDialogs.pas.

Values converted in the method TStrings instance where the filters are stored Indicates if existing values in AStrings are cleared True if the filter description is included in the converted values True if the filter mask expression is included in the converted values File mask for the selected filter in the control

Mask is a read-only String property with the file mask for the selected Filter in the control.

When reading the value for Mask, a temporary TStringList instance is used to convert the values in Filter into individual file masks by calling the ConvertFilterToStrings method. The value in ItemIndex determines the value returned for the property.

The property value is an empty string ('') if Filter is unassigned, or ItemIndex contains -1.

Mask can be used to provide the file mask for the selected filter to related controls.

Connects the control to a TShellListView instance

ShellListView is a TShellListView property which contains an optional list view control connected to the combo-box control. The files shown in the TShellListView will be limited to the Mask (or selected Filter) in the control.

When a shell list view control is assigned to the property, the value in Mask is copied into the Mask property for the list view control. The list view is added to the free notification list for the combo-box. ShellListView is updated (when assigned) in the Select method to use the current value in the Mask property.

TShellListView Implements a combo-box used to select a file filter

TFilterComboBox is a TCustomFilterComboBox descendant which implements a combo-box used to select files which match a selection filter. Use the Filter property to define the filter names and expressions available in the drop-down for the combo-box. Only the filter name is displayed in the combo-box.

Use AutoComplete to enable or disable case-insensitive automatic text completion in the edit area for the combo-box. When set to True, the Filter which starts the the typed value is located and selected in the control. Please note that AutoComplete works when the text area is empty, or the entire contents of the editable are are selected.

Use ItemIndex to get the ordinal position in Filter for the selected filter. Use the OnSelect event handler to perform actions needed when a new value is selected in the combo-box.

TFilterComboBox includes a ShellListView property with the TShellListView instance used to display the list of files matching the selected filter. ShellListView is updated (when assigned) in the Select method to use the value in Mask in the list view control. Set the Root property in ShellListView to control the directory displayed in the control.

TFilterComboBox sets the visibility for properties defined in an ancestor class, and does not introduce any new properties, methods, or events. Please note that Some properties are not published for the control, so do they do not appear in the Object Inspector at design-time. For example: Mask.

TShellListView

Please note that some themes (or styles) in Windows may use a fixed height for the combo-box.

Contains one or more file filters used in the combo-box

Filter is a String property which is published in TFilterComboBox. Filter contains the file filter(s) which are used in the Items property. Each filter value in the string contains a textual description and mask. For example:

'Text files (*.txt *.pas)|*.txt;*.pas|Binaries (*.exe)|*.exe'.

Setting a new value for the property causes ConvertFilterToStrings to be called to parse and store the filter descriptions in the Items property. Existing values in Items are cleared before storing the new filter values. The value in ItemIndex is set to 0 to select the initial filter in Items.

TCustomComboBox.Items TCustomComboBox.ItemIndex Returns a shortened version of a file name, so that it fits within the given MaxWidth

This function will return a shortened version of FileName, so that it fits within the width given in MaxWidth. It uses the Font currently assigned to the Canvas argument.

For example: 'C:\Documents and Settings\User\Application Data\Microsoft\Word\custom.dic' would be shortened to a value like: 'C:\...\Word\custom.dic'.

No actions are performed in the routine when path information is not included in FileName. Normalizes all path delimiters in the file name to the first path delimiter found in the argument.

When FileName is longer than the value in MaxWidth, directory names are dropped and replaced with a single '...' string value until the shortened file name fits within the specified width. Please note that this is a string with three (3) period ('.') characters, and NOT an Ellipsis (…)(#$2026) character.

File name shortened to the maximum length when needed File name examined and shortened in the routine Canvas with the font used to measure the file name Maximum width (in pixels) for the file name on the canvas Registers components in the unit for use in the Lazarus IDE

Register is a procedure used to register components in the unit for use in the Lazarus IDE. Register calls RegisterComponents to add the TFileListBox and TFilterComboBox components on the Misc tab in the Lazarus IDE.