Mapping Content

Each of the different Tile templates has an associated class that defines the data consumed by the Tile. For the Flip Tile this is the FlipTileData class. You don’t use this class directly when defining your default tile but rather enter values in the PrimaryToken element in the WPAppManifest.xaml file. The names of the properties on the FlipTileData class don’t correspond directly to the element names contained in the PrimaryToken. Table 4-2 shows how each property maps to its corresponding element. You’ll see this class in use in the recipes in Recipe 4-5 on creating Secondary Tiles in this chapter as well as in Chapter 5 on Tile notifications.

Character Content

Character-based content is limited to predefined areas of the template and therefore limited in length. The Flip Tile template won’t wrap text or add an ellipsis to the end of a line and will simply truncate the data if it is too long for display. Table 4-3 shows the number of characters that can be accommodated by each text area in the template. The Segoe WP font that is used to display text on the start screen is not a fixed width font, and therefore the character counts are approximations only.

Visual Layout

The layout of the Flip Tile is predefined and you have no control over how the content is presented. This is a good thing because it enables you to focus on the content data and not have to worry about providing a consistent visual experience for the user. Figure 4-5 shows a typical Flip Tile with complete content.

The content provided by the values you enter for the properties in Table 4-2 gets mapped into the Tile in a predefined way. Figure 4-6 shows how each of these values maps into the Flip Tile template for each of the small, medium, and large Tile formats.

Figure 4-7 illustrates the layout of the various parts of the Tile for each of the sizes. Table 4-4 lists the size of the images used for each size.

Mapping Content

Each of the different Tile templates has an associated class that defines the data consumed by the Tile. For the Iconic Tile this is the IconicTileData class. You don’t use this class directly when defining your default tile but, rather, enter values in the PrimaryToken element in the WPAppManifest.xaml file. The names of the properties on the IconicTileData class don’t correspond directly to the element names contained in the PrimaryToken. Table 4-5 shows how each property maps to its corresponding element. You’ll see this class in use in Recipe 4-5 on creating Secondary Tiles in this chapter as well as in Chapter 5 on Tile notifications.

Figure 4-8 shows a typical Iconic Tile with complete content.

Character Content

Character-based content is limited to predefined areas of the template and therefore limited in length. The Iconic Tile template won’t wrap text or add an ellipsis to the end of a line and will simply truncate the data if it is too long for display. Table 4-6 shows the number of characters that can be accommodated by each text area in the template. The Segoe WP font that is used to display text on the start screen is not a fixed width font, and therefore the character counts are approximations only.

Visual Layout

The layout of the Iconic Tile is predefined and you have no control over how the content is presented. This is a good thing because it enables you to focus on the content data and not have to worry about providing a consistent visual experience for the user.

The content provided by the values you enter for the properties in Table 4-5 gets mapped into the Tile in a predefined way. Figure 4-9 shows how each of these values maps into the Iconic Tile template for each of the small, medium, and large Tile formats. Figure 4-10 shows the dimensions of the various layout areas of the Tile.

Icon Design

There are a few things you need to keep in mind when creating your icon to ensure proper scalability across resolutions. You’ll need to supply two images: one for SmallIconImage and one for IconImage (SmallIconImageURI and IconImageURI, respectively, in WPAppManifest).

• SmallIconImage

• Used when the Tile is set to small or when the Tile is set to large and you’ve provided content in the WideContent properties. See Figure 4-9.
• The maximum size of this image is 110 pixels by 110 pixels but. . .
• The recommended “best fit” dimensions are 70 pixels wide by 110 pixels high.

• IconImage

• Used when the Tile is set to medium or when the Tile is wide and has no content strings on it and may or may not have a count. See Figure 4-9.
• The maximum size of this image is 202 pixels by 202 pixels, but. . .
• The recommended “best fit” dimensions are 130 pixels by 202 pixels

For the best results when creating your assets, always pad vertically with a transparent buffer to the full size of the asset you’re creating. Let’s assume you have an icon where the white pixels in the medium or large image are only 130 pixels high. In this case you would pad the top and bottom of the icon out to 202 pixels high using a transparent buffer area. Remember to always keep the image centered vertically.

