<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
<package name="LazControls">
<!--
========================================================================
ListViewFilterEdit
========================================================================
-->
<module name="ListViewFilterEdit">
<short>
Implements an edit control used to filter an associated TListView control.
</short>
<descr>
<p>
<file>listviewfilteredit.pas</file> contains classes and types used to 
implement the <var>TListViewFilterEdit</var> control. It is used to filter the 
items displayed for an associated <var>TListView</var> control by the caption 
or sub-items in list item data.
</p>
<p>
<file>listviewfilteredit.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="Fgl"/>
<element name="LCLType"/>
<element name="Graphics"/>
<element name="ComCtrls"/>
<element name="EditBtn"/>
<element name="LazUTF8"/>


<element name="TListViewDataItem">
<short>
Record type with data and lines of text for an item in a list view control.
</short>
<descr>
<p>
TListViewDataItem is the typed maintained in TListViewDataList, and passed an 
argument to the method in TListViewFilterEdit which finds matches for its 
Filter criteria.
</p>
</descr>
<seealso>
<link id="TListViewDataList"/>
<link id="TListViewFilterEdit.SortAndFilter"/>
</seealso>
</element>

<element name="TListViewDataItem.Data">
<short>Pointer to the data for the list item.</short>
<descr/>
<seealso>
<link id="#lcl.comctrls.TListItem.Data">TListItem.Data</link>
</seealso>
</element>

<element name="TListViewDataItem.StringArray">
<short>
Array of String values with the text displayed for the list item.
</short>
<descr/>
<seealso>
<link id="#rtl.sysutils.TStringArray">TStringArray</link>
</seealso>
</element>

<element name="TListViewDataItem.OperatorEqual">
<short>
Implements the Equal (=) comparison operator for TListViewDataItem instances.
</short>
<descr>
<p>
The return value is <b>True</b> when both the <var>Data</var> and the 
<var>StringArray</var> for the compared <var>TListViewDataItem</var> 
instances are the same.
</p>
</descr>
<seealso/>
</element>
<element name="TListViewDataItem.OperatorEqual.Result">
<short>
<b>True</b> when the compared items have the same Data and StringArray values.
</short>
</element>
<element name="TListViewDataItem.OperatorEqual.a">
<short>TListViewDataItem instance for the comparison operator.</short>
</element>
<element name="TListViewDataItem.OperatorEqual.b">
<short>TListViewDataItem instance for the comparison operator.</short>
</element>

<element name="TListViewDataList">
<short>List container for TListViewDataItem instances.</short>
<descr>
<p>
<var>TListViewDataList</var> is a specialization of TFPGList to use 
TListViewDataItem instances in the container. TListViewDataList is the type 
used to implement the <var>Items</var> property in 
<var>TListViewFilterEdit</var>.
</p>
</descr>
<seealso>
<link id="TListViewDataItem"/>
<link id="TListViewFilterEdit.Items"/>
</seealso>
</element>

<element name="TListViewFilterEdit">
<short>
Implements a control used to filter list items in an associated TListView 
control.
</short>
<descr>
<p>
<var>TListViewFilterEdit</var> is a <var>TCustomControlFilterEdit</var> 
descendant which implements a control used to filter list item data from an 
associated TCustomListView control. It includes the FilteredListview property 
which provides the original list items and selections, and displays the 
filtered results. Overridden methods are provided to apply the filter and 
sort the list items for the associated list view control. The button on the 
edit control is used to clear the filter applied to the list items. Other 
overridden methods are provided to navigate between and select the filtered 
list items.
</p>
<remark>
TListViewFilterEdit requires FilteredListview to have list items available in 
its Items property. This prevents use of virtual mode (when OwnerData is 
<b>True</b>) in the associated list view control.
</remark>
</descr>
<seealso>
<link id="#lcl.editbtn.TCustomControlFilterEdit">TCustomControlFilterEdit</link>
</seealso>
</element>

<!-- private -->
<element name="TListViewFilterEdit.FFilteredListView">
<short>TListView control showing the filtered data.</short>
</element>

