<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
<package name="LazControls">
<!-- 
======================================================================
TreeFilterEdit 
======================================================================
-->
<module name="TreeFilterEdit">
<short>
Implements a control used to filter an associated TTreeView control.
</short>
<descr>
<p>
<file>treefilteredit.pas</file> contains classes and other types used to 
implement a control used to filter an associated TTreeView control. 
<file>treefilteredit.pas</file> is part of the <file>LazControls</file> 
package.
</p>
</descr>

<element name="TImageIndexEvent">
<short>
Specifies an event handler used to get the position of the image for a tree node.
</short>
<descr>
<p>
<var>TImageIndexEvent</var> is an <var>Integer</var> 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.
</p>
<p>
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.
</p>
<p>
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.
</p>
</descr>
<seealso>
<link id="TTreeFilterEdit.OnGetImageIndex"/>
<link id="TTreeFilterBranch.AddNodeData"/>
<link id="TTreeFilterBranch.GetData"/>
</seealso>
</element>
<element name="TImageIndexEvent.Result">
<short>
Ordinal position for the image selected for a tree node in the event handler 
routine.
</short>
</element>
<element name="TImageIndexEvent.Str">
<short>
Text for the tree node used in the event handler.
</short>
</element>
<element name="TImageIndexEvent.Data">
<short>
Object reference with the data for the tree node.
</short>
</element>
<element name="TImageIndexEvent.AIsEnabled">
<short>
Returns <b>True</b> if the tree node is enabled.
</short>
</element>

<element name="TFilterNodeEvent">
<short>
Specifies an event handler signalled to determine if a tree node matches the 
Filter in a TTreeFilterEdit control.
</short>
<descr>
<p>
<var>TFilterNodeEvent</var> is a <var>Boolean</var> 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.
</p>
<p>
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.
</p>
<p>
<var>ItemNode</var> is the <var>TTreeNode</var> instance examined in the 
handler, and provides access to its properties and methods.
</p>
<p>
<var>Done</var> is an output parameter which indicates whether the tree node 
was examined in the handler routine. Set Done to <b>True</b> if the node was 
used or examined in the handler. Set Done to <b>False</b> if the node was not 
/ could not be handled in the routine.
</p>
<p>
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 <b>True</b>.
</p>
</descr>
<seealso>
<link id="TTreeFilterEdit.OnFilterNode"/>
</seealso>
</element>
<element name="TFilterNodeEvent.Result">
<short>
<b>True</b> if the specified tree node can be used for the Filter value.
</short>
</element>
<element name="TFilterNodeEvent.ItemNode">
<short>
Tree node examined in the handler routine.
</short>
</element>
<element name="TFilterNodeEvent.Done">
<short>
<b>True</b> if the node was handled in the routine. <b>False</b> if the node 
was ignored in the handler. The return value is significant when Done is set 
to <b>True</b>.
</short>
</element>

<element name="TTreeFilterBranch">
<short>
Represents a branch for an existing tree node when a filter is used in 
"sub-branches" mode.
</short>
<descr/>
<seealso/>
</element>

<element name="TTreeFilterBranch.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<p>
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.
</p>
</descr>
<seealso/>
</element>
<element name="TTreeFilterBranch.Create.AOwner">
<short>
Filter edit control which owns the class instance.
</short>
</element>
<element name="TTreeFilterBranch.Create.ARootNode">
<short>
Tree node which is the root for the brance, or Nil when all nodes are 
considered as top-level tree nodes.
</short>
</element>

<element name="TTreeFilterBranch.AddNodeData">
<short>
Adds an entry in Items for a root node in a branch.
</short>
<descr>
<p>
Text, a data reference, and an associated file name can be added for the node.
</p>
</descr>
</element>
<element name="TTreeFilterBranch.AddNodeData.ANodeText">
<short>
Text for the tree node data.
</short>
</element>
<element name="TTreeFilterBranch.AddNodeData.AData">
<short>
Object reference with the user-specified data for the tree node.
</short>
</element>
<element name="TTreeFilterBranch.AddNodeData.AFullFilename">
<short>
Full file path and name for a tree node used in a directory hierarchy.
</short>
</element>

