Problem

You want to be able to allow the user to create and save an appointment in the Calendar application.

Solution

Use the SaveAppointmentTask in the Microsoft.Phone.Tasks namespace.

How It Works

The SaveAppointmentTask falls under the Launcher category of tasks, and its use couldn’t be easier. The first thing you need to do, however, is ensure that your application specifies the capabilities needed in the WPAppManifest.xaml file. Double-click the manifest file under the Properties folder in your project and then select the Capabilities tab. Make sure there is a check in the box beside ID_CAP_APPOINTMENTS.

With the capability added, you are now ready to create a new appointment. You might want to get comfortable and put on some coffee because this is going to take a little time to demonstrate. Ready?

SaveAppointmentTask newAppointment = new SaveAppointmentTask();
newAppointment.Show();

OK, so I might have been exaggerating just a little bit. Those two lines are all you need to launch the new Appointment screen in the Calendar application on the phone. The user can then fill in all of the details and save the new appointment. Or not. You’ll remember from the introduction to this chapter that Launchers don’t return a value or any kind of result to your application. They are “fire and forget.” You won’t even be notified if the user cancels the task. More than likely, you are going to have a specific reason in your application for wanting to create a new appointment, so let’s expand the example a little bit more. First let’s add an app bar button, as shown in Listing 6-1.

Listing 6-1. App Bar Icon Button for Adding an Appointment

<phone:PhoneApplicationPage.ApplicationBar>
    <shell:ApplicationBar IsVisible="True" IsMenuEnabled="False">
        <shell:ApplicationBarIconButton
            Click="AddAppointmentClick"
            IconUri="/Assets/AppBar/add.png"
            Text="add"/>
    </shell:ApplicationBar>
</phone:PhoneApplicationPage.ApplicationBar>

Listing 6-2 shows the XAML for a UI that allows the user to enter a few details. We’ll add a DatePicker for the start and end dates of the appointment and provide a TextBox for the user to enter a location. Figure 6-1 shows the visual results. Ignore the LongListSelector for now. It’s just hanging out backstage waiting for its cue coming up in Recipe 6-2.

Listing 6-2. XAML for the New Appointment User Interface

<Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
     <Grid.RowDefinitions>
         <RowDefinition/>
         <RowDefinition Height="Auto"/>
         <RowDefinition Height="Auto"/>
         <RowDefinition Height="Auto"/>
         <RowDefinition Height="Auto"/>
     </Grid.RowDefinitions>
     <Grid.ColumnDefinitions>
         <ColumnDefinition/>
         <ColumnDefinition/>
     </Grid.ColumnDefinitions>
     <phone:LongListSelector
         Grid.Row="0"
         Grid.Column="0"
         ItemsSource="{Binding Appointments}"
         ItemTemplate="{StaticResource SelectorDataTemplate}"
         Grid.ColumnSpan="2"
         VerticalAlignment="Stretch"
         HorizontalAlignment="Stretch"
         x:Name="appointmentList"/>
     <TextBlock
         VerticalAlignment="Center"
         Grid.Row="1"
         Grid.Column="0"
         Text="start"
         Style="{StaticResource PhoneTextNormalStyle}"/>
     <toolkit:DatePicker
         Grid.Column="0"
         Grid.Row="2"
         x:Name="startDatePicker"/>
     <TextBlock
         VerticalAlignment="Center"
         Grid.Column="1"
         Grid.Row="1"
         Text="end"
         Style="{StaticResource PhoneTextNormalStyle}"/>
     <toolkit:DatePicker
         x:Name="endDatePicker"
         Grid.Column="1"
         Grid.Row="2"/>
     <TextBox
         Grid.Column="0"
         Grid.Row="3"
         Grid.ColumnSpan="2"
         x:Name="locationTextBox"/>
</Grid>

With the user interface in place, we’ll add some code to the Click event of the app bar icon button that prepopulates some of the new appointment’s properties. Listing 6-3 shows the required code.

Listing 6-3. App Bar Icon Button Code for Adding a New Appointment

private void AddAppointmentClick(object sender, EventArgs e)
{
    SaveAppointmentTask newAppointment = new SaveAppointmentTask();
    newAppointment.StartTime = startDatePicker.Value;
    newAppointment.EndTime = endDatePicker.Value;
    newAppointment.Location = locationTextBox.Text;
    newAppointment.Subject = "The CODEZ";
    newAppointment.Show();
}

We just pick up the values from the controls and set the various properties of the SaveAppointmentTask and then call the Show method. Figure 6-2 shows the result of the call to Show. It’s worth repeating that as a Launcher, the SaveAppointmentTask does not return a result or status to the calling code. The only way to know if it succeeded would be to retrieve the appointments and see whether an appointment exists that corresponds to the values you were expecting. Of course, the user may have changed the values that you preset, so your code shouldn’t count on anything being the same.³ Recipe 6-2 will cover searching for an appointment.

