Making a toast

Updated for Release Preview

After Tiles, badges and raw, toast is the last kind of notification in Metro.

Toast notifications are popups popping out on the screen (hence the name toast), showing some information (Image or text).

You can dismiss them, let them timeout or, if you click on it, you go to the application that sent it.

Toasts notifications are always on the foreground, so they will show even if your application is not showing right now.

Example here : a toast notification appearing when Visual Studio is on foreground (So you can see toast notifications works also in desktop mode) :

Toasts are useful to warn user about a new email, or a meeting reminder,etc... There are some guideline for toast notifications that will explain well the do and don’t.

Making your app toast capable

As usual, we have to go to the manifest :

What you have to do is :

• State your application is toast capable
• Set a text and background colour (note : those values are shared with the tiles)
• Add a small logo (small logo is shown on the notification, so you can see for which application it is)

Now you are ready !

Local toast

First thing is to choose what kind of toast template you want. Here is the list of toast templates and XML.

The ToastNotificationManager and the ToastTemplateType will help you to get the XML. Then you can set the values you need :

var toastXml = ToastNotificationManager.GetTemplateContent(ToastTemplateType.ToastImageAndText02);

var image = toastXml.GetElementsByTagName("image")[0];
var title = toastXml.GetElementsByTagName("text")[0];

var text = toastXml.GetElementsByTagName("text")[1];

image.Attributes[1].AppendChild(toastXml.CreateTextNode("ms-appx:///Assets/Local.jpg"));

title.AppendChild(toastXml.CreateTextNode("Local Toast"));

text.AppendChild(toastXml.CreateTextNode("Hello world"));

Now you have to create a ToastNotification from it, and, using the ToastNotificationManager, show it :

var toastnotifier = ToastNotificationManager.CreateToastNotifier();

var toastnotification = new ToastNotification(toastxml);

toastnotifier.Show(toastnotification);

That’s all! Your toast should appears :

Scheduled toast

Just like tiles, you can also schedule a toast notification. Instead of using ToastNotification class, you just use the ScheduledToastNotification class. It is (of course) mandatory to set a delivery time, but you can also, if you want, add a snooze (repetition ) interval (more than 1 minute, but less than 1 hour) and the maximum number of repetition (which range from 1 to 5) :

var deliveryTime = new DateTimeOffset(DateTime.Now.AddMinutes(1));

var snoozeInterval = new TimeSpan(0, 5, 0);

uint maxSnoozeCount = 5;

var scheduledtoastnotification = new ScheduledToastNotification(toastxml, deliveryTime, snoozeInterval, maxSnoozeCount);

Cancel scheduled toast

You can have the list of all the scheduled toast user ToastNotifier GetScheduledToastNotifications method.

Then, you can use its RemoveFromSchedule method to remove the toast :

var toastnotifier = ToastNotificationManager.CreateToastNotifier();

foreach (var scheduledToastNotification in toastnotifier.GetScheduledToastNotifications())
{
    toastnotifier.RemoveFromSchedule(scheduledToastNotification);
}

Push toast

Again, just like that tile notification, you can have push notification for toast. The principle is the same as with the tiles, except you have to use a toast XML, and set the type of request to “wns/toast”. So you can check Bard’s Tile III for how-to. Or check the sample solution at the end of this post.

Intercept a push toast

To intercept a push toast, it is like with push tile notification : use the PushNotificationChannel PushNotificationReceived event.

The example shows hot to cancel a push toast notification :

void pushChannel_PushNotificationReceived(PushNotificationChannel sender, PushNotificationReceivedEventArgs args)
{
    if (args.ToastNotification == null)
        return;
    args.Cancel = true;
}

Toast interaction

The ToastNotification class has several events that allow you to react upon user interaction (or non interaction). The events are :  Activated (User clicks on the toast) Dismissed (User dismisses it, or toast expires) and Failed (There is a problem raising the toast).

Example, this will show a popup when activated from a toast :

var toastnotification = new ToastNotification(toastxml);

toastnotification.Activated += toastnotification_Activated;

async void toastnotification_Activated(ToastNotification sender, object args)
{
   var toastxml = sender.Content;
   Dispatcher.RunAsync(CoreDispatcherPriority.Low, async () =>
                 {
                   var msg = new MessageDialog(toastxml.GetXml(), "Local toast activated");
                   await msg.ShowAsync();
                 });
}

Conclusion

Like for tile notification, I encourage people to read the guideline for toast notifications, there is a lot of advices on how to use (and not use) the toast, in order to avoid lot meaningless notifications (Information tsunami, as I call it)

Here is a sample application where you can send local and push toast. Making a Toast