Contrary to what is done for the vertical plane, the horizontal plane is always cropped tight to the image. Crop the image to its actual width and don’t pad the horizontal plane with a transparent buffer. Adding a transparent horizontal buffer will push the count too far away from the image and it won’t look consistent with the icons of other application tiles.

You will achieve the best results if you begin with the layout of your large icon image and, if possible, scale it down for the small icon. For example, if we assume a “best fit” large icon that’s 130 pixels wide by 202 pixels tall, set the small aspect ratio to 110 pixels tall and approximately 70 pixels wide. This is virtually the same aspect ratio, so everything should look fine when scaling down.

Mapping Content

Each of the different Tile templates has an associated class that defines the data consumed by the Tile. For the Cycle Tile this is the CycleTileData class. You don’t use this class directly when defining your default tile but rather enter values in the PrimaryToken element in the WPAppManifest.xaml file. The names of the properties on the CycleTileData class don’t correspond directly to the element names contained in the PrimaryToken. Table 4-7 shows how each property maps to its corresponding element. You’ll see this class in use in the recipes in Recipe 4-5 on creating Secondary Tiles in this chapter as well as in Chapter 5 on Tile notifications.

Character Content

The only character-based content that can be configured is the Title and has the same limitations as the Title of the other Tile templates. Table 4-8 shows the number of characters that can be accommodated by each text area in the template. The Segoe WP font that is used to display text on the start screen is not a fixed-width font, and therefore the character counts are approximations only.

Visual Layout

The visual layout of the Cycle Tile template is fairly simple. The Count is displayed in the top-right corner of all three sizes of tile and the Title is displayed in the bottom-left corner of the medium and large sizes. No Title is displayed for the small size. Figure 4-11 shows how each property of the CycleTileData class maps into the Tile. Figure 4-12 shows the dimensions of the layout areas.

The images you provide to the Cycle Tile are, you guessed it, cycled through one at a time at random intervals. The image may be cropped or zoomed depending on its size and it is also animated to slide slowly across the tile. Think of someone carrying a large picture past a smaller window. You have no control over any of the manipulations applied to your image and are at the mercy of Windows Phone 8.³ It’s because of these random animations and transitions that text content in the images isn’t very practical. Figure 4-13 shows an example, albeit a static one, of this transition.

Add an App Bar

The first thing you’ll need is an application bar for the page that contains the content you want to pin. See Recipe 2-3 in Chapter 2 for the gory details of working with the app bar. We’ll keep it simple in this recipe. Listing 4-2 shows the XAML to add to create an app bar with a pin/unpin button.

Listing 4-2. XAML for the App Bar With a Pin/Unpin Button

<phone:PhoneApplicationPage.ApplicationBar>
    <shell:ApplicationBar IsVisible="True" IsMenuEnabled="True">
         <shell:ApplicationBarIconButton
            x:Name="btnPinToStart"
            IconUri="/Assets/pin.png"
            IsEnabled="True"
            Text="pin to start"
            Click="PinToStartScreenClick"/>
    </shell:ApplicationBar>
</phone:PhoneApplicationPage.ApplicationBar>

Creating the Tile

Unlike the default Tile that you configure in the WPAppManifest.xml file, secondary Tiles can only be created through code at the explicit request of the user. You can refer to the other recipes in this chapter for information on the design of each type of Tile. Here we’ll just create a Flip Tile. First, we’ll need some content that the user of our application can pin to the start screen. You can follow along in the sample application included with the book’s source or you can create a new project using the Windows Phone Databound App project template and work with the Details.xaml page in that.

The next thing we need to do is handle the Click event of the pin button. There are three things we need to do here:

1. If there is already a Tile for the current content, then it was previously pinned and we need to remove it.
2. If a Tile doesn’t exist for the current content, then we need to create one.
3. Update the app bar button to reflect the proper state for the current content.

