Skip to main content
Table of Contents

Search Edit Guide

TTMSFNCSearchEdit is an edit box that opens a dropdown list when the user types, filtering items as they go. The list supports multiple columns, category buttons, and a configurable search button. Filtering behaviour is controlled by the FilterCondition property.

Basic setup

Add items to the Items collection, set EmptyText for the placeholder, and wire OnSelect to respond when the user picks an entry from the dropdown.

Basic setupPascalC++
// Populate the dropdown item list and handle a selection
TMSFNCSearchEdit1.Items.Add('Apple');
TMSFNCSearchEdit1.Items.Add('Banana');
TMSFNCSearchEdit1.Items.Add('Cherry');
TMSFNCSearchEdit1.Items.Add('Mango');
TMSFNCSearchEdit1.EmptyText := 'Search fruit…';

// OnSelect fires when the user picks an item from the dropdown
procedure TForm1.TMSFNCSearchEdit1Select(Sender: TObject);
begin
  Caption := 'Selected: ' + TMSFNCSearchEdit1.Text;
end;
void __fastcall TForm1::ConfigureSearchEdit()
{
  // Populate the dropdown item list and handle a selection
  TMSFNCSearchEdit1->Items->Add("Apple");
  TMSFNCSearchEdit1->Items->Add("Banana");
  TMSFNCSearchEdit1->Items->Add("Cherry");
  TMSFNCSearchEdit1->Items->Add("Mango");
  TMSFNCSearchEdit1->EmptyText = "Search fruit...";
}

// OnSelect fires when the user picks an item from the dropdown
void __fastcall TForm1::TMSFNCSearchEdit1Select(TObject *Sender)
{
  Caption = "Selected: " + TMSFNCSearchEdit1->Text;
}

AutoDropDown (default True) opens the list automatically as the user types. Set it to False if you want the list to appear only on explicit action.

Multi-column layout, categories, and the search button

The Columns collection defines the display columns, and each item fills one caption per column through Captions[] (adding a string with Items.Add sets only the first column). CategoryID ties an item to an entry of the Categories collection, which populates the popup on the optional category button so users can pre-filter by group; IDs run from 0 to Categories.Count - 1. The SearchButton adds an explicit submit button.

Multi-column layout, categories, and the search buttonPascalC++
// Multi-column dropdown with categories and a search button
procedure TForm1.FormCreate(Sender: TObject);

  procedure AddCity(const ACity, ACountry: string; ACategoryID: Integer);
  var
    item: TSearchListItem;
  begin
    item := TMSFNCSearchEdit1.Items.Add;
    item.Captions[0] := ACity;      // first column
    item.Captions[1] := ACountry;   // second column
    item.CategoryID := ACategoryID; // index into Categories
  end;

var
  col: TColumnItem;
begin
  // Two columns: city and country
  col := TMSFNCSearchEdit1.Columns.Add;
  col.Width := 120;

  col := TMSFNCSearchEdit1.Columns.Add;
  col.Width := 100;

  // Category IDs run from 0 to Categories.Count - 1
  TMSFNCSearchEdit1.Categories.Add('Europe', 0);
  TMSFNCSearchEdit1.Categories.Add('Asia', 1);

  AddCity('Paris', 'France', 0);
  AddCity('Berlin', 'Germany', 0);
  AddCity('Rome', 'Italy', 0);
  AddCity('Tokyo', 'Japan', 1);
  AddCity('Seoul', 'South Korea', 1);

  // Show a search button on the right of the edit
  TMSFNCSearchEdit1.SearchButton.Visible := True;
  TMSFNCSearchEdit1.SearchButton.Text    := 'Go';
end;

procedure TForm1.TMSFNCSearchEdit1SearchButtonClick(Sender: TObject);
begin
  // Trigger an explicit search action when the button is clicked
  ExecuteSearch(TMSFNCSearchEdit1.Text);
end;
// Multi-column dropdown with categories and a search button
void __fastcall TForm1::AddCity(const System::UnicodeString ACity,
  const System::UnicodeString ACountry, int ACategoryID)
{
  TSearchListItem *item = TMSFNCSearchEdit1->Items->Add();
  item->Captions[0] = ACity;       // first column
  item->Captions[1] = ACountry;    // second column
  item->CategoryID = ACategoryID;  // index into Categories
}

void __fastcall TForm1::FormCreate(TObject *Sender)
{
  TColumnItem *col;

  // Two columns: city and country
  col = TMSFNCSearchEdit1->Columns->Add();
  col->Width = 120;

  col = TMSFNCSearchEdit1->Columns->Add();
  col->Width = 100;

  // Category IDs run from 0 to Categories->Count - 1
  TMSFNCSearchEdit1->Categories->Add("Europe", 0);
  TMSFNCSearchEdit1->Categories->Add("Asia", 1);

  AddCity("Paris", "France", 0);
  AddCity("Berlin", "Germany", 0);
  AddCity("Rome", "Italy", 0);
  AddCity("Tokyo", "Japan", 1);
  AddCity("Seoul", "South Korea", 1);

  // Show a search button on the right of the edit
  TMSFNCSearchEdit1->SearchButton->Visible = true;
  TMSFNCSearchEdit1->SearchButton->Text = "Go";
}

