Implements a control used to filter the items in an associated list box.

listfilteredit.pas contains classes and types used to implement the TListFilterEdit control, an edit control which filters values found in an associated list box.

listfilteredit.pas is part of the LazControls package.

Not used in the current implementation.
Implements an edit control used to filter items from an associated TListBox control.

TListFilterEdit is a TCustomControlFilterEdit descendant which implements an edit control used to filter an associated TListBox control. It consists of an edit control used to located and optionally select item(s) in the list box control, and a button used to clear the filter value entered in the edit control.

TListFilterEdit introduces properties and methods needed to access the items and selections in the associated list box control. Use FilteredListbox to specify the TListBox instance with the values filtered in the control. You can also use other TCustomListBox descendants in FilteredListbox; i. e. TCheckListBox. Use the Items property to access the list items for the filtered edit control. Use SelectionList to access the list of selected items in the list box control.

Overridden methods are provided to navigate between the values in the list box, store or remove selection(s) in for the control, and to apply the filter condition.

TCustomControlFilterEdit TCustomListBox TListBox TCheckListBox
The list box control with the items for the control.
Stores / restores the selections in the associated control.
Stores a flag that indicates a single selection is used for the control.
The original item values from the associated list box control.
Item values sorted for viewing in the associated list box.
Contains the checked items for an associated TCheckListBox control.
Implements the routine used to order list Items when SortData is enabled.

CompareFNs is an Integer function which implements the routine used to order the values in Items before they are stored in the sorted data for the control. CompareFNs calls the CompareFilenames routine in the lazfileutils.pas unit to perform a case-insensitive comparison for the specified caption values in Items and the internal sorted data. Contrary to the names for the arguments, the values are not file names.

The return value is 0 when SortData is not enabled, or when the captions contain the same value. A negative value indicates that AFilename1 comes before AFilename2 in the sort order. A Positive value indicates that AFilename1 comes after AFilename2 in the sort order.

CompareFNs is called from the SortAndFilter method and determines if a value (and its Object instance) in Items is relocated in the internal sorted data.

TCustomControlFilterEdit.SortData
Position for AFilename1 relative to AFilename2.
List item caption from Items compared in the method.
List item caption from the sorted data compared in the method.
Sets the value for the FilteredListbox property.
New value for the FilteredListbox property.
Handles a notification when a component is added to or removed from the control.

Notification is an overridden method in TListFilterEdit, and calls the inherited method on entry. It ensures that the FilteredListbox property is set to Nil when the component is removed from the class instance. It also sets the value for IdleConnected to False, and resets the internal update flag for the control.

TCustomControlFilterEdit.IdleConnected TControl.Notification
Component for the notification.
Operation for the component notification.
Changes the position in FilteredListbox and optionally selects the value.
New position in FilteredListbox.
True to add the list item to Selected items in the list box.
Moves to the next item in FilteredListbox and optionally selects the value.
True to add the list item to the Selected items in the list box.
Moves to the previous item in FilteredListbox and optionally selects the value.
True to add the list item to the Selected items in the list box.
Moves the position in FilteredListbox by one page towards the start of the list.
True to add the list item to the Selected items in the list box.
Moves the position in FilteredListbox by one page towards the end of the list.
True to add the list item to the Selected items in the list box.
Moves the position in FilteredListbox to the first entry in the list.
True to add the list item to the Selected items in the list box.
Moves the position in FilteredListbox to the last entry in the list.
True to add the list item to the Selected items in the list box.
Returns True if a Return key press was forwarded to the list box.

ReturnKeyHandled is an overridden method in TListFilterEdit. It implements the abstract virtual method defined in the ancestor class.

ReturnKeyHandled passes a VK_RETURN virtual key code to the list box in FilteredListbox when it has been received by the edit control. The OnKeyPress event handler in FilteredListbox is signalled (when assigned) to respond to the key press event.

No actions are performed in the method if FilteredListbox or its OnKeyPress event handler have not been assigned.

TCustomControlFilterEdit.EditKeyDown
True if a Return key press was forwarded to the list box.
Copies string and object values from Items to SortData, and sorts and filters the item values.

SortAndFilter is an overridden method in TListFilterEdit. It implements the abstract virtual method defined in the ancestor class. SortAndFilter is used to copy values found in Items to a list where the caption values are stored in sorted order. The existing list of sorted data is cleared on entry.

SortAndFilter iterates over the caption values in Items and calls DoFilterItem to determine the handler routine used filter each value in the list. If a caption matches the Filter value, the CompareFNs method is called to determine its order in the sorted list of data. SortAndFilter stores caption values and Object instances from Items to the sorted list.

SortAndFilter is called from the ApplyFilter method, and indirectly when the OnIdle handler applies a pending update for the control.

Use the OnFilterItemEx or OnFilterItem event handler to determine if a caption value is allowed for the Filter in the control. Use FilterOptions to control case-sensitivity and partial matches when the Filter value is applied. Use OnAfterFilter to perform actions needed when sorting and filtering are completed in the OnIdle handler for the control.

TCustomControlFilterEdit.Filter TCustomControlFilterEdit.SortData TCustomControlFilterEdit.DoFilterItem TCustomControlFilterEdit.DoDefaultFilterItem TCustomControlFilterEdit.OnFilterItemEx TStringList
Copies sorted list box data which matches the filter value to the FilteredListBox control.

ApplyFilterCore is an overridden method in TListFilterEdit used to update the list box in FilteredListbox to display the items that match the value in Filter. It implements the abstract virtual method defined in the ancestor class.

No actions are performed in the method if FilteredListbox has not been assigned.

ApplyFilterCore calls the Clear method in FilteredListbox to remove existing Items in the list box control. It iterates over the values in the sorted data to store both the caption and object instance to the Items property in FilteredListbox.

