<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
<package name="LazControls">
<!--
========================================================================
ListFilterEdit
========================================================================
-->
<module name="ListFilterEdit">
<short>
Implements a control used to filter the items in an associated list box.
</short>
<descr>
<p>
<file>listfilteredit.pas</file> contains classes and types used to implement 
the <var>TListFilterEdit</var> control, an edit control which filters values 
found in an associated list box.
</p>
<p>
<file>listfilteredit.pas</file> is part of the <file>LazControls</file> 
package.
</p>
</descr>

<!-- unresolved external references -->
<element name="Classes"/>
<element name="SysUtils"/>
<element name="Math"/>
<element name="LCLType"/>
<element name="Graphics"/>
<element name="StdCtrls"/>
<element name="EditBtn"/>
<element name="CheckLst"/>
<element name="LazFileUtils"/>
<element name="LazUTF8"/>
<element name="AvgLvlTree"/>

<element name="TImageIndexEvent">
<short>
Not used in the current implementation.
</short>
<descr/>
<seealso/>
</element>
<element name="TImageIndexEvent.Result"/>
<element name="TImageIndexEvent.Str"/>
<element name="TImageIndexEvent.Data"/>
<element name="TImageIndexEvent.IsEnabled"/>

<element name="TListFilterEdit">
<short>
Implements an edit control used to filter items from an associated TListBox 
control.
</short>
<descr>
<p>
<var>TListFilterEdit</var> is a <var>TCustomControlFilterEdit</var> 
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
</descr>
<seealso>
<link id="#lcl.editbtn.TCustomControlFilterEdit">TCustomControlFilterEdit</link>
<link id="#lcl.stdctrls.TCustomListBox">TCustomListBox</link>
<link id="#lcl.stdctrls.TListBox">TListBox</link>
<link id="#lcl.checklst.TCheckListBox">TCheckListBox</link>
</seealso>
</element>

<!-- private -->
<element name="TListFilterEdit.FFilteredListbox">
<short>The list box control with the items for the control.</short>
</element>

<element name="TListFilterEdit.FSelectionList">
<short>Stores / restores the selections in the associated control.</short>
</element>

<element name="TListFilterEdit.FSimpleSelection">
<short>
Stores a flag that indicates a single selection is used for the control.
</short>
</element>

<element name="TListFilterEdit.FOriginalData">
<short>The original item values from the associated list box control.</short>
</element>

<element name="TListFilterEdit.FSortedData">
<short>Item values sorted for viewing in the associated list box.</short>
</element>

<element name="TListFilterEdit.FCheckedItems">
<short>
Contains the checked items for an associated TCheckListBox control.
</short>
</element>

<element name="TListFilterEdit.CompareFNs">
<short>
Implements the routine used to order list Items when SortData is enabled.
</short>
<descr>
<p>
<var>CompareFNs</var> is an <var>Integer</var> 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 <file>lazfileutils.pas</file> 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.
</p>
<p>
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.
</p>
<p>
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.
</p>
</descr>
<seealso>
<link id="TListFilterEdit.SortAndFilter"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.SortData">TCustomControlFilterEdit.SortData</link>
</seealso>
</element>
<element name="TListFilterEdit.CompareFNs.Result">
<short>Position for AFilename1 relative to AFilename2.</short>
</element>
<element name="TListFilterEdit.CompareFNs.AFilename1">
<short>List item caption from Items compared in the method.</short>
</element>
<element name="TListFilterEdit.CompareFNs.AFilename2">
<short>List item caption from the sorted data compared in the method.</short>
</element>

<element name="TListFilterEdit.SetFilteredListbox">
<short>Sets the value for the FilteredListbox property.</short>
</element>
<element name="TListFilterEdit.SetFilteredListbox.AValue">
<short>New value for the FilteredListbox property.</short>
</element>

<!-- protected -->
<element name="TListFilterEdit.Notification">
<short>
Handles a notification when a component is added to or removed from the 
control.
</short>
<descr>
<p>
<var>Notification</var> is an overridden method in 
<var>TListFilterEdit</var>, and calls the inherited method on entry. It 
ensures that the <var>FilteredListbox</var> property is set to <b>Nil</b> 
when the component is removed from the class instance. It also sets the value 
for <var>IdleConnected</var> to <b>False</b>, and resets the internal update 
flag for the control.
</p>
</descr>
<seealso>
<link id="TListFilterEdit.FilteredListbox"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.IdleConnected">TCustomControlFilterEdit.IdleConnected</link>
<link id="#lcl.controls.TControl.Notification">TControl.Notification</link>
</seealso>
</element>
<element name="TListFilterEdit.Notification.AComponent">
<short>Component for the notification.</short>
</element>
<element name="TListFilterEdit.Notification.Operation">
<short>Operation for the component notification.</short>
</element>

