ToastNotification ToastNotification ToastNotification ToastNotification Class

Definition

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

public : sealed class ToastNotification : IToastNotification, IToastNotification2, IToastNotification3, IToastNotification4
public sealed class ToastNotification : IToastNotification, IToastNotification2, IToastNotification3, IToastNotification4
Public NotInheritable Class ToastNotification Implements IToastNotification, IToastNotification2, IToastNotification3, IToastNotification4
var toastNotification = new toastNotification(content);
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Examples

The following example shows how to create and send a toast notification that includes text and images, including use of the ToastNotification 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;
    }
}

Remarks

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

Constructors

ToastNotification(XmlDocument) ToastNotification(XmlDocument) ToastNotification(XmlDocument) ToastNotification(XmlDocument)

Creates and initializes a new instance of the ToastNotification.

public : ToastNotification(XmlDocument content)
public ToastNotification(XmlDocument content)
Public Sub New(content As XmlDocument)
var toastNotification = new toastNotification(content);
Parameters
content
XmlDocument XmlDocument XmlDocument XmlDocument

The XML content that defines the toast notification.

Examples

The following example shows how to create and send a toast notification that includes text and images, including use of the ToastNotification 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);
See Also

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
var xmlDocument = toastNotification.content;
Value
XmlDocument XmlDocument XmlDocument XmlDocument

The object that contains the XML.

Remarks

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

See Also

Data Data Data Data

Gets or sets additional information about the status of the toast notification.

public : NotificationData Data { get; set; }
public NotificationData Data { get; set; }
Public ReadWrite Property Data As NotificationData
var notificationData = toastNotification.data;
toastNotification.data = notificationData;
Value
NotificationData NotificationData NotificationData NotificationData

An object that provides additional information about the status of the toast notification, such as the progress of the action described by the notification.

Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

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 Nullable<DateTimeOffset> ExpirationTime { get; set; }
Public ReadWrite Property ExpirationTime As Nullable<DateTimeOffset>
var nullable = toastNotification.expirationTime;
toastNotification.expirationTime = nullable;
Value
IReference<DateTime> Nullable<DateTimeOffset> Nullable<DateTimeOffset> Nullable<DateTimeOffset>

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, so this property is rarely used.

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

See Also

Group Group Group Group

Gets or sets the group identifier for the notification.

public : Platform::String Group { get; set; }
public string Group { get; set; }
Public ReadWrite Property Group As string
var string = toastNotification.group;
toastNotification.group = string;
Value
Platform::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
var notificationMirroring = toastNotification.notificationMirroring;
toastNotification.notificationMirroring = notificationMirroring;
Value
NotificationMirroring NotificationMirroring NotificationMirroring NotificationMirroring

A value that specifies whether notification mirroring is allowed.

Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Priority Priority Priority Priority

Gets or sets the priority of the toast notification.

public : ToastNotificationPriority Priority { get; set; }
public ToastNotificationPriority Priority { get; set; }
Public ReadWrite Property Priority As ToastNotificationPriority
var toastNotificationPriority = toastNotification.priority;
toastNotification.priority = toastNotificationPriority;
Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

Remarks

The priority setting provides hints on how and at what urgency level a notification should be presented to the user (whether to wake up the screen, etc). Whether the notification is displayed in high priority is based on the state and power management policy of the device.

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 : Platform::String RemoteId { get; set; }
public string RemoteId { get; set; }
Public ReadWrite Property RemoteId As string
var string = toastNotification.remoteId;
toastNotification.remoteId = string;
Value
Platform::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.

Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

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 : Platform::Boolean SuppressPopup { get; set; }
public bool SuppressPopup { get; set; }
Public ReadWrite Property SuppressPopup As bool
var bool = toastNotification.suppressPopup;
toastNotification.suppressPopup = bool;
Value
Platform::Boolean 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 : Platform::String Tag { get; set; }
public string Tag { get; set; }
Public ReadWrite Property Tag As string
var string = toastNotification.tag;
toastNotification.tag = string;
Value
Platform::String string string string

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

Remarks

The tag can be maximum 16 characters long. Build 14971 (Creators Update) extends this limit to 64 characters.

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 Activated<ToastNotification, object>
public event TypedEventHandler Activated<ToastNotification, object>
Public Event TypedEventHandler Activated( Of ( Of ToastNotification ), ( Of object ))
function onActivated(eventArgs){/* Your code */}


toastNotification.addEventListener("activated", onActivated);
toastNotification.removeEventListener("activated", onActivated);

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.

See Also

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 Dismissed<ToastNotification, ToastDismissedEventArgs>
public event TypedEventHandler Dismissed<ToastNotification, ToastDismissedEventArgs>
Public Event TypedEventHandler Dismissed( Of ( Of ToastNotification ), ( Of ToastDismissedEventArgs ))
function onDismissed(eventArgs){/* Your code */}


toastNotification.addEventListener("dismissed", onDismissed);
toastNotification.removeEventListener("dismissed", onDismissed);

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;

    }

}

Remarks

The ToastDismissalReason is included in the ToastDismissedEventArgs parameter.

See Also

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 Failed<ToastNotification, ToastFailedEventArgs>
public event TypedEventHandler Failed<ToastNotification, ToastFailedEventArgs>
Public Event TypedEventHandler Failed( Of ( Of ToastNotification ), ( Of ToastFailedEventArgs ))
function onFailed(eventArgs){/* Your code */}


toastNotification.addEventListener("failed", onFailed);
toastNotification.removeEventListener("failed", onFailed);

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 settings error, for instance a block on toast notifications for this user. We recommend that you call ToastNotifier.Setting before you call Show instead of handling that situation through this event.

See Also

See Also