ToastNotification ToastNotification ToastNotification ToastNotification Class

Defines the content, associated metadata and events, and expiration time of a toast notification.

Syntax

Declaration

public sealed class ToastNotificationpublic sealed class ToastNotificationPublic NotInheritable Class ToastNotification

Remarks

A desktop app must subscribe to at least the Activated event to handle activation.

Examples

The following example shows how to create and send a toast notification that includes text and images, including use of the @Windows.UI.Notifications.ToastNotification.#ctor(Windows.Data.Xml.Dom.XmlDocument) constructor.


var notifications = Windows.UI.Notifications;

// Get the toast notification manager for the current app.
var notificationManager = notifications.ToastNotificationManager;

// The getTemplateContent method returns a Windows.Data.Xml.Dom.XmlDocument object
// that contains the toast notification XML content.
var template = notifications.toastTemplateType.toastImageAndText01;
var toastXml = notificationManager.getTemplateContent(notifications.ToastTemplateType[template]);

// You can use the methods from the XML document to specify the required elements for the toast.
var images = toastXml.getElementsByTagName("image");
images[0].setAttribute("src", "images/toastImageAndText.png");

var textNodes = toastXml.getElementsByTagName("text");
textNodes.forEach(function (value, index) {
    var textNumber = index + 1;
    var text = "";
    for (var j = 0; j < 10; j++) {
        text += "Text input " + /*@static_cast(String)*/textNumber + " ";
    }
    value.appendChild(toastXml.createTextNode(text));
});

// Create a toast notification from the XML, then create a ToastNotifier object
// to send the toast.
var toast = new notifications.ToastNotification(toastXml);

notificationManager.createToastNotifier().show(toast);

The following example shows how to listen for and handle the Dismissed event.


var notifications = Windows.UI.Notifications;