<element name="TTreeFilterBranch.DeleteData">
<short>
Removes the specified tree node from the data for the class instance.
</short>
<descr>
<p>
Removes the specified tree node from Items, the internal list for sorted 
data, and the items in the FilteredTreeview for the owner control.
</p>
</descr>
<seealso/>
</element>
<element name="TTreeFilterBranch.DeleteData.ANode">
<short>
Tree node deleted in the method.
</short>
</element>

<element name="TTreeFilterBranch.FreeNodeData">
<short>
Frees the specified tree node including its node object data.
</short>
<descr/>
<seealso/>
</element>
<element name="TTreeFilterBranch.FreeNodeData.ANode">
<short>
Tree node freed in the method.
</short>
</element>

<element name="TTreeFilterBranch.GetData">
<short>
Gets the object data for the node at the specified position in the sorted 
data.
</short>
<descr/>
<seealso/>
</element>
<element name="TTreeFilterBranch.GetData.Result">
<short>
TObject instance at the specified position, or Nil when AIndex does not exist 
in the sorted data.
</short>
</element>
<element name="TTreeFilterBranch.GetData.AIndex">
<short>
Ordinal position in the sorted data where the object instance is stored.
</short>
</element>

<element name="TTreeFilterBranch.ClearNodeData">
<short>
Frees the specified tree node and all of its child nodes.
</short>
<descr/>
<seealso/>
</element>

<element name="TTreeFilterBranch.InvalidateBranch">
<short>
Causes nodes in the class instance to be sorted, filtered, and applied to the 
owner control.
</short>
<descr/>
<seealso/>
</element>

<element name="TTreeFilterBranch.Move">
<short>
Moves the tree node and data at the specified position to the position in 
NewIndex.
</short>
<descr>
<p>
<var>Move</var> is a method used to change the ordinal position for a tree node and its associated data in the root node for the branch. 
</p>
<p>
CurIndex contains the ordinal position for the tree node relocated in the 
method.
</p>
<p>
NewIndex contains the new ordinal position for the tree node.
</p>
<p>
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.
</p>
<p>
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.
</p>
</descr>
<seealso>
<link id="TTreeFilterBranch.Items"/>
<link id="TBranchList"/>
<link id="#lcl.comctrls.TCustomTreeview.Items">TCustomTreeview.Items</link>
<link id="#lcl.comctrls.TTreeNode.Index">TTreeNode.Index</link>
<link id="#lcl.comctrls.TTreeNode.MakeVisible">TTreeNode.MakeVisible</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.OnFilterItemEx">TCustomControlFilterEdit.OnFilterItemEx</link>
<link id="#rtl.classes.TStrings.Move">TStrings.Move</link>
</seealso>
</element>
<element name="TTreeFilterBranch.Move.CurIndex">
<short>
Ordinal position for the tree node and data moved in the method.
</short>
</element>
<element name="TTreeFilterBranch.Move.NewIndex">
<short>
Ordinal position where tree node and data are relocated in the method.
</short>
</element>

<element name="TTreeFilterBranch.Items">
<short>
Contains the original tree node data for the class instance.
</short>
<descr/>
<p>
<var>Items</var> is a read-only <var>TStringList</var> 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.
</p>
<seealso>
<link id="TTreeFilterBranch.AddNodeData"/>
<link id="TTreeFilterBranch.GetData"/>
<link id="TTreeFilterBranch.FreeNodeData"/>
<link id="TTreeFilterBranch.ClearNodeData"/>
</seealso>
</element>

<element name="TBranchList">
<short>
Specializes TFPGObjectList for the TTreeFilterBranch type.
</short>
<descr>
<p>
Used in the implementation of the TTreeFilterEdit control.
</p>
</descr>
<seealso>
<link id="TTreeFilterBranch"/>
<link id="TTreeFilterEdit"/>
</seealso>
</element>

