LookUpEdit Class

The editor that provides lookup functionality using a lightweight grid in a drop-down window.

Assembly: DevExpress.XtraEditors.v19.1.dll

Declaration

C#
VB.NET

[DefaultBindingProperty("EditValue")]
[SmartTagAction(typeof(LookUpEditActions), "Columns", "Columns", SmartTagActionType.CloseAfterExecute)]
[SmartTagAction(typeof(LookUpEditActions), "PopulateColumns", "Populate Columns")]
[ToolboxBitmap(typeof(ToolboxIconsRootNS), "LookUpEdit")]
public class LookUpEdit :
    LookUpEditBase

<DefaultBindingProperty("EditValue")>
<SmartTagAction(GetType(LookUpEditActions), "Columns", "Columns", SmartTagActionType.CloseAfterExecute)>
<SmartTagAction(GetType(LookUpEditActions), "PopulateColumns", "Populate Columns")>
<ToolboxBitmap(GetType(ToolboxIconsRootNS), "LookUpEdit")>
Public Class LookUpEdit
    Inherits LookUpEditBase

The following members return LookUpEdit objects:

Remarks

Demo: LookUp Edit module in the XtraEditors MainDemo

A lookup editor is an editor with an embedded dropdown window, which displays lookup records (the records from which an end-user can select). When a lookup record is selected, the editor’s value (the BaseEdit.EditValue bindable property) and display text are modified accordingly.

The LookUpEdit presents lookup records as a lightweight grid control.

LookUpEditor

To present lookup records using a feature-rich GridControl, use the GridLookUpEdit or SearchLookUpEdit control instead.

To learn how to set up lookup editors in different binding modes, see the following topics:

You may want to filter the popup data source of one (secondary) lookup editor based on the value of another (primary) lookup editor. This scenario is covered in the following topic:

Cascading Lookups

Additional Customization

The following list shows some of the members that help you perform the additional customization of the LookUpEdit control.

RepositoryItemLookUpEditBase.TextEditStyle property - Enables the text editing feature in the edit box.
RepositoryItemLookUpEditBase.ProcessNewValue event - Enables you to add a new record to the lookup data source (RepositoryItemLookUpEditBase.DataSource).
RepositoryItemLookUpEdit.PopulateColumns method - Creates columns for all fields available in the lookup data source (RepositoryItemLookUpEditBase.DataSource).

At design time, you can accomplish this by clicking the Populate Columns link in the editor’s smart tag menu.
RepositoryItemLookUpEdit.Columns - Provides access to the collection of columns displayed in the dropdown window.
RepositoryItemLookUpEdit.GetNotInListValue event - You can add unbound columns to the RepositoryItemLookUpEdit.Columns collection (unbound columns are those that are not bound to any field in the lookup data source). In this case, handle the GetNotInListValue event to populate these columns with data.
RepositoryItemLookUpEdit.PopupWidth - Gets or sets the width of the dropdown window (in pixels).
RepositoryItemLookUpEdit.DropDownRows - Gets or sets the number of rows simultaneously displayed in the dropdown window.
RepositoryItemLookUpEditBase.BestFitMode - Gets or sets the “best-fit” mode for columns in the dropdown window.
RepositoryItem.NullText - Gets or sets the text that presents the editor’s null value (null, System.DBNull.Value and RepositoryItemDateEdit.NullDate - for DateEdit).
RepositoryItemLookUpEdit.SearchMode - Gets or sets whether to immediately apply the found value to the editor as a user types a query, or only highlight the found value in the drop-down window.
RepositoryItemLookUpEdit.AutoSearchColumnIndex - Gets or sets the visible column index against which an incremental search is performed in SearchMode.AutoComplete and SearchMode.OnlyInPopup modes.

To embed a LookUpEdit in a cell within a container control (XtraGrid, XtraTreeList, etc), use the RepositoryItemLookUpEdit component. See the Repositories and Repository Items topic, for more information.

Example

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).

C#
VB.NET

using DevExpress.XtraEditors;
using DevExpress.XtraEditors.Controls;
using System;
using System.Collections.Generic;
using System.Windows.Forms;