<element name="TListFilterEdit.MoveTo">
<short>
Changes the position in FilteredListbox and optionally selects the value.
</short>
<descr/>
<seealso/>
</element>
<element name="TListFilterEdit.MoveTo.AIndex">
<short>New position in FilteredListbox.</short>
</element>
<element name="TListFilterEdit.MoveTo.ASelect">
<short>
<b>True</b> to add the list item to Selected items in the list box.
</short>
</element>

<element name="TListFilterEdit.MoveNext">
<short>
Moves to the next item in FilteredListbox and optionally selects the value.
</short>
<descr/>
<seealso/>
</element>
<element name="TListFilterEdit.MoveNext.ASelect">
<short>
<b>True</b> to add the list item to the Selected items in the list box.
</short>
</element>

<element name="TListFilterEdit.MovePrev">
<short>
Moves to the previous item in FilteredListbox and optionally selects the 
value.
</short>
<descr/>
<seealso/>
</element>
<element name="TListFilterEdit.MovePrev.ASelect">
<short>
<b>True</b> to add the list item to the Selected items in the list box.
</short>
</element>

<element name="TListFilterEdit.MovePageUp">
<short>
Moves the position in FilteredListbox by one page towards the start of the 
list.
</short>
<descr/>
<seealso/>
</element>
<element name="TListFilterEdit.MovePageUp.ASelect">
<short>
<b>True</b> to add the list item to the Selected items in the list box.
</short>
</element>

<element name="TListFilterEdit.MovePageDown">
<short>
Moves the position in FilteredListbox by one page towards the end of the list.
</short>
<descr/>
<seealso/>
</element>
<element name="TListFilterEdit.MovePageDown.ASelect">
<short>
<b>True</b> to add the list item to the Selected items in the list box.
</short>
</element>

<element name="TListFilterEdit.MoveHome">
<short>
Moves the position in FilteredListbox to the first entry in the list.
</short>
<descr/>
<seealso/>
</element>
<element name="TListFilterEdit.MoveHome.ASelect">
<short>
<b>True</b> to add the list item to the Selected items in the list box.
</short>
</element>

<element name="TListFilterEdit.MoveEnd">
<short>
Moves the position in FilteredListbox to the last entry in the list.
</short>
<descr/>
<seealso/>
</element>
<element name="TListFilterEdit.MoveEnd.ASelect">
<short>
<b>True</b> to add the list item to the Selected items in the list box.
</short>
</element>

<element name="TListFilterEdit.ReturnKeyHandled">
<short>
Returns <b>True</b> if a Return key press was forwarded to the list box.
</short>
<descr>
<p>
<var>ReturnKeyHandled</var> is an overridden method in 
<var>TListFilterEdit</var>. It implements the abstract virtual method defined 
in the ancestor class.
</p>
<p>
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.
</p>
<p>
No actions are performed in the method if FilteredListbox or its OnKeyPress 
event handler have not been assigned.
</p>
</descr>
<seealso>
<link id="TListFilterEdit.FilteredListbox"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.EditKeyDown">TCustomControlFilterEdit.EditKeyDown</link>
</seealso>
</element>
<element name="TListFilterEdit.ReturnKeyHandled.Result">
<short>
<b>True</b> if a Return key press was forwarded to the list box.
</short>
</element>

<element name="TListFilterEdit.SortAndFilter">
<short>
Copies string and object values from Items to SortData, and sorts and filters 
the item values.
</short>
<descr>
<p>
<var>SortAndFilter</var> is an overridden method in 
<var>TListFilterEdit</var>. 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.
</p>
<p>
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.
</p>
<p>
SortAndFilter is called from the ApplyFilter method, and indirectly when the 
OnIdle handler applies a pending update for the control.
</p>
<p>
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.
</p>
</descr>
<seealso>
<link id="#lcl.editbtn.TCustomControlFilterEdit.Filter">TCustomControlFilterEdit.Filter</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.SortData">TCustomControlFilterEdit.SortData</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.DoFilterItem">TCustomControlFilterEdit.DoFilterItem</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.DoDefaultFilterItem">TCustomControlFilterEdit.DoDefaultFilterItem</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.OnFilterItemEx">TCustomControlFilterEdit.OnFilterItemEx</link>
<link id="#rtl.classes.TStringList">TStringList</link>
</seealso>
</element>

