Alex Golesh's Blog About Silverlight Development

Silverlight for Windows Phone 7: Launchers and Choosers

This post will talk about launchers and choosers mechanism in Windows Phone 7 applications.

The Windows Phone application model isolates every application in its own sandbox, both for execution and file storage. Applications are not able to directly access common stores of information, such as the contacts list to directly invoke other applications such as the phone or messaging applications. To enable scenarios that require common tasks such as these, Windows Phone exposes a set of APIs referred to as Launchers and Choosers that allow applications indirect access to these useful phone features. The Launcher and Chooser APIs invoke distinct built-in applications that replace the currently running application.

A Launcher is an API that launches one of the built-in applications through which a user completes a task, and in which no data is returned to the calling application. An example of this is the PhoneCallTask. An application can provide this Launcher with a phone number and a display name with which to invoke the phone. When the Phone application is displayed, the user can choose whether to initiate a call using the supplied parameters. When the user closes the Phone application, the calling application is usually activated again, but the Phone application does not return any data about or resulting from the user’s actions. When an application invokes a Launcher, it does not get a return value.

A Chooser is an API that launches one of the built-in applications through which a user completes a task, and which returns some kind of data to the calling application. An example of this is the PhotoChooserTask. An application can use this Chooser to show the Photo Chooser application. The user can either select a photo or cancel out of the Photo Chooser. Usually, when this occurs, the calling application is activated and supplied with the Chooser result. The result includes a value that indicates whether the user completed the task and, if the user did complete the task, the result includes an IO stream that contains the image data of the chosen photo. Note: that after the Photo Chooser chooser is launched, the user can also press the Start button and select another application. In this case, the calling application may never be reactivated and the result of the Chooser may never be returned. Applications should expect and handle this ambiguity properly.

Recall application I created to introduce push notifications. This application uses two launchers (SearchTask and EmailComposeTask) and one Chooser (EmailAddressChooserTask).

All the launchers work very similar way – create new instance of correspondent launcher class, add launcher properties (where relevant) and invoke Show() function. For example, launching search task looking for myself:

SearchTask searchTask = new SearchTask();
searchTask.SearchQuery = "Alex Golesh";
searchTask.Show();

The result will show the follwing screen:

Note: for the first time after emulator startup you could see the following screen:

Accept privacy statement – it happens only once between emulator restarts and only once in real device.

The second launcher (EmailComposeTask) expects the mail address. It could be provided just as a string, but in-real world application user expect to select it from his contacts and if not found enter manually. To provide the email address I’ll use EmailAddressChooserTask. Using the Choosers in generally is pretty similar to using launchers with one big difference – you have to subscribe to Completed event to receive your data back:

EmailAddressChooserTask emailAddressChooserTask; //defined at class level

////////////////////////////////////
emailAddressChooserTask = new EmailAddressChooserTask();
      emailAddressChooserTask.Completed += (s, args) =>
      {
        if (args.TaskResult == TaskResult.OK)
        {
          EmailComposeTask emailComposeTask = new EmailComposeTask();
          emailComposeTask.To = args.Email;
          emailComposeTask.Subject = "Weather Sample";
          emailComposeTask.Body = "Hi!\nJust wanted to share, how good Weather sample is!\n\nTake care!";
          emailComposeTask.Show();
        }
      };
      emailAddressChooserTask.Show();

Note: to create a create a contact(s) on emulator use “Add email” menu item of sample application :)

Sources here.

Stay tuned for more posts about Windows Phone 7 development,

Alex