namespace WindowsFormsApplication9 {
    public partial class Form1 : Form {
        public Form1() {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e) {
            List<Person> Persons = new List<Person>();
            Persons.Add(new Person() { Name = "Carlos Gonzalez", CityID = 0 });
            Persons.Add(new Person() { Name = "Mario Pontes", CityID = 5 });
            Persons.Add(new Person() { Name = "Horst Kloss", CityID = 2 });
            Persons.Add(new Person() { Name = "Martin Sommer", CityID = 3 });
            Persons.Add(new Person() { Name = "Diego Roel", CityID = 3 });
            Persons.Add(new Person() { Name = "Catherine Dewey", CityID = 4 });
            Persons.Add(new Person() { Name = "Pascale Cartrain", CityID = 4 });
            Persons.Add(new Person() { Name = "Bernardo Batista", CityID = 1 });

            List<CityInfo> Cities = new List<CityInfo>();
            Cities.Add(new CityInfo() { ID = 0, City= "Barquisimeto", Country= "Venezuela", Region="Lara" });
            Cities.Add(new CityInfo() { ID = 1, City = "Rio de Janeiro", Country = "Brazil", Region = "RJ" });
            Cities.Add(new CityInfo() { ID = 2, City = "Cunewalde", Country = "Germany", Region = "" });
            Cities.Add(new CityInfo() { ID = 3, City = "Madrid", Country = "Spain", Region = "" });
            Cities.Add(new CityInfo() { ID = 4, City = "Charleroi", Country = "Belgium", Region = "" });
            Cities.Add(new CityInfo() { ID = 5, City = "Sao Paulo", Country = "Brazil", Region = "SP" });


            DataNavigator dataNavigator1 = new DataNavigator();
            dataNavigator1.Parent = this;
            dataNavigator1.Location = new System.Drawing.Point(12, 12);
            dataNavigator1.Size = new System.Drawing.Size(385, 25);
            TextEdit textEdit1 = new TextEdit();
            textEdit1.Parent = this;
            textEdit1.Location = new System.Drawing.Point(198, 52);
            textEdit1.Size = new System.Drawing.Size(199, 20);
            LookUpEdit lookUpEdit1 = new LookUpEdit();
            lookUpEdit1.Parent = this;
            lookUpEdit1.Location = new System.Drawing.Point(198, 78);
            lookUpEdit1.Size = new System.Drawing.Size(199, 20);


            dataNavigator1.DataSource = Persons;
            textEdit1.DataBindings.Add(new Binding("EditValue", Persons, "Name"));
            lookUpEdit1.DataBindings.Add(new Binding("EditValue", Persons, "CityID"));
            lookUpEdit1.Properties.DataSource = Cities;
            lookUpEdit1.Properties.ValueMember = "ID";
            lookUpEdit1.Properties.DisplayMember = "City";
            lookUpEdit1.Properties.PopulateColumns();
            lookUpEdit1.Properties.Columns["ID"].Visible = false;

            lookUpEdit1.CustomDisplayText += LookUpEdit1_CustomDisplayText;
        }

        // Display the city and country in the edit box
        private void LookUpEdit1_CustomDisplayText(object sender, CustomDisplayTextEventArgs e) {
            LookUpEdit lookUpEdit = sender as LookUpEdit;
            CityInfo city = lookUpEdit.Properties.GetDataSourceRowByKeyValue(e.Value) as CityInfo;
            if(city!=null) {
                e.DisplayText = city.City + ", " + city.Country;
            }
        }
    }

    public class Person {
        public string Name { get; set; }
        public int CityID { get; set; }
    }

    public class CityInfo {
        public int ID { get; set; }
        public string City { get; set; }
        public string Country { get; set; }
        public string Region { get; set; }
    }
}

Imports DevExpress.XtraEditors
Imports DevExpress.XtraEditors.Controls

