Using Lookup Editors
- 10 minutes to read
The ExpressEditors Library introduces four editors implementing lookup functionality:
LookupComboBox editors (represented by the TcxLookupComboBox and TcxDBLookupComboBox classes) display dataset records within a dropdown window in a column-based format
ExtLookupComboBox editors (TcxExtLookupComboBox and TcxDBExtLookupComboBox editors) display a data-aware (banded) table view within the dropdown window
This topic explains how to set up a LookupComboBox control. However, an ExtLookupComboBox editor can be customized in a similar way. The main differences are as follows:
a data source to display in the dropdown window is assigned indirectly, via the view object (the Properties.View attribute). The view determines the visibility of columns, their group indexes, etc.
a column whose data is displayed in the edit box and against which an incremental search/filtering is performed is specified by the Properties.ListFieldItem property
In the first section you can find detailed information on the LookupComboBox and the second section contains information on how to manage the DBLookupComboBox which is designed to edit a dataset field.
1.Setting up a LookupComboBox
The LookupComboBox editor is capable of displaying dataset values. Values are displayed within the edit region of an editor and its dropdown window (which displays data in a tabular manner). To establish a connection between the LookupComboBox and the dataset being displayed within the editor, a user needs to specify the Properties.ListSource property value. This property identifies a TDataSource instance connected to the dataset (for instance, a TTable object). In this example, the LookupComboBox will be connected to the Customer table from the DBDEMOS database shipped with Borland Delphi or C++ Builder. The following image demonstrates how to connect a LookupComboBox to a data source at design time:
The following code line performs the same actions:
After that, you must choose the dataset fields to display within the LookupComboBox by setting the Properties.ListFieldNames property value. This property contains the names of dataset fields and they are separated by semicolon(s). The following image demonstrates how to set up the Properties.ListFieldNames property value at design time:
The following code sets the Properties.ListFieldNames property value:
cxLookupComboBox1.Properties.ListSource := DataSource1;
cxLookupComboBox1.Properties.ListFieldNames := 'Company;Addr1';
Note: On adding a dataset field to the Properties.ListFieldNames property value, a column is added to the Properties.ListColumns collection. Use the list columns collection editor at design time to edit this collection (or modify the Properties.ListFieldNames property value):
This editor allows you to set up different options for the dropdown list columns of a lookup combo box. The main property of each lookup combo box column is the FieldName property, which specifies the dataset field displayed within a specific column. The Sorting and SortOrder properties determine the display order of a specific column. The RepositoryItem property is used to specify the repository item to use as an editor of a specific column’s contents. For instance, a user can assign a TcxCheckBox control to represent the values when the ListSource field contains Boolean data. Other properties define the visual representation of columns within the editor dropdown (Caption, Width, MinWidth and HeaderAlignment properties).
The next important thing is to specify the key field used to identify records of the dataset to be displayed within the editor dropdown. The name of the Properties.ListSource key field must be assigned to the Properties.KeyFieldNames property. The design time approach is demonstrated on the following image:
The following code shoes how to set the Properties.KeyFieldNames property value programmatically:
cxLookupComboBox1.Properties.ListSource := DataSource1;
cxLookupComboBox1.Properties.ListFieldNames := 'Company;Addr1';
cxLookupComboBox1.Properties.KeyFieldNames := 'CustNo';
To choose which field values to display within the edit region of the LookupComboBox, set the Properties.ListFieldIndex property to the required value. This value represents the index of a field within the Properties.ListFieldNames list. In this example, the Properties.ListFieldIndex property value is 0 (the default value).
After this step, the LookupComboBox is connected to the dataset and is fully operational. However, if we launch the application, you will notice that the edit region of the LookupComboBox is empty. When you select a specific record in the dropdown, the value of the record’s field addressed by the Properties.ListFieldIndex property is picked out into the edit region.
The editor’s edit value is also obtained from the selected record and can be accessed via the EditValue property. This property value matches the ListSource key field value (identified via the Properties.KeyFieldNames property). A user can specify the EditValue property by code or via the Object Inspector, but if there is no records whose key field values match the edit value, the editor displays nothing.
If the EditValue property value is specified at design time (see the image below), the LookupComboBox displays an appropriate value:
You may also adjust the editor by setting the Properties.DropDownAutoSize property to True. This allows the width of the LookupComboBoxs dropdown window to resize according to it’s contents. Set the Properties.IncrementalFiltering property to True (the default), to enable filtering during the incremental search. The following image demonstrates a LookupComboBox with the Properties.IncrementalFiltering set to True):
2. Setting up a DBLookupComboBox
The DBLookupComboBox is a data-aware version of the LookupComboBox described in the previous section. The DBLookupComboBox editor is capable of editing dataset values using values from the lookup combo box’s dropdown list.
Setting up a DBLookupComboBox consists of two phases: the first phase includes setting up the editor dropdown list, similar to the actions described in the previous section; and the second, which enables the editing capability of the DBLookupComboBox.
To set up a DBLookupComboBox we must have two datasets: one providing values for the editor dropdown list and another, the one being edited using values from the editor dropdown. In this example, the dataset used for populating the DBLookupComboBox dropdown list is the Customer table of the DBDEMOS database and the Orders table is being edited. A one-to-many relation connects these two tables via their common CustNo field
Connect your DBLookupComboBox to the Customer table as described in the previous section. Unlike the LookupComboBox, the data-aware version uses the DataBinding property instead of the EditValue property to specify the value to display within the edit region of its combo box. Next, assign a TDataSource instance to the DataBinding.DataSource property of the DBLookupComboBox. The following image demonstrates the design time approach:
Use the following code to set a specific value to the DataBinding.DataSource property:
You should now choose a dataset field to be edited via the DBLookupComboBox. This field is identified via the DataBinding.DataField property value. The following image demonstrates how to set the DataBinding.DataField property value at design time:
The following code demonstrates how to set the DataBinding.DataField property value programmatically:
cxDBLookupComboBox1.DataBinding.DataSource := DataSource2;
cxDBLookupComboBox1.DataBinding.DataField := 'CustNo';
Note
A dataset field identified via the DataBinding.DataField property must contain the same values as the field specified via the Properties.KeyFieldNames property. Note: these fields may have different names.
Now that the DBLookupComboBox is set up, let’s test its editing capabilities.
Place the TcxGrid control onto a form. Connect it to the dataset, that you have previously assigned to the DataBinding.DataSource property of the DBLookupComboBox. Now launch the application. If you navigate through the TcxGrid rows, you will notice that the value displayed within the DBLookupComboBox edit region changes. The following image demonstrates the created sample form:
Note that the currently focused row within the TcxGrid has 1380 as a CustNo field value and the DBLookupComboBox displays the Company field value (the Properties.ListSource dataset) corresponding to the current value of the CustNo field.
Now open the DBLookupComboBox dropdown list and select any item except for the currently focused one. See the image below:
Note that the TcxGrid has switched into editing mode for the focused record. If we post the EditValue to the editor, the dataset record will be updated. See the changes on the following image:
The TcxGrid now displays 1351 as the CustNo field value. That value corresponds to the CustNo field value within the Properties.ListSource dataset as displayed within the DBLookupComboBox.
The DBLookupComboBox can obtain data from the lookup field defined for the dataset. This lookup field is a read-only field that displays values at runtime based on the search criteria you specify. In its simplest form, the following parameters are passed to a lookup field: the name of the existing field to search by, the field value to search for and the lookup dataset field to be displayed.
Let’s create a lookup field to display values from the Customer table identified via the Orders table records. Place two TTable components onto a form and connect them to the Orders and Customer tables. Lookup fields can be defined via the Fields Editor for a specific dataset.
Activate the New Field dialog for the dataset corresponding to the Orders table. This dialog provides a convenient way of adding new dataset fields
Enter a new name for the lookup field in the Name edit box. (not an existing field).
Choose a data type for the field from the Type combo box.
Enter the size of the field in the Size edit box (as appropriate).
Select Lookup in the Field type radio group. Selecting Lookup enables the Dataset and Key Fields combo boxes.
Choose a DataSet from the Dataset combo box drop-down list. This will be used to look up field values. The lookup dataset must differ from the dataset for the field component itself, or else a circular reference exception will be raised at runtime. Specifying a lookup dataset enables the Lookup Keys and Result Field combo boxes.
Choose from the Key Fields drop-down list a field in the current dataset for which to match the lookup data set key field values. To match more than one field, enter field names directly instead of choosing from the drop-down list. Separate multiple field names with semicolons. If you are using more than one field, you must use persistent field components.
Choose from the Lookup Keys drop-down list a field in the lookup dataset to match against the Key Fields field you specified in the previous step. If you specified more than one key field, you must specify the same number of lookup keys. To specify more than one field, enter field names directly, separating multiple field names with semicolons.
Choose from the Result Field drop-down list a field in the lookup dataset to return as the value of the lookup field you are creating.
See the image below to know how to populate a New Field dialog:
When a lookup field is used as a data source for a DBLookupComboBox, setting up a lookup combo box is very simple – assign the dataset containing a lookup field to the Databinding.DataSource property and specify the lookup field name as a DataBinding.DataField property value. If an appropriate dataset is active, the DBLookupComboBox displays appropriate values within the edit region and the dropdown list. Note that in this instance, the DBLookupComboBox property values are obtained from the lookup field settings. This relates to the Properties.ListFieldNames property, which is assigned the name of the resulting field and to the Properties.KeyFieldNames property, which is assigned the name of the lookup key field. The Properties.ListSource property value is not specified, but all necessary settings are obtained from the lookup field. A user can add required field names from the lookup dataset to the Properties.ListFieldNames property value, but the name of the resulting lookup field must remain unchanged.