WP7 Launchers – Mango (Windows Phone 7.1)

Posted on by

Launchers are a set of APIs that Windows Phone applications can use to enable common tasks such as making a phone call or sending an email. Unlike Choosers, Launchers do not return a value back to the calling application.

If you are developing an application that uses a Launcher or Chooser, you should be aware that these features behave differently on a physical device and on Windows Phone Emulator. For a detailed list of the behaviour of each Launcher and Chooser in both environments, see Launcher and Chooser Support in Windows Phone Emulator.

This topic contains information about the following launchers:

  • BingMapsDirectionsTask

  • BingMapsTask

  • EmailComposeTask

  • MarketplaceDetailTask

  • MarketplaceHubTask

  • MarketplaceReviewTask

  • MarketplaceSearchTask

  • MediaPlayerLauncher

  • PhoneCallTask

  • SearchTask

  • SmsComposeTask

  • ShareLinkTask

  • ShareStatusTask

  • WebBrowserTask

Using Launchers in Your Application

The Launcher APIs belong to the Microsoft.Phone.Tasks namespace. You need to add a using directive for this namespace to the PhoneApplicationPage class file. All of the Launcher APIs function in a similar manner. First, you create an instance of the Launcher class you want to use. Next, you set properties of the Launcher object that will determine the behaviour of the task application when it is invoked. For example, you can specify a phone number that will be displayed when the Phone application launches. Finally, you call the Launcher’s Show method to launch the task application.

It is important to note that when you use a Launcher, a separate application is launched to complete the task. For example, the EmailComposeTask invokes the Messaging application. When the separate application is launched, your application is deactivated and is no longer running. After completing the task, the user can return to your application, at which point it is reactivated. For information about handling the activation and deactivation of your application see, Execution Model for Windows Phone.

BingMapsDirectionsTask

BingMapsDirectionsTask launches the Bing Maps application and displays driving directions between two points. If you do not set the start or end point, Bing Maps will use the user’s current location for the one that is not set. If you omit both the start and the end point, an exception will be thrown when you call Show().

The start and end points are LabeledMapLocation objects that contain a string label and a GeoCoordinate specifying the latitude and longitude of the location. You must add a reference to the System.Device assembly to your project and include the using directive referencing the System.Device.Location namespace to your page in order to access the GeoCoordinate API.

BingMapsDirectionsTask bingMapsDirectionsTask = new BingMapsDirectionsTask();         
GeoCoordinate spaceNeedleLocation = new GeoCoordinate(47.6204,-122.3493);
LabeledMapLocation spaceNeedleLML = new LabeledMapLocation("Space Needle", spaceNeedleLocation);
bingMapsDirectionsTask.End = spaceNeedleLML;
// bingMapsDirectionsTask.Start is not set. The user’s current location is used as the start point.
bingMapsDirectionsTask.Show();

BingMapsTask

BingMapsTask launches the Bing Maps application. You can optionally set a Center point for the map that is displayed. If you do not set this property, the user’s current location is used as the center point of the map. You can also provide a search string that will be used to mark locations on the map. The ZoomLevel parameter allows you to specify the zoom level that is initially displayed when the map is shown.

The center point is specified using a GeoCoordinate object. You must add a reference to the System.Device assembly to your project and include the using directive referencing the System.Device.Location namespace to your page to access the GeoCoordinate API.

BingMapsTask bingMapsTask = new BingMapsTask();
// Omit the Center property to use the user’s current location.
// bingMapsTask.Center = new GeoCoordinate(47.6204, -122.3493);
bingMapsTask.SearchTerm = "coffee";
bingMapsTask.ZoomLevel = 2;

EmailComposeTask

EmailComposeTask launches the Email application, which displays a new email message. You can optionally specify recipients, a message subject, and a message body that are prepopulated in the new message. You can also specify a code page for the new message. The message is not sent until it is initiated by the user.

EmailComposeTask emailComposeTask = new EmailComposeTask();
emailComposeTask.Subject = "message subject"; 
emailComposeTask.Body = "message body";
emailComposeTask.To = "recipient@webservicesuk.com";
emailComposeTask.Cc = "cc@example.com";
emailComposeTask.Bcc = "bcc@example.com";
emailComposeTask.Show();

MarketplaceDetailTask

MarketplaceDetailTask launches the Windows Phone Marketplace client application, which then shows the details page for a product specified by the unique identifier you provide. If you do not provide an identifier, the details page for the calling application is shown. The only allowed value for the ContentType property is Applications.

// Show an application, using the default ContentType.
MarketplaceDetailTask marketplaceDetailTask = new MarketplaceDetailTask();
marketplaceDetailTask.ContentIdentifier = "<ID>";
marketplaceDetailTask.ContentType = MarketplaceContentType.Applications;
marketplaceDetailTask.Show();