<element name="TTreeFilterEdit">
<short>
Implements a filter edit control for an associated TTreeView control.
</short>
<descr>
<p>
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.
</p>
<p>
<b>Mode 1</b>: Sub-branches under root nodes Items for each branch are 
maintained in a TTreeFilterBranch class instance.
</p>
<p>
<b>Mode 2</b>: 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.
</p>
</descr>
</element>

<!-- private -->
<element name="TTreeFilterEdit.fFilteredTreeview"/>
<element name="TTreeFilterEdit.fImageIndexDirectory"/>
<element name="TTreeFilterEdit.FScrolledPos"/>
<element name="TTreeFilterEdit.fSelectionList"/>
<element name="TTreeFilterEdit.fShowDirHierarchy"/>
<element name="TTreeFilterEdit.fBranches"/>
<element name="TTreeFilterEdit.fExpandAllInitially"/>
<element name="TTreeFilterEdit.fIsFirstTime"/>
<element name="TTreeFilterEdit.fFirstPassedNode"/>
<element name="TTreeFilterEdit.fOnGetImageIndex"/>
<element name="TTreeFilterEdit.fOnFilterNode"/>
<element name="TTreeFilterEdit.SetFilteredTreeview"/>
<element name="TTreeFilterEdit.SetShowDirHierarchy"/>
<element name="TTreeFilterEdit.FilterTree"/>
<element name="TTreeFilterEdit.OnBeforeTreeDestroy"/>

<!-- protected -->
<element name="TTreeFilterEdit.Notification">
<short>
Performs actions needed when the specified component is added to or removed 
from the control.
</short>
<descr>
<p>
<var>Notification</var> 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 <b>Nil</b>s resources allocated to 
the internal TBranchList instance in the control.
</p>
</descr>
<seealso/>
</element>
<element name="TTreeFilterEdit.Notification.AComponent">
<short>
Component for the notification event.
</short>
</element>
<element name="TTreeFilterEdit.Notification.Operation">
<short>
Operation for the specified component.
</short>
</element>

<element name="TTreeFilterEdit.MoveNext">
<short>
Moves to and optionally selects the next node in the associated tree view 
control.
</short>
<descr>
<p>
Implements the abstract virtual method introduced in the TCustomControlFilterEdit ancestor. 
</p>
<p>
MoveNext ensures that FilteredTreeview has been configured to allow 
multi-selections and use of the Shift key when selecting nodes on the control.
</p>
<p>
ASelect indicates whether the next Node is selected (<b>True</b>) or unselected 
(<b>False</b>). If the tree view controls has not enabled multi-selections 
using the Shift key, its value is changed to <b>False</b>.
</p>
<p>
No actions are performed in the method if the FilteredTreeview property has not been assigned.
</p>
</descr>
<seealso/>
</element>
<element name="TTreeFilterEdit.MoveNext.ASelect">
<short>
<b>True</b> if the new tree node is marked as selected in the tree view 
control.
</short>
</element>

<element name="TTreeFilterEdit.MovePrev">
<short>
Moves to and optionally selects the previous node in the associated tree view 
control.
</short>
<descr>
<p>
Implements the abstract virtual method introduced in the 
TCustomControlFilterEdit ancestor.
</p>
<p>
MovePrev ensures that FilteredTreeview has been configured to allow 
multi-selections and use of the Shift key when selecting nodes on the control.
</p>
<p>
ASelect indicates whether the previous Node is selected (<b>True</b>) or 
unselected (<b>False</b>). If the tree view controls has not enabled 
multi-selections using the Shift key, its value is changed to <b>False</b>.
</p>
<p>
No actions are performed in the method if the FilteredTreeview property has not been assigned.
</p>
</descr>
<seealso/>
</element>
<element name="TTreeFilterEdit.MovePrev.ASelect">
<short>
<b>True</b> if the new tree node is marked as selected in the tree view 
control.
</short>
</element>