You’ll see these tasks reflected in the code from the sample application shown in Listing 4-3. Also included are some helper functions for working with the Tiles. The Source property of the NavigationService will tell us how we got to this page. See Recipe 2-4 in Chapter 2 for more information on the NavigationService. This is the same URI that would have been used to create the secondary tile in the first place. Key to all of these functions is the ShellTile class.

The ShellTile class exposes a static property called ActiveTiles that contains all of the Tiles for your application. ActiveTiles always contains at least one item representing the Application Tile which cannot be deleted. The Application Tile is always the first item in the list. The ActiveTiles list also contains any secondary Tiles that have been created. The CharacterTileExists and DeleteCharacterTile helper methods use the ActiveTiles property to find a specific tile reference.

The ShellTileClass also exposes a static method called CreateTile. The CreateTile method has two implementations. When working with Windows Phone 8, you should always use the overload that requires three parameters. When passed anything other than a StandardTileData object, the other implementation will throw an InvalidOperationException. There’s nothing to stop you from using StandardTileData bit it’s not part of the official design guidelines and is only there for backwards compatibility with Windows Phone 7.x. It will behave pretty much the same as FlipTileData but has no support for the large size and you can’t configure a different image for the small size.

The SetPinBar method is pretty straight forward. It again uses the Source property of the NavigationService to test if a character tile exists and changes the icon and text of the app bar button based on the results.

Listing 4-3. The Click Event Handler for the App Bar Pin Button

private void PinToStartScreenClick(object sender, EventArgs e)
{
    string uri = NavigationService.Source.ToString();
 
    if (CharacterTileExists(uri))
    {
        // If the tile already exists, then we delete it
        DeleteCharacterTile(uri);
    }
    else
    {
        // Otherwise create it
        SetCharacterTile(uri);
    }
 
    SetPinBar();
 
}
private bool CharacterTileExists(string navigationSource)
{
    ShellTile tile = ShellTile.ActiveTiles
         .FirstOrDefault(o => o.NavigationUri.ToString().Contains(navigationSource));
    return tile == null ? false : true;
}
 
private void DeleteCharacterTile(string navigationSource)
{
    ShellTile tile = ShellTile.ActiveTiles
         .FirstOrDefault(o => o.NavigationUri.ToString().Contains(navigationSource));
    if (tile != null)
    {
        tile.Delete();
    }
 
}
 
private void SetCharacterTile(string navigationSource)
{
 
    FlipTileData tileData = new FlipTileData()
    {
        Title = selectedCharacter.CharacterName,
        SmallBackgroundImage =
             new Uri(selectedCharacter.ImageUri, UriKind.RelativeOrAbsolute),
        BackgroundImage =
             new Uri(selectedCharacter.ImageUri, UriKind.RelativeOrAbsolute),
        BackTitle = selectedCharacter.CharacterName
    };
 
    ShellTile.Create(new Uri(navigationSource, UriKind.Relative), tileData, true);
 
}
 
private void SetPinBar()
{
    var uri = NavigationService.Source.ToString();
    if (CharacterTileExists(uri))
    {
        PinButton.IconUri = new Uri("/Assets/unpin.png", UriKind.Relative);
        PinButton.Text = "Unpin";
    }
    else
    {
        PinButton.IconUri = new Uri("/Assets/pin.png", UriKind.Relative);
        PinButton.Text = "Pin";
    }
}

Handling Navigation

The whole point of a secondary tile is to provide the users of your application with a deep link into your content. If you run the application now with only what we’ve done so far, you’ll find yourself on the right page but the app bar button won’t reflect the fact that this content is already pinned. Everything still works fine, but the user is going to be confused. Fortunately, this is easily solved by adding a call to SetPinBar in the OnNavigatedTo method override.

You should already have code in this method to handle setting the DataContext of your page to the right item. Simply add the call to SetPinBar as the last line of code in this method so it can fix up the app bar button. See Listing 4-4 for an example.

