Working with the Auto-Complete TextBox

MM .NET includes an Auto-Complete TextBox control that functions similarly to Google's Auto-Complete search box. The user can type in one or more characters, and a list pops up below the TextBox with items that match the entered string.

The control's SearchStringChanged event is raised each time the user types a character in the TextBox (or deletes a character). You can handle this event and retrieve items that should appear in the list below the TextBox.

The control's SearchStringSelected event is raised when the user selects an item from the list. Typically, you handle this event by using the selected item as a search parameter to retrieve a list of entities.

Auto-Complete TextBox Features

When you enter characters in the Auto-Increment TextBox, your custom SearchStringChanged event handler method is executed and a list of matching items is displayed below the TextBox:

Navigation

To navigate through items in the list, you can press the Down Arrow and Up Arrow to move down and up through the list. As each item is selected in the list, its associated text is displayed in the TextBox:

If you also want the Tab and Shift+Tab keys to navigate down and up through the list (as it does in the Google Auto-Complete search box), just set the Auto-Complete TextBox NavigateListOnTab property to true.

As you navigate through the list, the TextBox never loses focus. As shown in this image, the cursor is always placed at the end of the TextBox text.

As you navigate up from the first item in the list, or down from the last item in the list, the TextBox displays the original search characters typed in by the user:

If you press Escape while the list is open, the list is closed, and the TextBox displays the original search characters with all text selected:

Selecting an Item in the List

To select an item in the list, navigate to the item you want to select and press Enter. You can also select an item in the list by clicking on it with your mouse:

Using the AutoComplete TextBox

Add the mmAutoCompleteTextBox to your WPF window, resize the control to suit your needs, and set the Name property to something descriptive of its use (for example, actCustomerID).
In the code editor, go to the constructor of the Window that contains the Auto-Complete TextBox. Add a line of code that sets the FocusOnSelectElement property. This specifies the user interface element that receives focus after the user selects an item from the Auto-Complete TextBox list. For example:
```
this.actCustomerID.FocusOnSelectElement = this.grdOrders;
```
Next, you need to add a handler for the SearchStringChanged event. This event is raised by the Auto-Complete TextBox each time the user types a character in the TextBox. The full character string in the TextBox is passed as a parameter to the event handler method you specify. To create a handler method for this event, double-click the Auto-Complete TextBox in the design surface.
Here is an example of a method that handles the SearchStringChanged event:
```
void actCustomerID_SearchStringChanged(object sender, SearchStringChangedEventArgs e)
```
```
{
```
```
    // Get a strongly typed reference to the AutoComplete TextBox
```
```
    mmAutoCompleteTextBox acTextBox = (mmAutoCompleteTextBox)sender;
```
```
 
```
```
      // Call a method on the Customer controller object and store it in the AutoComplete TextBox's BindingList
```
```
      acTextBox.BindingList = this.Customer.GetCustomersLikeCustomerID(e.SearchString);
```
```
}
```
The first line of code in this handler method gets a strongly typed reference to the Auto-Complete Text Box. The second line of code calls a method on the Customer controller object that returns an entity list that is stored in the BindingList property of the Auto-Complete Text Box.
You also need to create a handler for the Auto-Complete TextBox SearchStringSelected event. This event is raised when the user selects an item from the Auto-Complete TextBox list. The full character string of the selected item is passed to the handler method you specify. To create a handler for this event, select the Auto-Complete TextBox in design mode, then go to the Visual Studio Properties Window and select the Events button (lightning bolt). Find the SearchStringSelected event and double-click it.
Here is an example of a method that handles the SearchStringSelected event:
```
void actCustomerID_SearchStringSelected(object sender, SearchStringSelectedEventArgs e)
```
```
{
```
```
      this.grdOrders.ItemsSource = this.Order.GetOrdersByCustomerID(e.SearchString);
```
```
}
```
This code passes the SearchString event argument property to a Customer controller object method that returns a list of Customer entities that match the search criteria, and assigns it to the ItemSource property of a WPF DataGrid.
Go back to the Auto-Complete TextBox in design mode, and set its ListDisplayMember property to the property name that contains the text you want to display in the Auto-Complete TextBox list. This should normally be the name of a property on the entity objects returned in your SearchStringChanged() handler method.
Next, set the ListSelectedValueMember property to the property name that contains the value associated with the items in the Auto-Complete TextBox list. This should normally be the name of a property on the entity objects returned in your SearchStringChanged() handler method.
Typically, the Auto-Complete TextBox's Grid.RowSpan must be set to at least 2 so its associated list appears when you start typing in the text box.
You may also need to change the Z-Order of the Auto-Complete TextBox so both the textbox and the associated list appear above other controls. To do this, select the Auto-Complete TextBox in design mode, then from the Format menu, select Order | Bring to Front
If you want the Tab and Shift+Tab keys to navigate down and up through the Auto-Complete TextBox list (as it does in the Google Auto-Complete search box), just set the Auto-Complete TextBox NavigateListOnTab property to true.