Implements a control used to filter an associated TTreeView control.

treefilteredit.pas contains classes and other types used to implement a control used to filter an associated TTreeView control. treefilteredit.pas is part of the LazControls package.

Specifies an event handler used to get the position of the image for a tree node.

TImageIndexEvent is an Integer object function type which specifies an event handler signalled to get the position for an image associated with a tree node in a tree view control. Arguments passed to the object method indicates the text for the tree node, it data, and its enabled state in the tree.

The return value contains the ordinal position for the image selected for a tree node. It is stored in both the ImageIndex and SelectedIndex properties for the TTreeNode instance.

TImageIndexEvent is the type used to implement the OnGetImageIndex event handler in the TTreeFilterEdit control. The event is signalled when TTreeFilterBranch sorts, filters and displays the tree nodes on its TTreeFilterEdit and TTreeView controls.

Ordinal position for the image selected for a tree node in the event handler routine.
Text for the tree node used in the event handler.
Object reference with the data for the tree node.
Returns True if the tree node is enabled.
Specifies an event handler signalled to determine if a tree node matches the Filter in a TTreeFilterEdit control.

TFilterNodeEvent is a Boolean object function which defines an event handler used to determine whether a tree node can be used in a TTreeFilterEdit control. TFilterNodeEvent is the type used to implement the OnFilterNode property in TTreeFilterEdit.

TFilterNodeEvent can be used to determine whether a specific tree node is visible (or matches a filter value) using criteria other than the text or data for the TTreeNode instance.

ItemNode is the TTreeNode instance examined in the handler, and provides access to its properties and methods.

Done is an output parameter which indicates whether the tree node was examined in the handler routine. Set Done to True if the node was used or examined in the handler. Set Done to False if the node was not / could not be handled in the routine.

Set the return value to indicate whether ItemNode matched the filter value and is visible in its filtered tree view control. Its value is significant when Done is set to True.

True if the specified tree node can be used for the Filter value.
Tree node examined in the handler routine.
True if the node was handled in the routine. False if the node was ignored in the handler. The return value is significant when Done is set to True.
Represents a branch for an existing tree node when a filter is used in "sub-branches" mode.
Constructor for the class instance.

Allocates resources for the Items property, and other internal members. Stores AOwner in the Owner property, and ARootNode to the internal member used in the class instance.

Filter edit control which owns the class instance.
Tree node which is the root for the brance, or Nil when all nodes are considered as top-level tree nodes.
Adds an entry in Items for a root node in a branch.

Text, a data reference, and an associated file name can be added for the node.

Text for the tree node data.
Object reference with the user-specified data for the tree node.
Full file path and name for a tree node used in a directory hierarchy.
Removes the specified tree node from the data for the class instance.

Removes the specified tree node from Items, the internal list for sorted data, and the items in the FilteredTreeview for the owner control.

Tree node deleted in the method.
Frees the specified tree node including its node object data.
Tree node freed in the method.
Gets the object data for the node at the specified position in the sorted data.
TObject instance at the specified position, or Nil when AIndex does not exist in the sorted data.
Ordinal position in the sorted data where the object instance is stored.
Frees the specified tree node and all of its child nodes.
Causes nodes in the class instance to be sorted, filtered, and applied to the owner control.
Moves the tree node and data at the specified position to the position in NewIndex.

Move is a method used to change the ordinal position for a tree node and its associated data in the root node for the branch.

CurIndex contains the ordinal position for the tree node relocated in the method.

NewIndex contains the new ordinal position for the tree node.

Move changes the value in the Index property for the TTreeNode instance to NewIndex to reorder the tree node in the branch. It also moves data for the tree node supplied by the caller using the specified ordinal positions.

Move calls the MakeVisible method in the TTreeNode instance to ensure that it is visible on the Tree View control (when assigned). If the Tree View control is not assigned, the parent nodes for the tree node are expanded to make the node visible in the tree.