Listing 4-4. DataContext management code with SetPinBar function call

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    if (DataContext == null)
    {
        string selectedCharacterName = "";
        if (NavigationContext.QueryString
            .TryGetValue("selectedItem", out selectedCharacterName))
        {
            if (!string.IsNullOrEmpty(selectedCharacterName))
            {
                selectedCharacter = (from character in App.ViewModel.Items
                                     where character.CharacterName == selectedCharacterName
                                     select character).FirstOrDefault();
                DataContext = selectedCharacter;
            }
        }
    }
 
    SetPinBar();
}

Design Guide

There aren’t too many restrictions on the background image, but there are a couple of important things to keep in mind. You should keep any text content in your image to a minimum. The image also shouldn’t be too “busy”. The lock screen is more than just eye candy. It is also interactive in that it provides the user with relevant information at a glance without them having to unlock the phone.

The current time and the next upcoming appointment are two of the default pieces of information that are displayed on the lock screen. Too much text, or a vivid and complex image, is going to interfere with, and distract from, this information as well as annoy the user. Annoyed users ususally uninstall your application. That’s no good for anybody. Figure 4-14 shows a nice example of an appropriate lock screen background image.

It’s certainly appropriate to include your application’s logo and your company name or other brief information on the background, but keep in mind that this information is static. It’s possible to replace the lock screen from a background agent to update the information, but this requires swapping out the entire background. The lock screen has a clearly defined area in which you should contain your content. It’s always in the top-left region of the screen but differs in dimensions for each screen resolution. Figure 4-15 shows the location and dimensions of the application content section for each of the three device resolutions, and Figure 4-16 shows three excellent examples of the use of this area.

You’ll want to keep the text as well as the logo, if you include one, relatively small so that they won’t compete with the date, time, and notifications. You might even consider making your logo slightly transparent. The text you include should be directly related to the image you are displaying and not, for example, an advertisement for your application. People have been killed for less.⁴ The focus of the lock screen image should be the visual and not the text.

Provide a Default Lock Screen Image

Now that you’ve designed the most awesome lock screen image anyone will ever need, you must now unleash it upon the world.⁵ Providing a default lock screen image couldn’t be simpler.

All you need to do is register your application by adding the Lockscreen_Background extension in the WPAppManifest.xml file and provide a default lock screen image in the root of your application named, of all things, DefaultLockScreen.jpg. In the manifest file, immediately after the </Tokens> section, which always exists, you may need to add an <Elements> section to the manifest. Listing 4-5 shows the required XML element. The ConsumerID is just one of those “magic strings” and will never change.

Listing 4-5. Extension Element XML to register as a LockScreen Background provider

</Tokens>
<!-- Immediately after Tokens -->
<Extensions>
  <Extension
    ExtensionName="LockScreen_Background"
    ConsumerID="{111DFF24-AA15-4A96-8006-2BFF8122084F}"
    TaskID="_default"/>
</Extensions>

Now that you have registered your application to provide a lock screen background you will find that you application now shows up in the Settings on your phone. Deploy your application to your device or emulator and then open the Settings on the device. Tap on lock screen and you should see the screen in Figure 4-17. Tap on the box below the Background caption and you will be presented with a screen listing all of the applications that can provide a background. Your application should appear in this list. See Figure 4-18.

Select your application from the list and then lock your device to see your image displayed. If you are using the emulator you can lock the device in one of two ways. You can press F12 when the emulator has focus to turn off the screen and lock the device and then again to wake it up. The other way is to use the Simulation Dashboard in Visual Studio by choosing it from Tools menu. Figure 4-19 shows the Dashboard. Simply toggle the radio button below Lock Screen between Locked and Unlocked to lock the emulator.

Let the User Choose a Lock Screen Background

Setting the lock screen image in code is almost as easy as setting up the default. You provide an app bar button for the page that represents the image you want to use and then use the LockScreenManager and LockScreen classes to set the selected image as the background.

Create a method in your code-behind that will be called when the user makes a selection. You can use a contextual menu, an app bar button, or your own button. The method in Listing 4-6 is for the Click event of an app bar button.

