Here's the list of changes, new functionality, and breaking changes between the two official Silverlight Toolkit releases so far. I covered key differences in the previously published "AutoCompleteBox: The missing guide," a must-read for anyone developing with the control. This will also guide application developers in updating their existing code.

AutoCompleteBox is one of the core controls in the Silverlight Toolkit. It provides suggestions when text is typed into the control, and supports rich collections of items, data templating, and extensibility opportunities for control developers. It can be found in the the Microsoft.Windows.Controls.dll assembly.

New features & changes

ObservableCollection support

The original release of AutoCompleteBox did not support ObservableCollection objects and the underlying INotifyCollectionChanged system. The functionality to support this was added in the December release, so it is consistent with the items control experiene that ListBox, ComboBox, and other controls exhibit for working with dynamic data.

Improvements to the text and SelectedItem experience

In the November release, the only way for the SelectedItem property to be set was through two specific user interactions:

• Clicking on / selecting an item in the drop-down popup
• Typing part of an item's value with the IsTextCompletionEnabled property set to 'True'

Less than ideal, this lead to a situation where your control could be bound to a rich set of business objects. You could have a business object that is offered as a suggest when "Jeff Wilcox" is typed into the field - a user could type "Jeff Wilcox", but not select the suggestion in the drop-down, at which point SelectedItem would be null.

We've corrected this, and you'll now find that we always perform a search when text is updated over your local, existing items in the collection. This is not dependent on the IsTextCompletionEnabled property at all. This opens up form editing applications to make much better use of the AutoCompleteBox control.

To help demonstrate the use of the SelectionChanged event, that is fired when the SelectedItem value is updated, all of the sample application pages for AutoCompleteBox have been updated to show the selected item's value next to the input control.

Here are some screen shots showing selected items on the right:

The IsTextCompletionEnabled change

After examining existing AutoCompleteBox controls out there, and fixing the aforementioned text and SelectedItem update experience, we decided to change the default text completion value to 'False'. It was 'True' in the November release.

Most users expect AutoComplete to offer suggestions, as opposed to automatically select the first suggestion. The only major browser that performs text completion automatically on the URL, for instance, is Safari. Hope you like this change - it won't affect any apps that explicitly set IsTextCompletionEnabled in code or XAML before, since the behavior stays the same.

API updates

To better resemble other common items controls, we're corrected the names of some of the APIs and events:

• The SelectedItemChanged event has been renamed to SelectionChanged. Along with that, the protected OnSelectedItemChanged method has been renamed to OnSelectionChanged
• A read-only CLR property named IsEditable was added, whose value is always 'True'
• Additions to the AutoCompleteSearchMode enum, covered below.

Automation support

User interface automation peers were added for the AutoCompleteBox control. This supports accessibility tools, including screen readers when using Windows and Internet Explorer. The ISelectionAdapter interface and SelectorSelectionAdapter types were updated to expose a CreateAutomationPeer method.

Community feedback

We evaluated all of the great feedback observed in the forums, in CodePlex work items, and were able to incorporate that into the changes for the release. Specifically,

• Issue #1027: Add ObservableCollection support
• Issue #1031: IsTextCompletionEnabled should default to False
• Issue #1035: Text updates should always update SelectedItem, if present in Items

Vote to make SelectedItem settable

There's also been some activity in the community that has not yet been implemented by the control, I'd like to point people to one in particular:

CodePlex work item #117, "Make SelectedItem property settable," originated in our Silverlight.net forum and is now receiving votes. The request is that the read-only behavior be changed, so that bindings can be used.

I'm supportive of this change, but would love to see the vote count move higher - we use customer voting to help triage and make the call on what to fix for the next release.

So, get out and vote!

Now a stable control

The control moves into the Stable quality band with the December release. You can expect that the control will meet the vast majority of usage scenarios. As a stable component, it may experience a very small number of API or behavior changes if feedback demands it.

One note in particular, the binding and item-to-text conversion semantics of the control are heavily limited by the Silverlight 2 binding system: without accessible BindingExpression support in the platform, the performance penalty of introducing bindings would be too great. The current Converter + ToString logic will remain for the Silverlight 2 release of the control, unless there is an elegant workaround that magically appears.

Ordinal string comparisons added to the AutoCompleteSearchMode enumeration

