Toast Notification Manager

• Mar 12, 2021
• 6 minutes to read

The Toast Notification Manager component shows toast notifications - a Windows 10 version of traditional alert windows.

Note

Toast notifications can only be displayed in Windows 8.0 or higher. For older Windows versions, use alert windows instead.

An application can display multiple notifications simultaneously, or one notification multiple times at once. The ToastNotification object which represents a notification can be visualized using one of nine predefined templates. The notification can also play a sound when shown.

• Create Notifications
• Manage End-User Interactions
• Customize Notifications with the “Generic” Template
• Notes

Create Notifications

Follow the steps below to create toast notifications.

1. Locate the ToastNotificationManager component in your Visual Studio toolbox and drop it onto the form.

   

2. Windows allows toast notifications only for those apps that are pinned to the Start menu, so make sure your application has a valid shortcut with an Application User Model ID. For debugging purposes, invoke the component’s smart tag and click the “Create Application Shortcut” link.

   

3. Invoke the manager’s smart-tag and click the Edit Notifications… link.

   

4. In the Collection Editor dialog that pops up, click the Add button to add a notification. This creates new ToastNotification objects and add them to the manager’s ToastNotificationsManager.Notifications collection. You can customize the notification settings in the property grid.

   • ToastNotification.Body and IToastNotificationProperties.Body2 - two regular text strings that represent the main notification text. The Body2 line can be disabled, depending on the selected template (see below).
   • ToastNotification.Duration - gets or sets how long this notification is visible if an end-user does not close it.
   • ToastNotification.Header - a bold text string displayed in the notification header. The header string can occupy one or two lines, depending on the current notification template.
   • ToastNotification.ID - a read-only property that stores a unique ID, assigned to this notification.
   • ToastNotification.Image - gets or sets the notification image.
   • ToastNotification.Sound - allows you to specify a sound that is played when this notification is shown. The sound played depends on the sound settings of the end-user’s system.

   • ToastNotification.Template - gets or sets the notification template. The table below illustrates different notification types depending on the template.

     Template	Description
     Text01	A single IToastNotificationProperties.Body string wrapped across a maximum of three lines of text.
     Text02	A bold IToastNotificationProperties.Header text string on the first line and a regular IToastNotificationProperties.Body text string wrapped across the second and third lines.
     Text03	One string of bold IToastNotificationProperties.Header text wrapped across the first and second lines and one string of regular IToastNotificationProperties.Body text on the third line.
     Text04	One string of bold IToastNotificationProperties.Header text on the first line, one string of regular IToastNotificationProperties.Body text on the second line and one string of regular IToastNotificationProperties.Body2 text on the third line.
     ImageAndText01	The Text01 template plus an image.
     ImageAndText02	The Text02 template plus an image.
     ImageAndText03	The Text03 template plus an image.
     ImageAndText04	The Text04 template plus an image.
     Generic	A Windows 10-styled notification. The following properties provide its content: ToastNotification.AppLogoImage (48x48 pixels at 100% scaling). Cropped according to the ToastNotification.AppLogoImageCrop property value ToastNotification.AttributionText ToastNotification.Body and IToastNotificationProperties.Body2 ToastNotification.Header ToastNotification.HeroImage (364x180 pixels) ToastNotification.Image (332x180 pixels)

5. To display a specific notification, use the ToastNotificationsManager.ShowNotification method.

   C#

   
   toastNotificationsManager1.ShowNotification(toastNotificationsManager1.Notifications[3]);
   //or
   toastNotificationsManager1.ShowNotification("3b7fcd8b-a1e0-4ff5-83ce-023cdf6be24b");
   

   VB.NET

   
   toastNotificationsManager1.ShowNotification(toastNotificationsManager1.Notifications(3))
   'or
   toastNotificationsManager1.ShowNotification("3b7fcd8b-a1e0-4ff5-83ce-023cdf6be24b")
   

Manage End-User Interactions

Depending on end-user actions, the following events rise.

