Saturday, September 1, 2012

Notifications Extensions

When I wrote my first article on tile notifications in WinRT apps back when the developer preview was released I commented that the method for setting up the content for the tiles was a little cumbersome and I hoped that a better way would come along in the release version. There was no changes to the actual framework, but the WinRT samples do come with  a helper library called NotificationsExtensions that does make things easier.
You can get the source code for the library from the App tile and badge sample. You can find the source there in both C# and VB.NET. In this article I will be showing how to use it in C#. Once you have downloaded the sample you will want to pull out the NotificationsExtensions project folder and add it to your own project. If you want, once you have compiled the project, you can just add the NotficationsExtensions.winmd file found in the bin directory into other projects and included it as a reference instead of using the source project.
To use the library the first thing you will want to do is include a couple namespaces:

using NotificationsExtensions.TileContent;
using Windows.UI.Notifications;

The first is the namespace for the tile notification helper classes and the second is the WinRT namespace for notifications. Also remember that if you want to see the wide tile on the start screen you will need to create a 150x310 pixel jpg or png and point the Wide Logo property in the application manifest to it.

Now we are ready to setup the tile content.

ITileWideText03 tileContent = TileContentFactory.CreateTileWideText03();
tileContent.TextHeadingWrap.Text = "Wide tile notification";

ITileSquareText04 squareContent = TileContentFactory.CreateTileSquareText04();
squareContent.TextBodyWrap.Text = "Square tile notification";
tileContent.SquareContent = squareContent;

The first line uses the TileContentFactory class from the NotificationsExtensions library to create a helper class to build the wide tile content template. In TileContentFactory there is a function to create a class for each tile template. You can see all the available templates on the Tile Template Catalog page on MSDN. Once the template class is created you can use its properties to set the content of the template instead of having to deal directly with the XML template.  The second line sets the text to appear on this tile.

The next three lines use a similar process to setup a square tile template. If your application supports both tile sizes then you should always create a notification template for each size so it will display no matter which size the user has set the tile to. The third line of that section attaches the square content to the content we created for the wide tile.

Once we have the templates setup it’s a simple matter to display them using the notification functions:

TileUpdateManager.CreateTileUpdaterForApplication().Update(tileContent.CreateNotification());

If you compare this to how the notification was done in my original post, you can see that this does make thing a little easier.

Badge Notifications

Besides tile notifications the library also has helpers for doing badge notifications. As described in my earlier post, badges are either small numbers or symbols that can be shown in the lower right corner of a tile. To do badges you will want to include one more namespace:

using NotificationsExtensions.BadgeContent;

The code to show a numeric badge looks like this:

BadgeNumericNotificationContent badgeContent = new BadgeNumericNotificationContent(10);
BadgeUpdateManager.CreateBadgeUpdaterForApplication().Update(badgeContent.CreateNotification());

The first line creates the content for the numeric badge using the new library. You can see that the number to be displayed is passed to the constructor. The second line uses the framework functions to display the badge.

The code to display glyph badges is similar:

BadgeGlyphNotificationContent badgeContent = new BadgeGlyphNotificationContent(GlyphValue.Busy);
BadgeUpdateManager.CreateBadgeUpdaterForApplication().Update(badgeContent.CreateNotification());

In this case we pass one of the GlyphValue enumerations to the constructor to specify which shape we want to display.

1 comment:

Leon Cullens said...

Thanks a lot for this! The examples all used TileUpdateManager.CreateTileUpdaterForSecondaryTile() but I just couldn't wrap my head around what the "tileId" parameter should contain, it drove me crazy since Google wasn't especially helpful. But you saved me out :)