yourToastNotification.addEventListener("dismissed", function (e) {
    switch (e.reason) {
        case notifications.ToastDismissalReason.applicationHidden:
            // The application hid the toast using ToastNotifier.hide.
            break;
        case notifications.ToastDismissalReason.userCanceled:
            // The user dismissed the toast.
            break;
        case notifications.ToastDismissalReason.timedOut:
            // The toast has expired.
            break;
    }
}

Constructors summary

Creates and initializes a new instance of the ToastNotification.

Properties summary

Gets the XML that defines the current toast notification.

Gets or sets the time after which a toast notification should not be displayed.

Gets or sets the group identifier for the notification.

Gets or sets a value that specifies whether notification mirroring is allowed.

Gets or sets a remote id for the notification that enables the system to correlate this notification with another one generated on another device.

Gets or sets whether a toast's pop-up UI is displayed on the user's screen.

Do not set this property to true in a toast sent to a Windows 8.x device. Doing so will cause a compiler error or a dropped notification.

Gets or sets the unique identifier of this notification within the notification Group.

Events summary

Occurs when user activates a toast notification through a click or touch. Apps that are running subscribe to this event

.

Occurs when a toast notification leaves the screen, either by expiring or being explicitly dismissed by the user. Apps that are running subscribe to this event.

Occurs when an error is caused when Windows attempts to raise a toast notification. Apps that are running subscribe to this event

.

Constructors

  • ToastNotification(Windows.Data.Xml.Dom.XmlDocument)
    ToastNotification(Windows.Data.Xml.Dom.XmlDocument)
    ToastNotification(Windows.Data.Xml.Dom.XmlDocument)
    ToastNotification(Windows.Data.Xml.Dom.XmlDocument)

    Creates and initializes a new instance of the ToastNotification.

    public ToastNotification(Windows.Data.Xml.Dom.XmlDocument)public ToastNotification(Windows.Data.Xml.Dom.XmlDocument)Public Function ToastNotification(Windows.Data.Xml.Dom.XmlDocument) As

    Parameters

    Remarks

    Examples

    The following example shows how to create and send a toast notification that includes text and images, including use of the @Windows.UI.Notifications.ToastNotification.#ctor(Windows.Data.Xml.Dom.XmlDocument) constructor.

    
    var notifications = Windows.UI.Notifications;
    
    // Get the toast notification manager for the current app.
    var notificationManager = notifications.ToastNotificationManager;
    
    // The getTemplateContent method returns a Windows.Data.Xml.Dom.XmlDocument object
    // that contains the toast notification XML content.
    var template = notifications.toastTemplateType.toastImageAndText01;
    var toastXml = notificationManager.getTemplateContent(notifications.ToastTemplateType[template]);
    
    // You can use the methods from the XML document to specify the required elements for the toast.
    var images = toastXml.getElementsByTagName("image");
    images[0].setAttribute("src", "images/toastImageAndText.png");
    
    var textNodes = toastXml.getElementsByTagName("text");
    textNodes.forEach(function (value, index) {
        var textNumber = index + 1;
        var text = "";
        for (var j = 0; j < 10; j++) {
            text += "Text input " + /*@static_cast(String)*/textNumber + " ";
        }
        value.appendChild(toastXml.createTextNode(text));
    });
    
    // Create a toast notification from the XML, then create a ToastNotifier object
    // to send the toast.
    var toast = new notifications.ToastNotification(toastXml);
    
    notificationManager.createToastNotifier().show(toast);
    

Properties

  • Content
    Content
    Content
    Content

    Gets the XML that defines the current toast notification.

    public XmlDocument Content { get; }public XmlDocument Content { get; }Public ReadOnly Property Content As XmlDocument

    Property Value

    Remarks

    The retrieved elements and their attributes are manipulated through Document Object Model (DOM) manipulation functions to customize the toast content. See toast schema for an explanation of toast elements and attributes.

  • ExpirationTime
    ExpirationTime
    ExpirationTime
    ExpirationTime

    Gets or sets the time after which a toast notification should not be displayed.

    public IReference<DateTime> ExpirationTime { get; set; }public IReference<DateTime> ExpirationTime { get; set; }Public ReadWrite Property ExpirationTime As IReference<DateTime>

    Property Value

    • The date and time after which the toast is no longer considered current or valid and should not be displayed.

    Remarks

    Windows attempts to raise toast notifications immediately after you call Show(Windows.UI.Notifications.ToastNotification), so this property is rarely used.

    For Windows Phone Store app: this property also causes the toast notification to be removed from the action center once the specified date and time is reached.

  • Group
    Group
    Group
    Group

    Gets or sets the group identifier for the notification.

    public string Group { get; set; }public string Group { get; set; }Public ReadWrite Property Group As string

    Property Value

    • string
      string
      string
      string

      The group identifier for the notification.

  • NotificationMirroring
    NotificationMirroring
    NotificationMirroring
    NotificationMirroring

    Gets or sets a value that specifies whether notification mirroring is allowed.

    public NotificationMirroring NotificationMirroring { get; set; }public NotificationMirroring NotificationMirroring { get; set; }Public ReadWrite Property NotificationMirroring As NotificationMirroring

    Property Value

  • RemoteId
    RemoteId
    RemoteId
    RemoteId

    Gets or sets a remote id for the notification that enables the system to correlate this notification with another one generated on another device.

    public string RemoteId { get; set; }public string RemoteId { get; set; }Public ReadWrite Property RemoteId As string

    Property Value

    • string
      string
      string
      string

      A remote id for the notification that enables the system to correlate this notification with another one generated on another device.

  • SuppressPopup
    SuppressPopup
    SuppressPopup
    SuppressPopup

    Gets or sets whether a toast's pop-up UI is displayed on the user's screen.

    Do not set this property to true in a toast sent to a Windows 8.x device. Doing so will cause a compiler error or a dropped notification.

    public bool SuppressPopup { get; set; }public bool SuppressPopup { get; set; }Public ReadWrite Property SuppressPopup As bool

    Property Value

    • bool
      bool
      bool
      bool

      Set to true to suppress the popup message; otherwise, false. The default value is false, meaning the toast's pop-up message will be shown. Setting this property to true places the toast notification silently into the action center. This enables your app to communicate with the user without interrupting them.

  • Tag
    Tag
    Tag
    Tag

    Gets or sets the unique identifier of this notification within the notification Group.

    public string Tag { get; set; }public string Tag { get; set; }Public ReadWrite Property Tag As string

    Property Value

    • string
      string
      string
      string

      Gets or sets the unique identifier of this notification within the notification Group.

Events

  • Activated
    Activated
    Activated
    Activated

    Occurs when user activates a toast notification through a click or touch. Apps that are running subscribe to this event

    .

    public event TypedEventHandler Activatedpublic event TypedEventHandler ActivatedPublic Event Activated

    Remarks

    In the case of toast raised by a desktop app, that app must subscribe to at least the Activated event so that it can handle the expected activation of the app from the toast when the user selects it.

  • Dismissed
    Dismissed
    Dismissed
    Dismissed

    Occurs when a toast notification leaves the screen, either by expiring or being explicitly dismissed by the user. Apps that are running subscribe to this event.

    public event TypedEventHandler Dismissedpublic event TypedEventHandler DismissedPublic Event Dismissed

    Remarks

    The ToastDismissalReason is included in the ToastDismissedEventArgs parameter.

    Examples

    The following example shows how to listen for and handle the Dismissed event.

    
    var notifications = Windows.UI.Notifications;
    
    yourToastNotification.addEventListener("dismissed", function (e) {
        switch (e.reason) {
            case notifications.ToastDismissalReason.applicationHidden:
                // The application hid the toast using ToastNotifier.hide.
                break;
            case notifications.ToastDismissalReason.userCanceled:
                // The user dismissed the toast.
                break;
            case notifications.ToastDismissalReason.timedOut:
                // The toast has expired.
                break;
        }
    }
    
  • Failed
    Failed
    Failed
    Failed

    Occurs when an error is caused when Windows attempts to raise a toast notification. Apps that are running subscribe to this event

    .

    public event TypedEventHandler Failedpublic event TypedEventHandler FailedPublic Event Failed

    Remarks

    The reason for the toast's failure can be found in the ErrorCode property of the ToastFailedEventArgs parameter.

    The most common failure that you'll see when you raise a toast is a NotificationSetting error, for instance a block on toast notifications for this user. We recommend that you call Setting before you call Show(Windows.UI.Notifications.ToastNotification) instead of handling that situation through this event.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.DualApiPartitionAttribute

Details

Assembly

Windows.UI.Notifications.dll