Auto Complete Box Control With Double Line Items


In this article I'll explain how to create an "auto complete box" control with two line items. An auto complete box is a combination of two controls, one is used for input and that is a text box, the second one is used for selecting the item and that is similar to a list box. In this article I'll cover the "auto complete box" control with two line items. After reading this article you will be familiar with the advanced features of "auto complete box" control and how to use it in your apps or existing projects. let's start with the description of this control.

Auto Complete Box Control

As the name indicates, it's a control that provides an auto text completion capability to the user on the basis of predefined collections. This control is a combination of a text box and a list box. The text box is where the user types the text and the list box works as a container of items that can be selected for completing the text box value. The list box contains the items that are filtered on the basis of input. The two line items basically consist of two text blocks. Both of the text blocks can be used for various purposes. The list box is known as drop down since it opens only when there is an item to select.

Some of the properties of an Auto Complete Box that I have used in this demo are as follows:

  • Text

    This property is used for setting the default text in the text box of the auto complete box.
  • Filter Mode

    A very important and useful one. It allows you to set the type of filtering you want on collections. Some of the filters are like contains, contains case sensitive, equal and so on.
  • ValueMemberPath

    This property is very essential for the proper working of the auto complete box. This property sets the value that is to be used for comparison. The Filter method compares the input with the item assigned to this property.

Apart from the above properties the following two events are also used.

  1. Selection changed

    This event is fired when the item selected in the drop down has changed. 
  2. Got Focus

    This event is fired when the text box gets the focus.

I have also used an item template and data template to design the UI of the dropdown items.

Installing Windows Phone 8 Toolkit

Before you can run the following demo you need to install a Windows Phone 8 toolkit in your project. It's very easy to do this.

Use the following procedure to install the Windows Phone 8 toolkit using Nugget:

  1. Open your app project (either an existing one or a new one). 

  2. From the toolbar select "Tools" -> "NuGet Package Manager" -> "Package Manager Console". 

  3. Now in the Package Manager Console type the following:

    Install-Package WPtoolkit

    After typing this you will probably see the log similar to this:

    install-package wptoolkit
    'WPtoolkit 4.2013.08.16' already installed.
    Adding 'WPtoolkit 4.2013.08.16' to Demo.
    Successfully added 'WPtoolkit 4.2013.08.16' to Demo. 

  4. The next step is to add its reference to the XAML page. To do this just add this line:



