Custom soft keys for Notifications

Screenshot of custom notification displayed on the screen with two custom soft key menu items.Since my previous posting about Notifications within the .NET Compact Framework I have seen the question of how to provide custom menu items at the bottom of a notification come up a number of times. Today I am going to provide you with one solution to this challenge.

The short answer is that the Microsoft.WindowsCE.Forms.Notification class provided by the .NET Compact Framework does not expose the required functionality. Although the native notification API allows custom menus to be associated with a notification, for some reason this hasn’t be exposed to managed developers. With a little bit of work however (i.e. some PInvoking) you can produce your own managed wrapper around the Notification APIs to expose the required functionality.

I have done this and produced a class called NotificationWithSoftKeys. You can download a copy of this class, along with a sample application which demonstrates it’s various features below.

[Download notificationsoftkeys.zip 32KB]

The rest of this blog entry will demonstrate how you can utilise the class within your own applications. It is designed to be a stand in replacement for the existing class, but adds some additional properties and events.

Adding Spinners
Screenshot of custom notification showing the use of spinnersSpinners are the first additional functionality the NotificationWithSoftKeys control exposes. A notification spinner is a little bit of text on the right hand side of a notification which sits in-between a pair of < and > buttons. The user can tap on these buttons to “spin” through a series of related notifications.

Here is a brief example of how to enable this feature within your notification.

private NotificationWithSoftKeys notification;
 
private void btnCreateNotification_Click(object sender, EventArgs e)
{
  notification = new NotificationWithSoftKeys();
  notification.Icon = Properties.Resources.Icon;
  notification.Caption = "This is my notification";
  notification.Text = "Spinner Test\t1 of 5";
  notification.Spinners = true;
  notification.SpinnerClicked +=
      new SpinnerClickEventHandler(notification_SpinnerClicked);
  notification.Visible = true;
}

The main thing you need to do is set the Spinners property to True in order to enable the Spinner functionality. After this any text within the Caption property after the first tab (\t) character will be displayed on the right hand side of the notification’s caption.

When the user presses the < or > buttons the SpinnerClicked event will fire. Within your event handler you should update your Notification’s Caption and Text properties to give the illusion that another notification has been displayed.

Display Current Time on Caption
Screenshot of custom notification showing the use of the TitleTimer propertyDisplaying the current system time on the caption is very straight forward. All you need to do is set the TitleTime property to true.

Custom Buttons
This is the feature which will probably generate the most interest. The standard notification has a “Hide” button on the left soft key. Some built in applications however display notifications with alternative softkeys and perform different actions depending upon which softkey was selected. Using the NotificationWithSoftKey class we can achieve the same effect as demonstrated with the following example.

private NotificationWithSoftKeys notification;
 
private void btnCreateNotification_Click(object sender, EventArgs e)
{
  notification = new NotificationWithSoftKeys();
  notification.Icon = Properties.Resources.Icon;
  notification.Caption = "This is my notification";
  notification.Text = "A soft key test";
  notification.LeftSoftKey =
      new NotificationSoftKey(SoftKeyType.Dismiss, "Close");
  notification.RightSoftKey =
      new NotificationSoftKey(SoftKeyType.StayOpen, "View");
  notification.RightSoftKeyClick +=
      new EventHandler(notification_rightSoftKeyClick);
  }
 
  notification.Visible = true;
}

This example will display a notification with two soft keys. The left soft key will be labeled “Close” and will remove the notification, while the right soft key will be labeled “View” and trigger the RightSoftKeyClick event when selected.

Within this event handler you could open up a second form, delete something from a database or perform any other task you would like to in response to the user pressing the soft key.

There are a number of soft key types to choose from as shown below:

Type Description
Dismiss Remove the notification when the soft key is pressed
Hide Hide the notification when the softkey is pressed (but do not dismiss)
StayOpen Do not dismiss or hide the notification when the softkey is pressed.
Submit Submit the HTML form in the notification instead of calling the click event handler
Disabled The softkey is disabled (grayed out)

Backwards Compatibility
The additional features discussed today are only available on devices running Windows Mobile 5.0 or higher. If your application is targeting multiple device types, and you need to run on Pocket PC 2003 devices the new functionality will not work.

The NotificationWithSoftKeys class utilises techniques outlined in my blog posting on device and platform detection to fail gracefully on older devices. When the class detects an older device type, it will simply ignore all the soft key related properties and revert back to the old notification style.

