In Windows 8.1, the notification system has got some new improvements that make it much more flexible. Since the very first relase you have been able to send different typer of notifications called badges, toasts and tiles. These notifications let you interact with the user from the running application and also from a background task, allowing the application to notify messages when it is not running.
Starting from the latest relase the toast notifications have got some new interesting features. When the user is notified he can not only dismiss the notification or open the application by clicking the toast, but he can also use a number of predefined commands, presented by the application in specific scenarios. Let start explore the alarm scheduling scenario:
Send alarm toasts
The most simple form of notification, added to this release, is made to emulate an alarm clock. This kind of notification should be raised to notify a scheduled event and it allows to add two additional button, the first to dismiss the notification and the second to snooze the alarm.
As usual, presenting a toast notification means compiling a short chunk of xml. This is because the notifications are designed to be send over a network channel when they are raised by a push notification system. Here is the xml that is composed by the app to send an alarm notification:
1: <toast duration="long" launch="alarm(eb6c47a8-e5e2-40d0-bc4e-3aa957f36484)">
2: <visual>
3: <binding template="ToastImageAndText04">
4: <text id="1">Silverlight Show</text>
5: <text id="2">New article by A. Boschin</text>
6: <text id="3">Windows 8.1: Alarm and Lock screen call toasts</text>
7: <image id="1" src="ms-appx:///Assets/SilverlightShow.png" alt="hallo" />
8: </binding>
9: </visual>
10: <audio loop="true" src="ms-winsoundevent:Notification.Looping.Alarm2" />
11: <commands scenario="alarm">
12: <command id="snooze" />
13: <command id="dismiss" />
14: </commands>
15: </toast>
The notification xml is divided in three parts:
visual: it contains the visual aspect of the notification. It can be selected between 8 different templates you can see on this page. http://msdn.microsoft.com/en-us/library/windows/apps/hh761494.aspx The showed xml is the most complex that contains three lines of text (the first one in bold) and an image of 90x90 pixels.
audio: it describes the sound to be played when the notification appears. It can assume a number of predefined sounds that are listed in this page: http://msdn.microsoft.com/en-us/library/windows/apps/br230842.aspx
commands: this is the most important section that determines the scenarion (in this case "alarm") and the enabled commands. They must be "snooze" or "dismiss" for alarm notifications.
Once you compiled the xml it is time to send it to the notification system. In this scenario I'll use a ScheduledToastNotification that allows to specify some parameters that apply to the given commands.
1: private void NotifyScheduled(string toast, int delay = 5, int snooze = 300, int maxSnoozeCount = 3)
2: {
3: XmlDocument document = new XmlDocument();
4: document.LoadXml(toast);
5:
6: var notifier = ToastNotificationManager.CreateToastNotifier();
7: var scheduledToast = new ScheduledToastNotification(document, DateTime.Now.AddSeconds(delay), TimeSpan.FromSeconds(snooze), (uint)maxSnoozeCount);
8: notifier.AddToSchedule(scheduledToast);
9: }
In the first line the xml is converted to a XmlDocument instance. It is because the ToastNotification require this type. After the xml has been parsed, using the ToastNotificationManager it is created an instance of a notifier, responsible to communicate with the notification system. Then the code creates the scheduled notification passing as arguments the date and time of the alarm, the snooze timeout and the max number of snoozes it allows (0 means infinite). The notification is then added to the notifier.
This code cause the appearance of the following notification, after a couple of seconds (the delay):
The two buttons in the figure corresponds to the commands that has been send to the notifier. They act automatically without the needs of intervention by the developer code.
The sole thing you have to be aware is that the manifest should be modified partially with the designer and partially by hand. You have to create a dummy background task (no code required) to allow the app to run when it is closed. In a real world application this task should work to collect notification and schedule notifications. Here a snippet from the manifest:
1: <Extensions>
2: <Extension Category="windows.backgroundTasks" EntryPoint="SamplePlaceholder">
3: <BackgroundTasks>
4: <Task Type="audio" />
5: <Task Type="timer" />
6: </BackgroundTasks>
7: </Extension>
8: <m2:Extension Category="windows.alarm" />
9: </Extensions>
The "windows.alarm" category has to be added manually because it is not supported by the designer.
Handle incoming calls
Many applications are currently made to communicate each other. In these days the traditional phone call and text messages have been often passed by applications like skype and whatsapp that give better features for free or at a lower rate. This requires that the application framework directly supports these new scenarios and accept a new kind of notification that is able to notify an incoming call. Windows 8.1 accepted the challenge in this scenario so they added a new kind of toast notifications, able to work in lock screen applications that enable the developers to present notifications to the user and receive the choosen options as answer.
As for alarm notifications, the lock screen calls are made of a brief chunk of xml. It is presented in the following snippet:
1: <toast duration="long" launch="ls(60129d07-a1af-4b53-840b-669d09f1c013)">
2: <visual>
3: <binding template="ToastImageAndText04">
4: <text id="1">Silverlight Show calling</text>
5: <text id="2">A new call is incoming</text>
6: <text id="3">You can answer the call in voice or video...</text>
7: <image id="1" src="ms-appx:///Assets/SilverlightShow.png" alt="hallo" />
8: </binding>
9: </visual>
10: <audio loop="true" src="ms-winsoundevent:Notification.Looping.Call3" />
11: <commands scenario="incomingCall">
12: <command id="decline" />
13: <command id="video" arguments="Incoming Video Call" />
14: <command id="voice" arguments="Incoming Voice Call" />
15: </commands>
16: </toast>
The sections in the xml are exactly the same as in alarm notifications. the sole difference are in the scenario's name that is "incomingCall" and in the commands. The commands for an incoming call includes "decline" to close the call without an answer, "voice" to accept the voice call or "video" to accept both voice and video parts of the call. In these two commands you can specify an argument that will be used by the application to understand how to operate with the user's choice.
The provided snippet will show a toast notification like the following:
Of course you are not required to specify both the commands "video" and "voice" but you can tailor the needed commands on the basis of the features of your applications. You can also omit to specify the "decline" command and it will not be showed in the toast, but the user can always dismiss the notification with the well known gestures.
To raise the notification you can use a simplified version of the code presented for alarm notifications. The following snippet show the code required:
1: private void NotifyImmediate(string toast)
2: {
3: XmlDocument document = new XmlDocument();
4: document.LoadXml(toast);
5:
6: var notifier = ToastNotificationManager.CreateToastNotifier();
7: var scheduledToast = new ToastNotification(document);
8: notifier.Show(scheduledToast);
9: }
I think the code is so simple and it does not requires a detailed explanation. Once you have setup the commands and raised the notification you probably would want to get a notification when the user clicks one of the commands. This is done using the OnLaunched event in the App.xaml.cs. In the following snippet I show the simple code required to handle the incoming call:
1: protected async override void OnLaunched(LaunchActivatedEventArgs e)
2: {
3: // ...initialization here...
4:
5: if (!string.IsNullOrEmpty(e.Arguments))
6: {
7: rootFrame.Navigate(typeof(NotificationPage), e.Arguments);
8: }
9:
10: // Ensure the current window is active
11: Window.Current.Activate();
12: }
A toolkit to generate toast xml
There are a number of ways to compile the xml required to send a notification, you can simply concatenate a string (no, I do not suggest to take this in serious consideration), you can use a XDocument object or you can create a number of types to be serialized to the required xml format. In the download provided with the article you will find a portable class library called XPG.ToastToolkit.dll that contains a useful object model and utility classes that let you generate easily the xml toast. You can write a code similar to the following to send an alarm notification:
1: private void bAlarm_Click(object sender, RoutedEventArgs e)
2: {
3: Toast toast = new Toast
4: {
5: Duration = "long",
6: Launch = "alarm(" + Guid.NewGuid().ToString() + ")",
7: Audio = new ToastAudio { Loop = true, Source = "ms-winsoundevent:Notification.Looping.Alarm2" },
8: Visual = new ToastVisual
9: {
10: Binding = new ToastImageAndText04Binding
11: {
12: Text1 = "Silverlight Show",
13: Text2 = "New article by A. Boschin",
14: Text3 = "Windows 8.1: Alarm and Lock screen call toasts",
15: Image1 = new ToastImage { AltText = "hallo", Source = new Uri("ms-appx:///Assets/SilverlightShow.png") }
16: }
17: },
18: Scenario = new Alarm
19: {
20: CanDismiss = true,
21: CanSnooze = true
22: }
23: };
24:
25: this.NotifyScheduled(toast);
26: }
All the work is made inside the Toast class and the inner hierarchy. Feel free to use it in your applications.