<element name="TListViewFilterEdit.FByAllFields">
<short>Stores the value for the ByAllFields property.</short>
</element>

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

<element name="TListViewFilterEdit.FOriginalData">
<short>Data supplied by the caller through the Items property.</short>
</element>

<element name="TListViewFilterEdit.FFilteredData">
<short>Data sorted for viewing.</short>
</element>

<element name="TListViewFilterEdit.MatchesFilter">
<short>
<b>True</b> when the list view item matches a filter condition for the 
control.
</short>
</element>
<element name="TListViewFilterEdit.MatchesFilter.Result">
<short>
<b>True</b> when the list view item matches a filter condition for the 
control.
</short>
</element>
<element name="TListViewFilterEdit.MatchesFilter.AData">
<short>
TListViewDataItem instance with the strings and a pointer to data used in the 
filter comparison.
</short>
</element>

<element name="TListViewFilterEdit.SetByAllFields">
<short>
Sets the value for the ByAllFields property.
</short>
<descr/>
<seealso>
<link id="TListViewFilterEdit.ByAllFields"/>
</seealso>
</element>
<element name="TListViewFilterEdit.SetByAllFields.AValue">
<short>
New value for the ByAllFields property.
</short>
</element>

<element name="TListViewFilterEdit.SetFilteredListview">
<short>Sets the value for the FilteredListview property.</short>
<seealso>
<link id="TListViewFilterEdit.FilteredListview"/>
</seealso>
</element>
<element name="TListViewFilterEdit.SetFilteredListview.AValue">
<short>New value for the FilteredListview property.</short>
</element>

<element name="TListViewFilterEdit.Notification">
<short>
Handles a notification message received when a component is added to or 
removed from the control.
</short>
<descr>
<p>
Overridden in <var>TListViewFilterEdit</var> to ensure that the 
<var>FilteredListview</var> property is set to <b>Nil</b> when the component 
is removed from the control.
</p>
</descr>
<seealso>
<link id="TListViewFilterEdit.FilteredListview"/>
<link id="#lcl.controls.TControl.Notification">TControl.Notification</link>
</seealso>
</element>
<element name="TListViewFilterEdit.Notification.AComponent">
<short>Component for the notification message.</short>
</element>
<element name="TListViewFilterEdit.Notification.Operation">
<short>Operation for the component.</short>
</element>

<element name="TListViewFilterEdit.GetLastSelectedIndex">
<short>Gets the ordinal position for the last selected list view item.</short>
<descr>
<p>
The return value is retrieved from the Index property in LastSelected (when 
assigned). The value is -1 if LastSelected has not been assigned.
</p>
</descr>
<seealso>
<link id="#lcl.comctrls.TCustomListView.LastSelected">TCustomListView.LastSelected</link>
</seealso>
</element>
<element name="TListViewFilterEdit.GetLastSelectedIndex.Result">
<short>
Ordinal position for the last selected list view item, or -1 when 
LastSelected has not been assigned.
</short>
</element>

<element name="TListViewFilterEdit.MoveTo">
<short>
Changes the selection for the associated list view control to the specified 
item position.
</short>
<descr/>
<seealso/>
</element>
<element name="TListViewFilterEdit.MoveTo.AIndex">
<short>
Ordinal position for the list item to select, multi-select, or de-select.
</short>
</element>
<element name="TListViewFilterEdit.MoveTo.ASelect">
<short>
<b>True</b> if the item is selected or included in a multi-selection.
</short>
</element>

