Windows Phone Launchers

The Windows Phone does not support multi-tasking (yet), however you can call many of the built-in applications on the phone from 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 launcher from your application. The specific launcher will be the SavePhoneNumberTask as shown in Figure 1.

Figure 1: Enter a Phone Number, then call the SavePhoneNumberTask launcher.

Figure 1: Enter a Phone Number, then call the SavePhoneNumberTask launcher.

Launcher Overview

When you use the Launcher API on the Windows Phone, your application calls one of the built-in applications in which the user will simply complete a task, then return to your application. No data will be returned from a launcher application, however, your application may pass in some data to the launcher. An example of a launcher is where you might ask a user to input a phone number, then you pass that phone number to the SavePhoneNumberTask. If the user saves that phone number and returns, a return result of OK will be returned, but no other data.

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.

Launchers

There are several built-in applications on the Windows Phone that can be “launched” through the launcher API. All of the launcher APIs are under the Microsoft.Phone.Tasks namespace. The list of launchers are listed below:

  • EmailComposeTask
  • MarketplaceDetailTask
  • MarketplaceHubTask
  • MarketplaceReviewTask
  • MarketplaceSearchTask
  • MediaPlayerLauncher
  • PhoneCallTask
  • SearchTask
  • SmsComposeTask
  • WebBrowserTask

To use any of the launcher 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 launcher you wish to use.

SavePhoneNumberTask _Task;

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

public LauncherPage()
{
  InitializeComponent();
     
  _Task = new SavePhoneNumberTask();
  _Task.Completed += new
    EventHandler<TaskEventArgs>(_Task_Completed);
}

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

In Figure 1 you can see that you are asked to put a phone number into a text box on this page. This text box is named “txtPhone”. When you click on the Save Phone Number button the Click event will be fired. At this point you take the value from the txtPhone.Text property and set the PhoneNumber property on your SavePhoneNumberTask object. Now you call the Show() method of the task object and the launcher application will now run and will receive the phone number from your application. Once the new application is running your application will be tombstoned.

private void Button_Click(object sender, RoutedEventArgs e)
{
  // Pass phone number into contacts
  _Task.PhoneNumber = txtPhone.Text;
  // Display contact info app
  // This WILL tombstone your app
  _Task.Show();
}

In the Completed event you will want to check the e.TaskResult to see if the user actually accomplished the task. For example, when saving a phone number, if they do not actually click the save button after adding the new phone number/contact, then the result will not come back as an “OK”. Each launcher may report different results depending on what each one is supposed to do. In the completed event procedure below you will simply display a message box telling the user that the phone number was saved.

void _Task_Completed(object sender, TaskEventArgs e)
{
  if (e.TaskResult == TaskResult.OK)
    MessageBox.Show("Phone Number Saved");
}

Summary

In this blog post you were introduced to the Launchers that are available in the Windows Phone. Using the launcher APIs you can call many built-in applications on the Windows Phone. Each launcher allows you to pass in different sets of data depending on what each one does. They will all fire a completed event once they return control back to your application. Be sure to program for tombstoning as launchers typically deactivate your application.

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 Launchers” 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