Sometimes you may want to check if this fallback has occurred. For instance you may want to utilise the soft key buttons for user input. In this case you would need to use an alternative approach (such as HTML based buttons) when running on Pocket PC 2003 or older devices which don’t have softkeys. You can do this by checking the PlatformSupportsCustomSoftKeyButtons property and altering the other properties of the NotificationWithSoftKeys class as required.

Summary
This is still only scratching the surface of what is possible with the native notification APIs. There are a number of notification features which are not exposed by this wrapper. For example there are the following flags which could easily be exposed as properties.

  • SHNF_DISPLAYON – the display is forced to turn on for the notification
  • SHNF_SILENT – the notification is forced to be silent and not vibrate, regardless of system settings

Please feel free to download the sample project and have a play around with it. I would be keen to hear from anyone who attempts to use it or modifies it to expose additional functionality etc.

58 Responses to “Custom soft keys for Notifications”

  1. Hi Juan,

    No there’s no problem with using this code within your application. In fact that’s the very reason I decided to start blogging :-)

    It’s not so easy to find, but unless explicitly mentioned all of my code samples and blog posts here fall under a license I’ve posted at the bottom of http://www.christec.co.nz/blog/projects. This license should be fairly compatible with the desires of most people. If it doesn’t suit, contact me and I’m sure we can work something out.

  2. Thanks, Christopher, for this code.
    I’m having some problems though:
    None of the button events are fired. I’m running your code the VS2005 on a Windows Mobile 6 Classic emulator. Here the code:
    _notification = new NotificationWithSoftKeys();
    _notification.Caption = “Error”;
    _notification.Text = “A message”;
    _notification.LeftSoftKey = new NotificationSoftKey(SoftKeyType.StayOpen, “Review”);
    _notification.RightSoftKey = new NotificationSoftKey(SoftKeyType.Dismiss, “Dismiss”);
    _notification.BalloonChanged += new Microsoft.WindowsCE.Forms.BalloonChangedEventHandler(notification_BalloonChanged);
    _notification.LeftSoftKeyClick += new EventHandler(notification_Sync_LeftSoftKeyClick);
    _notification.RightSoftKeyClick += new EventHandler(notification_Sync_RightSoftKeyClick);
    _notification.InitialDuration = 60;
    _notification.Visible = true;

    Anything i’m doing wrong?

  3. ed says:

    I am trying to use your code in a project but notification.dispose is not clearing up the notification. In fact I have made a dll file of the class and then referenced it.

  4. AOEN says:

    We have a application which consists of N modules whenever a module is loaded it will load the module related menu items in left soft key.

    I have a serious issue when ever the notification dispalys on a window, upon dismiss it will remove the existing left softkey menu items. how can i maintain the state of the already existing menu items.

  5. Matt says:

    Hi Chris,
    Using your Notificationwithsoftkeys and running into an issue (Dev environment = VS 2008 and deploying to Windows Mobile 6

    NotificationWithSoftKeys n = new NotificationWithSoftKeys();
    n.Caption = “Load Info”;
    n.Text = information;
    n.Critical = true;
    n.Visible = true;
    n.InitialDuration = 5;
    n.Icon = Properties.Resources.CAR4;
    n.LeftSoftKey = new NotificationSoftKey(SoftKeyType.Dismiss, “Close”);

    When I run it in the application, the messages appear fine, but when I click the left key, I get an error saying “KeyNotFoundException”. Any thoughts on what might cause that?

  6. Matthias says:

    Hi.
    This class is just great. Thank you very much.
    I have only one small problem. When I click “Dismiss” the NotificationSoftKey EventHandler is called.
    In the function I need to identify which notification was dismissed (the text in the notification or an index….).
    Is there a way to identify that in the Eventhandler function?
    Thank you very much in advance.
    Matthias

  7. jis says:

    Hi Cristopher,

    This article is very helpful. I have a doubt, hope you can help me out. I need to show the notification from a thread running as a service in WM. It throws an error : ‘Control.Invoke must be used to interact with controls created on a separate thread.’ But Notification class is not ‘Control’, it is a Component. Is there any way to show up the notification from a background thread from an app which doesnt have a UI form.

    Thanks & Regards,
    Jis.

  8. MathiasF says:

    Hi!
    I need my notification to make the device vibrate and make a sound until the user gives a response.
    Is there a way to do that with your code?
    Thanks!

Leave a Reply