How to Use the ProcessNewValue Event of a LookUp Editor

Description:
How to Use the ProcessNewValue Event of a LookUp Editor

Answer:
The LookUp editor allows a user to enter values which cannot be found in the lookup list. A programmer should handle this situation, otherwise a new value is lost. The LookUp editor provides a ProcessNewValue event for this.
First of all, you should set the SearchMode property to OnlyInPopup and TextEditStyle to Standard to enable free text entry.
There are two common approaches for handling the ProcessNewValue event:

1. Immediately insert the new record in the lookup table and generate a new ID for it.
2. Display a dialog, where a user can set values for a new data row.
   Below are two code snippets which demonstrate the implementation of these approaches.

C#
// solution 1  
private void LookUpEdit1_ProcessNewValue(object sender, DevExpress.XtraEditors.Controls.ProcessNewValueEventArgs e) {  
   DataRow Row;  
   RepositoryItemLookUpEdit Edit;  
   Edit = ((LookUpEdit)sender).Properties;  

   if(e.DisplayValue == null || Edit.NullText.Equals(e.DisplayValue) || string.Empty.Equals(e.DisplayValue))  
       return;  

   Row = LookupTable.NewRow();  
   Row["Name"] = e.DisplayValue;  
   LookupTable.Rows.Add(Row);  

   e.Handled = true;  
}  

// solution 2  
private void LookUpEdit1_ProcessNewValue(object sender, DevExpress.XtraEditors.Controls.ProcessNewValueEventArgs e) {  
   DataRow Row;  
   RepositoryItemLookUpEdit Edit;  
   Edit = ((LookUpEdit)sender).Properties;  

   if(e.DisplayValue == null || Edit.NullText.Equals(e.DisplayValue) || string.Empty.Equals(e.DisplayValue))  
       return;  

   using(Form2 f = new Form2()) {  
       f.ItemID = "(Auto Number)";  
       f.ItemName = e.DisplayValue.ToString();  
       if(f.ShowDialog(this) == System.Windows.Forms.DialogResult.OK) {  
           e.DisplayValue = f.ItemName;  
           Row = LookupTable.NewRow();  
           Row["Name"] = f.ItemName;  
           LookupTable.Rows.Add(Row);  
       }  
   }  

   e.Handled = true;  
}  

Visual Basic
' Solution 1  
Private Sub LookUpEdit1_ProcessNewValue(ByVal sender As Object, ByVal e As _  
    DevExpress.XtraEditors.Controls.ProcessNewValueEventArgs) Handles LookUpEdit1.ProcessNewValue  

    Dim Row As DataRow  
    Dim Edit As Repository.RepositoryItemLookUpEdit  
    Edit = CType(sender, LookUpEdit).Properties  

    If e.DisplayValue = Edit.NullString OrElse e.DisplayValue = String.Empty Then Exit Sub  

    Row = LookupTable.NewRow()  
    Row("Name") = e.DisplayValue  
    LookupTable.Rows.Add(Row)  

    e.Handled = True  
End Sub  

' Solution 2  
Private Sub LookUpEdit1_ProcessNewValue(ByVal sender As Object, ByVal e As _  
    DevExpress.XtraEditors.Controls.ProcessNewValueEventArgs) Handles LookUpEdit1.ProcessNewValue  

    Dim Row As DataRow  
    Dim Edit As Repository.RepositoryItemLookUpEdit  
    Edit = CType(sender, LookUpEdit).Properties  

    If e.DisplayValue = Edit.NullString OrElse e.DisplayValue = String.Empty Then Exit Sub  

    With New Form2()  
        .ItemID = "(Auto Number)"  
        .ItemName = e.DisplayValue  
        If .ShowDialog(Me) = DialogResult.OK Then  
            e.DisplayValue = .ItemName  
            Row = LookupTable.NewRow()  
            Row("Name") = .ItemName  
            LookupTable.Rows.Add(Row)  
        End If  
        .Dispose()  
    End With  

    e.Handled = True  
End Sub  

There is also another way to insert new lookup records: add a button to the LookUp editor. When the button is pressed, you should display a dialog where a user can set values for a new lookup row. Then he/she can pick it up from the lookup list.
A sample project for version 7.3 and higher is accessible from the Code Central: How to Use the ProcessNewValue Event of a LookUp Editor.
See Also:
A quick-reference guide - it contains cheat sheets, best practices, and troubleshooting sections:
DevExpress WinForms Cheat Sheets

Does the LookUp editor allow users to modify the values displayed?