If FilteredListbox is a TCheckListBox instance, the Checked state for the list items is updated. The OnCheckItem event handler is signalled (when assigned) using the object instance for the list item. The Boolean value returned from the handler is applied as the Checked state for the corresponding list items. If OnCheckItem is not assigned, the Checked state is True when the internal map contains an entry with the caption for the list item.

The selected item in FilteredListBox is also updated to match the SelectedPart property for the control.

Updates to the Items in FilteredListBox are surrounded by calls to its BeginUpdate and EndUpdate methods. This is done to reduce screen flicker while the filter value is applied to list items.

If SimpleSelection is enabled, the MoveTo method is called to position and select the list item in FilteredListbox using the Text (when assigned) or the sorted data values.

TCustomControlFilterEdit.Text TCustomControlFilterEdit.OnCheckItem TCustomControlFilterEdit.Filter TCustomControlFilterEdit.ApplyFilterCore TCustomControlFilterEdit.SelectedPart
Gets the name for the resource used as the default glyph in the control.
TCustomEditButton.Glyph TCustomEditButton.LoadDefaultGlyph TCustomEditButton.GlyphChanged
Name of the resource with the default image used in Glyph.
Constructor for the class instance.

Create is the overridden constructor for the class instance. It calls the inherited method on entry to initialize the control and to set its default property values. Create allocates resources needed for the Items and SelectionList properties, as well as an internal member used to store sorted values in Items.

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

Destroy is the overridden destructor for the class instance. Destroy ensures that resources allocated to members in the class instance are freed, including:

- Items
- SelectionList
- The internal member for sorted list item data.
- The internal member for check box-style list items.

Destroy calls the inherited method prior to exit.

TCustomControlFilterEdit.Destroy
Removes the specified string value from the Items property.

RemoveItem calls the IndexOf method in Items to get the ordinal position for the value in AItem. When found, the Delete method in Items is called to remove the list item. If FilteredListbox is a TCheckListBox instance, the value is also removed from the internal string map used for the check box item values.

No actions are performed in the method if AItem is not found in the Items property.

TCheckListBox TStringList.IndexOf TStringList.Delete
Item located and removed in the method.
Notifies the control when the checked state for an item has been changed.

ItemWasClicked is significant when FilteredListbox contains a TCheckListBox instance. It is not used internally in the implementation for the control, but can be used to synchronize the control when a check box in the FilteredListbox is toggled.

An example of its usage can be found in the ide/editorfilemanager.pas unit in the Lazarus IDE.

TCheckListBox
String with the list item changed in an associated checked list box control.
Checked state for the list box item.
Stores the selected list item(s) in FilteredListbox to the SelectionList for the control.

StoreSelection is an overridden method in TListFilterEdit used to load the values in SelectionList from the Selected items in FilteredListbox. No actions are performed in the method if FilteredListbox has not been assigned.

StoreSelection calls the Clear method in SelectionList to remove any existing values. It iterates over the Selected property values in FilteredListbox, and calls the Add method in SelectionList to store the caption for the selected list items.

StoreSelection is called from the ApplyFilter method. It occurs after the list items in FilteredListbox have been sorted and filtered in the sorted data and Items properties for the control.

TCustomControlFilterEdit.Filter TCustomListBox.Selected
Restores values in SelectionList as the selected Items in FilteredListbox.
Indicates whether a single selection has been made using the FilteredListbox for the control.

The property value is updated in StoreSelection, and is set to True when SelectionList contains a single entry. The property value is updated before the items in SelectionList are checked.

It is used in RestoreSelection to prevent un-needed updates to check boxes in SelectionList.

It is also used in the ApplyFilterCore method when checked values in Items and SelectionList are located and displayed in the FilteredListbox control.

The list of selected list items for the FilteredListbox control.

SelectionList is a read-only TStringList property with the list of items that are marked as Selected in the associated list box control. Values in SelectionList are cleared and reloaded in the StoreSelection method, and occurs before the Filter value and sorting are applied to the control.

Values is SelectionList are re-applied to the FilteredListbox control in the RestoreSelection method, and occurs after the Filter value and sorting are applied to the control.

TCustomControlFilterEdit.Filter TCustomListBox.Selected
Contains the list items which are filtered and displayed for the associated list box control.

Items is a read-only TStringList property with the list items available to the filter edit control. It contains the original list item data loaded from the associated list box control, and is populated when the value is assigned to the FilteredListbox property. Its content is modified when the RemoveItem method is called to delete a list item with a given caption. Values in Items are copied into the sorted data when the value in Filter is applied to the control.

Use SelectionList to access the list item(s) which are marked as Selected in associated list box control.

TCustomControlFilterEdit.Filter TCustomListBox.Items
The list box associated with the filtered edit control.

FilteredListbox is a TCustomListBox property with the list box which provides the data for the filter edit control. TCustomListBox descendants can be assigned to the property; i. e. TCheckListBox.

The Items and Selected properties in the list box instance are used to populate the Items, sorted data, and SelectionList properties in the control. FilteredListbox is also used to display the results after the Filter is applied to the Items in the edit control. The original data in FilteredListBox is preserved internally while a Filter and/or Selections are active, and restored when these items are cleared.

Assigning a new value to the property causes the Filter and Items properties for the control to be updated when AValue is not Nil. The inherited InternalSetFilter method is called to apply the value in Text to the Filter and Items for the control. Button is disabled when the new text value is an empty string ('').

The updated results from the filtered list box are stored internally and used in the SelectionList for the control. If the new list box in AValue is derived from TCustomCheckListBox, the internal map used for checked items is created.

TCustomControlFilterEdit.Filter TCustomControlFilterEdit.InternalSetFilter TCustomControlFilterEdit.Text TCustomListBox TListBox TCheckListBox