Public Class Form1
    Private Sub Form1_Load(sender As Object, e As EventArgs) Handles MyBase.Load
        Dim Persons As List(Of Person) = New List(Of Person)()
        Persons.Add(New Person() With {
            .Name = "Carlos Gonzalez",
            .CityID = 0
        })
        Persons.Add(New Person() With {
            .Name = "Mario Pontes",
            .CityID = 5
        })
        Persons.Add(New Person() With {
            .Name = "Horst Kloss",
            .CityID = 2
        })
        Persons.Add(New Person() With {
            .Name = "Martin Sommer",
            .CityID = 3
        })
        Persons.Add(New Person() With {
            .Name = "Diego Roel",
            .CityID = 3
        })
        Persons.Add(New Person() With {
            .Name = "Catherine Dewey",
            .CityID = 4
        })
        Persons.Add(New Person() With {
            .Name = "Pascale Cartrain",
            .CityID = 4
        })
        Persons.Add(New Person() With {
            .Name = "Bernardo Batista",
            .CityID = 1
        })
        Dim Cities As List(Of CityInfo) = New List(Of CityInfo)()
        Cities.Add(New CityInfo() With {
            .ID = 0,
            .City = "Barquisimeto",
            .Country = "Venezuela",
            .Region = "Lara"
        })
        Cities.Add(New CityInfo() With {
            .ID = 1,
            .City = "Rio de Janeiro",
            .Country = "Brazil",
            .Region = "RJ"
        })
        Cities.Add(New CityInfo() With {
            .ID = 2,
            .City = "Cunewalde",
            .Country = "Germany",
            .Region = ""
        })
        Cities.Add(New CityInfo() With {
            .ID = 3,
            .City = "Madrid",
            .Country = "Spain",
            .Region = ""
        })
        Cities.Add(New CityInfo() With {
            .ID = 4,
            .City = "Charleroi",
            .Country = "Belgium",
            .Region = ""
        })
        Cities.Add(New CityInfo() With {
            .ID = 5,
            .City = "Sao Paulo",
            .Country = "Brazil",
            .Region = "SP"
        })

        Dim dataNavigator1 As DataNavigator = New DataNavigator()
        dataNavigator1.Parent = Me
        dataNavigator1.Location = New System.Drawing.Point(12, 12)
        dataNavigator1.Size = New System.Drawing.Size(385, 25)
        Dim textEdit1 As TextEdit = New TextEdit()
        textEdit1.Parent = Me
        textEdit1.Location = New System.Drawing.Point(198, 52)
        textEdit1.Size = New System.Drawing.Size(199, 20)
        Dim lookUpEdit1 As LookUpEdit = New LookUpEdit()
        lookUpEdit1.Parent = Me
        lookUpEdit1.Location = New System.Drawing.Point(198, 78)
        lookUpEdit1.Size = New System.Drawing.Size(199, 20)

        dataNavigator1.DataSource = Persons
        TextEdit1.DataBindings.Add(New Binding("EditValue", Persons, "Name"))
        LookUpEdit1.DataBindings.Add(New Binding("EditValue", Persons, "CityID"))
        LookUpEdit1.Properties.DataSource = Cities
        LookUpEdit1.Properties.ValueMember = "ID"
        LookUpEdit1.Properties.DisplayMember = "City"
        LookUpEdit1.Properties.PopulateColumns()
        LookUpEdit1.Properties.Columns("ID").Visible = False
        AddHandler LookUpEdit1.CustomDisplayText, AddressOf LookUpEdit1_CustomDisplayText
    End Sub

    Private Sub LookUpEdit1_CustomDisplayText(ByVal sender As Object, ByVal e As CustomDisplayTextEventArgs)
        Dim lookUpEdit As LookUpEdit = TryCast(sender, LookUpEdit)
        Dim city As CityInfo = TryCast(lookUpEdit.Properties.GetDataSourceRowByKeyValue(e.Value), CityInfo)
        If city IsNot Nothing Then
            e.DisplayText = city.City & ", " & city.Country
        End If
    End Sub
End Class

Public Class Person
    Public Property Name As String
    Public Property CityID As Integer
End Class

Public Class CityInfo
    Public Property ID As Integer
    Public Property City As String
    Public Property Country As String
    Public Property Region As String
End Class

Example

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.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/lookupedit-standard-binding-to-simple-data-types-t378801

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using System.Windows.Forms;

namespace LookupEdit_StandardBinding {
    static class Program {
        /// <summary>
        /// The main entry point for the application.
        /// </summary>
        [STAThread]
        static void Main() {
            Application.EnableVisualStyles();
            Application.SetCompatibleTextRenderingDefault(false);
            Application.Run(new Form1());
        }
    }
}

using DevExpress.XtraEditors.Repository;
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Windows.Forms;

namespace LookupEdit_StandardBinding {
    public partial class Form1 : Form {
        public Form1() {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e) {
            InitData();

            gridControl1.DataSource = Products;
            gridView1.Columns["UnitPrice"].DisplayFormat.FormatType = DevExpress.Utils.FormatType.Numeric;
            gridView1.Columns["UnitPrice"].DisplayFormat.FormatString = "c2";

            // Create an in-place LookupEdit control.
            RepositoryItemLookUpEdit riLookup = new RepositoryItemLookUpEdit();
            riLookup.DataSource = Categories;
            riLookup.ValueMember = "ID";
            riLookup.DisplayMember = "CategoryName";

            // Enable the "best-fit" functionality mode in which columns have proportional widths and the popup window is resized to fit all the columns.
            riLookup.BestFitMode = DevExpress.XtraEditors.Controls.BestFitMode.BestFitResizePopup;
            // Specify the dropdown height.
            riLookup.DropDownRows = Categories.Count;

            // Enable the automatic completion feature. In this mode, when the dropdown is closed, 
            // the text in the edit box is automatically completed if it matches a DisplayMember field value of one of dropdown rows. 
            riLookup.SearchMode = DevExpress.XtraEditors.Controls.SearchMode.AutoComplete;
            // Specify the column against which an incremental search is performed in SearchMode.AutoComplete and SearchMode.OnlyInPopup modes
            riLookup.AutoSearchColumnIndex = 1;

            // Optionally hide the Description column in the dropdown.
            // riLookup.PopulateColumns();
            // riLookup.Columns["Description"].Visible = false;

            // Assign the in-place LookupEdit control to the grid's CategoryID column.
            // Note that the data types of the "ID" and "CategoryID" fields match.
            gridView1.Columns["CategoryID"].ColumnEdit = riLookup;
            gridView1.BestFitColumns();
        }