<element name="TListViewFilterEdit.MoveNext">
<short>Moves the list view control to the next list item.</short>
<descr>
<p>
<var>MoveNext</var> is an overridden method in <var>TListViewFilterEdit</var> 
used to position the associated list view control on the next list item which 
matches the filter condition. The value in LastSelected is used as the 
starting point for the navigation request.
</p>
<p>
MoveNext calls the MoveTo method to reposition the list view and determine 
the existing selected state for the list item.
</p>
<p>
ASelect indicates whether the list item is included in the Selection 
(multi-selection) for the list view control.
</p>
<p>
No actions are performed in the method when FilteredListview has not been 
assigned, or does not contain any list items.
</p>
</descr>
<seealso>
<link id="#lcl.editbtn.TCustomControlFilterEdit.MoveNext">TCustomControlFilterEdit.MoveNext</link>
</seealso>
</element>
<element name="TListViewFilterEdit.MoveNext.ASelect">
<short>
<b>True</b> if the new list item should become selected, or added to the 
multi-selection for the list view control.
</short>
</element>

<element name="TListViewFilterEdit.MovePrev">
<short>
Moves the associated list view control to the previous list item.
</short>
<descr/>
<seealso/>
</element>
<element name="TListViewFilterEdit.MovePrev.ASelect">
<short>
<b>True</b> if the list item should be become selected (or multi-selected).
</short>
</element>

<element name="TListViewFilterEdit.MovePageUp">
<short>
Moves the associated list view control towards the start of its list items by 
the number of visible rows for the control.
</short>
<descr/>
<seealso/>
</element>
<element name="TListViewFilterEdit.MovePageUp.ASelect">
<short>
<b>True</b> if the list item should be become selected (or multi-selected).
</short>
</element>

<element name="TListViewFilterEdit.MovePageDown">
<short>
Moves the associated list view control towards the end of its list items by 
the number of visible rows for the control.
</short>
<descr/>
<seealso/>
</element>
<element name="TListViewFilterEdit.MovePageDown.ASelect">
<short>
<b>True</b> if the list item should be become selected (or multi-selected).
</short>
</element>

<element name="TListViewFilterEdit.MoveHome">
<short>
Move the associated list view control to the first list item.
</short>
<descr/>
<seealso/>
</element>
<element name="TListViewFilterEdit.MoveHome.ASelect">
<short>
<b>True</b> if the list item should be become selected (or multi-selected).
</short>
</element>

<element name="TListViewFilterEdit.MoveEnd">
<short>
Move the associated list view control to the last list item.
</short>
<descr/>
<seealso/>
</element>
<element name="TListViewFilterEdit.MoveEnd.ASelect">
<short>
<b>True</b> if the list item should be become selected (or multi-selected).
</short>
</element>

<element name="TListViewFilterEdit.ReturnKeyHandled">
<short>
Returns <b>True</b> if a Return or Enter key press was forwarded to the list 
view control.
</short>
<descr>
<p>
<var>ReturnKeyHandled</var> is an overridden <var>Boolean</var> function used 
to the signal the OnKeyPress event handler in FilteredListView when a Return 
(Enter) key down event is handled for the edit box on the control. No actions 
are performed in the method if either FilteredListView or its OnKeyPress event 
handler have not been assigned.
</p>
</descr>
<seealso>
<link id="TListViewFilterEdit.FilteredListview"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.ReturnKeyHandled">TCustomControlFilterEdit.ReturnKeyHandled</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.EditKeyDown">TCustomControlFilterEdit.EditKeyDown</link>
<link id="#lcl.controls.TWinControl.OnKeyPress">TWinControl.OnKeyPress</link>
</seealso>
</element>
<element name="TListViewFilterEdit.ReturnKeyHandled.Result">
<short>
<b>True</b> if a Return (Enter) key press was forwarded to the list view 
control.
</short>
</element>

<element name="TListViewFilterEdit.SortAndFilter">
<short>
Sorts the data in the associated control and applies the filter.
</short>
<descr>
<p>
<var>SortAndFilter</var> is an overridden method in 
<var>TListViewFilterEdit</var> which implements the abstract virtual method 
from the ancestor class. It discards previous filtering results and 
re-evaluates the filter condition(s) for each of the list items in 
<var>FilteredListview</var>.
</p>
</descr>
<seealso>
<link id="TListViewFilterEdit.FilteredListview"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.SortAndFilter">TCustomControlFilterEdit.SortAndFilter</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.DoFilterItem">TCustomControlFilterEdit.DoFilterItem</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.OnFilterItem">TCustomControlFilterEdit.OnFilterItem</link>
<link id="#lcl.editbtn.TCustomControlFilterEdit.OnFilterItemEx">TCustomControlFilterEdit.OnFilterItemEx</link>
</seealso>
</element>

