Windows Phone Toolkit AutoCompleteBox

A Windows Phone From Scratch Mini-Tutorial

The Windows Phone Toolkit offers a number of useful controls that you can use right out of the box.  This is the first in a sub-series of mini-tutorials on the Windows Phone Toolkit.

From this link you can download either the tools in the toolkit or the source-code. The latter comes with an excellent sample program that exercises all the tools.  Since there is no documentation to speak of other than the sample program, I’ll walk through implementing many of the controls. 

To begin, download the .msi file and double click on it to install the toolkit.  Next, open Visual Studio and create a new Windows Phone program, and name it AutoComplete.  Right click on the toolbar and select Choose Items…  In the dialog box that opens, click on the controls you’d like to add (in this case, be sure to click on AutoCompleteBox.

The AutoCompleteBox depends on your creating a resource that can provide an IEnumerable collection of words.  This is accomplished in the four steps:

1. Create a class that implements IEnumerable
2. Add the necessary namespace to the Xaml file
3. Add a resource section to the Xaml file
4. Add the AutoCompleteBox to the Xaml file

Create A Class That Implements IEnumerable

Right click on the project and select .Add –> New Folder. Name the folder Data.  Right click on the folder and select Add –> Class…, name the new class WordCompletion.cs.   In the new class file add the following code (see below for how I added the strings):

public class WordCompletions : IEnumerable
{
    public IEnumerable AutoCompletions = new List<string>()
    {
         "Lorem", "ipsum", "dolor", "sit", "amet", "consectetur", "adipiscing", "elit", "Nullam", "felis", "dui", "gravida", "at", 
         "condimentum", "eget", "mattis", "non", "est", "Duis", "porta", "ornare", "tellus", "at", "convallis", "nibh", "aliquam", 
         "faucibus", "Vivamus", "molestie", "fringilla", "ullamcorper", "Aenean", "non", "diam", "eu", "sapien", "pretium", "iaculis", 
         "Quisque", "at", "ante", "libero", "eu", "tincidunt", "urna", "Cras", "libero", "ligula", "hendrerit", "at", "posuere", "at", 
         "tempor", "at", "nulla", "Aliquam", "feugiat", "sagittis", "dolor", "convallis", "porttitor", "neque", "commodo", "ut", "Praesent",
         "egestas", "tincidunt", "lectus", "et", "pharetra", "enim", "semper", "et", "Fusce", "placerat", "orci", "vel", "iaculis", 
         "dictum", "nulla", "sem", "convallis", "nunc", "in", "viverra", "leo", "mauris", "eu", "odio", "Nullam", "et", "ultricies", 
         "sapien", "Proin", "quis", "mi", "a", "sapien", "semper", "lobortis", "ut", "eget", "est", "Suspendisse", "scelerisque", "porta",
         "mattis", "In", "eleifend", "tellus", "vel", "nulla", "aliquam", "ornare", "Praesent", "tincidunt", "dui", "ut", "libero",
         "iaculis", "consequat", "Nunc", "interdum", "eleifend", "rhoncus", "Curabitur", "sollicitudin", "nulla", "sagittis", "quam", 
         "vehicula", "cursus", "Fusce", "laoreet", "arcu", "vitae", "fringilla", "scelerisque", "nisi", "purus", "laoreet", "ipsum", "id", 
         "suscipit", "erat", "tellus", "eu", "sapien", "Proin", "pharetra", "tortor", "nisl", "Etiam", "et", "risus", "eget", "lectus",
         "vulputate", "dignissim", "ac","sed", "erat", "Nulla", "vel", "condimentum", "nunc", "Suspendisse", "aliquam", "euismod", "dictum",
         "Ut", "arcu", "enim", "consectetur", "at", "rhoncus", "at", "porta", "ut", "lacus", "Donec", "nisi", "quam", "faucibus", "tempor",
         "tincidunt", "eu", "porttitor", "id", "ipsum", "Proin", "nec", "neque", "nulla", "Suspendisse", "sapien", "metus", "aliquam", "nec", 
         "dapibus", "consequat", "rutrum", "id", "leo", "Donec", "ac", "fermentum", "tortor", "Pellentesque", "nisl", "orci", "tincidunt", 
         "at", "iaculis", "vitae", "consequat", "scelerisque", "ante", "Suspendisse", "potenti", "Maecenas", "auctor", "justo", "a", "nibh",
         "sagittis", "facilisis", "Phasellus", "ultrices", "lectus", "a", "nisl", "pretium", "accumsan"
    };

    public IEnumerator GetEnumerator()
    {
        return AutoCompletions.GetEnumerator();
    }
}

Adding the Strings

To create the List of strings I went to the Lorem Ipsum site,  and copied the first two paragraphs of words. I pasted these words into my class and then replaced (control-H) all the commas and periods with nothing, and all the spaces with

 ", "  

thus surrounding each word with quotes, and separating all the words with commas.   You, of course, are free to just copy and paste from the listing above.

Implementing the Interface

The interface requires  that you implement GetEnumerator. In this case I just delegate that responsibility to the List, which already implements IEnumerable.  Since my class now implements IEnumerable, I’m free to use it as a source for the AutoComplete box.

Add the necessary namespace to the Xaml file

Step 2 is to add the namespace in which the WordCompletions class was created to the Xaml file,

xmlns:data="clr-namespace:AutoCompleteData"

Add a resource section to the Xaml file

The next step is to add a resource section to the Xaml file, just below the namespaces.  The purpose of this is to link the WordCompletions class to a key that can be referred to in a StaticResource declaration later in the Xaml file,

<phone:PhoneApplicationPage.Resources>
    <data:WordCompletions
        x:Key="AutoCompletions" />
</phone:PhoneApplicationPage.Resources>

Add the AutoCompleteBox to the Xaml file

The final step is to add the AutoCompleteBox to the grid. The AutoCompleteBox is defined in the toolkit namespace

<toolkit:AutoCompleteBox
    HorizontalAlignment="Left"
    Name="Pseudo-Latin-Words"
    VerticalAlignment="Center"
    Grid.Row="0"
    Width="450"
    ItemsSource="{StaticResource AutoCompletions}"/>

You can of course add this control right in the Xaml or by dragging it from the Toolbox (the latter has the distinct advantage of setting up the namespace for you. If you add it manually, you’ll need to add the toolkit namespace to the file as well).