        List<Product> Products = new List<Product>();
        List<Category> Categories = new List<Category>();

        private void InitData() {
            Products.Add(new Product() { ProductName = "Sir Rodney's Scones", CategoryID = 3, UnitPrice = 10 });
            Products.Add(new Product() { ProductName = "Gustaf's Knäckebröd", CategoryID = 5, UnitPrice = 21 });
            Products.Add(new Product() { ProductName = "Tunnbröd", CategoryID = 5, UnitPrice = 9 });
            Products.Add(new Product() { ProductName = "Guaraná Fantástica", CategoryID = 1, UnitPrice = 4.5m });
            Products.Add(new Product() { ProductName = "NuNuCa Nuß-Nougat-Creme", CategoryID = 3, UnitPrice = 14 });
            Products.Add(new Product() { ProductName = "Gumbär Gummibärchen", CategoryID = 3, UnitPrice = 31.23m });
            Products.Add(new Product() { ProductName = "Rössle Sauerkraut", CategoryID = 7, UnitPrice = 45.6m });
            Products.Add(new Product() { ProductName = "Thüringer Rostbratwurst", CategoryID = 6, UnitPrice = 123.79m });
            Products.Add(new Product() { ProductName = "Nord-Ost Matjeshering", CategoryID = 8, UnitPrice = 25.89m });
            Products.Add(new Product() { ProductName = "Gorgonzola Telino", CategoryID = 4, UnitPrice = 12.5m });

            Categories.Add(new Category() { ID = 1, CategoryName = "Beverages", Description = "Soft drinks, coffees, teas, beers, and ales" });
            Categories.Add(new Category() { ID = 2, CategoryName = "Condiments", Description = "Sweet and savory sauces, relishes, spreads, and seasonings" });
            Categories.Add(new Category() { ID = 3, CategoryName = "Confections", Description = "Desserts, candies, and sweet breads" });
            Categories.Add(new Category() { ID = 4, CategoryName = "Dairy Products", Description = "Cheeses" });
            Categories.Add(new Category() { ID = 5, CategoryName = "Grains/Cereals", Description = "Breads, crackers, pasta, and cereal" });
            Categories.Add(new Category() { ID = 6, CategoryName = "Meat/Poultry", Description = "Prepared meats" });
            Categories.Add(new Category() { ID = 7, CategoryName = "Produce", Description = "Dried fruit and bean curd" });
            Categories.Add(new Category() { ID = 8, CategoryName = "Seafood", Description = "Seaweed and fish" });
        }
    }

    public class Product {
        public string ProductName { get; set; }
        public decimal UnitPrice { get; set; }
        public int CategoryID { get; set; }
    }

    public class Category {
        public int ID { get; set; }
        public string CategoryName { get; set; }
        public string Description { get; set; }
    }
}

Imports DevExpress.XtraEditors.Repository
Imports System
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Data
Imports System.Drawing
Imports System.Linq
Imports System.Text
Imports System.Threading.Tasks
Imports System.Windows.Forms

