Windows Phone Choosers

Windows Phone does not yet support multi-tasking, however you can interact with some of the built-in applications on the phone from within your application. Depending on the application you call, you will either launch the application and pass in some data to the application, or you will launch the application and have some data returned. The former is called a launcher, while the later is called a chooser. In this blog post you will learn to call a chooser from your application and have that chooser return some data from the built-in application. The specific chooser for this blog post will be the PhoneNumberChooserTask as shown in Figure 1.

Call the PhoneNumberChooserTask to return a phone number to your application.

Figure 1: Call the PhoneNumberChooserTask to return a phone number to your application.

Overview

A Chooser on the Windows Phone application allows your application to call a built-in application to get some data from that application and return data. As an example, you might want to access the contacts on your phone and return a phone number to your application from one of those contacts. You can use the PhoneNumberChooserTask to have your application make a call to get that data. The data that is returned is specific to the task that you call. For a phone number, you will get a string that contains the phone number. For a photo chooser you would get back an IO stream that contains the image. You could then turn this into an image to display in your application.

One important thing to keep in mind when using either of the launcher or chooser APIs is that calling these applications could cause your application to be tombstoned. It will be your responsibility to restore any data that you want after your application is reactivated from the tombstoned state.

Calling a Chooser

You may call any of the several built-in Chooser applications on the Windows Phone by simply using the classes contained in the Microsoft.Phone.Tasks namespace. The list of chooser classes are listed below:

CameraCaptureTask
EmailAddressChooserTask
PhoneNumberChooserTask
PhotoChooserTask
SaveEmailAddressTask
SavePhoneNumberTask

Most of the names are pretty self-explanatory so you just need to figure out where you want to get the data that you need for your application. To use any of the Chooser task classes, you will first need to add a using statement at the top of your Page class.

using Microsoft.Phone.Tasks;

Next, you create a field in your Page class with a variable that will point to the specific chooser you wish to use.

PhoneNumberChooserTask task = null;

Now create an instance of the chooser class in the constructor for your page and hook up the “Completed” event.

public ChooserPage()
{
  InitializeComponent();

  // Need to create this here as your app could be tombstoned
  // Need to rehook the event for this chooser app
  task = new PhoneNumberChooserTask();
  task.Completed += new
      EventHandler<PhoneNumberResult>(task_Completed);
}

You must create the instance of the task and hook up Completed event handler in the constructor because your application could be tombstoned once it calls the choose application. Upon reactivating your application the constructor will be called again and the completed event needs to be hooked back up so the chooser can call the event.

NOTE:  Not all choosers are tombstoned. Some are just temporarily deactivated. However, you should program defensively and always assume that your application will be tombstoned.

In the sample application shown in Figure 1 you will click on a button to invoke the Phone Number Chooser task using the Show() method. On the emulator there is a set of contacts that you will be able to select from so you can try this out even if you don’t have a real Windows Phone. Once you select a phone number from your contact list you will be returned to your application. To make the call to the Phone Number chooser call the Show() method of the task object in the button click event procedure as shown in the code below.

private void Button_Click(object sender, RoutedEventArgs e)
{
  // Show Phone Number Chooser
  // NOTE: This particular task does NOT necessarily
  // tombstone your app.
  task.Show();
}

In the Completed event you will want to check the e.TaskResult to see if the user actually selected a phone number from the chooser. If the user goes to the chooser, but immediately clicks on the back button, then the e.TaskResult will NOT be equal to OK. If the user clicks on one of the contacts, then the chooser application will immediately end and the phone number will be returned. In this case the e.TaskResult will be set to OK and you can access the e.PhoneNumber property to place the phone number into the text box in your application.

void task_Completed(object sender, PhoneNumberResult e)
{
  // See if task completed
  if (e.TaskResult == TaskResult.OK)
    txtPhone.Text = e.PhoneNumber;  // Grab phone number
}

Summary

In this blog post you were introduced to the Choosers that are available in the Windows Phone. You learned how to call the PhoneNumberChooserTask to access the contact list and return a phone number to your application. Using the chooser APIs allows you to call many of the built-in applications on the Windows Phone. Each chooser will return different data depending on what each one does. All choosers will fire a completed event once they return control back to your application. Even though all choosers will not necessarily tombstone your application, be sure to program for tombstoning just to be on the safe side.

NOTE: You can download this article and many samples like the one shown in this blog entry at my website. http://www.pdsa.com/downloads. Select “Tips and Tricks”, then “Windows Phone Choosers” from the drop down list.

Good Luck with your Coding,
Paul Sheriff

** SPECIAL OFFER FOR MY BLOG READERS **
We frequently offer a FREE gift for readers of my blog. Visit http://www.pdsa.com/Event/Blog for your FREE gift!

No Comments