<element name="TTreeFilterEdit.MovePageUp">
<short>
Moves the associated tree view control by one page in the upward direction, 
and optionally selects the first node.
</short>
<descr>
<p>
Implements the abstract virtual method introduced in the 
TCustomControlFilterEdit ancestor.
</p>
</descr>
<seealso/>
</element>
<element name="TTreeFilterEdit.MovePageUp.ASelect">
<short>
<b>True</b> if the new tree node is marked as selected in the tree view 
control.
</short>
</element>

<element name="TTreeFilterEdit.MovePageDown">
<short>
Moves the associated tree view control by one page in the downward direction, 
and optionally selects the first node.
</short>
<descr>
<p>
Implements the abstract virtual method introduced in the 
TCustomControlFilterEdit ancestor.
</p>
</descr>
<seealso/>
</element>
<element name="TTreeFilterEdit.MovePageDown.ASelect">
<short>
<b>True</b> if the new tree node is marked as selected in the tree view 
control.
</short>
</element>

<element name="TTreeFilterEdit.MoveHome">
<short>
Moves the tree view control to the first (or root) node in the tree.
</short>
<descr>
<p>
Implements the abstract virtual method introduced in the 
TCustomControlFilterEdit ancestor.
</p>
</descr>
<seealso/>
</element>
<element name="TTreeFilterEdit.MoveHome.ASelect">
<short>
<b>True</b> if the new tree node is marked as selected in the tree view 
control.
</short>
</element>

<element name="TTreeFilterEdit.MoveEnd">
<short>
Moves the tree view control to the last node in the tree.
</short>
<descr>
<p>
Implements the abstract virtual method introduced in the 
TCustomControlFilterEdit ancestor.
</p>
</descr>
<seealso/>
</element>
<element name="TTreeFilterEdit.MoveEnd.ASelect">
<short>
<b>True</b> if the new tree node is marked as selected in the tree view 
control.
</short>
</element>

<element name="TTreeFilterEdit.ReturnKeyHandled">
<short>
Indicates if a Return key in the Edit control was forwarded to the OnKeyPress 
event handler for the associated tree view.
</short>
<descr>
<p>
<var>ReturnKeyHandled</var> is an overridden <var>Boolean</var> 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.
</p>
<p>
The return value is <b>True</b> if the key down event was forwarded to the 
FilteredTreeView control for the class instance.
</p>
</descr>
<seealso>
<link id="TTreeFilterEdit.FilteredTreeview"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.EditKeyDown">TCustomControlFilterEdit.EditKeyDown</link>
<link id="#lcl.controls.TWinControl.OnKeyPress">TWinControl.OnKeyPress</link>
</seealso>
</element>
<element name="TTreeFilterEdit.ReturnKeyHandled.Result">
<short>
<b>True</b> if the Return key press was forwarded to the tree view control.
</short>
</element>

<element name="TTreeFilterEdit.EditKeyDown">
<short>
Implements the OnKeyDown event handler for the Edit on the control.
</short>
<descr>
<p>
<var>EditKeyDown</var> is an overridden method in <var>TTreeFilterEdit</var>. 
It extends the inherited method to ensure that key strokes in the Edit for the 
control are applied (when needed) to its FilteredTreeview control.
</p>
<p>
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.
</p>
<p>
When FilteredTreeview has been assigned in the control, the following values 
in Key and Shift are handled:
</p>
<dl>
<dt>Alt+Left</dt>
<dd>
Moves the selection in the associated tree view and collapses its child nodes. 
</dd>
<dt>Alt+Right</dt>
<dd>
Moves the selection in the associated tree view and expands its child nodes. 
</dd>
<dt>Shift+Alt+Left</dt>
<dd>
Collapses all of the tree nodes in the FilteredTreeview control.
</dd>
<dt>Shift+Alt+Right</dt>
<dd>
Expands all of the tree nodes in the FilteredTreeview control.
</dd>
</dl>
<p>
The value in Key is set to 0 if it was handled in the method.
</p>
</descr>
<version>
Added in LazControls version 3.0.
</version>
<seealso>
<link id="TTreeFilterEdit.FilteredTreeview"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.EditKeyDown">TCustomControlFilterEdit.EditKeyDown</link>
<link id="#lcl.editbtn.TCustomEditBtn.Edit">TCustomEditBtn.Edit</link>
</seealso>
</element>
<element name="TTreeFilterEdit.EditKeyDown.Key">
<short>
Virtual key code examined and handled in the method.
</short>
</element>
<element name="TTreeFilterEdit.EditKeyDown.Shift">
<short>
Ctrl, Alt, or Shift modifiers for the key code.
</short>
</element>