<element name="TListViewFilterEdit.ApplyFilterCore">
<short>
Implements the method used to apply filter data to the associated control.
</short>
<descr>
<p>
Called when the ApplyFilter method in the ancestor class is executed.
</p>
</descr>
<seealso/>
</element>

<element name="TListViewFilterEdit.GetDefaultGlyphName">
<short>
Gets the default resource name for the button glyph on the control.
</short>
<descr/>
<seealso/>
</element>
<element name="TListViewFilterEdit.GetDefaultGlyphName.Result">
<short>Resource name for the button glyph.</short>
</element>

<element name="TListViewFilterEdit.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the overridden constructor for the class instance, and 
calls the inherited method on entry. It allocates resources for the 
<var>SelectionList</var> and <var>Items</var> properties. It creates an 
internal <var>TListViewDataList</var> instance used to store the filtered 
data for the list view control.
</p>
</descr>
<seealso/>
</element>
<element name="TListViewFilterEdit.Create.AOwner">
<short>Owner of the class instance.</short>
</element>

<element name="TListViewFilterEdit.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. It 
frees resources allocated to <var>SelectionList</var>, <var>Items</var>, and 
the internal filtered data list. It calls the inherited method prior to exit.
</p>
</descr>
<seealso/>
</element>

<element name="TListViewFilterEdit.StoreSelection">
<short>
Clears the selection list for the control, and stores any list items from 
FilteredListview with their Selected property set to <b>True</b>.
</short>
<descr>
<p>
<var>StoreSelection</var> is an overridden method in 
<var>TListViewFilterEdit</var>. It implements the abstract virtual method 
from the ancestor class. StoreSelection calls the Clear method in 
SelectionList to remove existing values in the list. When FilteredListview 
has selected items (SelCount &gt; 0), the Caption for each selected TListItem 
is added to SelectionList.
</p>
<p>
No actions are performed in the method if FilteredListview has not been 
assigned.
</p>
<p>
StoreSelection is used in the implementation for the ApplyFilter method in 
the ancestor class.
</p>
<p>
See RestoreSelection for the action performed to select the list items in 
SelectionList in the Items for the associated TListView control.
</p>
</descr>
<seealso>
<link id="TListViewFilterEdit.SelectionList"/>
<link id="TListViewFilterEdit.RestoreSelection"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.StoreSelection">TCustomControlFilterEdit.StoreSelection</link>
<link id="#lcl.comctrls.TCustomListView.Items">TCustomListView.Items</link>
<link id="#lcl.comctrls.TListItems">TListItems</link>
<link id="#lcl.comctrls.TListItem.Selected">TListItem.Selected</link>
</seealso>
</element>

<element name="TListViewFilterEdit.RestoreSelection">
<short>
Restores the Selected property for list items in FilteredListview which are 
stored in StoreSelection.
</short>
<descr>
<p>
<var>RestoreSelection</var> is an overridden method in 
<var>TListViewFilterEdit</var>. It implements the abstract virtual method 
from the ancestor class.
</p>
<p>
RestoreSelection locates and updates the Selected property for TListItem 
entries found in th associated TListView control. RestoreSelection visits 
each of the caption values in SelectionList and calls the IndexOf method for 
the Items in FilteredListview. When a caption value is located, the Selected 
property for the TListItem entry is set to <b>True</b>.
</p>
<p>
No actions are performed in the method when SelectionList does not contain 
any caption values (Count = 0) or when FilteredListview has not been assigned.
</p>
<p>
RestoreSelection is used in the implementation for the ApplyFilter method in 
the ancestor class.
</p>
<p>
See StoreSelection for the actions performed to store the selected items in 
FilteredListview to the SelectionList property.
</p>
</descr>
<seealso>
<link id="TListViewFilterEdit.SelectionList"/>
<link id="TListViewFilterEdit.StoreSelection"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.RestoreSelection">TCustomControlFilterEdit.RestoreSelection</link>
<link id="#lcl.comctrls.TCustomListView.Items">TCustomListView.Items</link>
<link id="#lcl.comctrls.TListItems">TListItems</link>
<link id="#lcl.comctrls.TListItem.Selected">TListItem.Selected</link>
</seealso>
</element>