Listing 4-6. App Bar Button Click Code

private async void SetAsLockScreenBackGround(object sender, EventArgs e)
{
    if (!LockScreenManager.IsProvidedByCurrentApplication)
    {
        await LockScreenManager.RequestAccessAsync();
    }
 
    if (LockScreenManager.IsProvidedByCurrentApplication)
    {
        Uri tempUri = new Uri
            (
            string.Format("ms-appx://{0}", selectedCharacter.ImageUri),
            UriKind.RelativeOrAbsolute
            );
 
        LockScreen.SetImageUri(tempUri);
    }
}

First we check with the LockScreenManager to see if we are currently set as the lock screen background provider, and if not, we request access. Calling The RequestAccessAsync method of the LockScreenManager will pop up a dialog (Figure 4-20) asking the user if they will allow us to set the background. When we return from this call, we again check the IsProvidedByCurrentApplication property and if the user agreed, we go ahead and set the background image. Setting the background image is a simple matter of calling the SetImageUri static method of the LockScreen and passing it a valid Uri pointing to the image you want on the lock screen.

Lock Screen Icon

The lock screen icon must be a PNG file that is 38 x 38 pixels in size. The image must contain only white pixels and have some level of transparency. Once you have the image, edit the WPAppManifest.xml file by right-clicking it and choosing Open With. Within the <PrimaryToken> element you will find the <DeviceLockImageURI> element. Set the IsRelative attribute to “true” and the IsResource attribute to “false”. Add the full path to your icon inside the element as shown in the following example:

<DeviceLockImageURI
  IsRelative="true"
  IsResource="false">AssetsLockIcon.png</DeviceLockImageURI>

Extension Configuration

After configuring the <DeviceLockImageURI> you can add in the extensions while you are editing the manifest. Add the LockScreen_Notification_IconCount and LockScreen_NotificationTextField extensions to the <Extensions> element. You may have to add this element to the manifest, and if so, it should be added immediately after the <Tokens> element. Listing 4-7 shows a properly configured manifest.

Listing 4-7. The <Extensions> Element in WPAppManifest.xml

</Tokens>
<!-- Immediately after Tokens -->
<Extensions>
  <Extension
    ExtensionName="LockScreen_Notification_IconCount"
    ConsumerID="{111DFF24-AA15-4A96-8006-2BFF8122084F}"
    TaskID="_default"/>
  <Extension
    ExtensionName="LockScreen_Notification_TextField"
    ConsumerID="{111DFF24-AA15-4A96-8006-2BFF8122084F}"
    TaskID="_default"/>
  <Extension
    ExtensionName="LockScreen_Background"
    ConsumerID="{111DFF24-AA15-4A96-8006-2BFF8122084F}"
    TaskID="_default"/>
</Extensions>

Linking to the Lock Screen Settings

The last thing you might want to consider is to add a way for the user to get to the lock screen settings page from within your application. For this example, we’ll use an app bar menu item on the main page of the application. Listing 4-8 shows the code and XAML needed. In the Click event handler you simple call the LaunchUriAsync method of the System.Windows.Launcher class passing in the ms-settings-lock: path.

Listing 4-8. App Bar Menu Item and Click Handler for Lock Screen Settings Page Navigation

<phone:PhoneApplicationPage.ApplicationBar>
    <shell:ApplicationBar Mode="Minimized">
        <shell:ApplicationBar.MenuItems>
            <shell:ApplicationBarMenuItem
                x:Name="AboutMenuItem"
                IsEnabled="True"
                Text="lock screen settings"
                Click="SettingsMenuItemClick"/>
        </shell:ApplicationBar.MenuItems>
    </shell:ApplicationBar>
</phone:PhoneApplicationPage.ApplicationBar>
 
private async void SettingsMenuItemClick(object sender, EventArgs e)
{
    // Launch URI for the lock screen settings screen.
    Uri lockSettingsUri = new Uri("ms-settings-lock:");
    await Launcher.LaunchUriAsync(lockSettingsUri);
 
}