<element name="TTreeFilterEdit.SortAndFilter">
<short>
Sorts and filters either branches or the whole tree depending on the operation 
mode for the control.
</short>
<descr>
<p>
<var>SortAndFilter</var> is an overridden method in <var>TTreeFilterEdit</var> 
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.
</p>
<p>
SortAndFilter is called (from the ancestor class) when the value in Filter is 
applied to the nodes in the tree.
</p>
</descr>
<seealso>
<link id="TTreeFilterEdit.GetCleanBranch"/>
<link id="TTreeFilterEdit.GetExistingBranch"/>
<link id="TTreeFilterBranch"/>
<link id="TBranchList"/>
</seealso>
</element>

<element name="TTreeFilterEdit.ApplyFilterCore">
<short>
Applies the Filter to branches in the tree view or the entire tree depending 
on the mode of operation for the control.
</short>
<descr>
<p>
<var>ApplyFilterCore</var> is an overridden method in 
<var>TTreeFilterEdit</var>. It implements the abstract virtual method 
introduced in the TCustomControlFilterEdit ancestor.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
No actions are performed in the method if a value has not been assigned to the 
FilteredTreeview property.
</p>
</descr>
<seealso>
<link id="TTreeFilterEdit.FilteredTreeview"/>
<link id="TTreeFilterEdit.SortAndFilter"/>
<link id="TTreeFilterEdit.ExpandAllInitially"/>
<link id="TTreeFilterBranch"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.Filter">TCustomControlFilterEdit.Filter</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.FilterLowercase">TCustomControlFilterEdit.FilterLowercase</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.ResetFilter">TCustomControlFilterEdit.ResetFilter</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.ForceFilter">TCustomControlFilterEdit.ForceFilter</link>
<link id="#lcl.comctrls.TCustomTreeView.FullExpand">TCustomTreeView.FullExpand</link>
<link id="#lcl.comctrls.TCustomTreeView.ClearInvisibleSelection">TCustomTreeView.ClearInvisibleSelection</link>
<link id="#lcl.comctrls.TCustomTreeView.BeginUpdate">TCustomTreeView.BeginUpdate</link>
<link id="#lcl.comctrls.TCustomTreeView.EndUpdate">TCustomTreeView.EndUpdate</link>
</seealso>
</element>

<element name="TTreeFilterEdit.GetDefaultGlyphName">
<short>
Gets the resource name for the glyph used on the Button in the filter edit 
control.
</short>
<descr/>
<seealso/>
</element>
<element name="TTreeFilterEdit.GetDefaultGlyphName.Result">
<short>
Name of the resource with the glyph image for the button.
</short>
</element>

<element name="TTreeFilterEdit.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<p>
Allocates resource for the SelectionList property. Sets the default values 
for the ExpandAllInitially and ImageIndexDirectory properties.
</p>
</descr>
<seealso/>
</element>
<element name="TTreeFilterEdit.Create.AOwner">
<short>
Owner of the class instance.
</short>
</element>

