DBLookup Extended Dialog Control

The DB Lookup Extended control is a dataset-driven dropdown lookup field for use on report dialog pages. It wraps a grid control and provides incremental search, a multi-column dropdown grid, and full script access to the selected key value and display text.

It is well suited for letting users pick a customer, vendor, item, or any other entity from a list before the report runs — returning the selected key value that can then be used to filter report data.

---

Adding to a Report

Drop a DB Lookup Extended onto a dialog page. Set the following properties in the Object Inspector to connect it to data:

1. Set DataSetName to the name of the dataset that provides the lookup list
2. Set KeyFieldNames to the field whose value will be returned as the selected key
3. Set ListFieldNames to the field (or fields) displayed in the dropdown
4. Optionally double-click the control to open the Column Editor and configure the dropdown grid columns

---

Column Editor

Double-clicking the control in the report designer opens the Lookup Column Editor, which lets you define the columns shown in the dropdown grid. Each column has three settings:

Setting	Description
Field Name	The dataset field to display in this column. If the dataset is open, a dropdown lists available fields.
Caption	The column header text shown in the dropdown grid
Width	The column width in pixels

Column definitions are stored internally as the ColumnDefs property in the format FieldName|Caption|Width separated by semicolons. For example:

CustNo|Customer No|100;CustName|Name|200;City|City|120

---

Properties

Property	Type	Default	Description
DataSetName	String		Name of the report dataset that provides the lookup list
KeyFieldNames	String		The field name whose value is returned as the selected key. Can be a semicolon-delimited list for composite keys.
ListFieldNames	String		The field name(s) shown in the edit portion of the control when a selection is made
ListFieldIndex	Integer	0	Index of the field from ListFieldNames to display in the edit box
ColumnDefs	String		Column definitions for the dropdown grid. Set via the Column Editor or directly as a formatted string.
AutoOpenDataSet	Boolean	False	When True, automatically opens the lookup dataset when the dialog page is activated if it is not already open
IncrementalFiltering	Boolean	True	Filters the dropdown list as the user types
UseContainsOperator	Boolean	False	When True, incremental filtering matches anywhere in the string (contains). When False, matches from the start of the string (starts with).
HighlightSearchText	Boolean	False	Highlights matching text in the dropdown as the user types
DropDownRows	Integer	8	Number of rows visible in the dropdown grid before scrolling
DropDownWidth	Integer	0	Width of the dropdown in pixels. 0 means match the control width.
DropDownHeight	Integer	0	Height of the dropdown in pixels. 0 means automatic.
DropDownSizeable	Boolean	True	Allows the user to resize the dropdown by dragging
DropDownAutoSize	Boolean	False	Automatically sizes the dropdown to fit its content
GridMode	Boolean	False	Displays the dropdown as a full grid rather than a simple list
AutoSelect	Boolean	True	Automatically selects all text when the control receives focus
ImmediateDropDown	Boolean	False	Opens the dropdown immediately when the control is activated
MaxLength	Integer	0	Maximum number of characters the user can type. 0 means unlimited.
Hint	String		Tooltip text shown when the user hovers over the control
ShowHint	Boolean	False	Enables display of the Hint tooltip

---

Runtime Properties

These properties are read-only at design time and are typically accessed from script during or after dialog interaction.

Property	Type	Description
KeyValue	Variant	The key value of the currently selected record. Read or set this from script to get or pre-select a value.
Text	String	The display text currently shown in the edit portion of the control (read-only)

---

Events

Event	Description
OnChange	Fires when the selected value changes. Use this to react to selection changes during the dialog — for example to populate another control based on the selection.
OnClick	Fires when the control is clicked
OnDblClick	Fires when the control is double-clicked
OnEnter	Fires when focus enters the control
OnExit	Fires when focus leaves the control
OnKeyDown	Fires when a key is pressed down
OnKeyPress	Fires when a key is pressed
OnKeyUp	Fires when a key is released
OnMouseDown	Fires when a mouse button is pressed
OnMouseMove	Fires when the mouse moves over the control
OnMouseUp	Fires when a mouse button is released

---

Examples

Reading the selected key value in BeforeStartReport

After the user makes a selection in the dialog and clicks OK, read the KeyValue in BeforeStartReport to use it as a report parameter or dataset filter.

procedure BeforeStartReport;
begin
  // Pass the selected customer ID to a dataset parameter
  SetParam('qryOrders', 'CustomerID', DBLookupExtended1.KeyValue);
end;

Reading the display text

// Show the selected customer name in a report variable
Report.Variables['SelectedCustomer'] := DBLookupExtended1.Text;

Pre-selecting a value from script

// Pre-select a customer by key value when the dialog opens
DBLookupExtended1.KeyValue := 1001;

Reacting to selection changes with OnChange

Wire up the OnChange event to populate a second lookup based on the first selection. For example, selecting a customer could filter an orders lookup.

procedure DBLookupExtended1Change(Sender: TObject);
begin
  // Filter the orders dataset based on selected customer
  SetParam('qryCustomerOrders', 'CustomerID', DBLookupExtended1.KeyValue);
  qryCustomerOrders.Close;
  qryCustomerOrders.Open;
end;

Using the selected value in a SQL WHERE clause

procedure BeforeStartReport;
var
  custID: Variant;
begin
  custID := DBLookupExtended1.KeyValue;
  if not VarIsNull(custID) then
    SetParam('qryReport', 'CustomerID', custID)
  else
    RaiseException('Please select a customer before running this report.');
end;

Configuring ColumnDefs in script

Column definitions can also be set from script if needed, using the pipe-and-semicolon format.

// FieldName|Caption|Width separated by semicolons
DBLookupExtended1.ColumnDefs :=
  'CustNo|Customer No|80;CustName|Name|200;City|City|120';

Contains search vs starts-with search

// Allow matching anywhere in the field (e.g. typing 'smith' finds 'John Smith')
DBLookupExtended1.UseContainsOperator := True;
DBLookupExtended1.HighlightSearchText := True;

---