<element name="TListFilterEdit.ApplyFilterCore">
<short>
Copies sorted list box data which matches the filter value to the 
FilteredListBox control.
</short>
<descr>
<p>
<var>ApplyFilterCore</var> is an overridden method in 
<var>TListFilterEdit</var> 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.
</p>
<p>
No actions are performed in the method if FilteredListbox has not been 
assigned.
</p>
<p>
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.
</p>
<p>
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 <b>True</b> when the 
internal map contains an entry with the caption for the list item.
</p>
<p>
The selected item in FilteredListBox is also updated to match the SelectedPart 
property for the control.
</p>
<p>
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.
</p>
<p>
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.
</p>
</descr>
<seealso>
<link id="TListFilterEdit.FilteredListbox"/>
<link id="TListFilterEdit.SimpleSelection"/>
<link id="TListFilterEdit.MoveTo"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.Text">TCustomControlFilterEdit.Text</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.OnCheckItem">TCustomControlFilterEdit.OnCheckItem</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.Filter">TCustomControlFilterEdit.Filter</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.ApplyFilterCore">TCustomControlFilterEdit.ApplyFilterCore</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.SelectedPart">TCustomControlFilterEdit.SelectedPart</link>
</seealso>
</element>

<element name="TListFilterEdit.GetDefaultGlyphName">
<short>
Gets the name for the resource used as the default glyph in the control.
</short>
<descr/>
<seealso>
<link id="#lcl.editbtn.TCustomEditButton.Glyph">TCustomEditButton.Glyph</link>
<link id="#lcl.editbtn.TCustomEditButton.LoadDefaultGlyph">TCustomEditButton.LoadDefaultGlyph</link>
<link id="#lcl.editbtn.TCustomEditButton.GlyphChanged">TCustomEditButton.GlyphChanged</link>
</seealso>
</element>
<element name="TListFilterEdit.GetDefaultGlyphName.Result">
<short>
Name of the resource with the default image used in Glyph.
</short>
</element>

<!-- public -->
<element name="TListFilterEdit.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> 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.
</p>
</descr>
<seealso>
<link id="TListFilterEdit.Items"/>
<link id="TListFilterEdit.SelectionList"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.Create">TCustomControlFilterEdit.Create</link>
</seealso>
</element>
<element name="TListFilterEdit.Create.AOwner">
<short>Owner of the class instance.</short>
</element>

<element name="TListFilterEdit.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. 
Destroy ensures that resources allocated to members in the class instance are 
freed, including:
</p>
<ul>
<li>Items</li>
<li>SelectionList</li>
<li>The internal member for sorted list item data.</li>
<li>The internal member for check box-style list items.</li>
</ul>
<p>
Destroy calls the inherited method prior to exit.
</p>
</descr>
<seealso>
<link id="TListFilterEdit.Items"/>
<link id="TListFilterEdit.SelectionList"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.Destroy">TCustomControlFilterEdit.Destroy</link>
</seealso>
</element>

<element name="TListFilterEdit.RemoveItem">
<short>
Removes the specified string value from the Items property.
</short>
<descr>
<p>
<var>RemoveItem</var> 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.
</p>
<p>
No actions are performed in the method if AItem is not found in the Items 
property.
</p>
</descr>
<seealso>
<link id="TListFilterEdit.Items"/>
<link id="TListFilterEdit.FilteredListbox"/>
<link id="#lcl.checklst.TCheckListBox">TCheckListBox</link>
<link id="#rtl.classes.TStringList.IndexOf">TStringList.IndexOf</link>
<link id="#rtl.classes.TStringList.Delete">TStringList.Delete</link>
</seealso>
</element>
<element name="TListFilterEdit.RemoveItem.AItem">
<short>Item located and removed in the method.</short>
</element>

