Windows Phone 8 : Phone Integration - Using Tasks (part 1) - Launchers

Windows Phone has several of the features of the operating system, including accessing the address book, launching the web browser, and using the camera. To give you access to these features, the Windows Phone SDK supports a list of tasks you can execute. These tasks are divided into two categories: launchers and choosers. A launcher simply takes the user to another part of the phone experience to accomplish some goal (for example, launch a web page, make a phone call, and so on). A chooser takes the user to a facility on the phone but returns to the app with some information (for instance, choose an email address, take a picture, and so on). Tables 1 and 2 show the launchers and choosers available for the phone.

TABLE 1 Launchers

TABLE 2 Choosers

All these tasks are in the same namespace: Microsoft.Phone.Tasks.

void webBrowserTask_Click(object sender, RoutedEventArgs e)
{
  var task = new WebBrowserTask();
  task.Uri = new Uri("http://microsoft.com");
  task.Show();
}

Although the launchers do not use a common interface, they do follow the same convention, so they should be easy to work with. Let’s look at each one.

void composeEmailButton_Click(object sender, RoutedEventArgs e)
{
  var task = new EmailComposeTask();
  task.To = "[email protected]";
  task.Cc = "[email protected]";
  task.Subject = "Your Email";
  task.Body = "This is an email";
  task.Show();
}

All these properties are completely optional. If the user just wants to launch an email, you can create it and call Show. The Body property is always plain text. There is no support for creating a body with HTML in this release or adding attachments to emails.

This task is like the others in that you simply set default data and then call the Show method. In this case the task has a Start and Stop property. Each of these properties takes a structure called a LabeledMapLocation. The location, in turn, takes both a Label and a Location. The Label is a string that can contain a simple label or can contain a search term. The Location property takes a GeoCoordinate object that contains the latitude and longitude to use for the maps. For example

var start = new LabeledMapLocation()
{
  Label = "Home",
  Location = new GeoCoordinate(33.769138, -84.33596)
};

var end = new LabeledMapLocation()
{
  Label = "Turner Field",
  Location = new GeoCoordinate(33.735194, -84.389645)
};

var task = new MapsDirectionsTask()
{
  Start = start,
  End = end
};

task.Show();

When the Show method is executed, the Maps application is launched and attempts to calculate the directions. If your goal is to navigate from the user’s current location, you can just omit the Start property on the MapsDirectionsTask altogether:

var end = new LabeledMapLocation()
{
  Label = "Turner Field",
  Location = new GeoCoordinate(33.735194, -84.389645)
};

var task = new MapsDirectionsTask()
{
  End = end
};

task.Show();

By leaving off the Start property, this simply assumes that you want to start from the user’s current location. Calculating GeoCoordinates can be a pain so you can also omit the Location property to have the Label of the LabeledMapLocation act as a search phrase:

var end = new LabeledMapLocation()
{
  Label = "Turner Field"
};

var task = new MapsDirectionsTask()
{
  End = end
};

task.Show();

In this example, the ending location will be marked as “Turner Field” and the map application will attempt to find Turner Field from your location. You can also do this using any search information like an address as the Label:

var end = new LabeledMapLocation()
{
  Label = "755 Hank Aaron Drive Southeast  Atlanta, GA 30315"
};

var task = new MapsDirectionsTask()
{
  End = end
};

task.Show();

var task = new MapsTask()
{
  Center = new GeoCoordinate(33.735194, -84.389645),
  ZoomLevel = 2
};

task.Show();

The Center property is the center of the map to show. The ZoomLevel is how far into the map to display. In this case, ZoomLevel of 2 is going to show most of the world. If you omit the Center property, it will simply center the map on the current location for the user.

The other way the MapsTask works is to enable you to search on the map. In this case you would just supply the SearchPhrase property with what you want to search for. If you simply want to show an address, just use the SearchPhrase with the address:

var task = new MapsTask()
{
  SearchTerm = "755 Hank Aaron Drive Southeast  Atlanta, GA 30315",
};

task.Show();

More commonly you would use the SearchTerm property to search the map. For instance, to find pizza restaurants, you would:

var task = new MapsTask()
{
  SearchTerm = "pizza",
};

task.Show();

Note that the ZoomLevel and Center properties are ignored if you use the SearchPhrase.

var task = new MapDownloaderTask();

task.Show();

void marketplaceDetailButton_Click(object sender, RoutedEventArgs e)
{
  // Show our Detail Page
  var task = new MarketplaceDetailTask();
  task.Show();
}

If you have a specific application content identifier (the GUID that represents the application), you can specify it:

void marketplaceDetailButton_Click(object sender, RoutedEventArgs e)
{
  // Show our Detail Page
  var task = new MarketplaceDetailTask();
  task.ContentIdentifier = "a518bd6c-280e-e011-9264-00237de2db9e";
  task.ContentType = MarketplaceContentType.Applications;
  task.Show();
}