<element name="TTreeFilterEdit.Destroy">
<short>
Destructor for the class instance.
</short>
<descr>
<p>
Frees resource allocated in the class instance for:
</p>
<ul>
<li>FilteredTreeview</li>
<li>SelectionList</li>
<li>Other internal members</li>
</ul>
</descr>
<seealso/>
</element>

<element name="TTreeFilterEdit.SetTreeFilterSilently">
<short>
Silently applies the filter for a specified tree view in the edit control.
</short>
<descr>
<p>
<var>SetTreeFilterSilently</var> is a method used to apply the filter value in 
<var>AFilter</var> to the tree view control in <var>ATree</var>. 
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.
</p>
<p>
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.
</p>
<p>
An example of its usage can be found in the 
<url href="https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/ide/searchresultview.pp">Search Results view</url> in the Lazarus IDE.
</p>
</descr>
<seealso>
<link id="TTreeFilterEdit.FilteredTreeview"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.Filter">TCustomControlFilterEdit.Filter</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.InvalidateFilter">TCustomControlFilterEdit.InvalidateFilter</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.InternalSetFilter">TCustomControlFilterEdit.InternalSetFilter</link>
</seealso>
</element>

<element name="TTreeFilterEdit.StoreSelection">
<short>
Stores the first visible node for the selected tree node in FilteredTreeview 
to the SelectionList property.
</short>
<descr>
<p>
<var>StoreSelection</var> is an overridden method in <var>TTreeFilterEdit</var> 
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.
</p>
<p>
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 <b>is</b> 
the first tree node in the selection list.
</p>
<p>
No actions are performed in the method for the following conditions:
</p>
<ul>
<li>FilteredTreeview has not been assigned.</li>
<li>FilteredTreeview does not have a Selected tree node.</li>
</ul>
</descr>
<version>
Modified in LCL version 4.0 to use the ScrolledLeft and ScrolledTop values from the FilteredTreeView control.
</version>
<seealso>
<link id="TTreeFilterEdit.FilteredTreeview"/>
<link id="TTreeFilterEdit.RestoreSelection"/>
<link id="TTreeFilterEdit.SelectionList"/>
<link id="#lcl.comctrls.TCustomTreeView.Selected">TCustomTreeView.Selected</link>
<link id="#lcl.comctrls.TCustomTreeView.ScrolledLeft">TCustomTreeView.ScrolledLeft</link>
<link id="#lcl.comctrls.TCustomTreeView.ScrolledTop">TCustomTreeView.ScrolledTop</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.StoreSelection">TCustomControlFilterEdit.StoreSelection</link>
</seealso>
</element>

<element name="TTreeFilterEdit.RestoreSelection">
<short>
Makes the tree node in SelectionList the Selected node in the 
FilteredTreeview control.
</short>
<descr>
<p>
<var>RestoreSelection</var> is an overridden method in 
<var>TTreeFilterEdit</var> 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.
</p>
<p>
No actions are performed in the method if FilteredTreeview has not been 
assigned.
</p>
<p>
Raises an assertion exception if SelectionList has more than one node in the 
list.
</p>
</descr>
<version>
Modified in LCL version 4.0 to update the ScrolledLeft and ScrolledTop 
properties in the FilteredTreeView control.
</version>
<seealso>
<link id="TTreeFilterEdit.FilteredTreeview"/>
<link id="TTreeFilterEdit.StoreSelection"/>
<link id="TTreeFilterEdit.RestoreSelection"/>
<link id="TTreeFilterEdit.SelectionList"/>
<link id="#lcl.comctrls.TCustomTreeView.Selected">TCustomTreeView.Selected</link>
<link id="#lcl.comctrls.TCustomTreeView.ScrolledTop">TCustomTreeView.ScrolledTop</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.StoreSelection">TCustomControlFilterEdit.StoreSelection</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.RestoreSelection">TCustomControlFilterEdit.RestoreSelection</link>
</seealso>
</element>