TCustomTreeview.Items TTreeNode.Index TTreeNode.MakeVisible TCustomControlFilterEdit.OnFilterItemEx TStrings.Move
Ordinal position for the tree node and data moved in the method.
Ordinal position where tree node and data are relocated in the method.
Contains the original tree node data for the class instance.

Items is a read-only TStringList property which contains the original data displayed for a branch in a filtered tree view control. It contains data for the tree nodes stored using AddNodeData, and maintained using GeteData / DeleteData / FreeNodeData / ClearNodeData. Items is used when the tree nodes are sorted and filtered in the class instance.

Specializes TFPGObjectList for the TTreeFilterBranch type.

Used in the implementation of the TTreeFilterEdit control.

Implements a filter edit control for an associated TTreeView control.

This control has 2 different modes of operation. One mode maintains and filters sub-items of root-nodes in a tree. The other mode filters the whole tree using the TreeNode.Visible property for each of the nodes.

Mode 1: Sub-branches under root nodes Items for each branch are maintained in a TTreeFilterBranch class instance.

Mode 2: A whole tree When no branches are defined (no calls made to GetBranch), the TreeFilterEdit control filters the whole tree automatically. It uses the Visible property in the TTreeNode instances to show/hide it.

Performs actions needed when the specified component is added to or removed from the control.

Notification frees event handlers and other resources allocated for the FilteredTreeview property when the TCustomTreeview component is removed in the class instance. It also frees and Nils resources allocated to the internal TBranchList instance in the control.

Component for the notification event.
Operation for the specified component.
Moves to and optionally selects the next node in the associated tree view control.

Implements the abstract virtual method introduced in the TCustomControlFilterEdit ancestor.

MoveNext ensures that FilteredTreeview has been configured to allow multi-selections and use of the Shift key when selecting nodes on the control.

ASelect indicates whether the next Node is selected (True) or unselected (False). If the tree view controls has not enabled multi-selections using the Shift key, its value is changed to False.

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

True if the new tree node is marked as selected in the tree view control.
Moves to and optionally selects the previous node in the associated tree view control.

Implements the abstract virtual method introduced in the TCustomControlFilterEdit ancestor.

MovePrev ensures that FilteredTreeview has been configured to allow multi-selections and use of the Shift key when selecting nodes on the control.

ASelect indicates whether the previous Node is selected (True) or unselected (False). If the tree view controls has not enabled multi-selections using the Shift key, its value is changed to False.

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

True if the new tree node is marked as selected in the tree view control.
Moves the associated tree view control by one page in the upward direction, and optionally selects the first node.

Implements the abstract virtual method introduced in the TCustomControlFilterEdit ancestor.

True if the new tree node is marked as selected in the tree view control.
Moves the associated tree view control by one page in the downward direction, and optionally selects the first node.

Implements the abstract virtual method introduced in the TCustomControlFilterEdit ancestor.

True if the new tree node is marked as selected in the tree view control.
Moves the tree view control to the first (or root) node in the tree.

Implements the abstract virtual method introduced in the TCustomControlFilterEdit ancestor.

True if the new tree node is marked as selected in the tree view control.
Moves the tree view control to the last node in the tree.

Implements the abstract virtual method introduced in the TCustomControlFilterEdit ancestor.

True if the new tree node is marked as selected in the tree view control.
Indicates if a Return key in the Edit control was forwarded to the OnKeyPress event handler for the associated tree view.

ReturnKeyHandled is an overridden Boolean function which implements the abstract virtual method introduced in the TCustomControlFilterEdit ancestor. ReturnKeyHandled is used to forward a Return (Enter) key to the FilteredTreeView for the control when it is handled in the edit box for the control. No actions are performed in the method if either FilteredTreeView or its OnKeypress event handler has not been assigned.

The return value is True if the key down event was forwarded to the FilteredTreeView control for the class instance.