The following demo demonstrates the basic code required for adding the auto complete box to any project. The code is very simple to follow and works in the following steps:

  • Add the auto complete box control to your design file.
  • Provide whatever name you want to the control. This name will be used from the code behind for referring and controlling its behavior.
  • Set the value member path equal to "Key" since we are comparing input against the dictionary keys.
  • Now create an item template and a data template.
  • Add two text blocks to the data template and bind them with dictionary key and value properties.
  • Now move to the code behind. In the page constructor we have the "startDemo" function that basically initiates the demo.
  • Inside the start demo we have the "createRandomItemSource" function that prepares a collection of randomly generated strings. These strings serve the purpose of auto completion source for the auto completion box control. Here the item source is of dictionary type.
  • The Selection change event is used for fetching the selected item.
  • The Search text is text being entered by the user in the text box and it is retrieved by the Search text property.

    Let's see how to code it.


    1. <phone:PhoneApplicationPage  
    2.     x:Class="Demo.MainPage"  
    3.     xmlns=""  
    4.     xmlns:x=""  
    5.     xmlns:phone="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone"  
    6.     xmlns:shell="clr-namespace:Microsoft.Phone.Shell;assembly=Microsoft.Phone"  
    7.     xmlns:d=""  
    8.     xmlns:mc=""  
    9.     xmlns:toolkit="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone.Controls.Toolkit"  
    10.     mc:Ignorable="d"  
    11.     FontFamily="{StaticResource PhoneFontFamilyNormal}"  
    12.     FontSize="{StaticResource PhoneFontSizeNormal}"  
    13.     Foreground="{StaticResource PhoneForegroundBrush}"  
    14.     SupportedOrientations="Portrait" Orientation="Portrait"  
    15.     shell:SystemTray.IsVisible="True">  
    17.     <!--LayoutRoot is the root grid where all page content is placed-->  
    18.     <Grid x:Name="LayoutRoot" Background="Transparent">  
    19.         <Grid.RowDefinitions>  
    20.             <RowDefinition Height="112.662"/>  
    21.             <RowDefinition Height="655.338"/>  
    22.         </Grid.RowDefinitions>  
    24.         <!--TitlePanel contains the name of the application and page title-->  
    25.         <StackPanel x:Name="TitlePanel" Grid.Row="0" Margin="12,17,0,512" Grid.RowSpan="2">  
    26.             <TextBlock Text="Demo" Style="{StaticResource PhoneTextNormalStyle}" Margin="12,0"/>  
    27.             <TextBlock  Text="Demo" Margin="9,-7,0,0" FontSize="40" />  
    28.         </StackPanel>  
    30.         <!--ContentPanel - place additional content here-->  
    31.         <StackPanel Orientation="Vertical" Grid.Row="1" Margin="0,0,0,352.338">  
    33.             <toolkit:AutoCompleteBox Name="acb" Text="Start typing..." FilterMode="Contains" ValueMemberPath="Key" SelectionChanged="acb_SelectionChanged" GotFocus="acb_GotFocus">  
    34.                 <toolkit:AutoCompleteBox.ItemTemplate>  
    35.                     <DataTemplate>  
    36.                         <StackPanel Orientation="Vertical">  
    37.                             <TextBlock Text="{Binding Path=Key}" FontSize="25" Foreground="Red"></TextBlock>  
    38.                             <TextBlock Text="{Binding Path=Value}" FontSize="20"></TextBlock>  
    39.                         </StackPanel>  
    40.                     </DataTemplate>  
    41.                 </toolkit:AutoCompleteBox.ItemTemplate>  
    42.             </toolkit:AutoCompleteBox>  
    43.         </StackPanel>  
    44.         <TextBlock Text="Selected Item:" FontSize="25" Margin="0,406,307,209.338" Grid.Row="1"></TextBlock>  
    45.         <TextBlock Name="selectedText" TextWrapping="Wrap" Text="None" FontSize="25" Margin="178,406.338,0,178" Grid.Row="1"></TextBlock>  
    46.         <TextBlock Text="Searched Text:" FontSize="25" Margin="0,482.338,307,133" Grid.Row="1"/>  
    47.         <TextBlock x:Name="searchText" FontSize="25" Text="None" Margin="178,482.338,0,133" Grid.Row="1"/>  
    48.     </Grid>  
    49. </phone:PhoneApplicationPage> 

    C# Code Behind

    1. using Microsoft.Phone.Controls;   
    2. using System;   
    3. using System.Collections.Generic;   
    4. using System.Linq;   
    5. using System.Net;   
    6. using System.Windows;   
    7. using System.Windows.Controls;   
    8. using System.Diagnostics;   
    9. using Microsoft.Phone.Tasks;   
    10. using System.IO;      
    12. namespace Demo   
    13. {   
    14.     public partial class MainPage : PhoneApplicationPage   
    15.     {   
    16.         // Constructor   
    17.         public MainPage()   
    18.         {   
    19.             InitializeComponent();   
    20.             startDemo();   
    21.         }        
    22.         Dictionary<stringstring> textList = new Dictionary<stringstring>();        
    23.         private void startDemo()   
    24.         {   
    25.             createRandomItemSource();   
    26.         }        
    27.         private void createRandomItemSource()   
    28.         {   
    29.             for (int i = 0; i < 50; i++)   
    30.             {   
    31.                 textList.Add(getRandomText(), getRandomText() + getRandomText() + getRandomText());   
    32.             }   
    33.             acb.ItemsSource = textList;  
    34.        }   
    35.         Random random = new Random();   
    36.         private string getRandomText()   
    37.         {   
    38.             var chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";   
    39.             var result = new string(   
    40.                 Enumerable.Repeat(chars, 8)   
    41.                           .Select(s => s[random.Next(s.Length)])   
    42.                           .ToArray());   
    43.             return result.ToLower();   
    44.         }        
    45.         private void acb_SelectionChanged(object sender, SelectionChangedEventArgs e)   
    46.         {   
    47.             if (acb.SelectedItem != null)   
    48.             {   
    49.                 selectedText.Text = acb.SelectedItem.ToString();   
    50.                 searchText.Text = acb.SearchText;   
    51.             }   
    52.         }      
    54.         private void acb_GotFocus(object sender, RoutedEventArgs e)   
    55.         {   
    56.             acb.Text = "";   
    57.         }        
    58.     }