• ToastNotificationsManager.Activated - occurs if an end-user clicks this notification. Handle this event to check which notification was clicked, and perform specific actions depending on the result. The code below illustrates an example.

  C#

  
  private void toastNotificationsManager1_Activated(object sender, DevExpress.XtraBars.ToastNotifications.ToastNotificationEventArgs e) {
      switch (e.NotificationID.ToString()) {
          case "3b7fcd8b-a1e0-4ff5-83ce-023cdf6be24b":
              MessageBox.Show("Notification #1 Clicked");
              break;
          case "66501f90-ac6b-440d-bf73-483c5ab22143":
              MessageBox.Show("Notification #2 Clicked");
              break;
      }
  }
  

  VB.NET

  
  Private Sub toastNotificationsManager1_Activated(sender As Object, e As DevExpress.XtraBars.ToastNotifications.ToastNotificationEventArgs)
      Select Case (e.NotificationID.ToString()
          Case "3b7fcd8b-a1e0-4ff5-83ce-023cdf6be24b"
              MessageBox.Show("Notification #1 Clicked")
              Exit Select
          Case "66501f90-ac6b-440d-bf73-483c5ab22143"
              MessageBox.Show("Notification #2 Clicked")
              Exit Select
      End Select
  End Sub
  

• ToastNotificationsManager.UserCancelled - occurs if an end-user closes the notification.

• ToastNotificationsManager.TimedOut - occurs when an end-user does not respond to the notification, and the notification is hidden after a certain period. The code below illustrates how to show the notification again.

  C#

  
  private void toastNotificationsManager1_TimedOut(object sender, DevExpress.XtraBars.ToastNotifications.ToastNotificationEventArgs e) {
      toastNotificationsManager1.ShowNotification(e.NotificationID);
  }
  

  VB.NET

  
  Private Sub toastNotificationsManager1_TimedOut(sender As Object, e As DevExpress.XtraBars.ToastNotifications.ToastNotificationEventArgs)
      toastNotificationsManager1.ShowNotification(e.NotificationID)
  End Sub
  

• ToastNotificationsManager.Hidden - occurs when a toast notification is hidden via the ToastNotificationsManager.HideNotification or ToastNotificationsManager.HideNotifications method.
• ToastNotificationsManager.Dropped - fires when a notification is canceled due to end-user’s system settings.

Customize Notifications with the “Generic” Template

The following XML markup describes the layout of a toast notification’s content with the “Generic” template applied:

XML

<toast displayTimestamp="2018-01-05T13:35:00Z">
  <visual>
    <binding template="ToastGeneric">
      <text id="1">Header Text</text>
      <text id="2">Body Text</text>
      <text id="3">Body 2 Text</text>
      <text placement="attribution">Attribution Text</text>
      <image src="file:///C:/Users/John.Doe/AppData/Local/Temp/tmpBC2C.tmp4e9214ef-f478-4cea-972a-3fdd6c3acac0.png" placement="appLogoOverride" hint-crop="circle" />
      <image src="file:///C:/Users/John.Doe/AppData/Local/Temp/tmpBC2D.tmpeb4a5986-fd2a-4d7d-a69d-a78f0061d754.png" placement="hero" />
      <image src="file:///C:/Users/John.Doe/AppData/Local/Temp/tmpBC1B.tmp43598461-7e59-4600-a95c-88edbc57b2ec.png" />
    </binding>
  </visual>
</toast>

You can handle the ToastNotificationsManager.UpdateToastContent event to modify this template using the API the System.XML namespace provides. For instance, the following code adds a group with two subgroups to the notification layout. Each subgroup displays two additional text blocks, arranged vertically.

C#

using System.Xml;

 public Form1() {
     InitializeComponent();
     //. . .
     toastNotificationsManager1.UpdateToastContent += ToastNotificationsManager1_UpdateToastContent;    
 }

 private void ToastNotificationsManager1_UpdateToastContent(object sender, DevExpress.XtraBars.ToastNotifications.UpdateToastContentEventArgs e) {
     XmlDocument content = e.ToastContent;
     XmlNode bindingNode = content.GetElementsByTagName("binding").FirstOrDefault();
     XmlElement group = content.CreateElement("group");
     bindingNode.AppendChild(group);

     XmlElement subGroup = content.CreateElement("subgroup");
     group.AppendChild(subGroup);

     XmlElement text = content.CreateElement("text");
     subGroup.AppendChild(text);
     text.SetAttribute("hint-style", "base");
     text.InnerText = "subgroup1";

     text = content.CreateElement("text");
     subGroup.AppendChild(text);
     text.SetAttribute("hint-style", "captionSubtle");
     text.InnerText = "captionSubtle";

     subGroup = content.CreateElement("subgroup");
     group.AppendChild(subGroup);

     text = content.CreateElement("text");
     subGroup.AppendChild(text);
     text.SetAttribute("hint-style", "captionSubtle");
     text.SetAttribute("hint-align", "right");
     text.InnerText = "subgroup2";

     text = content.CreateElement("text");
     subGroup.AppendChild(text);
     text.SetAttribute("hint-style", "captionSubtle");
     text.SetAttribute("hint-align", "right");
     text.InnerText = "captionSubtle";
     //save the toast markup as an XML file for debugging purposes
     content.Save(@"D:\Toast.xml");
 }

VB.NET

Imports System.Xml

 Public Sub New()
     InitializeComponent()
     '. . .
     AddHandler toastNotificationsManager1.UpdateToastContent, AddressOf ToastNotificationsManager1_UpdateToastContent
 End Sub

 Private Sub ToastNotificationsManager1_UpdateToastContent(ByVal sender As Object, ByVal e As DevExpress.XtraBars.ToastNotifications.UpdateToastContentEventArgs)
     Dim content As XmlDocument = e.ToastContent
     Dim bindingNode As XmlNode = content.GetElementsByTagName("binding").FirstOrDefault()
     Dim group As XmlElement = content.CreateElement("group")
     bindingNode.AppendChild(group)

     Dim subGroup As XmlElement = content.CreateElement("subgroup")
     group.AppendChild(subGroup)

     Dim text As XmlElement = content.CreateElement("text")
     subGroup.AppendChild(text)
     text.SetAttribute("hint-style", "base")
     text.InnerText = "subgroup1"

     text = content.CreateElement("text")
     subGroup.AppendChild(text)
     text.SetAttribute("hint-style", "captionSubtle")
     text.InnerText = "captionSubtle"

     subGroup = content.CreateElement("subgroup")
     group.AppendChild(subGroup)

     text = content.CreateElement("text")
     subGroup.AppendChild(text)
     text.SetAttribute("hint-style", "captionSubtle")
     text.SetAttribute("hint-align", "right")
     text.InnerText = "subgroup2"

     text = content.CreateElement("text")
     subGroup.AppendChild(text)
     text.SetAttribute("hint-style", "captionSubtle")
     text.SetAttribute("hint-align", "right")
     text.InnerText = "captionSubtle"
     'save the toast markup as an XML file for debugging purposes
     content.Save("D:\Toast.xml")
 End Sub

Notes

• The notification background color is chosen automatically by the operating system, you cannot modify it manually.
• Notifications are displayed by the operating system, so they can remain visible even after an end-user closes the application.
• Windows 8-styled notifications automatically display a shortcut icon in the bottom right corner. This icon cannot be removed.
• The number of notifications that a visible simultaneously depends on the end-user’s system settings.
• Windows 10 Anniversary Update (Redstone 1, build 1607) and newer versions support the Generic notification template.