TCustomControlFilterEdit.EditKeyDown TWinControl.OnKeyPress
True if the Return key press was forwarded to the tree view control.
Implements the OnKeyDown event handler for the Edit on the control.

EditKeyDown is an overridden method in TTreeFilterEdit. It extends the inherited method to ensure that key strokes in the Edit for the control are applied (when needed) to its FilteredTreeview control.

EditKeyDown calls the inherited method on entry to handle key down events supported in the TCustomControlFilterEdit ancestor. The value in Key is set to 0 if it was handled in the inherited method, and no additional actions are performed in the method.

When FilteredTreeview has been assigned in the control, the following values in Key and Shift are handled:

Alt+Left
  Moves the selection in the associated tree view and collapses its child nodes.
Alt+Right
  Moves the selection in the associated tree view and expands its child nodes.
Shift+Alt+Left
  Collapses all of the tree nodes in the FilteredTreeview control.
Shift+Alt+Right
  Expands all of the tree nodes in the FilteredTreeview control.

The value in Key is set to 0 if it was handled in the method.

Added in LazControls version 3.0.
TCustomControlFilterEdit.EditKeyDown TCustomEditBtn.Edit
Virtual key code examined and handled in the method.
Ctrl, Alt, or Shift modifiers for the key code.
Sorts and filters either branches or the whole tree depending on the operation mode for the control.

SortAndFilter is an overridden method in TTreeFilterEdit which implements the abstract virtual method introduced in the TCustomControlFilterEdit ancestor. It ensures that the SortAndFilter method in TTreeFilterBranch instances is called to sort and filter selected branches in the control (when assigned). If the internal TBranchList has not been assigned, the ApplyFilterCore method is called to filter the entire tree.

SortAndFilter is called (from the ancestor class) when the value in Filter is applied to the nodes in the tree.

Applies the Filter to branches in the tree view or the entire tree depending on the mode of operation for the control.

ApplyFilterCore is an overridden method in TTreeFilterEdit. It implements the abstract virtual method introduced in the TCustomControlFilterEdit ancestor.

ApplyFilterCore is used to apply the value in Filter to either the entire list of nodes or the selected child node branches in the tree view control. When child tree nodes have been selected, the filter is applied using the TTreeFilterBranch list.

If the entire list of tree nodes are the target, the nodes are expanded when ExpandAllInitially is enabled and the method is called for the first time. The tree nodes are recursively filtered and the Visible property for the nodes is updated as required for the Filter value.

ApplyFilterCore is called from methods in the ancestor class when an idle state is detected and the control has pending updates for the filter value, or when the ForceFilter method is called.

The BeginUpdate and EndUpdate methods in the FilteredTreeview control are called to reduce the number of screen updates as the filter value is applied to tree nodes. The ClearInvisibleSelection method in the tree view is called to hide the selected tree node if it is no longer visible for the new filter value, or to clear multi-selections when the new filter is applied.

No actions are performed in the method if a value has not been assigned to the FilteredTreeview property.

TCustomControlFilterEdit.Filter TCustomControlFilterEdit.FilterLowercase TCustomControlFilterEdit.ResetFilter TCustomControlFilterEdit.ForceFilter TCustomTreeView.FullExpand TCustomTreeView.ClearInvisibleSelection TCustomTreeView.BeginUpdate TCustomTreeView.EndUpdate
Gets the resource name for the glyph used on the Button in the filter edit control.
Name of the resource with the glyph image for the button.
Constructor for the class instance.

Allocates resource for the SelectionList property. Sets the default values for the ExpandAllInitially and ImageIndexDirectory properties.

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

Frees resource allocated in the class instance for:

- FilteredTreeview
- SelectionList
- Other internal members

Silently applies the filter for a specified tree view in the edit control.

