Windows Phone 8 : Windows Phone Toolkit (part 1) - AutoCompleteBox Control

In addition to the controls that are part of the Windows Phone SDK, there is another download called the Windows Phone Toolkit. The version of the Toolkit for the phone includes a set of controls specific to the phone to help you create compelling applications. You should install the Windows Phone Toolkit to add these controls to your applications. You can download the Windows Phone Toolkit directly from the CodePlex site at http://phone.codeplex.com. You can download only the installer, or you can opt to download the source code and other assets if you’re interested in how these controls have been built. The entire project is open source.

The Windows Phone Toolkit includes the following controls:

• AutoCompleteBox

• ContextMenu

• DatePicker

• TimePicker

• ListPicker

• LongListSelector2

2 This control is part of the phone controls in Windows Phone 7. It was moved from the Windows Phone Toolkit to the main Windows Phone runtime for Windows Phone 8.

• ToggleSwitch

• ExpanderView

• PhoneTextBox

• Rating

• CustomMessageBox

• WrapPanel

We will discuss these controls in the subsections that follow.

Before you can get started using the Windows Phone Toolkit, you will need to add it to your project. Visual Studio Express 2012 for the Windows Phone Developers includes built-in support for a package management system called NuGet. With NuGet you can easily add the Toolkit to your project by right-clicking the project and selecting “Manage NuGet Packages.” The dialog box that opens lets you add any of a number of Microsoft or community contributes packages to your project. Figure 1 shows how you can select the Online packages and simply search for “wptoolkit” to locate the Windows Phone Toolkit. Clicking the Install button will add it to your project.

FIGURE 1 Using NuGet to add the Windows Phone Toolkit

FIGURE 2 AutoCompleteBox example

The control is a list control, so you can assign an arbitrary list to the ItemsSource property:

theBox.ItemsSource = new string[]
{
  "Shawn",
  "Steve",
  "Sally",
  "Bob",
  "Kevin"
};

You can customize the control using XAML attributes in a number of ways, including specifying whether text completion is enabled and what type of filtering to support (StartsWith is the default, but you can have the suggestions based on Contains or Equals as well):

<toolkit:AutoCompleteBox x:Name="theBox"
                         IsTextCompletionEnabled="True"
                         FilterMode="Contains" />

A common approach with the AutoCompleteBox is to support a list of values that are not known at development time. This is how the Bing and Google search boxes work on the Web. You can achieve this by handling the TextChanged event and then filling in the ItemsSource as the text changes:

// Constructor
public MainPage()
{
  InitializeComponent();

  theBox.TextChanged += theBox_TextChanged;
}

void theBox_TextChanged(object sender, RoutedEventArgs e)
{
  // Go retrieve a list of items from a service
}