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.
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.
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.
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 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.
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.
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.
// Look for a match in the last letter.
// If no match, return false.
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 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.
As you can see when you type some letter only the names with length greater that 6 appear as suggested results.
text box before AutoCompleteBox control populates the list of possible matches in the drop-down.
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.
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 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 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 is a dependency property of type bool that gets or sets a value indicating whether the drop-down portion of the control is open.
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.
Occurs when the AutoCompleteBox has populated the drop-down with possible matches based on the Text property.
Occurs when the AutoCompleteBox is populating the drop-down with possible matches based on the Text property.
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.
Occurs when the text in the text box portion of the AutoCompleteBox changes.
Notifies the AutoCompleteBox that its ItemsSource property has been set and the data can be filtered to provide possible matches in the drop-down.
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.
First, thanks for the article, this is VERY helpful and probably saved me several days of trial and error.
One question for you, is the AutoCompleteBox supported within Pivot/Panorama pages? I've tried in both, but i get strange behavious with the popup showing in strage places and the selected item showing something other than what I've tapped on.
I have the same problem with Neil. But this time, no Pivot/Panorama involved. I just use it in normal ApplicationPage descendant and it always show the popup up at the top of the screen.
But strangely, I need to interact (like scrolling the popup's content) to it's original area of view where the popup suppose to show. If I interact in the area where the popup actually shown, it will just dismiss the popup saying that I touch outside of the popup.
Can anyone explain why I experience this? I use this hierarchy for the view: ScrollView -> StackPanel -> AutoCompleteBox. Is there anything wrong with this hierarchy?
Hi can the autocompletebox be used to filter and show the results of filtered serach in list box rather than the DropDown box?
Hi, I have a problem I can not solve : the Enter Key is not detected in the KeyDown Event. Is there a solution to iomplement this ?
It has been announced that support of AutoCompleteBox within Pivot/Panorama/ScrollViewer is fixed in September 2012 Release.