Hands-On Lab
Choosers
Lab version: 1.0.0
Last updated: 12/13/2011
CONTENTS
Overview 3
Exercise 1: Introduction to the Windows Phone Choosers 6
Task 1 – Using Choosers 6
Task 2 – Searching for Contacts and Appointments 26
Summary 48
Overview
The launchers and choosers framework enables Windows Phone applications to provide common functions such as placing phone calls, sending emails, and taking pictures for their users.
The Windows Phone application model isolates every application in its own work area for both execution (including memory isolation) and file storage. Windows Phone applications are not able to directly access common information stores such as the contacts list or to directly invoke other applications such as phoning or messaging. To support scenarios requiring common tasks such as phoning or messaging, the Windows Phone provides a set of launcher and chooser APIs that enables applications to access these useful phone features indirectly. The launcher and chooser APIs invoke distinct built-in applications that replace the currently running application. The launchers and choosers framework provides the end user with a seamless experience while masking the application switching that occurs in the background.
The framework components are as follows:
· Chooser - An “open file dialog” action, where information is selected from a specific phone application’s storage area, for example, selecting an email address, contact, or picture
Below is the complete list of choosers that Windows Phone 7 Codenamed “Mango” supports:
Choosers
· EmailAddressChooserTask - Enables an application to launch the Contacts application, so users can extract selected contact email addresses
· CameraCaptureTask - Enables an application to launch the Camera application, so users can take a photo from within an application
· PhoneNumberChooserTask - Enables an application to launch the Contacts application, so users can extract selected contact phone numbers
· PhotoChooserTask - Enables an application to launch the Photo Chooser application, so users can select a photo
· Contacts – Allows an application to search for contacts according to their name, e-mail address or phone number.
· Appointments – Allows an application to search for appointments which occur in a specified time span.
While it is always a good practice to think about application tombstoning during Window Phone development, one should consider tombstoning even more seriously when dealing with launchers and choosers.
When does an application get tombstoned?
Generally speaking, an application gets tombstoned [that is, it is placed in the back stack] when a user forward navigates away from it. While there are a few exceptions to this general rule, applications in the background may be tombstoned at any time if the system requires additional resources to carry out the current foreground activity.
An application will not be automatically tombstoned when it launches an experience that feels to the user like an extension of the original application. These experiences are native flows that help the user complete some task, like choosing a photo. Avoiding tombstoning in these cases ensures a smooth flow between the application and the experience it has called [for example, no delay between choosing a photo and returning to the application that uses it].
Below is the list of native experiences that, when invoked, do not trigger an automatic tombstone in the calling application:
· PhotoChooserTask
· CameraCaptureTask
· MediaPlayerLauncher
· EmailAddressChooserTask
· PhoneNumberChooserTask
There are three scenarios in which an application in the background will immediately be tombstoned:
· User forward navigates away from an application [for example, user presses the Start key]
· Application invokes choosers not listed above
· System requires more resources to carry out a foreground activity
Note: All the above information regarding tombstoning is true for Windows® Phone 7.0. On Windows® Phone 7.1 launchers and choosers never initiate tombstoning, but it may be initiated nonetheless if the device requires additional resources. For more information on the new 7.1 application execution model please refer to documentation.
Objectives
Upon completion of this lab, you will:
· Be familiar with the choosers concept as implemented in the Windows Phone 7 application model
· Understand how and when to use choosers
· Have created a Silverlight application that uses the wide array of available choosers
Prerequisites
The following is required to complete this hands-on lab:
· Microsoft Visual Studio 2010 Express for Windows Phone or Microsoft Visual Studio 2010
· Windows Phone Codenamed “Mango” Developer Tools
Note: You can download all of these tools together in a single package from http://go.microsoft.com/?linkid=9772716.
Exercises
This hands-on lab is comprised of the following exercises:
· Introduction to the Windows Phone Choosers
Estimated time to complete this lab: 30 minutes.
Exercise 1: Introduction to the Windows Phone Choosers
A chooser is an API that launches one of the built-in applications through which a user completes a task and then returns some kind of data to the calling application. For example, the phone chooser launches the "contact people" experience, enabling a search for a particular contact. When successful, the requested contact information is returned. Another example of this is the PhotoChooserTask. An application can use this chooser to show the Photo Chooser application to allow the user to select a photo. The user can always cancel out of the Photo Chooser instead. Once the chooser is dismissed, the calling application is activated and supplied with the Chooser’s results. The result includes a value that indicates whether the user completed the task and, if the user did complete the task, the result includes additional relevant data, such as an IO stream containing the selected photo’s image data.
Task 1 – Using Choosers
1. Open the starter solution from this lab’s Source\Begin folder.
Note: Alternatively, you can choose to continue working on the solution created in the previous exercise.
2. Open MakePhoneCallPage.xaml.cs.
3. Note we overrode the OnNavigatedFrom and OnNavigatedTo functions in order to add debug information when the application is being tombstoned.
In this page, a phone call is made to one of the contacts added during the previous exercise. To get a contact’s phone number, this page uses the PhoneNumberChooserTask class. This class enables an application to launch the Contacts application to obtain the phone number of a contact selected by the user. The chooser works asynchronously, therefore the “Completed” event must be subscribed to before launching the Chooser. After the chooser returns a phone number, this page uses PhoneCallTask which makes a phone call to the selected phone number.
4. Start by adding the following variable to the class:
C#
PhoneNumberChooserTask phoneNumberChooserTask;
5. Add the following bold-yellow-highlighted code to the class’s constructor after the InitializeComponent method call:
C#
public MakePhoneCallPage()
{
InitializeComponent();
Debug.WriteLine("***\t In constructor of MakePhoneCallPage\t ***");
phoneNumberChooserTask = new PhoneNumberChooserTask();
phoneNumberChooserTask.Completed += new EventHandlerPhoneNumberResult>(phoneNumberChooserTask_Completed);
}
6. Add the phoneNumberChooserTask_Completed event handler function to manage the completed event using the following code:
C#
void phoneNumberChooserTask_Completed(object sender,
PhoneNumberResult e)
{
string debugMsg = string.Format(
"***\t In phoneNumberChooserTask_Completed function of MakePhoneCallPage, phone number returned: {0}, for contact: {1}\t ***",
e.PhoneNumber, e.DisplayName);
Debug.WriteLine(debugMsg);
if (e.TaskResult == TaskResult.OK)
{
PhoneCallTask phoneCallTask = new PhoneCallTask();
phoneCallTask.PhoneNumber = e.PhoneNumber;
phoneCallTask.Show();
}
else if (e.TaskResult == TaskResult.Cancel)
MessageBox.Show("Cannot make a phone call without a phone number", "Number not selected", MessageBoxButton.OK);
else
MessageBox.Show("Error getting phone number:\n" + e.Error.Message, "Fail", MessageBoxButton.OK);
}
7. Add the following code to the btnMakePhoneCall_Click handler function:
C#
private void btnMakePhoneCall_Click(object sender, RoutedEventArgs e)
{
phoneNumberChooserTask.Show();
}
8. Press F5 to compile and run the application.
9. Navigate to the “Make a Phone Call” page and click Make Call:
10. Select the contact:
Figure 1
Selecting a contact
11. If there are multiple phone numbers for a single contact, an additional phone selection step is displayed. In this case, select one of the contact’s phone numbers. If there is only one phone number, the contact selection serves as the phone selection.
12. Click call to make the phone call:
Figure 2
Making a Call
13. Click end call to return to MakePhoneCallPage:
14. Press SHIFT+F5 to stop the debugging and return to the Visual Studio.
15. Open the SendSMSPage.xaml.cs.
16. Note we overrode the OnNavigatedFrom and OnNavigatedTo functions in order to add debug information when the application is being tombstoned.
This page allows us to send an SMS message to one of the contacts added during the previous exercise. Like the previous page we added, this page uses the PhoneNumberChooserTask class to pick a contact’s phone number. After the chooser returns a phone number, this page uses SmsComposeTask, which enables composing SMS messages and sending them to the selected phone number.
17. Start by adding the following variable to the class:
C#
PhoneNumberChooserTask phoneNumberChooserTask;
18. Add the following bold-yellow-highlighted code to the class’s constructor after the InitializeComponent method call:
C#
public UsePhoneNumberPage()
{
InitializeComponent();
Debug.WriteLine("***\t In constructor of SendSMSPage\t ***");
phoneNumberChooserTask = new PhoneNumberChooserTask();
phoneNumberChooserTask.Completed += new EventHandlerPhoneNumberResult>(phoneNumberChooserTask_Completed);
}
19. Add the phoneNumberChooserTask_Completed event handler function to manage the completed event using the following code:
C#
void phoneNumberChooserTask_Completed(object sender,
PhoneNumberResult e)
{
string debugMsg = string.Format(
"***\t In phoneNumberChooserTask_Completed function of SendSMSPage, phone number returned: {0}, for contact: {1}\t ***",
e.PhoneNumber, e.DisplayName);
Debug.WriteLine(debugMsg);
if (e.TaskResult == TaskResult.OK)
{
SmsComposeTask smsComposeTask = new SmsComposeTask();
if(!string.IsNullOrEmpty(txtInput.Text))
smsComposeTask.Body = txtInput.Text;
smsComposeTask.To = e.PhoneNumber;
smsComposeTask.Show();
}
else if (e.TaskResult == TaskResult.Cancel)
MessageBox.Show("Cannot send SMS without a phone number", "Number not selected", MessageBoxButton.OK);
else
MessageBox.Show("Error getting phone number:\n" + e.Error.Message, "Fail", MessageBoxButton.OK);
}
20. Add the following code to the btnSendSMS_Click handler function:
C#
private void btnSendSMS_Click(object sender, RoutedEventArgs e)
{
phoneNumberChooserTask.Show();
}
21. Press F5 to compile and run the application.
22. Navigate to the “Send SMS” page, enter a message and click Send SMS:
Figure 3
Sending the SMS message
23. Select the contact.
24. If there are multiple phone numbers for a single contact, an additional phone selection step is displayed. In this case, select one of the contact’s phone numbers. If there is only one phone number, the contact selection serves as the phone selection.
25. Modify the message entered previously, if needed, and click Send ():
Figure 4
Sending the SMS message
26. Press SHIFT+F5 to stop the debugging and return to the Visual Studio.
Note: The following steps demonstrate sending an email to a contact. Remember, as we have previously stated, that this functionality is unavailable when using the Windows® Phone Emulator.
27. Open the UseEmailAddressPage.xaml.cs.
28. Note we overrode the OnNavigatedFrom and OnNavigatedTo functions in order to add debug information when the application is being tombstoned.
In this page an email message is sent to one of the contacts added during the previous exercise. To get a contact’s email address, this page uses the EmailAddressChooserTask class. This class enables an application to launch the Contacts application to obtain an email address for a contact selected by the user. The chooser works asynchronously, therefore the “Completed” event must be subscribed to before launching the Chooser. After the chooser returns an email address, this page uses the EmailComposeTask which we have seen in the previous exercise.
29. Press F5 to compile and run the application.
30. Navigate to the “Use Contact’s Email Address” page and click Send Email:
Figure 5
Sending the Email message
31. Select the contact.
32. If there are multiple email addresses for a single contact, an additional selection step is displayed. In this case, select one of the contact’s addresses.
33. Compose an email message (or keep the pre-populated email text) and click Send.
34. Press SHIFT+F5 to stop the debugging and return to the Visual Studio.
35. Open ChoosePhotoPage.xaml.cs.
36. Add the following using statements to the class:
C#
using System.Windows.Media.Imaging;
37. Note we overrode the OnNavigatedFrom and OnNavigatedTo functions in order to add debug information when the application is being tombstoned.
In this page a photo is chosen from the Image Hub. To choose the photo, this page uses the PhotoChooserTask class. This class allows an application to launch an image selector that displays images from the Image Hub. The chooser works asynchronously, therefore the “Completed” event must be subscribed to before launching the chooser. After the chooser returns an image stream, this page displays it.
38. Start by adding the following variable to the class:
C#
PhotoChooserTask photoChooserTask;
39. Add the following bold-yellow-highlighted code to the class’s constructor after the InitializeComponent method call:
C#
public ChoosePhotoPage()
{
InitializeComponent();
Debug.WriteLine("***\t In constructor of ChoosePhotoPage\t ***");
photoChooserTask = new PhotoChooserTask();
photoChooserTask.Completed += new EventHandlerPhotoResult>(photoChooserTask_Completed);
}
40. Add the photoChooserTask_Completed event handler function to manage the completed event using the following code:
C#
void photoChooserTask_Completed(object sender, PhotoResult e)
{
Debug.WriteLine("***\t In photoChooserTask_Completed function of ChoosePhotoPage\t ***");
if (e.TaskResult == TaskResult.OK)
{
BitmapImage bitmap = new BitmapImage();
bitmap.SetSource(e.ChosenPhoto);
imgChosenPhoto.Source = bitmap;
}
else if (e.TaskResult == TaskResult.Cancel)
MessageBox.Show("No photo was chosen - operation was cancelled", "Photo not chosen", MessageBoxButton.OK);
else
MessageBox.Show("Error while choosing photo:\n" + e.Error.Message, "Fail", MessageBoxButton.OK);
}
41. Add the following code to the btnChoosePhoto_Click handler function:
C#
private void btnChoosePhoto_Click(object sender, RoutedEventArgs e)
{
photoChooserTask.Show();
}
42. Press F5 to compile and run the application.
43. Navigate to the “Choose a Photo” page and click Choose a Photo:
44. Choose a photo from the Image Hub by clicking it.
Figure 6
Choosing an image from the Image Hub
45. The chosen photo should now appear in the ChoosePhotoPage.
Figure 7
Chosen photo appears in the ChoosePhotoPage
46. Press SHIFT+F5 to stop the debugging and return to the Visual Studio.
47. Open the TakePicturePage.xaml.cs.
48. Add the following using statements to the class:
C#
using System.Windows.Media.Imaging;
using System.IO.IsolatedStorage;
using System.IO;
using Microsoft.Xna.Framework.Media;
49. Note we overrode the OnNavigatedFrom and OnNavigatedTo functions in order to add debug information when the application is being tombstoned.
In this page, a new picture is captured and saved on the phone. To capture the picture, this page uses the CameraCaptureTask class. This class allows an application to launch the Camera application and capture a picture using the phone's camera. The chooser works asynchronously, therefore the “Completed” event must be subscribed to before launching the chooser. After the chooser returns a picture stream, this page saves it to the application's isolated storage as well as to the Image Hub.