<element name="TTreeFilterEdit.GetExistingBranch">
<short>
Get an existing branch for a given tree-node, or Nil if there is none.
</short>
<descr>
<p>
This can be used only with the "sub-branches" mode.
</p>
</descr>
<seealso/>
</element>
<element name="TTreeFilterEdit.GetExistingBranch.Result">
<short/>
</element>
<element name="TTreeFilterEdit.GetExistingBranch.ARootNode">
<short/>
</element>

<element name="TTreeFilterEdit.GetCleanBranch">
<short>
Get a new or existing branch with data cleared for a given tree-node.
</short>
<descr>
<p>
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.
</p>
</descr>
<seealso/>
</element>
<element name="TTreeFilterEdit.GetCleanBranch.Result">
<short/>
</element>
<element name="TTreeFilterEdit.GetCleanBranch.ARootNode">
<short/>
</element>

<element name="TTreeFilterEdit.DeleteBranch">
<short>
Deletes the branch with the specified root node from the internal list.
</short>
<descr>
<p>
<var>DeleteBranch</var> 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.
</p>
<p>
No actions are performed in the method if an internal TBranchList has not been 
allocated in the class instance by calling the GetCleanBranch method.
</p>
</descr>
<seealso>
<link id="TTreeFilterEdit.GetCleanBranch"/>
<link id="TTreeFilterEdit.GetExistingBranch"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.InvalidateFilter">TCustomControlFilterEdit.InvalidateFilter</link>
<link id="#lcl.comctrls.TTreeNode">TTreeNode</link>
<link id="#rtl.fgl.TFPSList.Delete">TFPSList.Delete</link>
</seealso>
</element>
<element name="TTreeFilterEdit.DeleteBranch.Result">
<short>
Returns <b>True</b> if the specified branch node was successfully removed from the internal list. Returns <b>False</b> if a branch with the specified root node is not found, or the branch list is empty.
</short>
</element>
<element name="TTreeFilterEdit.DeleteBranch.ARootNode">
<short>
Tree node that represents the root node for the branch deleted in the method.
</short>
</element>

<element name="TTreeFilterEdit.ImageIndexDirectory">
<short>
Ordinal position for the image displayed for a directory entry in the list of 
tree nodes.
</short>
<descr/>
<seealso/>
</element>

<element name="TTreeFilterEdit.SelectionList">
<short>
List of selected items in the FilteredTreeview control.
</short>
<descr>
<p>
<var>SelectionList</var> is a read-only <var>TStringList</var> property with 
the list of selected items in the <var>FilteredTreeview</var> control. It is 
used to save and restore selected item(s) when the Filter is (re)applied to 
the items for the control.
</p>
<p>
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.
</p>
</descr>
<seealso>
<link id="TTreeFilterEdit.StoreSelection"/>
<link id="TTreeFilterEdit.RestoreSelection"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.Filter">TCustomControlFilterEdit.Filter</link>
<link id="#lcl.comctrls.TCustomTreeView.Selected">TCustomTreeView.Selected</link>
<link id="#rtl.classes.TStringList">TStringList</link>
</seealso>
</element>

<element name="TTreeFilterEdit.ShowDirHierarchy">
<short>
When filtered text is a directory name, it is split and shown as a tree 
structure.
</short>
<descr>
<p>
<var>ShowDirHierarchy</var> is a <var>Boolean</var> 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.
</p>
<p>
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.
</p>
<p>
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.
</p>
</descr>
<seealso>
<link id="TTreeFilterEdit.FilteredTreeview"/>
<link id="TTreeFilterEdit.SortAndFilter"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.Filter">TCustomControlFilterEdit.Filter</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.FilterOptions">TCustomControlFilterEdit.FilterOptions</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.InvalidateFilter">TCustomControlFilterEdit.InvalidateFilter</link>
</seealso>
</element>

