Setting the Lock Screen’s Notification Text
,Unlike the lock screen background image, the values for the lock screen’s quick status and notification text are pulled from the app’s primary tile.
When using a flip tile template, the notification text corresponds to the WideBackContent property of the FlipTileData object that is used to update the tile. When using the iconic tile template, the three lines of text in the notification area correspond to the WideContent1, WideContent2, and WideContent3 properties of the IconicTileData object.
Note
The cycle tile template does not allow you to populate the notification area with text because the CycleTileData class does not contain a property that maps to the notification area text field.
Enabling your app to display notifications on the lock screen requires that the user select your app as the notification provider in the phone’s lock screen settings. Unlike the lock screen background image, there is no built-in confirmation dialog for enabling text notifications, and no way to request permission from your app.
The SetNotification method of the custom LockScreenService class, shown in Listing 13.2, retrieves the primary tile for the app. There is no API for determining the type of tile being used, so it attempts to update the tile using each type of tile data. The method is deemed successful as soon as an ArgumentException is not raised during the call to ShellTile.Update.
LISTING 13.2. LockScreenService.SetNotification Method
public void SetNotification(
string line1, int? count = null,
string line2 = null, string line3 = null)
{
ShellTile tile = ShellTile.ActiveTiles.First();
var iconicTileData = new IconicTileData
{
WideContent1 = line1,
WideContent2 = line2,
WideContent3 = line3,
Count = count
};
try
{
tile.Update(iconicTileData);
}
catch (ArgumentException)
{
var data = new FlipTileData
{
WideBackContent = string.Format(
"{0} {1} {2}", line1, line2, line3),
Count = count
};
try
{
tile.Update(data);
}
catch (ArgumentException ex)
{
var cycleTileData = new CycleTileData {Count = count};
try
{
tile.Update(cycleTileData);
}
catch (ArgumentException)
{
throw new Exception("Unable to set notification text. "
+ "Tile must be either flip or iconic.", ex);
}
}
}
}
Caution
When updating a tile, the tile data object replaces all of its content. Keep this in mind when you are attempting to update a single field—for example, the tile’s Count property—because you may unintentionally clear the tile and lock screen’s notification text.
The source code for this section is located in the LockScreen directory of the WPUnleashed.Examples project in the downloadable sample code. The LockScreenContentViewModel class uses the custom lock screen service to set the notification text, count field, and background image of the lock screen, as shown in the following excerpt:
async void SetLockScreen()
{
ILockScreenService lockScreenService =
Dependency.Resolve<ILockScreenService>();
lockScreenService.SetNotification(
"Text set at " + DateTime.Now.ToShortTimeString(), ++countField);
SetBackgroundResult result = await lockScreenService.SetBackgroundAsync(
"Images/LockScreenBackground.png", ResourceLocation.XapContent);
if (result == SetBackgroundResult.Success)
{
MessageService.ShowMessage(
"Lock screen background and notification text set.");
}
}
When trying out the sample, be sure to grant access to the sample app in the phone’s lock screen settings.