LookUpEdit Class
The editor that provides lookup functionality using a lightweight dropdown grid.
Namespace: DevExpress.XtraEditors
Assembly: DevExpress.XtraEditors.v18.2.dll
Declaration
[DefaultBindingProperty("EditValue")]
[SmartTagAction(typeof(LookUpEditActions), "Columns", "Columns", SmartTagActionType.CloseAfterExecute)]
[SmartTagAction(typeof(LookUpEditActions), "PopulateColumns", "Populate Columns")]
[ToolboxBitmap(typeof(ToolboxIconsRootNS), "LookUpEdit")]
public class LookUpEdit :
LookUpEditBase
Related API Members
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.
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:
- Standard Binding (to Simple Data Types)
- Advanced Binding (to Business Objects)
- Using a Dictionary Lookup Data Source
- Combobox Mode - Allow Entering New Values
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:
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 how an end-user can search for specific rows in the lookup data source by typing within the editor (auto-completion or incremental search mode).
- 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).
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; }
}
}
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());
}
}
}