SetTreeFilterSilently is a method used to apply the filter value in AFilter to the tree view control in ATree. SetTreeFilterSilently ensures that the FilteredTreeview property is set to the value in ATree, but does not force the tree view to be re-filtered (and its nodes to be expanded) unless the value in AFilter differs from an existing filter applied to the tree view. It allows one filtered edit control to be used to filter more than one tree view control - but does not refresh the tree view control unless the filter value has been explicitly changed. It suppresses node expansion in an associated tree view control which may already be filtered by the specified value.

SetTreeFilterSilently sets an internal flag to prevent refreshing the tree view in aTree simply because it is not the existing control in FilteredTreeview. The value in AFilter is applied to the Filter property, but does not force the nodes in the tree to be re-displayed / expanded unless the new filter value is different than the filter value already applied to the tree view control.

An example of its usage can be found in the Search Results view in the Lazarus IDE.

TCustomControlFilterEdit.Filter TCustomControlFilterEdit.InvalidateFilter TCustomControlFilterEdit.InternalSetFilter
Stores the first visible node for the selected tree node in FilteredTreeview to the SelectionList property.

StoreSelection is an overridden method in TTreeFilterEdit which implements the abstract virtual method introduced in TCustomControlFilterEdit. StoreSelection ensures that ScrolledLeft and ScrolledTop values from the tree view are used when the selected node is not within the visible area for the tree view control. ScrolledLeft and ScrolledTop are assumed to be -1 if the tree node is already visible on the FilteredTreeview control.

Values in SelectionList are cleared and reloaded if the selected tree node is not the first node in the list; SelectionList will contain only the selected tree node on exit. SelectionList is not changed if the selected node is the first tree node in the selection list.

No actions are performed in the method for the following conditions:

- FilteredTreeview has not been assigned.
- FilteredTreeview does not have a Selected tree node.

Modified in LCL version 4.0 to use the ScrolledLeft and ScrolledTop values from the FilteredTreeView control.
TCustomTreeView.Selected TCustomTreeView.ScrolledLeft TCustomTreeView.ScrolledTop TCustomControlFilterEdit.StoreSelection
Makes the tree node in SelectionList the Selected node in the FilteredTreeview control.

RestoreSelection is an overridden method in TTreeFilterEdit which implements the abstract virtual method introduced in the TTreeFilterEdit ancestor. RestoreSelection ensures that the ScrolledLeft and ScrolledTop properties in the FilteredTreeView control are updated when the selected node in SelectionList is located on the tree view control.

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

Raises an assertion exception if SelectionList has more than one node in the list.

Modified in LCL version 4.0 to update the ScrolledLeft and ScrolledTop properties in the FilteredTreeView control.
TCustomTreeView.Selected TCustomTreeView.ScrolledTop TCustomControlFilterEdit.StoreSelection TCustomControlFilterEdit.RestoreSelection
Get an existing branch for a given tree-node, or Nil if there is none.

This can be used only with the "sub-branches" mode.

Get a new or existing branch with data cleared for a given tree-node.

This can be used only with the "sub-branches" mode. In fact calling this method switches the filter into "sub-branches" mode. This is the way to add those branches.

Deletes the branch with the specified root node from the internal list.

DeleteBranch iterates over the items in the internal branch list to locate an entry with the root node specified in ARootNode. The delete method in list is called to remove the branch entry.

No actions are performed in the method if an internal TBranchList has not been allocated in the class instance by calling the GetCleanBranch method.

TCustomControlFilterEdit.InvalidateFilter TTreeNode TFPSList.Delete
Returns True if the specified branch node was successfully removed from the internal list. Returns False if a branch with the specified root node is not found, or the branch list is empty.
Tree node that represents the root node for the branch deleted in the method.
Ordinal position for the image displayed for a directory entry in the list of tree nodes.
List of selected items in the FilteredTreeview control.

SelectionList is a read-only TStringList property with the list of selected items in the FilteredTreeview control. It is used to save and restore selected item(s) when the Filter is (re)applied to the items for the control.