Problem

You want to display a list of appointments from the Calendar application within your application.

Solution

Use the SearchAsync method of the Appointments class in the Microsoft.Phone.UserData namespace.

How It Works

As mentioned in the introduction to this chapter, the Microsoft.Phone.UserData namespace contains classes that provide an aggregated view of the user’s contacts and appointments across all accounts.

The first thing you need to do, however, is ensure that your application specifies the capabilities needed in the WPAppManifest.xaml file. Double-click the manifest file under the Properties folder in your project and then select the Capabilities tab. Make sure there is a check in the box beside ID_CAP_APPOINTMENTS. With the capability added, you are now ready to provide appointment search functionality in your application.

First let’s add an app bar button, as shown in Listing 6-4.

Listing 6-4. App Bar Icon Button for Searching Appointments

<phone:PhoneApplicationPage.ApplicationBar>
    <shell:ApplicationBar IsVisible="True" IsMenuEnabled="False">
        <shell:ApplicationBarIconButton
            Click="SearchAppointmentsClick"
            IconUri="/Assets/AppBar/feature.search.png"
            Text="search"/>
    </shell:ApplicationBar>
</phone:PhoneApplicationPage.ApplicationBar>

Listing 6-5 shows the XAML for a UI that allows the user to enter the date range they want to search. We’ve added a DatePicker for the start date and end date. The DatePicker control can be found in the Windows Phone Toolkit available on CodePlex.⁴ We’ve also added a LongListSelector to display the results of our search. Take special note of the ItemTemplate element defined for the LongListSelector and its use of the built-in TextBlock styles defined by the Windows Phone 8 SDK. Using these styles will ensure that your application provides a seamless visual experience for your users. The display of calendar appointments in your application will look the same as those in the Calendar app. It also respects the user’s theme and accent color choices.

Listing 6-5. XAML for the Search Appointments User Interface

<Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
     <Grid.RowDefinitions>
         <RowDefinition/>
         <RowDefinition Height="Auto"/>
         <RowDefinition Height="Auto"/>
         <RowDefinition Height="Auto"/>
         <RowDefinition Height="Auto"/>
     </Grid.RowDefinitions>
     <Grid.ColumnDefinitions>
         <ColumnDefinition/>
         <ColumnDefinition/>
     </Grid.ColumnDefinitions>
     <phone:LongListSelector
         Grid.Row="0"
         Grid.Column="0"
         ItemsSource="{Binding Appointments}"
         Grid.ColumnSpan="2"
         VerticalAlignment="Stretch"
         HorizontalAlignment="Stretch"
         x:Name="appointmentList">
         <phone:LongListSelector.ItemTemplate>
             <DataTemplate >
                 <StackPanel Margin="0,0,0,5">
                     <TextBlock
                         Style="{StaticResource PhoneTextLargeStyle}"
                         Text="{Binding Subject}"/>
                     <TextBlock
                         Style="{StaticResource PhoneTextAccentStyle}"
                         Text="{Binding StartTime}"/>
                     <TextBlock
                         Style="{StaticResource PhoneTextAccentStyle}"
                         Text="{Binding Location}"/>
                 </StackPanel>
             </DataTemplate>
         </phone:LongListSelector.ItemTemplate>
     </phone:LongListSelector>
     <TextBlock
         VerticalAlignment="Center"
         Grid.Row="1"
         Grid.Column="0"
         Text="start"
         Style="{StaticResource PhoneTextNormalStyle}"/>
     <toolkit:DatePicker
         Grid.Column="0"
         Grid.Row="2"
         x:Name="startDatePicker"/>
     <TextBlock
         VerticalAlignment="Center"
         Grid.Column="1"
         Grid.Row="1"
         Text="end"
         Style="{StaticResource PhoneTextNormalStyle}"/>
     <toolkit:DatePicker
         x:Name="endDatePicker"
         Grid.Column="1"
         Grid.Row="2"/>
     <TextBox
         Grid.Column="0"
         Grid.Row="3"
         Grid.ColumnSpan="2"
         x:Name="locationTextBox"/>
</Grid>

Next we’ll need a property to hold the results of our search that we can bind to the LongListSelector for display. To keep things simple and not distract from our goal, we’ll just expose it in a code-behind file and then set the DataContext of the page to itself. MVVM is a fantastic pattern that enables much, but it is not without its overhead. In simple applications, it’s just more pragmatic to just use the code-behind. Listing 6-6 shows how to accomplish this.

Listing 6-6. Setting the DataContext and Exposing the Results of the Search