Ordinal string comparisons were added to the AutoCompleteSearchMode enumeration. The standard StartsWith and Contains filters were moved from using ordinal comparisons to using the current culture.

This opens up new scenarios for developers who have a specific comparison in mind. You can, as always, provide your own TextFilter lambda expression or even ItemFilter expression, too.

The current set of enumeration values for the SearchMode property of the control, straight from the source:

// (c) Copyright Microsoft Corporation.

// This source is subject to the Microsoft Public License (Ms-PL).

// Please see http://go.microsoft.com/fwlink/?LinkID=131993 for details.

// All other rights reserved.



using System;



namespace Microsoft.Windows.Controls

{

    // When adding to this enum, please update the OnSearchModePropertyChanged

    // in the AutoCompleteBox class that is used for validation.



    /// <summary>

    /// Represents the different types of built-in search modes available to 

    /// the AutoCompleteBox control.

    /// </summary>

    /// <QualityBand>Stable</QualityBand>

    public enum AutoCompleteSearchMode

    {

        /// <summary>

        /// No search mode, all elements in a collection will be included in 

        /// the results. This value would be used for a data source.

        /// </summary>

        None = 0,



        /// <summary>

        /// Matches the text value to start of the string, a current culture 

        /// case insensitive comparison is used.

        /// </summary>

        StartsWith = 1,



        /// <summary>

        /// Matches the text value to start of the string, the current culture 

        /// comparison is used.

        /// </summary>

        StartsWithCaseSensitive = 2,



        /// <summary>

        /// Matches the text value to start of the string, an ordinal comparison

        /// is used.

        /// </summary>

        StartsWithOrdinal = 3,



        /// <summary>

        /// Matches the text value to start of the string, an ordinal, case

        /// insensitive comparison is used.

        /// </summary>

        StartsWithOrdinalCaseSensitive = 4,



        /// <summary>

        /// Matches the text value if it is contained inside the string, a case 

        /// insensitive comparison is used. Uses the current culture value.

        /// </summary>

        Contains = 5,



        /// <summary>

        /// Matches the text value if it is contained inside the string. Uses 

        /// the current culture, case-sensitive comparison.

        /// </summary>

        ContainsCaseSensitive = 6,



        /// <summary>

        /// Matches the text value if it is contained inside the string. Uses 

        /// an ordinal comparison.

        /// </summary>

        ContainsOrdinal = 7,



        /// <summary>

        /// Matches the text value if it is contained inside the string. Uses 

        /// an ordinal comparison that is case-sensitive.

        /// </summary>

        ContainsOrdinalCaseSensitive = 8,



        /// <summary>

        /// Matches that the text if it's value equals the string, the current

        /// culture, case insensitive comparison is used.

        /// </summary>

        Equals = 9,



        /// <summary>

        /// Matches that the text if it's value equals the string using the 

        /// current culture's case sensitive comparison operator.

        /// </summary>

        EqualsCaseSensitive = 10,



        /// <summary>

        /// Matches that the text if it's value equals the string using an 

        /// ordinal case insensitive comparison operator.

        /// </summary>

        EqualsOrdinal = 11,



        /// <summary>

        /// Matches that the text if it's value equals the string using an 

        /// ordinal case sensitive comparison operator.

        /// </summary>

        EqualsOrdinalCaseSensitive = 12,



        /// <summary>

        /// Custom search mode: setting any of the item or text delegate 

        /// dependency properties and this value will enable non-standard, 

        /// custom functions and lambdas to be used.

        /// </summary>

        Custom = 13,

    }

}

Updating your existing applications

This is a quick guide, should be pretty easy:

• If you've set IsTextCompletionEnabled for your controls in code or XAML, no changes are necessary. But if you're using the default, double-check that you're OK with the new default value of 'False.'
• Rename anything that uses SelectedItemChanged event, it is now SelectionChanged
• If you've created or extended a selection adapter, make sure to add automation peer support (a CreateAutomationPeer method) - you can return a real automation peer (ideally), or, to get unblocked, simply return null.

Download the December 2008 release of the Silverlight Toolkit

• Binaries, samples and documentation (10 MB)
• Binaries, samples, documentation, unit tests and complete source code (11 MB)
• Explore the updated, combined sample explorer
• Subscribe to the syndicated feed of all team members (RSS)

Hope you're enjoying the control, and the toolkit as a whole! Let me know if you have any feedback.