void __fastcall TForm1::TMSFNCSearchEdit1SearchButtonClick(TObject *Sender)
{
  // Trigger an explicit search action when the button is clicked
  ExecuteSearch(TMSFNCSearchEdit1->Text);
}
Search edit with a category button, a placeholder, and a Go search button, above its two-column drop-down list of cities and countries Search edit with a category button, a placeholder, and a Go search button, above its two-column drop-down list of cities and countries

Filter condition and loading from a string list

FilterCondition.FilterType switches between mText (match anywhere) and mStartWord. Use LoadStrings to populate the item list in one call from any TStrings source.

Filter condition and loading from a string listPascalC++
procedure TForm1.ConfigureSearchEditFilter;
var
  sl: TStringList;
begin
  // Change how the user's input is matched against the item list.
  // FilterCondition is an object; FilterType picks the match mode:
  // mText (default) matches anywhere in the item text, mStartWord only at the
  // start of a word.
  TMSFNCSearchEdit1.FilterCondition.FilterType := mText;

  // Load items from a string list instead of adding one by one
  sl := TStringList.Create;
  try
    sl.LoadFromFile('products.txt');
    TMSFNCSearchEdit1.LoadStrings(sl);
  finally
    sl.Free;
  end;
end;

// OnChange fires on every keystroke; use it to drive live filtering
procedure TForm1.TMSFNCSearchEdit1Change(Sender: TObject);
begin
  Caption := 'Searching: ' + TMSFNCSearchEdit1.Text;
end;
void __fastcall TForm1::ConfigureSearchEditFilter()
{
  // Change how the user's input is matched against the item list.
  // FilterCondition is an object; FilterType picks the match mode:
  // mText (default) matches anywhere in the item text, mStartWord only at the
  // start of a word.
  TMSFNCSearchEdit1->FilterCondition->FilterType = Fmx::Tmsfncsearchlist::mText;

  // Load items from a string list instead of adding one by one
  TStringList *sl;

  sl = new TStringList();
  try
  {
    sl->LoadFromFile("products.txt");
    TMSFNCSearchEdit1->LoadStrings(sl);
  }
  __finally
  {
    delete sl;
  }
}

// OnChange fires on every keystroke; use it to drive live filtering
void __fastcall TForm1::TMSFNCSearchEdit1Change(TObject *Sender)
{
  Caption = "Searching: " + TMSFNCSearchEdit1->Text;
}

OnChange fires on every character change, making it suitable for driving status indicators or triggering secondary searches.

Changing items from OnSelect

OnSelect fires after the user picks an entry, and the handler may change Items while the drop-down is still settling: delete, insert, or reorder entries. A common use is a most-recently-used list that moves the chosen entry to the top, so the next search starts with what the user picked last. Read the choice from Text first, because the item it came from may be moved or removed by the handler.

Changing items from OnSelectPascalC++
procedure TForm1.FormCreate(Sender: TObject);
begin
  TMSFNCSearchEdit1.EmptyText := 'Recent projects...';
  TMSFNCSearchEdit1.Items.Add('Website relaunch');
  TMSFNCSearchEdit1.Items.Add('Quarterly report');
  TMSFNCSearchEdit1.Items.Add('Mobile app');
  TMSFNCSearchEdit1.OnSelect := TMSFNCSearchEdit1Select;
end;

procedure TForm1.TMSFNCSearchEdit1Select(Sender: TObject);
var
  Choice: string;
  Index: Integer;
begin
  Choice := TMSFNCSearchEdit1.Text;
  Index := TMSFNCSearchEdit1.Items.IndexOf(Choice);

  // Most-recently-used order: move the chosen entry to the top.
  // Changing Items from inside OnSelect is supported.
  if Index > 0 then
  begin
    TMSFNCSearchEdit1.Items.Delete(Index);
    TMSFNCSearchEdit1.Items.Insert(0).Captions[0] := Choice;
  end;
end;
void __fastcall TForm1::FormCreate(TObject *Sender)
{
  TMSFNCSearchEdit1->EmptyText = "Recent projects...";
  TMSFNCSearchEdit1->Items->Add("Website relaunch");
  TMSFNCSearchEdit1->Items->Add("Quarterly report");
  TMSFNCSearchEdit1->Items->Add("Mobile app");
  TMSFNCSearchEdit1->OnSelect = TMSFNCSearchEdit1Select;
}

void __fastcall TForm1::TMSFNCSearchEdit1Select(TObject *Sender)
{
  System::UnicodeString Choice = TMSFNCSearchEdit1->Text;
  int Index = TMSFNCSearchEdit1->Items->IndexOf(Choice);

  // Most-recently-used order: move the chosen entry to the top.
  // Changing Items from inside OnSelect is supported.
  if (Index > 0)
  {
    TMSFNCSearchEdit1->Items->Delete(Index);
    TMSFNCSearchEdit1->Items->Insert(0)->Captions[0] = Choice;
  }
}

