Table of Contents

Items, Columns, and Filtering

TTMSFNCSearchList is a multi-column list with built-in text filtering, category support, and match highlighting. TTMSFNCSearchEdit wraps the same list in a dropdown attached to an edit control.

TTMSFNCSearchList with two columns and category headers

Architecture

Collection Purpose
Columns Defines the number and width of columns.
Items All rows (regular items and category headers).
Categories Optional category definitions for grouping and filtering.

Columns

Each TColumnItem in Columns controls one column:

Property Description
Width Column width in pixels.
Visible Show or hide the column.
ControlFont Use the list's global font when True; use Font when False.
Font Per-column font (effective only when ControlFont = False).
Color Column background colour. clNone uses the control background.

Items

Items is a collection of TSearchListItem. Each item has:

  • ItemType — itItem (regular) or itCategory (category header row).
  • CategoryID — links the item to a category.
  • Columns — per-column data (TSearchColumnItems).

Each TSearchColumnItem exposes:

Property Description
Caption Primary text.
Description Secondary text shown below the caption.
Picture Optional image.
ImageIndex Index in an associated image list.
Color Per-cell background colour override.
TextColor Per-cell text colour override.
Shape Background shape: sNone, sRect, sBar (left-side coloured bar). 
// Build a two-column search list with categories
procedure TForm1.FormCreate(Sender: TObject);
var
  item: TSearchListItem;
  col: TSearchColumnItem;
begin
  TMSFNCSearchList1.BeginUpdate;
  try
    // --- Columns ---
    with TMSFNCSearchList1.Columns.Add do
    begin
      Width   := 60;
      Visible := True;
    end;
    with TMSFNCSearchList1.Columns.Add do
    begin
      Width   := 200;
      Visible := True;
    end;

    // --- Categories ---
    with TMSFNCSearchList1.Categories.Add do
    begin
      ID      := 1;
      Caption := 'Development';
    end;
    with TMSFNCSearchList1.Categories.Add do
    begin
      ID      := 2;
      Caption := 'Design';
    end;

    // --- Category header items ---
    item := TMSFNCSearchList1.Items.Add;
    item.ItemType  := itCategory;
    item.CategoryID := 1;
    item.Columns.Add.Caption := 'Development';

    // --- Regular items ---
    item := TMSFNCSearchList1.Items.Add;
    item.CategoryID := 1;
    item.Columns.Add.Caption := 'DEV';
    col := item.Columns.Add;
    col.Caption     := 'Delphi';
    col.Description := 'Pascal-based RAD IDE';

    item := TMSFNCSearchList1.Items.Add;
    item.CategoryID := 2;
    item.Columns.Add.Caption := 'IW';
    col := item.Columns.Add;
    col.Caption     := 'IntraWeb';
    col.Description := 'Web application framework';
  finally
    TMSFNCSearchList1.EndUpdate;
  end;
end;
Note

Wrap bulk item additions in BeginUpdate / EndUpdate to avoid incremental redraws.

Categories

Each TCategoryItem has:

Property Description
ID Numeric identifier referenced by Items[].CategoryID.
Caption Category display name.
Filter When True, items with this category ID are hidden.

Filtering

Set FilterCondition properties and call IUpdateFilter to apply:

// --- Filter by text ---
TMSFNCSearchList1.FilterCondition.Text            := 'Del';
TMSFNCSearchList1.FilterCondition.AllColumns      := True;   // search all columns
TMSFNCSearchList1.FilterCondition.CaseSensitive   := False;
TMSFNCSearchList1.FilterCondition.FilterType      := mStartWord; // mText/mStartWord/mEndWord/mEntireWord
TMSFNCSearchList1.FilterCondition.FilterData      := fdAll;      // fdCaption/fdDescription/fdAll
TMSFNCSearchList1.FilterCondition.AutoSelect      := True;       // auto-select first match
TMSFNCSearchList1.FilterCondition.MaxCategoryItems := 5;         // max shown per category
TMSFNCSearchList1.IUpdateFilter;

// --- Clear the filter ---
TMSFNCSearchList1.ClearFilter;

// --- Filter by category ---
TMSFNCSearchList1.FilterCondition.Categories := True;
// Mark a category as hidden
TMSFNCSearchList1.Categories.Items[1].Filter := True;  // hide Design category
TMSFNCSearchList1.IUpdateFilter;

