Toast Notification Manager

• Nov 17, 2018
• 5 minutes to read

The Toast Notification Manager component introduces toast notifications - a Windows 10 version of traditional alert windows. These notifications display important messages to an end-user by showing small rectangular windows, as the image below shows.

Note

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

A single application can display multiple notifications simultaneously, or one notification multiple times at once. Each notification, presented by the ToastNotification object, can be visualized using one of eight predefined templates that include an image, a bold header string and a regular text string. The notification can also play a specific sound when shown. Follow the steps below to create and customize toast notifications for your application.

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

   

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

   

3. In the dialog shown, click the Add button to add a notification. This will add a ToastNotification object in the manager’s ToastNotificationsManager.Notifications collection. In the property grid to the dialog’s right, you can customize the following notification settings.

   • ToastNotification.Body and IToastNotificationProperties.Body2 - two regular text strings that represent the main notification text. The Body2 line can be disabled, depending on the currently selected template (see below).
   • ToastNotification.Duration - gets or sets how long this notification will be 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. This image is only displayed if one of the four related notification templates is chosen.
   • ToastNotification.Sound - allows you to specify a sound that is played when this notification is shown. The sound played depends on the end-user’s system sound settings.

   • ToastNotification.Template - gets or sets the notification template. Depending on the current notification template, the text and image display may vary. The table below illustrates different notification types depending on the currently applied template.

     Template	Description
     Text01	A single IToastNotificationProperties.Body string wrapped across a maximum of three lines of text.
     Text02	One string of bold IToastNotificationProperties.Header text on the first line and one string of regular IToastNotificationProperties.Body text 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.

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

   C#

   
   toastNotificationsManager1.ShowNotification(toastNotificationsManager1.Notifications[3]);
   

   VB.NET

   
   toastNotificationsManager1.ShowNotification(toastNotificationsManager1.Notifications(3))
   

5. After a notification is shown, a number of Toast Notification Manager events can be fired, depending on end-user actions.

   • ToastNotificationsManager.Activated - occurs if an end-user clicks this notification. Handle this event to check which notification was clicked by ID, 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 of idle display. The code below illustrates how to show the timed-out 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 system settings.

Notes

There are several Toast Notification Manager specifics that you need to know.

• To display notifications correctly, the Toast Notifications Manager requires an application shortcut, pinned to the Windows 10 start screen. To create this shortcut while developing your application, set the ToastNotificationsManager.CreateApplicationShortcut property to DefaultBoolean.True. In this case, the application will check whether or not the start screen shortcut already exists. If no shortcut was found, the Toast Notification Manager will create a new shortcut with the specified caption (the ToastNotificationsManager.ApplicationName property) and icon (the ToastNotificationsManager.ApplicationIconPath property).

  

• You cannot set a notification background manually. The background color is chosen automatically, depending on the application shortcut’s icon color.
• Notifications are not displayed at the application layer, but at the operating system layer. Thus, displayed notifications can still be visible even after an end-user closes the application.
• Notifications automatically display a shortcut icon in the bottom right corner. This icon cannot be removed.
• The number of simultaneously visible notifications depends on the end-user’s system settings.