public AppointmentsView()
   {
       InitializeComponent();
       DataContext = this;
   }
 
   private ObservableCollection<Appointment> appointments
       = new ObservableCollection<Appointment>();
 
   public ObservableCollection<Appointment> Appointments
   {
       get
       {
           return appointments;
       }
       set
       {
           appointments = value;
       }
   }

Now that we have everything we need in place, all that’s left is the code to retrieve the data based on our date range. The SearchAsync method of the Appointments class takes a start date, an end date, and a parameter of type Object that allows you to pass any state information to the SearchCompleted event handler. The state object is stored in the AppointmentsSearchEventArgs. It also has three overloads that allow you to narrow your search by restricting the number of results or by limiting the search to a single account. See Table 6-1 for a description of each overload. Listing 6-7 shows the code-behind for our example.

Listing 6-7. Code-Behind for a Simple Appointment Date Range Search

private void SearchAppointmentsClick(object sender, EventArgs e)
  {
      GetAppointmentsByDateRange(
          startDatePicker.Value ?? DateTime.Today,
          endDatePicker.Value ?? DateTime.Today.AddDays(7));
 
  }
 
  private void GetAppointmentsByDateRange(DateTime startOfRange, DateTime endOfRange)
  {
      Appointments apps = new Appointments();
 
      apps.SearchCompleted += AppointmentsSearchCompleted;
 
      apps.SearchAsync(startOfRange,
          endOfRange,
          null);
  }
 
  void AppointmentsSearchCompleted(object sender, AppointmentsSearchEventArgs e)
  {
      Appointments = new ObservableCollection<Appointment>( e.Results);
  }

There are a couple of things to note in the code. The Value property of the DatePicker is defined as Nullable<DateTime>, but the SearchAsync method does not accept nulls. The easiest way to work with Nullable<T> types is to use the null-coalescing operator (??) to substitute in an appropriate value should the control not have a value set. For this example, a suitable substitute range might be the next seven days.

The GetAppointmentsByDateRange method takes a start date and an end date, adds a SearchCompleted handler, and then calls the SearchAsync method, passing in null for the state parameter because we have nothing interesting to communicate to the handler. The Results property of the AppointmentsSearchEventArgs parameter is an IEnumberable<Appointment>, which we pass to the constructor of a new ObservableCollection<Appointment> to reset the Appointments property we have bound to the LongListSelector.

Figure 6-3 shows the results of a search.

Problem

You want the users of your application to be able to create a new contact in contacts of their Microsoft account.

Solution

Use the SaveContactTask in the Microsoft.Phone.Tasks namespace to configure and launch the new contact page of the built-in People application.

How It Works

The SaveContactTask falls under the Launcher category of tasks, and its use couldn’t be easier. The first thing you need to do, however, is ensure that your application specifies the capabilities needed in the WPAppManifest.xaml file. Double-click the manifest file under the Properties folder in your project and then select the Capabilities tab. Make sure there is a check in the box beside ID_CAP_CONTACTS.

With the capability added, you are now ready to create a new contact. Here is the code required:

SaveContactTask newContact = new SaveContactTask();
newContact.Show();

Those two lines are all you need to launch the new Contact page in the People application on the phone. The user can then fill in all of the details and save the new contact. Or not. Just as I described in the introduction to this chapter, Launchers don’t return a value or any kind of result to your application. They are “fire and forget.” You won’t even be notified if the user cancels the task.

Let’s expand the example a little bit more and add the ability for your application to pass in some additional details before launching the new Contact page. First, let’s add an app bar button, as shown in Listing 6-8.

Listing 6-8. App Bar Icon Button for Adding an Appointment

<phone:PhoneApplicationPage.ApplicationBar>
    <shell:ApplicationBar IsVisible="True" IsMenuEnabled="False">
        <shell:ApplicationBarIconButton
            Click="AddContactClick"
            IconUri="/Assets/AppBar/add.png"
            Text="add"/>
    </shell:ApplicationBar>
</phone:PhoneApplicationPage.ApplicationBar>

Next we’ll add some controls that let the user enter a first name and a last name that will prepopulate the add contact page. The PhoneTextBox is available in the Windows Phone Toolkit, which you can add to your project using NuGet. The PhoneTextBox provides properties such as the Hint help to simplify the user interface. The Hint is displayed as a watermark placeholder in the text box, so there is no need for a label. See Recipe 2-6 for additional information on working with the Windows Phone Toolkit. Listing 6-9 shows the XAML we need.

Listing 6-9. XAML for the Add Contact Functionality

<Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
    <Grid.RowDefinitions>
        <RowDefinition Height="1*"/>
        <RowDefinition Height="2*"/>
        <RowDefinition Height="Auto"/>
        <RowDefinition Height="Auto"/>
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition/>
        <ColumnDefinition/>
    </Grid.ColumnDefinitions>
    <StackPanel Grid.Row="0" Grid.ColumnSpan="2">
        <TextBlock
            Text="accounts"/>
        <phone:LongListSelector
            Name="accountSources"
            ItemsSource="{Binding Accounts}"
            Margin="24,0,0,0">
            <phone:LongListSelector.ItemTemplate>
                <DataTemplate>
                    <TextBlock
                        Name="ContactResults"
                        Text="{Binding Path=Name}"/>
                </DataTemplate>
            </phone:LongListSelector.ItemTemplate>
        </phone:LongListSelector>
    </StackPanel>
    <StackPanel Grid.ColumnSpan="2" Grid.Row="1">
        <TextBlock
            Text="contacts"/>
        <phone:LongListSelector
            ItemTemplate="{StaticResource ContactDataTemplate}"
            ItemsSource="{Binding Contacts}"
            Margin="24,0,0,0"
            x:Name="contactList"/>
    </StackPanel>
    <toolkit:PhoneTextBox
        Grid.Row="3"
        Grid.Column="0"
        x:Name="firstNameTextBox"
        Hint="first name" />
    <toolkit:PhoneTextBox
        Grid.Column="1"
        Grid.Row="3"
        Hint="last name"
        x:Name="lastNameTextBox"/>
</Grid>

The only thing left to do now is to add some code to create a SaveContactTask, set the first and last name properties to the values entered in the PhoneTextBox, and start the Show. Listing 6-10 has the required code.

Listing 6-10. The Code Required to Save a New Contact

private void NewContactClick(object sender, EventArgs e)
{
    SaveContactTask saveContact = new SaveContactTask();
    saveContact.FirstName = firstNameTextBox.Text;
    saveContact.LastName = lastNameTextBox.Text;
    saveContact.Completed += SaveContactCompleted;
    saveContact.Show();
 
}
 
void SaveContactCompleted(object sender, SaveContactResult e)
{
    if (e.TaskResult == TaskResult.OK)
    {
        MessageBox.Show("Contact Added");
    }
    else if (e.TaskResult == TaskResult.Cancel)
    {
        MessageBox.Show("Contact not added. You cancelled it.");
    }
}

And that’s all there is to it. As I mentioned in the sidebar, interacting with user data and the Launcher and Chooser APIs is incredibly simple and straightforward.

Problem

You want to allow the user of your application to search for a specific contact or a piece of information about that contact.

Solution

There are several ways to solve this problem depending on the information you desire to retrieve. You can use the SearchAsync method of the Contacts class in the Microsoft.Phone.UserData namespace to find a contact. There are also several chooser tasks available to find specific pieces of information about a contact. They are as follows:

• AddressChooserTask
• PhoneNumberChooserTask
• EmailAddressChooserTask

How It Works

We’ll forego the creation of any type of user interface in this recipe so that we can devote more space to searching using the Contacts class in the Microsoft.Phone.UserData namespace. Using the Chooser tasks is quite straightforward, so we’ll focus on using the Contacts class only. As you will see, its implementation is. . .interesting.

The first thing you need to do, however, is ensure that your application specifies the capabilities needed in the WPAppManifest.xaml file. Double-click the manifest file under the Properties folder in your project and then select the Capabilities tab. Make sure there is a check in the box beside ID_CAP_CONTACTS. With the capability added, you are now ready to work with the various elements of this recipe.

Bubble yourBubble = new Bubble();
yourBubble.Burst();

Problem

You have an application that has a need to create and store its own contacts. You would like it if these contacts were also available to the user in the People hub.

Solution

You can create application-specific contacts that are stored on the phone by using the ContactStore class in the Microsoft.Phone.PersonalInformation namespace.

How It Works

I’ve been writing these recipes in the order in which they are listed in the book, so I’m coming from a different perspective than you might be if you just jumped right into this recipe. If you’ve been reading this chapter from the beginning, then you’ll understand when I say, “I get to use async/await! Finally!”⁹

Asynchronous programming is generally regarded as a must for Windows Phone 8 development, and almost everything you interact with has an asynchronous implementation. What is somewhat surprising, however, is that the APIs are implemented using the event-based asynchronous pattern. The .NET daddy of multithreading and asynchronous programming, Jeffrey Richter, believes that this model should never have been introduced into the framework,¹⁰ as do many others. There are very few classes in the entire Framework Class Library that implement this pattern. There are 17 to be exact. In any case, rant over. On with the code.

ContactStore store = await ContactStore.CreateOrOpenAsync();

StoredContact contact = new StoredContact(store);
contact.FamilyName = "Totzke";
contact.GivenName = "Dave";
await contact.SaveAsync();

IDictionary<string, object> props = await contact.GetExtendedPropertiesAsync();
props.Add("FavoriteColor", "CobaltBlue");
await contact.SaveAsync();

props.Add(KnownContactProperties.JobTitle, "Dark Wizard");