void marketplaceHubButton_Click(object sender, RoutedEventArgs e)
{
  // Show the Marketplace Hub
  var task = new MarketplaceHubTask();
  task.ContentType = MarketplaceContentType.Applications; // Or Music
  task.Show();
}

Note that this task does not work in the emulator because the Marketplace isn’t intended to work in emulation mode.

void marketplaceReviewButton_Click(object sender, RoutedEventArgs e)
{
  // Show the Application Review Page for this application
  var task = new MarketplaceReviewTask();
  task.Show();
}

Because your application is not technically in the Marketplace during development, this task will take you to a review page; then it will complain that it cannot find the application. This is enough to test this task. After your application has been deployed, it will take the user to the correct review page.

void marketplaceSearchButton_Click(object sender, RoutedEventArgs e)
{
  // Show the Marketplace Search Page
  var task = new MarketplaceSearchTask();
  task.ContentType = MarketplaceContentType.Applications; // Or Music
  task.SearchTerms = "Shooting Games";
  task.Show();
}

void mediaPlayerButton_Click(object sender, RoutedEventArgs e)
{
  // Launch the Media Player
  var task = new MediaPlayerLauncher();
  task.Location = MediaLocationType.Install; // Or Data
  task.Media = new Uri("bear.wmv", UriKind.Relative);
  task.Controls = MediaPlaybackControls.All;
  task.Show();
}

In addition, you can specify which controls are shown in the media player. When playing with the MediaPlayerTask, the media player can show three different controls, as highlighted in Figure 1. The control on the left is the Rewind control, the one on the right is the Fast-Forward control, and the one in the center is for toggling between Pause and Play.

FIGURE 1 Media player controls

The MediaPlaybackControls includes a set of enumeration flags, so you can select which controls are used. Table 3 shows the MediaPlaybackControls enumeration.

TABLE 3 MediaPlaybackControls Enumeration

Typically, you would show all controls. However, you can decide to use specific controls by mixing the flags, like so:

void mediaPlayerButton_Click(object sender, RoutedEventArgs e)
{
  // Launch the Media Player
  var task = new MediaPlayerLauncher();
  task.Location = MediaLocationType.Install; // Or Data
  task.Media = new Uri("bear.wmv", UriKind.Relative);
  task.Controls = MediaPlaybackControls.Pause |
                  MediaPlaybackControls.Rewind;
  task.Show();
}

void phoneCallButton_Click(object sender, RoutedEventArgs e)
{
  // Make a phone call
  var task = new PhoneCallTask();
  task.DisplayName = "Lottery Headquarters";
  task.PhoneNumber = "(404) 555 1212";
  task.Show();
}

When this task is launched, the user will be asked for permission to make the phone call, as shown in Figure 2.

FIGURE 2 PhoneCallTask confirmation

var task = new SaveAppointmentTask()
{
  Subject = "Dentist",
  StartTime = DateTime.Parse("11/11/2012 2:00pm"),
  EndTime = DateTime.Parse("11/11/2012 4:00pm"),
  AppointmentStatus = AppointmentStatus.Busy,
  IsAllDayEvent = false,
  Details = "Dr. Smith - 404-555-1212",
  Location = "123 Main Street, Atlanta, GA",
  Reminder = Reminder.FifteenMinutes
};

task.Show();

None of these properties are actually required, but they can be used to fill in default details. The user will still be prompted by the Appointment app to confirm and possibly change the data you send in. The Reminder property is an enumeration of different Reminder values, not the Reminder class that is used to create reminders programmatically. These values specify how long before an appointment to create a reminder (if any).

void searchButton_Click(object sender, RoutedEventArgs e)
{
  // Launch the Search App
  var task = new SearchTask();
  task.SearchQuery = "XBox Games";
  task.Show();
}

private void ShareLink_Click(object sender, RoutedEventArgs e)
{
  // Share a link
  var task = new ShareLinkTask();
  task.LinkUri = new Uri("http://wildermuth.com");
  task.Title = "Shawn's Blog";
  task.Message = "I can't believe his head is turning!";

  task.Show();
}

The user must have a social networking account registered on the phone for this launcher to succeed. If she has more than one social networking account on the phone, it displays a list of which services to use (similar to when you create a new email with more than one account).

private void ShareStatus_Click(object sender, RoutedEventArgs e)
{
  // Share a link
  var task = new ShareStatusTask();
  task.Status = "I'm writing a #wp7 book!";

  task.Show();
}

After shown, this will take you to the share status UI for the phone.

void smsButton_Click(object sender, RoutedEventArgs e)
{
  // Send an SMS Message
  var task = new SmsComposeTask();
  task.To = "(404) 555-1212; (206) 555-1212";
  task.Body = "This is a text message!";
  task.Show();
}

void webBrowserTask_Click(object sender, RoutedEventArgs e)
{
  var task = new WebBrowserTask();
  task.Uri = new Uri("http://microsoft.com");
  task.Show();
}