Programmatically create and display Notifications

Screenshot showing an example popup notification on a Windows Mobile 6 Professional deviceThe 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.

Screenshot of Visual Studio 2005 demonstrating how to find the Resources.resx file to include the icon resource

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
Screenshot of sample applicationA 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.

23 Responses to “Programmatically create and display Notifications”

  1. hacqua says:

    Great article. However, I just can’t make my notifications go away. I mean, when I click on “Hide”, the notification stays minimized (in ballon form), and it is not removed no matter what I do (only way to do it is to reset device). I’m using WM 6.0. Is there something I’m missing? Thanks!

  2. Hi hacqua,

    I’m glad you liked the article. I’m blogging about these topics as a way to give back to the community, so I’m glad I’ve been of help to someone.

    This is “by design”, the hide button simply hides the popup ballon part of the notification, but will leave the notification icon on the nav bar at the top of the form.

    This is to support scenarios such as “you are currently downloading a file: 42KB out of 5923KB completed so far” style progress notifications. i.e. long running notifications which should still be accessable to the user, but the user may want to temporarily hide in order to work with the device before the process has completed.

    To get the functionality you want (clicking the Hide button will remove the notification completely), you should listen to the BallonChanged event and do something like the following:

    void n_BalloonChanged(object sender, BalloonChangedEventArgs e)
    {
      // Has the popup balloon been hidden?
      if (e.Visible == false)
      {
        // If so, remove the notification completely by
        // setting it's visible property to false
        n.Visible = false;
      }
    }

    See if making that change to the sample application does what you desire.

    Hope this helps

  3. hacqua says:

    Yes, now it works!!! Thank you very much! :-)

  4. Dan says:

    On my WM6 device, there are numerous pop-ups that look identical to the Notification popup except they have custom text for the 2 soft keys rather then just having “Hide”. How can this be done?

  5. Hi Dan,

    Welcome to the world of the .NET Compact Framework :-)

    The Notification class within the Microsoft.WindowsCE.Forms assembly is a .NET wrapper around the native functionality present within the Operating System.

    Support for having custom menu bars associated with notifications is something which is missing from this wrapper class. I.e. it is supported by the operating system, but is not exposed by the .NET wrapper class.

    On MSDN you can see within the documentation for the SHNOTIFICATIONDATA structure used by the native API references to fields called skm and rgskn which allows control over the menu bar present.

    So at present setting custom menu bars up for a notification is not possible from a .NET Compact Framework application.

    It is possible you could PInvoke the entire notification API yourself in order to expose the required functionality. I might have a little bit of an investigation and see if I can come back with a better answer, it is possible for instance that someone has already produced such a wrapper.

  6. Hi Dan,

    As promised I have taken a look at what is required to get custom soft keys on a notification within the confines of a .NET Compact Framework application.

    Please see my newer blog entry “Custom soft keys for Notifications” for further details and an example application.

    This approach also provides an alternative way for hacqua to get a notification to remove itself when the “hide” button is pressed (make a custom soft key of type “Dismiss” instead of “Hide”).

  7. Aneesh Abraham says:

    Hi ,

    I am trying to implement the sample program provided in :

    http://msdn2.microsoft.com/en-us/library/aa454900.aspx#nw_pocket_transport_wm2k3_topic4

    ” Northwind Pocket Delivery: Transportation for Windows Mobile-based Pocket PCs” .

    It seems the notification API `s used in this project is obolete now.

    The target platform is Windows Mobile 6.

    My requirement is to get the notification in Mobile device which originates from the web interface.

    I have gone through your well explained posts here but could not find something related to this.
    Thanks for preparing and sharing your vast programming experience with us…:)

    _Aneesh

  8. Alex says:

    Hello,
    Is there a way to detect programmatically when a Notification Ballon is displayed. For instance a “Main batery Low” balloon?

    Thanks a lot in advance.

    Alex.

  9. andrei says:

    Hello,

    I have a problem using notification in an application on Pocket PC 2003 SE. when i click on the icon of may notification in the title bar the device resets.

    With pocket pc 2003, windows mobile 5.0 or 6.0 the problem doesn’t manifest.

  10. Can we have notification control for smartphone.

  11. anne says:

    Hello Sir,

    I create a custom notification for my application and notification icon will show up in the title bar of the PDA phone. If there is only one ballon notificaiton on the title bar, then i can click on the notification icon to show up the ballon message, but when there is also a sms notification icon , then when i try to click on one of the icons on the title bar, then the whole system crashed. Can anyone know what happeded to it.

    thanks a lot
    anne

  12. FetCh says:

    Hello,

    It’s a good exemple, i’m just a question, when i create my notification in my application, if my application close, so my notification disapeard, it’s normal or not ? I want to send a notification, close my apps, but i want to acces to my notification, it’s possible or not ?

    Thank a lot
    Fetch

  13. Jay says:

    I really appreciate the info posted in your Notification articles. These are some of the things that I have been playing with the last day or so. The two questions that I have that has not been answered in your posts or in the comments are:

    1. Do you know if it is possible to initiate a Notification and not have the balloon show up initially? In other words can I get the icon to display and not show the balloon? I want to let the user click on the icon to display the balloon when they want to.

    2. How can I change the icon without having the balloon pop up? I need to change the icon based on the current state of my app so that the user can see what is going on without popping the balloon up. I can change the icon through the standard C# API but every time I do that the balloon pops up.

    Thanks for the info,
    Jay

  14. xiao says:

    Hi,

    I would like to know if i can change the look and feel of the notification? i mean instead of that default box; can i change the apeareance (creating my own box with a different design). thx.
    If not is there any way to do it with another API?.

    Regards,

  15. jon says:

    Hi,
    Thanks for the article, I’m new to windows mobile development, so this definitely helped.
    One question:
    Is there a way to configure the location of the notification? I would like mine to stay at the top ‘Start’ menu bar, but by default it ends up at the bottom of the screen, even though the icon is at the top.
    I don’t see an obvious way to configure this, and when I originally tried it in the Pocket PC 2003 platform it was at the top.

    Regards,
    Jon

  16. Carl says:

    Great article with a simple and practical example. I used this today to get notifications working in my app.

  17. Roy says:

    Hi Christopher,

    Is it possible to create the popup window similar to the one when you clicked the icons in the taskbar such as sound icon and Time. It looks like a callout window.

    Regards,
    Roy

  18. [...] I grabbed  an application called AKToggleWifi from akarnik and created a small program that makes use of the Notifications class based on the code posted by Christopher Fairbairn. [...]

  19. Kareem Ayoub says:

    Hi Christopher,

    Can i display this notification during a call? will it beep like when a message is received?

    Thank a lot.

    Kareem Ayoub.

  20. Ruch says:

    Hi there,
    Great example.

    Is there a way to disable to balloon and just keep the icon on the top.
    Reason is that I want to use the icon to indicate wifi availability to the user from the app. I change the icon when the device has no signal.
    I can change the notification icon dynamically just fine but everytime it changes, the balloon also pops up and I don’t want that.

    Appreciate your help.
    Thanks

  21. Li Hong Bo says:

    Hi Christopher, Very nice example.

    I want to know how to implement the WM 6.1 short message notification UI(using C#).
    The rigth softkey is not a menuItem but a menu which has some menuItems.

    thank a lot.
    Li Hong Bo

  22. ezyclie says:

    Hi,

    Great example, but is it possible to change native SMS notification with this code ?

  23. Kappa de zeta says:

    Nice work! Excellent article! Keep it up!

Leave a Reply