Bagikan melalui

Quickstart: Managing toast notifications in action center (XAML)

  • Artikel

Windows Phone 8.1 introduces APIs that you can use to manage toast notifications in action center. This topic shows how to manage your toast notifications using these APIs.

Prerequisites

To understand this topic, you will need:

APIs for managing toast notifications in action center

The following table summarizes the major APIs related to managing toast notifications in action center.

API Description
ToastNotificationManager Class used in creating and sending a toast, but mentioned here because it provides access to the ToastNotificationHistory object.
ToastNotificationHistory Class that enables removal of toast notifications from action center.

ToastNotification.Group

ScheduledToastNotification.Group

 Optional property used to categorize a toast notification into a group.

ToastNotification.Tag

ScheduledToastNotification.Tag

 Optional property that identifies a toast notification. Multiple notifications can have the same tag.

ToastNotification.SuppressPopup

ScheduledToastNotification.SuppressPopup

 Properties that prevent a toast notification's pop-up UI from appearing on the screen and that send the notification directly to action center.

ToastNotification.ExpirationTime

ScheduledToastNotification.ExpirationTime

 Property that represents the maximum time a toast notification remains visible in action center before it is removed by the system. The default time is 7 days.

 

Sending a local toast notification

To demonstrate action center, we'll send toast notifications to populate it and to manipulate later. The simplest way to do that is to send local toast notifications. The code example here shows how to create a basic toast and send it locally. For an in-depth discussion of the procedure given in this step, see Quickstart: Sending a toast notification.

Here we create a toast by using the ToastText02 template. This template contains a maximum of two text elements. The first text element is treated as a header text and is always bold.

Important  In Windows Phone 8.1, all toast templates are rendered as a ToastText02 template even if another template is specified and used if the toast is received on a PC or tablet. Images are ignored in Windows Phone 8.1; instead, the app's icon (defined in its manifest) is displayed to the left of the toast text and is also shown in action center.

 

This example:

  1. Retrieves the template contents.
  2. Fills in the text elements with previously defined string variables.
  3. Sets a duration for the toast UI to appear on the screen.
  4. Packages the modified XML into a toast notification object.
  5. Sets an explicit expiration time of one hour.
  6. Sends the toast.
using Windows.UI.Notifications;
using Windows.Data.Xml.Dom;

ToastTemplateType toastTemplate = ToastTemplateType.ToastText02;
XmlDocument toastXml = ToastNotificationManager.GetTemplateContent(toastTemplate);

XmlNodeList toastTextElements = toastXml.GetElementsByTagName("text");
toastTextElements[0].AppendChild(toastXml.CreateTextNode(toastHeading));
toastTextElements[1].AppendChild(toastXml.CreateTextNode(toastBody));

IXmlNode toastNode = toastXml.SelectSingleNode("/toast");
((XmlElement)toastNode).SetAttribute("duration", "long");

ToastNotification toast = new ToastNotification(toastXml);
toast.ExpirationTime = DateTimeOffset.UtcNow.AddSeconds(3600);

ToastNotificationManager.CreateToastNotifier().Show(toast);

using namespace Windows::UI::Notifications;
using namespace Windows::Data::Xml::Dom;

ToastTemplateType toastTemplate = ToastTemplateType::ToastText02;
XmlDocument^ toastXml = ToastNotificationManager::GetTemplateContent(toastTemplate);

XmlNodeList^ toastTextElements = toastXml->GetElementsByTagName("text");
toastTextElements->Item(0)->InnerText = toastHeading;
toastTextElements->Item(1)->InnerText = toastBody;

IXmlNode^ toastNode = toastXml->SelectSingleNode("/toast");
static_cast<XmlElement^>(toastNode)->SetAttribute("duration", "long");

ToastNotification^ toast = ref new ToastNotification(toastXml);

int minutes = 60;
auto cal = ref new Windows::Globalization::Calendar();
cal->AddMinutes(minutes);    
toast->ExpirationTime = cal->GetDateTime();

ToastNotificationManager::CreateToastNotifier()->Show(toast);

When the toast is sent, it is displayed in a pop-up UI at the top of the phone's Start screen. If it is not explicitly acted on by the user, the toast is also shown in action center.

Sending a toast notification directly to action center

Instead of showing a pop-up UI for every toast, you can send some toast notifications directly to action center. This reduces noise while still keeping the user informed. This code example, which uses the toast object created in the previous example, suppresses the pop-up UI so that the same call to the Show method sends the notification directly to action center.

toast.SuppressPopup = true;
ToastNotificationManager.CreateToastNotifier().Show(toast);

toast->SuppressPopup = true;
ToastNotificationManager::CreateToastNotifier()->Show(toast);

Replacing a toast in action center

Keep info in action center fresh and unique. For example, multiple price notifications in action center for the same stock would be confusing. You can replace a notification in action center by sending a new toast with the same Tag and/or Group property values as the toast you want to replace.

In this code example, we assume that a finance app sends regular toast notifications with the current value of a stock whose symbol is BYA. Those notifications are always given a tag of "BYA" and a group of "DailyStockPrices". When you assign the Tag and Group properties in our standard toast notification, this notification replaces any existing notification in action center with the same tag and group. This practice ensures that there's only one notification for that stock in action center, and that it gives the most current price.

toast.Tag = "BYA";
toast.Group = "DailyStockPrices";

ToastNotificationManager.CreateToastNotifier().Show(toast);

toast->Tag = "BYA";
toast->Group = "DailyStockPrices";

ToastNotificationManager::CreateToastNotifier()->Show(toast);

Replacing a toast notification in action center is also useful when you use the snooze facility of the ScheduledToastNotification class. If you set the Tag and/or Group properties, the previous iteration of the notification is replaced in the action center every time the snoozed toast is raised. If you don't set those properties, each time the toast is raised and snoozed, it appears as an individual entry in action center.

Removing toasts from the action center

These code examples show the result of Remove and RemoveGroup method calls on the following set of labeled toast notifications in action center.

Remove a notification with a given tag and no group label

ToastNotificationManager.History.Remove("T2");

ToastNotificationManager::History->Remove("T2");

The preceding call results in the following set. Note that notifications with tag "T2" but also assigned to a group were not removed.

Remove a notification that matches a specified tag and a specified group

ToastNotificationManager.History.Remove("T2", "G1");

ToastNotificationManager::History->Remove("T2", "G1");

The preceding call results in the following set, removing the single notification that matches the criteria.

Remove all notifications in a specified group

ToastNotificationManager.History.RemoveGroup("G1");

ToastNotificationManager::History->RemoveGroup("G1");

The preceding call results in the following set, removing all notifications with the matching group label.

Summary and next steps

In this Quickstart, you managed toast notifications in action center by using the new notification-management APIs. You sent notifications directly to action center without displaying a pop-up UI. You used the Tag and Group notification properties and the ToastNotificationHistory object to remove notifications from action center and you also replaced a notification in action center with an updated message.

To see these action center concepts in action, download and run the Action Center Quickstart Sample.

Action Center Quickstart Sample

The toast template catalog

Sending toast notifications