Namespace LookupEdit_StandardBinding
    Partial Public Class Form1
        Inherits Form

        Public Sub New()
            InitializeComponent()
        End Sub

        Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs) Handles MyBase.Load
            InitData()

            gridControl1.DataSource = Products
            gridView1.Columns("UnitPrice").DisplayFormat.FormatType = DevExpress.Utils.FormatType.Numeric
            gridView1.Columns("UnitPrice").DisplayFormat.FormatString = "c2"

            ' Create an in-place LookupEdit control.
            Dim riLookup As New RepositoryItemLookUpEdit()
            riLookup.DataSource = Categories
            riLookup.ValueMember = "ID"
            riLookup.DisplayMember = "CategoryName"

            ' Enable the "best-fit" functionality mode in which columns have proportional widths and the popup window is resized to fit all the columns.
            riLookup.BestFitMode = DevExpress.XtraEditors.Controls.BestFitMode.BestFitResizePopup
            ' Specify the dropdown height.
            riLookup.DropDownRows = Categories.Count

            ' Enable the automatic completion feature. In this mode, when the dropdown is closed, 
            ' the text in the edit box is automatically completed if it matches a DisplayMember field value of one of dropdown rows. 
            riLookup.SearchMode = DevExpress.XtraEditors.Controls.SearchMode.AutoComplete
            ' Specify the column against which an incremental search is performed in SearchMode.AutoComplete and SearchMode.OnlyInPopup modes
            riLookup.AutoSearchColumnIndex = 1

            ' Optionally hide the Description column in the dropdown.
            ' riLookup.PopulateColumns();
            ' riLookup.Columns["Description"].Visible = false;

            ' Assign the in-place LookupEdit control to the grid's CategoryID column.
            ' Note that the data types of the "ID" and "CategoryID" fields match.
            gridView1.Columns("CategoryID").ColumnEdit = riLookup
            gridView1.BestFitColumns()
        End Sub

        Private Products As New List(Of Product)()
        Private Categories As New List(Of Category)()

        Private Sub InitData()
            Products.Add(New Product() With {.ProductName = "Sir Rodney's Scones", .CategoryID = 3, .UnitPrice = 10})
            Products.Add(New Product() With {.ProductName = "Gustaf's Knäckebröd", .CategoryID = 5, .UnitPrice = 21})
            Products.Add(New Product() With {.ProductName = "Tunnbröd", .CategoryID = 5, .UnitPrice = 9})
            Products.Add(New Product() With {.ProductName = "Guaraná Fantástica", .CategoryID = 1, .UnitPrice = 4.5D})
            Products.Add(New Product() With {.ProductName = "NuNuCa Nuß-Nougat-Creme", .CategoryID = 3, .UnitPrice = 14})
            Products.Add(New Product() With {.ProductName = "Gumbär Gummibärchen", .CategoryID = 3, .UnitPrice = 31.23D})
            Products.Add(New Product() With {.ProductName = "Rössle Sauerkraut", .CategoryID = 7, .UnitPrice = 45.6D})
            Products.Add(New Product() With {.ProductName = "Thüringer Rostbratwurst", .CategoryID = 6, .UnitPrice = 123.79D})
            Products.Add(New Product() With {.ProductName = "Nord-Ost Matjeshering", .CategoryID = 8, .UnitPrice = 25.89D})
            Products.Add(New Product() With {.ProductName = "Gorgonzola Telino", .CategoryID = 4, .UnitPrice = 12.5D})

            Categories.Add(New Category() With {.ID = 1, .CategoryName = "Beverages", .Description = "Soft drinks, coffees, teas, beers, and ales"})
            Categories.Add(New Category() With {.ID = 2, .CategoryName = "Condiments", .Description = "Sweet and savory sauces, relishes, spreads, and seasonings"})
            Categories.Add(New Category() With {.ID = 3, .CategoryName = "Confections", .Description = "Desserts, candies, and sweet breads"})
            Categories.Add(New Category() With {.ID = 4, .CategoryName = "Dairy Products", .Description = "Cheeses"})
            Categories.Add(New Category() With {.ID = 5, .CategoryName = "Grains/Cereals", .Description = "Breads, crackers, pasta, and cereal"})
            Categories.Add(New Category() With {.ID = 6, .CategoryName = "Meat/Poultry", .Description = "Prepared meats"})
            Categories.Add(New Category() With {.ID = 7, .CategoryName = "Produce", .Description = "Dried fruit and bean curd"})
            Categories.Add(New Category() With {.ID = 8, .CategoryName = "Seafood", .Description = "Seaweed and fish"})
        End Sub
    End Class

    Public Class Product
        Public Property ProductName() As String
        Public Property UnitPrice() As Decimal
        Public Property CategoryID() As Integer
    End Class

    Public Class Category
        Public Property ID() As Integer
        Public Property CategoryName() As String
        Public Property Description() As String
    End Class
End Namespace

Imports System
Imports System.Collections.Generic
Imports System.Linq
Imports System.Threading.Tasks
Imports System.Windows.Forms

Namespace LookupEdit_StandardBinding
    Friend NotInheritable Class Program

        Private Sub New()
        End Sub

        ''' <summary>
        ''' The main entry point for the application.
        ''' </summary>
        <STAThread>
        Shared Sub Main()
            Application.EnableVisualStyles()
            Application.SetCompatibleTextRenderingDefault(False)
            Application.Run(New Form1())
        End Sub
    End Class
End Namespace