AutoCompleteBox for WP7 in depth

One of the new components in the November update of the Silverlight Toolkit  for Windows Phone 7 is the AutoCompleteBox which shows suggestions in a drop-down, when the user types text into it. It is a control composed of a text box for text entry, a rich set of properties for customization and item display, data binding support, and all the necessary logic to provide suggestions and completion. For more information about all new controls in the updated version of the toolkit please visit the previous article.

In this post I am going to talk about the key properties, methods and events of the AutoCompleteBox  in details. To begin using AutoCompleteBox first  add a reference to  the Microsoft.Phone.Controls.Toolkit.dll  assembly which is installed with the toolkit and you can find it in :
       C:\Program Files (x86)\Microsoft SDKs\Windows Phone\v7.0\Toolkit\Nov10\Bin\Microsoft.Phone.Controls.Toolkit.dll.

You will also need to add the "toolkit" prefix declaration. Make sure that your page declaration includes the "toolkit" namespace:
       xmlns:toolkit="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone.Controls.Toolkit"

In this article I will use a simple List of city names which is set as AutoCompleteBox ItemSource: 
C#:  
         

   List<string> cities = new List<string>();  
            cities.Add("Barcelona");  
            cities.Add("Bogota");  
            cities.Add("Berlin");  
            cities.Add("London");  
            cities.Add("Las Vegas");  
            cities.Add("New York");  
            cities.Add("New Castle");  
            cities.Add("Sofia");  
            cities.Add("Paris");  
            cities.Add("Prague");  
            cities.Add("Madrid");  
            cities.Add("Milan");  
            this.acBox.ItemsSource = cities;  

XAML:  
          

<toolkit:AutoCompleteBox x:Name="acBox" Height="80"/>  

This is the easiest and the simplest way to populate this control with data so that you will be able to use its basic functionality. 
Now lets focus on some of the most specific and important properties of the AutoCompleteBox. (I will demonstrate how to set these properties in code behind but alternatively you can use each dependency property in XAML as well)

Key Properties

 

FilterMode
FilterMode is a dependency property of type AutoCompleteFilterMode which is used to filter items specified by the ItemsSource for display in the drop-down. Its default value is AutoCompleteFilterMode.StartsWith. For more information about AutoCompleteFilterMode and its available values please take a look at the documentation that comes with the toolkit.

Note: Use the FilterMode property to specify how possible matches are filtered. For example, possible matches can be filtered in a predefined or custom way. The search mode is automatically set to Custom if you set the ItemFilter property.

Example:
Lets say that we want to implement a case-sensitive search, then all we need to do is to set the FilterMode as demonstrated in the next example:
this.acBox.FilterMode = AutoCompleteFilterMode.StartsWithCaseSensitive;

      

As you can see in the first case we just type a small letter and nothing appears in the popup. In the second case we type a capital letter and the suggested names appear imediately.

ItemFilter

ItemFilter is a dependency property of type AutoCompleteFilterPredicate<object>. Its value is the custom method that uses the user-entered text to filter the items. The default is null.
Note: The filter mode is automatically set to Custom if you set the ItemFilter property.Use ItemFilter to provide custom object filtering for items displayed in the drop-down. Alternatively, you should use the TextFilter property to provide custom text filtering.

• public delegate bool AutoCompleteFilterPredicate<T>(string search, T item);

Represents the filter used by the AutoCompleteBox control to determine whether an item is a possible match for the specified text.
Returns true to indicate that the item  is a possible match for search otherwise false.
    search  - the string used as the basis for filtering
    item - the item that is compared with the"search" parameter.
    T - the type used for filtering the AutoCompleteBox. This type can be either a string or an object.

Example: 
Lets say we want to implement a custom search that is based on the last letter. Then all  we need to do is just to add the following code:

bool SearchCountry(string search, object value) 
        { 
            if (value != null) 
            { 
                // Look for a match in the last letter. 
                if (value.ToString().ToLower().EndsWith(search)) 
                    return true; 
            } 
            // If no match, return false. 
            return false; 
        } 

this.acBox.ItemFilter += SearchCountry;

As you can see in the first case when we type "b" nothing appears in the popup(that is because the search looks for a match in the last letter not in the first one). In the second case we type the letter "s" the suggested names that ends with "s" appear immediately. In similar way you can add your own custom search filtering that fits in your scenario.