<element name="TListViewFilterEdit.SelectionList">
<short>
Identifies the selected items in the associated TListView control.
</short>
<descr>
<p>
<var>SelectionList</var> is a read-only <var>TStringList</var> property which 
contains the list items which are marked as selected in FilteredListview. It 
contains the caption for the TListItem entries in FilteredListview which have 
their Selected property set to <b>True</b>.
</p>
<p>
Caption values are stored in the property when StoreSelection is called when 
the Filter value is applied to the associated list view control. 
SelectionList is cleared and reloaded each time StoreSelection is called.
</p>
<p>
RestoreSelection is used to re-apply the selected state for list items in 
FilteredListview when the Filter is cleared for the control.
</p>
</descr>
<seealso>
<link id="TListViewFilterEdit.FilteredListview"/>
<link id="#lcl.editbtn.TCustomControlFilterEdit.Filter">TCustomControlFilterEdit.Filter</link>
<link id="#lcl.comctrls.TCustomListView.Items">TCustomListView.Items</link>
<link id="#lcl.comctrls.TCustomListView.SelCount">TCustomListView.SelCount</link>
<link id="#lcl.comctrls.TListItems">TListItems</link>
<link id="#lcl.comctrls.TListItem.Caption">TListItem.Caption</link>
<link id="#lcl.comctrls.TListItem.Selected">TListItem.Selected</link>
</seealso>
</element>

<element name="TListViewFilterEdit.Items">
<short>Maintains the data which is filtered and shown in the ListView.</short>
<descr/>
<seealso/>
</element>

<element name="TListViewFilterEdit.FilteredListview">
<short>
The associated list view for the filtered edit control.
</short>
<descr>
<p>
<var>FilteredListview</var> is a <var>TCustomListView</var> property with the 
list view control which contains the list item data and selections filtered 
in the control.
</p>
<p>
Applications must assign a value to the property to enable filtering in edit 
control. No actions are performed in the control when FilteredListview has 
not been assigned (contains Nil), or FilteredListView does not contain any 
list items in its Items property.
</p>
<p>
Changing the value in the property causes the filter Text to be re-applied to 
the control by calling the InternalSetFilter method. Values in the Items 
property are updated to reflect the list Items in FilteredListView after the 
filter has been applied.
</p>
<p>
Use the ByAllFields property to control whether SubItems in the list item data 
are included in the filtered values for the control.
</p>
</descr>
<seealso>
<link id="TListViewFilterEdit.ByAllFields"/>
<link id="TListViewFilterEdit.Items"/>
<link id="TListViewFilterEdit.ApplyFilterCore"/>
<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.comctrls.TCustomListView">TCustomListView</link>
</seealso>
</element>

<element name="TListViewFilterEdit.ByAllFields">
<short>
Indicates whether all fields are compared using the filter.
</short>
<descr>
<p>
ByAllFields is a Boolean property which controls the properties used to find matches for the Filter in the control. When set to <b>True</b>, all properties in a TListViewDataItem are used when searching for a value that matches the Filter. Otherwise, only the Caption (element 0 in the list item data) is used.
</p>
<p>
The default value for the property is <b>False</b>. Changing the value for the 
property causes the inherited InvalidateFilter method to be called to update 
the control.
</p>
<p>
<var>ByAllFields</var> is used in the MatchesFilter method called when 
list item data is selected and sorted for the control.
</p>
</descr>
<seealso/>
</element>
</module>
<!-- ListViewFilterEdit -->
</package>
</fpdoc-descriptions>
