TAtlasDBLookupCombo

SelectKey method

procedure SelectKey(const Value: Variant);

Selects the lookup record whose KeyField equals Value and writes Value to the master field.

Checks, in order:

1. The ListSource dataset is active (An active data source is required), browsing and bidirectional (Lookup requires a browsing bidirectional dataset).
2. Value is found with Locate on KeyField (Lookup key does not exist). Null is not searched for; it clears the selection.
3. When DataSource is assigned: its dataset is active, the control is not ReadOnly, and the DataField field is a writable data field (Field is read-only: <name>). A Null value for a Required master field raises Lookup value is required.

The standard SelectKeyValue then puts the master dataset into edit state, assigns the field and fires OnClick. Without a DataSource, only KeyValue changes. The lookup dataset's current record is restored whether or not the call succeeds.

Lookup.SelectKey(3);   // CategoryID := 3, master record in dsEdit
Customers.Post;

SelectText method

function SelectText(const Text: string; Partial: Boolean = True): Boolean;

Searches the first field named in ListField for Text with Locate and loCaseInsensitive. With Partial True (the default) Text must be the start of the value (loPartialKey); with False it must equal the whole value.

Returns False and changes nothing when no record matches. When one matches, passes that record's KeyField value to SelectKey and returns True, so all of SelectKey's checks apply: a read-only master field still raises. The lookup dataset needs the same state as for SelectKey, and its cursor is restored.

if Lookup.SelectText('par') then  // finds "Partner"
  Customers.Post;

Add a lookup in code

Shows the category name of each customer and stores the category's ID in the customer's CategoryID field.

uses Data.DB, Vcl.Controls, Atlas.DBControls;

function AddCategoryLookup(Parent: TWinControl; Customers, Categories: TDataSource): TAtlasDBLookupCombo;
begin
  Result := TAtlasDBLookupCombo.Create(Parent);
  Result.Parent := Parent;
  Result.ListSource := Categories;  // lookup table with ID and Name
  Result.KeyField := 'ID';
  Result.ListField := 'Name';
  Result.DataSource := Customers;   // master table
  Result.DataField := 'CategoryID';
end;

Select by typed text or by key

ChooseCategory(Lookup, 'par') selects Partner and posts; an unknown text returns False and leaves the record alone. SetCategory(Lookup, 9) raises Lookup key does not exist when there is no category 9.

uses Atlas.DBControls;

function ChooseCategory(Lookup: TAtlasDBLookupCombo; const Typed: string): Boolean;
begin
  Result := Lookup.SelectText(Typed);  // case-insensitive prefix match on the first ListField
  if Result then
    Lookup.DataSource.DataSet.Post;    // SelectText leaves the master record in edit state
end;

procedure SetCategory(Lookup: TAtlasDBLookupCombo; CategoryID: Integer);
begin
  Lookup.SelectKey(CategoryID);        // raises EAtlasDatabaseError if the key is not in the list
  Lookup.DataSource.DataSet.Post;
end;