<element name="TTreeFilterEdit.FilteredTreeview">
<short>
The associated TTreeView with the filtered tree nodes for the control.
</short>
<descr>
<p>
<var>FilteredTreeview</var> is a <var>TCustomTreeview</var> 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.
</p>
</descr>
<seealso>
<link id="#lcl.editbtn.TCustomControlFilterEdit.InvalidateFilter">TCustomControlFilterEdit.InvalidateFilter</link>
</seealso>
</element>

<element name="TTreeFilterEdit.ExpandAllInitially">
<short>Tree branches are expanded also initially.</short>
<descr>
<p>
The branches are expanded in any case when the tree is filtered and matches 
are found. This setting only affects the initial state.
</p>
</descr>
<seealso/>
</element>

<element name="TTreeFilterEdit.OnGetImageIndex">
<short>
Gets the ordinal position for the image displayed for a node on the control.
</short>
<descr>
<p>
<var>OnGetImageIndex</var> is a <var>TImageIndexEvent</var> 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:
</p>
<dl>
<dt>Str</dt>
<dd>
Text for the tree node.
</dd>
<dt>Data</dt>
<dd>
Object instance with the data for the tree node.
</dd>
<dt>AIsEnabled</dt>
<dd>
Variable parameter which indicates whether the tree node is enabled on the 
control. <b>True</b> when enabled, otherwise <b>False</b>.
</dd>
</dl>
<p>
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.
</p>
</descr>
<seealso/>
</element>

<element name="TTreeFilterEdit.OnFilterNode">
<short>
Event handler signalled to determine if a tree node matches the Filter for 
the control.
</short>
<descr>
<p>
<var>OnFilterNode</var> is a <var>TFilterNodeEvent</var> 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.
</p>
<p>
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.
</p>
<p>
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 <b>False</b>, the OnFilterItem event 
handler is signalled to check visibility for the node using its text and data. 
If the Done argument is set to <b>True</b>, the OnFilterItem handler is not 
signalled and the return value from the handler determines the visibility for 
the node.
</p>
</descr>
<seealso>
<link id="TTreeFilterEdit.FilteredTreeview"/>
<link id="TFilterNodeEvent"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.Filter">TCustomControlFilterEdit.Filter</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.DoFilterItem">TCustomControlFilterEdit.DoFilterItem</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.OnFilterItemEx">TCustomControlFilterEdit.OnFilterItemEx</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.OnFilterItem">TCustomControlFilterEdit.OnFilterItem</link>
</seealso>
</element>

<element name="TTFENodeData">
<short>
Base class used to represent a tree node and the branch where it is stored.
</short>
<descr>
<p>
TreeFilterEditNodeData is the ancestor for the TFileNameItem type.
</p>
</descr>
<seealso>
<link id="TTreeFilterBranch"/>
<link id="TFileNameItem"/>
<link id="#lcl.comctrls.TTreeNode">TTreeNode</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.StoreSelection">TCustomControlFilterEdit.StoreSelection</link>
</seealso>
</element>
<element name="TTFENodeData.Node">
<short>Tree node for the class instance.</short>
</element>
<element name="TTFENodeData.Branch">
<short>Branch where the tree node is stored.</short>
</element>

<element name="TFileNameItem">
<short>
Stores information about a file name and the tree node which represents it.
</short>
<descr/>
<seealso>
<link id="TTFENodeData"/>
</seealso>
</element>
<element name="TFileNameItem.Data">
<short>
Pointer to the Object instance associated with the file aname in the instance.
</short>
<descr/>
<seealso/>
</element>
<element name="TFileNameItem.Filename">
<short>
Path and name for the file represented in the class instance.
</short>
<descr/>
<seealso/>
</element>

<element name="TFileNameItem.Create">
<short>
Constructor for the class instance.
</short>
<descr/>
<seealso/>
</element>
<element name="TFileNameItem.Create.AFilename">
<short>
Value assigned to the Filename member.
</short>
</element>
<element name="TFileNameItem.Create.AData">
<short>
Value assigned to the Data member.
</short>
</element>

</module>
<!-- TreeFilterEdit -->
</package>
</fpdoc-descriptions>