// --- Custom item filter event ---
procedure TForm1.TMSFNCSearchList1FilterItem(Sender: TObject;
  AItem: TSearchListItem; var Retain: Boolean);
begin
  // Retain only items from category 1 whose caption starts with 'D'
  Retain := (AItem.CategoryID = 1) and
            AItem.Columns[1].Caption.StartsWith('D', True);
end;
Property Description
Text Text to search for.
AllColumns Search all columns when True; otherwise use Column.
Column Index of the column to search (when AllColumns = False).
CaseSensitive Case-sensitive matching.
FilterType mText (anywhere), mStartWord, mEndWord, mEntireWord.
FilterData fdCaption, fdDescription, or fdAll.
Categories True filters items by category Filter flags.
CategoryItems True removes category header rows when they have no matching children.
AutoSelect Auto-select the first matching item.
MaxCategoryItems Cap the number of retained items per category. 
TMSFNCSearchList1.ClearFilter;  // remove the filter

Match highlighting

The matching portion of text is highlighted during a filter:

TMSFNCSearchList1.Appearance.HighlightColor     := gcYellow;
TMSFNCSearchList1.Appearance.HighlightTextColor := gcBlack;
TMSFNCSearchList1.Appearance.HighlightFontStyle := [fsBold];
Banded list with category filter count
Dual-column list with description search

Appearance

Property Description
ItemHeight Height of regular items.
CategoryItemHeight Height of category header items.
Appearance.Banding Alternate row background colours.
Appearance.BandColorEven / BandColorOdd Even/odd row colours.
Appearance.CategoryColor Category header background.
Appearance.SelectionColor / SelectionTextColor Selected item colours.
Appearance.FilterCount fcShow shows the match count in category headers.
Appearance.FilterCountFormat Format string for the count (default '(%d)').
Column shape set to sRect with short labels

TTMSFNCSearchEdit

TTMSFNCSearchEdit is an edit control that shows a TTMSFNCSearchList dropdown while the user types. Set FilterCondition.Column to determine which column's caption text populates the edit control when an item is selected.

TTMSFNCSearchEdit with dropdown

The optional category button (left of the edit) lets users filter by category. Its popup type is set via CategoryButton.PopupType:

  • pmMenu — plain menu of categories.
  • pmCheck — multi-select checkboxes.
  • pmRadio — single-select radio buttons.
TTMSFNCSearchEdit category selection popup

The optional search button (right of the edit) fires OnSearchButtonClick when clicked.

Combining columns, categories, filtering, and match highlighting

The following example builds a two-column product list with category grouping, applies a live text filter, and highlights matches:

procedure TForm1.FormCreate(Sender: TObject);
var
  cat: TCategoryItem;
  item: TSearchListItem;
begin
  TMSFNCSearchList1.BeginUpdate;

  // Two columns
  TMSFNCSearchList1.Columns.Add.Width := 180; // Name
  TMSFNCSearchList1.Columns.Add.Width := 100; // Price

  // Categories
  cat    := TMSFNCSearchList1.Categories.Add;
  cat.ID := 1; cat.Caption := 'Electronics';
  cat    := TMSFNCSearchList1.Categories.Add;
  cat.ID := 2; cat.Caption := 'Clothing';

  // Items
  for var d in [
    TArray<string>.Create('1', 'Laptop',    '999'),
    TArray<string>.Create('1', 'Phone',     '699'),
    TArray<string>.Create('2', 'T-Shirt',    '29'),
    TArray<string>.Create('2', 'Jeans',      '59')] do
  begin
    item := TMSFNCSearchList1.Items.Add;
    item.CategoryID := StrToInt(d[0]);
    item.Columns.Add.Caption := d[1];
    item.Columns.Add.Caption := '$' + d[2];
  end;

  // Highlight matches in yellow
  TMSFNCSearchList1.Appearance.HighlightColor     := gcYellow;
  TMSFNCSearchList1.Appearance.HighlightTextColor := gcBlack;

  TMSFNCSearchList1.EndUpdate;
end;

procedure TForm1.edtSearchChange(Sender: TObject);
begin
  TMSFNCSearchList1.FilterCondition.Text       := edtSearch.Text;
  TMSFNCSearchList1.FilterCondition.AllColumns := True;
  TMSFNCSearchList1.IUpdateFilter;
end;

See also