Combining columns, categories, filter condition, and selection handling

The following example builds a two-column product search with a category button for filtering by type, mText matching, and a selection handler that populates form fields:

Columns, categories, items, and the select eventPascalC++
procedure TForm1.FormCreate(Sender: TObject);
var
  Cat: TCategoryItem;
  Item: TSearchListItem;
begin
  TMSFNCSearchEdit1.EmptyText := 'Search products...';

  { FilterCondition is an object, not an enum: it describes HOW the typed text
    is matched. FilterType picks the match mode, FilterData picks which part of
    an item is searched. }
  TMSFNCSearchEdit1.FilterCondition.FilterType := mText;      // substring match
  TMSFNCSearchEdit1.FilterCondition.FilterData := fdAll;      // caption + description
  TMSFNCSearchEdit1.FilterCondition.CaseSensitive := False;
  TMSFNCSearchEdit1.FilterCondition.AllColumns := True;

  { Two columns: Name | Price. Columns.Add returns the new TColumnItem. }
  TMSFNCSearchEdit1.Columns.Add.Width := 180;
  TMSFNCSearchEdit1.Columns.Add.Width := 80;

  { Category buttons. The Add overload takes the caption and the ID that items
    reference through CategoryID. }
  Cat := TMSFNCSearchEdit1.Categories.Add('Electronics', 1);
  Cat.Filter := True;
  Cat := TMSFNCSearchEdit1.Categories.Add('Clothing', 2);
  Cat.Filter := True;

  { Items. A TSearchListItem has no single Text property - each column's value
    is set through Captions[ColumnIndex]. }
  Item := TMSFNCSearchEdit1.Items.Add;
  Item.Captions[0] := 'Laptop';
  Item.Captions[1] := '$999';
  Item.CategoryID := 1;

  Item := TMSFNCSearchEdit1.Items.Add;
  Item.Captions[0] := 'Phone';
  Item.Captions[1] := '$699';
  Item.CategoryID := 1;

  Item := TMSFNCSearchEdit1.Items.Add;
  Item.Captions[0] := 'T-Shirt';
  Item.Captions[1] := '$29';
  Item.CategoryID := 2;
end;

{ OnSelect is TTMSFNCSearchDropDownSelectEvent: it receives the selected text
  as a var parameter, not the item object. Assigning NewValue changes what is
  written into the edit. }
procedure TForm1.TMSFNCSearchEdit1Select(Sender: TObject; var NewValue: string);
begin
  edtName.Text := NewValue;
end;
void __fastcall TForm1::FormCreate(TObject *Sender)
{
  TCategoryItem *Cat;
  TSearchListItem *Item;

  TMSFNCSearchEdit1->EmptyText = "Search products...";

  // FilterCondition is an object, not an enum: it describes HOW the typed text
  // is matched. FilterType picks the match mode, FilterData picks which part of
  // an item is searched.
  TMSFNCSearchEdit1->FilterCondition->FilterType = Fmx::Tmsfncsearchlist::mText;      // substring match
  TMSFNCSearchEdit1->FilterCondition->FilterData = fdAll;      // caption + description
  TMSFNCSearchEdit1->FilterCondition->CaseSensitive = false;
  TMSFNCSearchEdit1->FilterCondition->AllColumns = true;

  // Two columns: Name | Price. Columns.Add returns the new TColumnItem.
  TMSFNCSearchEdit1->Columns->Add()->Width = 180;
  TMSFNCSearchEdit1->Columns->Add()->Width = 80;

  // Category buttons. The Add overload takes the caption and the ID that items
  // reference through CategoryID.
  Cat = TMSFNCSearchEdit1->Categories->Add("Electronics", 1);
  Cat->Filter = true;
  Cat = TMSFNCSearchEdit1->Categories->Add("Clothing", 2);
  Cat->Filter = true;

  // Items. A TSearchListItem has no single Text property - each column's value
  // is set through Captions[ColumnIndex].
  Item = TMSFNCSearchEdit1->Items->Add();
  Item->Captions[0] = "Laptop";
  Item->Captions[1] = "$999";
  Item->CategoryID = 1;

  Item = TMSFNCSearchEdit1->Items->Add();
  Item->Captions[0] = "Phone";
  Item->Captions[1] = "$699";
  Item->CategoryID = 1;

  Item = TMSFNCSearchEdit1->Items->Add();
  Item->Captions[0] = "T-Shirt";
  Item->Captions[1] = "$29";
  Item->CategoryID = 2;
}

// On the edit control itself OnSelect is a plain TNotifyEvent: read the
// selected text from the edit's Text property.
void __fastcall TForm1::TMSFNCSearchEdit1Select(TObject *Sender)
{
  edtName->Text = TMSFNCSearchEdit1->Text;
}