[Expand]General Information
[Collapse]WinForms Controls
  .NET Core Support
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications, and Dialogs
  [Collapse]Editors and Simple Controls
    Included Controls and Components
   [Expand]Common Editor Features and Concepts
   [Collapse]Lookup Editors
     Lookup Editors and Main Settings
     Standard Binding (to Simple Data Types)
     Advanced Binding (to Business Objects)
     Using a Dictionary Lookup Data Source
     Combobox Mode - Allow Entering New Values
     Cascading Lookups
    Popup Container Editor
   [Expand]Token Edit Control
   [Expand]Breadcrumb Edit Control
   [Expand]Range Control
   [Expand]Image Slider
    Camera Control
    Templated ListBox Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Property Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Gantt Control
  [Expand]Chart Control
  [Expand]Map Control
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]PDF Viewer
  [Expand]TreeMap Control
  [Expand]Sunburst Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Report and Dashboard Server
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

Standard Binding (to Simple Data Types)

This topic describes how to set up a lookup editor in standard binding mode, in which the editor's value is of a simple data type (e.g., integer).

Consider an example where two data tables are linked by column values.

You may want to substitute raw data in the Category ID field in the first (main) table with corresponding values from the second table. For instance, you may want to display "Confections" in the main table's Category ID column instead of value 3, and display "Grains/Cereals" instead of value 5. This can be performed by using a lookup editor for editing the Category ID column.

Besides this value substitution feature, a lookup editor provides the editing functionality using a built-in dropdown window, which shows all the available records from the secondary (lookup) data table. An end-user can open the editor's dropdown and change the main editor value by selecting a certain lookup record.

Expanded Setting Up

The following properties need to be specified for a lookup editor in standard binding mode.

  • RepositoryItemLookUpEditBase.DataSource - This identifies the lookup data source - a list of records (objects) displayed in the editor's dropdown.
  • RepositoryItemLookUpEditBase.ValueMember - Specifies a key field (from the lookup data source) that stores unique values used for record identification. This field's values must match the editor's edit value (the data types must match).

    In standard binding mode, a match for the editor's edit value among the lookup records is found by comparing the edit value with values of the ValueMember field of the lookup records. When an end-user picks up a lookup record in the dropdown, the value of this record's ValueMember field is assigned to the editor's edit value.

  • RepositoryItemLookUpEditBase.DisplayMember - Specifies the field (from the lookup data source) whose values are displayed in the lookup editor's edit box.

For standalone lookup editors, these properties are available from the editor's Properties object (e.g., LookUpEdit.Properties).

In-place lookup editors are presented by corresponding RepositoryItem class descendants - RepositoryItemLookUpEdit, RepositoryItemGridLookUpEdit, RepositoryItemSearchControl and RepositoryItemTreeListLookUpEdit. Thus, the DataSource, ValueMember and DisplayMember properties are explicitly available.

Certain lookup editors may need additional customization (e.g., customize columns in the dropdown, specify the dropdown window's width and height, enable text editing, etc.). See the Lookup Editors and Main Settings topic and the LookUpEdit, GridLookUpEdit, SearchLookUpEdit and TreeListLookUpEdit class descriptions for more information.

You may want to bind a standalone lookup editor to a data source. To do this, bind to the editor's edit value, which is specified by the BaseEdit.EditValue inherited property. For an inplace editor, its edit value is provided by a cell in which the editor is embedded.

Expanded Example - LookUpEdit (standalone)

The following example shows how to use a standalone LookUp editor to select a city from a dropdown list.

The example performs the following:

  • creates two lists (Persons and Cities) that contain Person and CityInfo objects. Each Person object is linked to a CityInfo object using the Person.CityID and the matching CityInfo.ID field.
  • uses the TextEdit and LookUpEdit controls to edit the Person.Name and Person.CityID properties, respectively.
  • uses a DataNavigator control to navigate between the Persons list items.
  • sets up the lookup data source to display the Cities list
  • handles the RepositoryItem.CustomDisplayText event to display the CityInfo.City and CityInfo.Country field values in the edit box. If this event is not handled, the edit box displays the RepositoryItemLookUpEditBase.DisplayMember property's value (CityInfo.City).

Expanded Example - LookUpEdit (in-place)

This example shows how to use an in-place LookUpEdit control (RepositoryItemLookUpEdit) for editing cells in a grid column.The lookup editor in the example is used to edit the CategoryID field values from the Products list. However, instead of displaying category IDs, the editor will display corresponding category names in the edit box.The main properties used to set up the LookUpEdit control are:- DataSource - Specifies the lookup data source.- ValueMember - Specifies the field from the lookup data source whose values match the editor's edit value.- DisplayMember - Identifies the field from the lookup data source whose values match the editor's display text.

The following image shows the result.

Expanded Example - GridLookUpEdit

The following example demonstrates how to create and customize a GridLookUpEdit control at runtime.

In the example, a lookup editor will be used to edit the values of the "ProductID" field in the "Order Details" table (NWind database). It must display a list of the available products in the dropdown, which are stored in the "Products" table in the NWind database. By selecting a row from the dropdown an end-user will change the current order's product. Also a data navigator will be created that will assist an end-user to navigate through the "Order Details" table.

To implement the required functionality the following key properties of the lookup editor must be set:

  • The editor's BaseEdit.EditValue property is bound to the "ProductID" field in the "Order Details" table via the DataBindings property.
  • The editor's RepositoryItemLookUpEditBase.DataSource property is set to a DataView object which contains rows from the "Products" table in the NWind database.
  • The editor's RepositoryItemLookUpEditBase.ValueMember property is set to the "ProductID" field in the "Products" table. This field's value must match the editor's edit value, and so the "ProductID" field in the "Order Details" table.
  • The editor's RepositoryItemLookUpEditBase.DisplayMember property is set to the "ProductName" field in the "Products" table. This identifies the field in the DataSource whose values match the editor's display text.
  • Two columns are created within the underlying View via the ColumnView.Columns property. These will display values from the "ProductID" and "ProductName" fields in the dropdown data source.

The result of the example is shown in the following image:

Is this topic helpful?​​​​​​​