/dev/mobile

The Windows Mobile operating system provides a Notifications feature which can be utilised to display prompts to the user in the form of toast or popup balloons (depending upon operating system version) even when your application is running in the background. These are ideal for when your application must inform the user that background tasks have completed, or that particular actions must be performed. This blog entry discusses how you can utilise notifications within your own applications.

Supported Platforms
Notifications are only supported on Windows Mobile Professional or Classic (i.e. Pocket PC) devices, they are not supported on Windows Mobile Standard (i.e. Smartphone) devices. If you develop a Compact Framework application which uses notifications, the application will compile when you target a Windows Mobile Standard device, but will cause a NotSupportedException when the application is ran on the device.

To utilise the Microsoft.WindowsCE.Forms.Notification class you must add a reference to the Microsoft.WindowsCE.Forms.dll assembly.

One of the easiest ways to obtain this reference, and to configure your notification is to drag a “Notification” component from the Toolbox within Visual Studio 2005 (it is located within the Device Components category). Doing this will automatically added the needed reference to your project, and allow you to configure the notification’s properties graphically via the Properties window.

Notification Properties
The notification class has a number of properties which control the look and feel of the notification balloon. These properties are as follows:

• Caption – the text displayed in the caption bar at the top of the notification balloon.
• Text – a string containing the HTML content to display in the main part of the notification popup. This enables you to use formatting, and different colours within your notifications.
• Critical – a boolean flag, if set to true this indicates that the notification is of urgent importance. This has the effect of using a different colour border around the edge of the notification.
• Icon – The icon to display on the nav bar for the notification. The user can tap on this icon to display a hidden notification, so it should be representative of the meaning of the notification.
• InitialDuration – the number of seconds the notification should appear on the screen when initially made visible. After this duration has expired the notification will hide itself, and the user will have to tap on the icon on the nav bar to make it re-appear. If this value is set to zero the popup notification is not displayed, instead going straight to the icon on the nav bar.
• Visible – setting the Visible property to true, will make the notification balloon appear on the screen.

Displaying a notification
To display a notification to the user is as simple as creating an instance of the Notification class, setting up the properties for the desired effect, and then finally setting the Visible property to true to make the notification visible to the user. This is demonstrated in the following sample:

using Microsoft.WindowsCE.Forms;
 
private Notification n = null;
 
private void button1_Click(object sender, EventArgs e)
{
  // Create an instance of the notification class and configure
  // its properties for the desired effect.
  n = new Notification();
  n.Caption = "Hello World!";
  n.Text = "<b>This</b> is a <u>sample</u> notification!";
  n.Critical = false;
  n.Icon = Properties.Resources.NotificationIcon;
 
  // Finally to make the notification appear on screen
  // set the Visible property to true.
  n.Visible = true;
}

One important thing to notice is that we have not used a local variable within the button1_Click method to hold the Notification we are displaying to the user. The reason for this has to do with the CLR and its Garbage Collection behavior. Although the code may work if you use a local variable, it is not guaranteed and will potentially lead to unpredictable behavior (more on this in a later section).

The only property which deserves further discussion is the Icon one. You can store an icon in a number of ways. Perhaps the easiest way to store an icon in your executable is to use the Resources.resx file the Visual Studio 2005 project wizard will have created for you. The following screenshot demonstrates where you can find this file within solution explorer. If you open the file you can add new icon(s) into it, and these icons will be accessible via strongly typed properties within the Properties.Resources class, as demonstrated by the code sample above.

Hiding a notification
There are two different ways you can remove a notification which is visible on the screen.

You can simply set the Visible property to false, as the following example demonstrates:

// Using this approach to hide a notification will allow you
// to re-display it by changing the Visible property back to true.
n.Visible = false;

This has the benefit that you can decide to re-display the notification, by simply resetting the Visible property back to true. You can change the Visible property as many times as you like.

The alternative approach is to call the Dispose method of the Notification class, as the following example demonstrates:

// Using this approach will hide the notification but won't
// allow you to re-display it without creating a new instance
// of the Notification class.
n.Dispose();

Once you have done this you will not be able to display the notification again, without creating a new instance of the Notification class.

Previously we mentioned that you should not use a local variable to reference your Notification object. This last code sample demonstrates the reason why. If you had stored your notification in a local variable within the button1_Click method, the garbage collector would detect your variable as potential garbage when the method completed. If a garbage collection occurred, and decided to collect this reference, the garbage collector would call the Dispose method on the notification, which would remove it from the screen. By keeping a reference to the notification “alive” for the life time of the form (by using a member variable to reference it) the garbage collector will not be able to dispose of it until the form is closed.

Detecting when the notification is hidden
The notification class has a BallonChanged event which fires whenever the notification balloon is made visible, or hidden.

The following example, demonstrates how you can listen to this event, in order to perform a task when the popup balloon is hidden:

Notification n = new Notification();
// configure the notification properties...
n.BallonChanged += new BallonChangedEventHandler(n_BallonChanged);
 
void n_BalloonChanged(object sender, BalloonChangedEventArgs e)
{
  // The Visible property indicates the current state of the
  // popup notification balloon
  if (e.Visible == false)
  {
    // If the balloon has now been hidden, display a message box
    // to the user.
    MessageBox.Show("The balloon has been closed", "Status");
  }
}

Sample Application
A sample application is available for download, which demonstrates the use of the Notification class. It enables you to experiment with the various properties of the notification class, and see how they alter a notification.

There is one member of the Notification class which we have not discussed in this blog entry. This is the ResponseSubmitted event which can be used to process feedback provided by the user when they dismiss the popup notification. For example in the HTML text of a notification, you could create a couple of radio buttons, and a text field. By handling the ResponseSubmitted event you can determine what values the user has entered and use them to alter the behavior of your application. Covering how to utilise the ResponseSubmitted event to process HTML based forms will be the topic of a future blog entry.