<element name="TListFilterEdit.ItemWasClicked">
<short>
Notifies the control when the checked state for an item has been changed.
</short>
<descr>
<p>
<var>ItemWasClicked</var> 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.
</p>
<p>
An example of its usage can be found in the 
<file>ide/editorfilemanager.pas</file> unit in the Lazarus IDE.
</p>
</descr>
<seealso>
<link id="TListFilterEdit.FilteredListbox"/>
<link id="#lcl.checklst.TCheckListBox">TCheckListBox</link>
</seealso>
</element>
<element name="TListFilterEdit.ItemWasClicked.AItem">
<short>
String with the list item changed in an associated checked list box control.
</short>
</element>
<element name="TListFilterEdit.ItemWasClicked.IsChecked">
<short>
Checked state for the list box item.
</short>
</element>

<element name="TListFilterEdit.StoreSelection">
<short>
Stores the selected list item(s) in FilteredListbox to the SelectionList for 
the control.
</short>
<descr>
<p>
<var>StoreSelection</var> is an overridden method in 
<var>TListFilterEdit</var> 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.
</p>
<p>
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.
</p>
<p>
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.
</p>
</descr>
<seealso>
<link id="TListFilterEdit.FilteredListbox"/>
<link id="TListFilterEdit.SelectionList"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.Filter">TCustomControlFilterEdit.Filter</link>
<link id="#lcl.stdctrls.TCustomListBox.Selected">TCustomListBox.Selected</link>
</seealso>
</element>

<element name="TListFilterEdit.RestoreSelection">
<short>
Restores values in SelectionList as the selected Items in FilteredListbox.
</short>
<descr/>
<seealso/>
</element>

<element name="TListFilterEdit.SimpleSelection">
<short>
Indicates whether a single selection has been made using the FilteredListbox 
for the control.
</short>
<descr>
<p>
The property value is updated in StoreSelection, and is set to <b>True</b> 
when SelectionList contains a single entry. The property value is updated 
before the items in SelectionList are checked.
</p>
<p>
It is used in RestoreSelection to prevent un-needed updates to check boxes in 
SelectionList.
</p>
<p>
It is also used in the ApplyFilterCore method when checked values in Items 
and SelectionList are located and displayed in the FilteredListbox control.
</p>
</descr>
<seealso/>
</element>

<element name="TListFilterEdit.SelectionList">
<short>
The list of selected list items for the FilteredListbox control.
</short>
<descr>
<p>
<var>SelectionList</var> is a read-only <var>TStringList</var> 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.
</p>
<p>
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.
</p>
</descr>
<seealso>
<link id="TListFilterEdit.StoreSelection"/>
<link id="TListFilterEdit.RestoreSelection"/>
<link id="TListFilterEdit.FilteredListbox"/>
<link id="TListFilterEdit.SortAndFilter"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.Filter">TCustomControlFilterEdit.Filter</link>
<link id="#lcl.stdctrls.TCustomListBox.Selected">TCustomListBox.Selected</link>
</seealso>
</element>

<element name="TListFilterEdit.Items">
<short>
Contains the list items which are filtered and displayed for the associated 
list box control.
</short>
<descr>
<p>
<var>Items</var> is a read-only <var>TStringList</var> 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.
</p>
<p>
Use SelectionList to access the list item(s) which are marked as Selected in 
associated list box control.
</p>
</descr>
<seealso>
<link id="TListFilterEdit.SelectionList"/>
<link id="TListFilterEdit.FilteredListbox"/>
<link id="TListFilterEdit.SelectionList"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.Filter">TCustomControlFilterEdit.Filter</link>
<link id="#lcl.stdctrls.TCustomListBox.Items">TCustomListBox.Items</link>
</seealso>
</element>

<!-- published -->
<element name="TListFilterEdit.FilteredListbox">
<short>
The list box associated with the filtered edit control.
</short>
<descr>
<p>
<var>FilteredListbox</var> is a <var>TCustomListBox</var> 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. 
</p>
<p>
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.
</p>
<p>
Assigning a new value to the property causes the Filter and Items properties 
for the control to be updated when AValue is not <b>Nil</b>. 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 ('').
</p>
<p>
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.
</p>
</descr>
<seealso>
<link id="TListFilterEdit.Items"/>
<link id="TListFilterEdit.SelectionList"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.Filter">TCustomControlFilterEdit.Filter</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.InternalSetFilter">TCustomControlFilterEdit.InternalSetFilter</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.Text">TCustomControlFilterEdit.Text</link>
<link id="#lcl.stdctrls.TCustomListBox">TCustomListBox</link>
<link id="#lcl.stdctrls.TListBox">TListBox</link>
<link id="#lcl.checklst.TCheckListBox">TCheckListBox</link>
</seealso>
</element>

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