An existing value in SelectionList is cleared prior to saving a new tree node in the StoreSelection method. The value in SelectionList is used in the RestoreSelection method to locate the node and restore it to the Selected property in FilteredTreeview. The current implementation does not handle multiple selections in the property; a single selected tree node can be stored or restored using the property.

TCustomControlFilterEdit.Filter TCustomTreeView.Selected TStringList
When filtered text is a directory name, it is split and shown as a tree structure.

ShowDirHierarchy is a Boolean property which determines whether directories and / or files are displayed using a tree structure. It is used when the SortAndFilter method is called to sort original data into the sorted order used when applying the Filter value for the control.

ShowDirHierarchy has effect only in the "sub-branches" mode. The "whole tree" mode uses the existing tree nodes as is and only changes their visibility.

Changing the value for the property causes the InvalidateFilter method to be called. An Exception is raised if a TCustomTreeView instance has not been assigned to the FilteredTreeView property.

TCustomControlFilterEdit.Filter TCustomControlFilterEdit.FilterOptions TCustomControlFilterEdit.InvalidateFilter
The associated TTreeView with the filtered tree nodes for the control.

FilteredTreeview is a TCustomTreeview property with the associated tree view for the filter control. FilteredTreeview is used to display the tree nodes which match the Filter for the control. Assigning a new value to the property causes the InvalidateFilter method to be called to reapply the text in Filter to the new tree view control.

TCustomControlFilterEdit.InvalidateFilter
Tree branches are expanded also initially.

The branches are expanded in any case when the tree is filtered and matches are found. This setting only affects the initial state.

Gets the ordinal position for the image displayed for a node on the control.

OnGetImageIndex is a TImageIndexEvent property with the event handler signalled to get the position for the image used for a tree node displayed on the control. The event handler includes the following arguments:

Str
  Text for the tree node.
Data
  Object instance with the data for the tree node.
AIsEnabled
  Variable parameter which indicates whether the tree node is enabled on the control. True when enabled, otherwise False.

OnGetImageIndex is signalled (when assigned) from the ApplyFilter method in TTreeFilterBranch. The return value provides the value stored in the ImageIndex property for the TTreeNode instance, and refers to the ordinal position in the Images property for the control. -1 indicates that an image (and its position) could not be determined using the specified argument values.

Event handler signalled to determine if a tree node matches the Filter for the control.

OnFilterNode is a TFilterNodeEvent property with the event handler signalled to determine whether a tree node matches the Filter value for the control. The event handler is signalled (when assigned) when the filter value is recursively applied to tree nodes to determine which are visible in the FilteredTreeView. It allows user-specified criteria other than the text or data for the node to be used to determine node visibility.

OnFilterNode is signalled when the ApplyFilterCore method is executed, and occurs after setting the value in Filter property or when the SortAndFilter method is called. An application must implement and assign a handler using the signature in TFilterNodeEvent to determine the visibility for a tree node and its child nodes.

OnFilterNode is signalled before the OnFilterItem event handler. The Done output parameter indicates whether the node was processed in the event handler. The return value indicates whether the node is visible (matches the filter). If the Done argument is set to False, the OnFilterItem event handler is signalled to check visibility for the node using its text and data. If the Done argument is set to True, the OnFilterItem handler is not signalled and the return value from the handler determines the visibility for the node.

TCustomControlFilterEdit.Filter TCustomControlFilterEdit.DoFilterItem TCustomControlFilterEdit.OnFilterItemEx TCustomControlFilterEdit.OnFilterItem
Base class used to represent a tree node and the branch where it is stored.

TreeFilterEditNodeData is the ancestor for the TFileNameItem type.

TTreeNode TCustomControlFilterEdit.StoreSelection
Tree node for the class instance.
Branch where the tree node is stored.
Stores information about a file name and the tree node which represents it.
Pointer to the Object instance associated with the file aname in the instance.
Path and name for the file represented in the class instance.
Constructor for the class instance.
Value assigned to the Filename member.
Value assigned to the Data member.