TextFilter
TextFilter is a dependency property of type AutoCompleteFilterPredicate<string>. Its value is the custom method that uses the user-entered text to filter items in a text-based way for display in the drop-down. (take a look at the previous point for AutoCompleteFilterPredicate reference).
 

Note: The search mode is automatically set to Custom if you set the TextFilter. Use TextFilter to provide custom string filtering for items displayed in the drop-down. Alternatively, you should use the ItemFilter property to provide custom object filtering.

Example:
Lets say we want to filter the names by their length. So we will need some kind of custom filter like the following:

bool CustomFilter(string search, string value) 
        { 
            return (value.Length > 6); 
        } 

this.acBox.TextFilter += CustomFilter;

As you can see when you type some letter only the names with length greater that 6 appear as suggested results.

MinimumPopulateDelay
MinimumPopulateDelay is a dependency property of type int. The default is 0. It gets or sets the minimum delay, in milliseconds, after text is typed in the
text box before AutoCompleteBox control populates the list of possible matches in the drop-down.

MinimumPrefixLength
MinimumPrefixLength is a dependency property of type int. The default is 1. It gets or sets the minimum number of characters required to be entered in thetext box before the AutoCompleteBox displays possible matches

Note: If you set MinimumPrefixLength to -1, the AutoCompleteBox will not provide possible matches. There is no maximum value, but setting MinimumPrefixLength to value that is too large will prevent the AutoCompleteBox from providing possible matches as well.

Example:
Lets say that we want to view the suggestions after the user enter at least 2 letters. The code for accomplishing this is as follows:

this.acBox.MinimumPrefixLength = 2;

In the first case when you enter a single letter nothing happens. In the second case the suggested results appear in the popup after entering at least 2 letters.

SearchText
SearchText is a dependency property that gets the text that is used to filter items in the ItemsSource item collection.
Remarks:The SearchText value is typically the same as the Text property, but is set after the TextChanged event occurs and before the Populating event.

TextBoxStyle
TextBoxStyle is a dependency property  that gets or sets the Style applied to the text box portion of the AutoCompleteBox control.The default is null.

IsDropDownOpen
IsDropDownOpen is a dependency property of type bool that gets or sets a value indicating whether the drop-down portion of the control is open.

IsTextCompletionEnabled
IsTextCompletionEnabled is a dependency property of type bool that gets or sets a value indicating whether the first possible match found during
the filtering process will be displayed automatically in the text box.The default is false.

That was some of the specific properties for this control. Now lets say some words about the exposed events.

Key Events

Populated
Occurs when the AutoCompleteBox has populated the drop-down with possible matches based on the Text property.

Example:

this.acBox.Populated += new PopulatedEventHandler(acBox_Populated); 
void acBox_Populated(object sender, PopulatedEventArgs e) 
        { 
            // 
        }

Populating
Occurs when the AutoCompleteBox is populating the drop-down with possible matches based on the Text property.

Note: If the event is canceled, by setting the PopulatingEventArgs.Cancel property to true, the AutoCompleteBox will not automatically populate the selection
adapter contained in the drop-down. In this case, if you want possible matches to appear, you must provide the logic for populating the selection adapter.

Example:

this.acBox.Populating += new PopulatingEventHandler(acBox_Populating); 
void acBox_Populating(object sender, PopulatingEventArgs e) 
        { 
            // 
        }

TextChanged
Occurs when the text in the text box portion of the AutoCompleteBox changes.

Example:

this.acBox.TextChanged += new RoutedEventHandler(acBox_TextChanged); 
void acBox_TextChanged(object sender, RoutedEventArgs e) 
        { 
            // 
        }

Key Methods

PopulateComplete

C#:

public void PopulateComplete();

 

Notifies the AutoCompleteBox that its ItemsSource property has been set and the data can be filtered to provide possible matches in the drop-down.

Note: Call this method when you are providing custom population of the drop-down portion of the AutoCompleteBox, to signal the control that you are done with
the population process. Typically, you use PopulateComplete() when the population process is a long-running process and you want to cancel built-in filtering of the ItemsSource items. In this case, you can handle the Populated event  and set PopulatingEventArgs.Cancel to true. When the long-running process has completed you call PopulateComplete() to indicate the drop-down is populated.

For more information about the full API please take a look at the toolkit documentation.
That was all about the AutoCompleteBox`s key  properties, methods and events. I hope that the article was helpful.

You can find the full source code here.

原文链接：http://www.windowsphonegeek.com/articles/autocompletebox-for-wp7-in-depth