MarketplaceHubTask

MarketplaceHubTask launches the Windows Phone Marketplace client application. Set the ContentType property to a value from the MarketplaceContentType enumeration to launch the Hub to a particular type of content.

MarketplaceHubTask marketplaceHubTask = new MarketplaceHubTask();

marketplaceHubTask.ContentType = MarketplaceContentType.Music;

marketplaceHubTask.Show();

MarketplaceReviewTask

MarketplaceReviewTask launches the Windows Phone Marketplace client application, which then displays the review page for your application.

MarketplaceReviewTask marketplaceReviewTask = new MarketplaceReviewTask();

marketplaceReviewTask.Show();

MarketplaceSearchTask

MarketplaceSearchTask launches the Windows Phone Marketplace client application, which then shows the search results based on search terms you provide. You must provide a value for the ContentType property to specify what type of content you are searching for unless you are searching for an application, which is the default content type.

To search for an application, use the following code.

//Search for an application, using the default ContentType.
MarketplaceSearchTask marketplaceSearchTask = new MarketplaceSearchTask();
marketplaceSearchTask.SearchTerms = "Apple Watch";
marketplaceSearchTask.Show();

To search for an application author, use the following code.

//Search for an application, using the default ContentType.
MarketplaceSearchTask marketplaceSearchTask = new MarketplaceSearchTask();
marketplaceSearchTask.SearchTerms = "Web Services UK";
marketplaceSearchTask.Show();

To search for a music item, use the following code.

//Search for a music item.
MarketplaceSearchTask marketplaceSearchTask = new MarketplaceSearchTask();
marketplaceSearchTask.ContentType = MarketplaceContentType.Music;
marketplaceSearchTask.SearchTerms = "Teenage Kicks";
marketplaceSearchTask.Show();

MediaPlayerLauncher

MediaPlayerLauncher launches the Media Player application and plays the media file you specify. Media files are stored in isolated storage when saved to disk by the application and are stored in the application’s installation directory if they are bundled into the applications .xap file. You must specify one of these locations using the MediaLocationType enumeration. You can optionally specify that one or more controls should be shown by the Media Player using bitwise OR combinations of the MediaPlaybackControls values. You can also specify a preferred orientation for the player when it is launched.

MediaPlayerLauncher mediaPlayerLauncher = new MediaPlayerLauncher();

mediaPlayerLauncher.Media = new Uri("MyVideo.wmv", UriKind.Relative);

mediaPlayerLauncher.Location = MediaLocationType.Data;

mediaPlayerLauncher.Controls = MediaPlaybackControls.Pause | MediaPlaybackControls.Stop;

mediaPlayerLauncher.Orientation = MediaPlayerOrientation.Landscape;

mediaPlayerLauncher.Show();

PhoneCallTask

PhoneCallTask launches the Phone application and displays the specified phone number and display name. The phone call is not placed until it is initiated by the user.

PhoneCallTask phoneCallTask = new PhoneCallTask();
phoneCallTask.PhoneNumber = "55555555555";
phoneCallTask.DisplayName = "Gage";
phoneCallTask.Show();

SearchTask

SearchTask launches the Search application and performs the search query you provide.

SearchTask searchTask = new SearchTask();
searchTask.SearchQuery = "XBox game trailers";
searchTask.Show();

ShareLinkTask

ShareLinkTask launches a dialog that enables the user to share a link on the social networks of their choice.

ShareLinkTask shareLinkTask = new ShareLinkTask();
shareLinkTask.Title = "Code Samples";
shareLinkTask.LinkUri = new Uri(http://rd3d2.wordpress.com, UriKind.Absolute);
shareLinkTask.Message = "Here is a blog all about Windows Phone.";
shareLinkTask.Show();

ShareStatusTask

ShareStatusTask launches a dialog that enables the user to share a status message on the social networks of their choice.

ShareStatusTask shareStatusTask = new ShareStatusTask();
shareStatusTask.Status = "This is my current status.";
shareStatusTask.Show();

SmsComposeTask

SmsComposeTask launches the Messaging application, which displays a new SMS message. You can optionally specify recipients and a message body that are prepopulated in the new message. The message is not sent until it is initiated by the user.

SmsComposeTask smsComposeTask = new SmsComposeTask();

smsComposeTask.To = "5555555555";

smsComposeTask.Body = "Check out this new app.";

smsComposeTask.Show();

WebBrowserTask

WebBrowserTask launches the Web browser and displays the URL you provide.

WebBrowserTask webBrowserTask = new WebBrowserTask();

webBrowserTask.Uri = new Uri("http://webservicesuk.com&quot;, UriKind.Absolute);

webBrowserTask.Show();