com.nokia.mid.ui
Class SoftNotification

java.lang.Object
  com.nokia.mid.ui.SoftNotification

public abstract class SoftNotification
extends java.lang.Object

The SoftNotification is a class to manage soft notifications. Soft notifications are reminders that inform the user of events that have occurred in the user's absence, or while the user was busy with some application. Text, and also graphics, can be used to communicate the message to the user. Soft notifications are displayed as pop-ups in device home screen (idle view).

This API is an optional feature in Nokia UI API, and depending on the device capabilities there may be implementations that do not support soft notifications. The System.getProperty("com.nokia.mid.ui.softnotification") will return "true" if this feature is available in the device.

Soft notifications are persistent and restarting the device does not delete created soft notifications from the home screen.

The user can respond to the soft notification by using the softkeys. The softkey 1 is used for activating a function, for example opening a message that has arrived. Application that created the soft notification will be activated when the soft notification is accepted by the user. The softkey 2 is used to discard the notification without taking any further action.

The application that launched a soft notification can control it and also discard it. It is possible to use the Applications key during a soft notification; in that case, the soft notification disappears, but reappears when the user returns to the device home screen, unless the application responsible for the notification has discarded it.

Grouping soft notifications

Soft notifications can be displayed for the user in two different appearances.

Ungrouped soft notification: These notifications contain one piece of information each. In ungrouped soft notification there can be one or two lines of text and an image visible. Ungrouped appearance is used when there's only one active soft notification or the topmost soft notification does not support grouping.

Grouped soft notification: If there are several soft notifications on the screen and they support grouping, the notifications are grouped and shown as a list of notifications. Only one line of text is shown per a notification and there are no images visible. The user can pick up one notification at a time and react to it. If user discards the notification group, then all the shown notifications are discarded and are not to be shown again.

Soft notifications created through this API may be grouped with other platform notifications if all of them supports grouping. A soft notification supports grouping if groupText is given in setText(String text, String groupText)

Persistent notifications

Soft notifications are persistent meaning that when an application has created a notification and set it to the home screen, the notification exists in the home screen until:

User accepts the notification,

User dismisses the notification, or

Application removes the notification

A soft notification stays on the device home screen even if the application is closed or the device is restarted.

Accepting (selecting) a soft notification created by an application causes this application to be activated in the following ways:

If the application was running on the background, it will be set to the foreground.

If the application was running and had registered a listener for the notification, SoftNotificationListener.notificationSelected(SoftNotification) is called.

If the application is not running, it will be started and set to the foreground.

Notice that accepting a notification belonging to a closed application causes only the application to be started but does not generate any listener events for the application. This is because there cannot be any listeners registered by the closed application. Thus, when an application is started by a notification, the application has to decide which view is shown for the user without having the information about the selected notification.

Dismissing a soft notification does not bring the application to the foreground or start the application neither. However, if a listener has been set, SoftNotificationListener.notificationDismissed(SoftNotification) is called.

Because soft notifications are persistent, they will remain on the home screen even if the application is closed. It is possible to get access to these notifications later when the application is restarted. For accessing notifications later, the application has to store the IDs of the notifications to a permanent memory (for example, RecordStore). When the application is restarted, the application may recreate those notifications by using the stored IDs.

Notice that since it is possible that the user has dismissed notifications when the application was closed, it is not possible to know whether the recreated notification still exist on the device home screen. In many cases it may be worthile to first remove all those notifications from the screen and then add only the needed ones back to the screen.

Example of usage

class SoftNoteExample implements SoftNotificationListener { private SoftNotification iSoftNotification; public SoftNoteExample() { iSoftNotification = SoftNotification.newInstance(); iSoftNotification.setListener( this ); } public void Show1NewMail() throws SoftNotificationException { // Read image e.g. from the MIDlet JAR package or filesystem byte[] image = readImage( "mail.png" ); // Supports grouping since groupText is given here. iSoftNotification.setText( "You have 1 new mail", "1 new mail" ); iSoftNotification.setSoftkeyLabels( "Show", "Exit" ); iSoftNotification.setImage( image ); iSoftNotification.post(); } public void notificationSelected(SoftNotification notification) { // called when user selects the soft notification } public void notificationDismissed(SoftNotification notification) { // called when user dismisses the soft notification } private byte[] readImage( String aImageName ) { // Read image e.g. from the MIDlet JAR package or filesystem. byte[] imageData = ... //... return imageData; } }

Since:

1.3

Constructor Summary

protected

SoftNotification() Hidden default constructor.

Method Summary

abstract int	getId() Get soft notification identification of this instance.
static SoftNotification	newInstance() Returns a new instance of SoftNotification class.
static SoftNotification	newInstance(int notificationId) Returns a new instance of SoftNotification class with a reference to previous soft notification instance.
abstract void	post() Shows a new soft notification or updates the content of previously posted notification.
abstract void	remove() Removes the posted soft notification from the device home screen.
abstract void	setImage(byte[] image) Sets an image to be displayed in the soft notification.
abstract void	setListener(SoftNotificationListener listener) Sets listener for the soft notification.
abstract void	setSoftkeyLabels(java.lang.String softkey1Label, java.lang.String softkey2Label) Sets the textual labels for the softkeys.
abstract void	setText(java.lang.String text, java.lang.String groupText) Sets the text field to be displayed in the soft notification.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SoftNotification

protected SoftNotification()

Hidden default constructor.

See Also:

newInstance(), newInstance(int notificationId)

Method Detail

newInstance

public static SoftNotification newInstance(int notificationId)

Returns a new instance of SoftNotification class with a reference to previous soft notification instance.

Identification is used to access a soft notification created by another instance of SoftNotification. If the provided identification is valid and such soft notification exists, it can be updated and removed through this instance. If the identification is not valid or does not exist, it will be ignored and a new soft notification is created as defined in newInstance().

Parameters:

notificationId - Identification of previous soft notification.

Returns:

An instance of SoftNotification class.

See Also:

getId()

newInstance

public static SoftNotification newInstance()

Returns a new instance of SoftNotification class. This instance's identification will be a nonvalid negative value until post() is called.

Returns:

an instance of SoftNotification class.

getId

public abstract int getId()

Get soft notification identification of this instance. Soft notifications are persistent, so client should store the identification, if it wants to access the soft notification from another instance e.g. after device is restarted.

Notice that identification might change during the lifetime of the instance if post() is called.

Returns:

Soft notification identification.

See Also:

newInstance(int notificationId)

post

public abstract void post()
                   throws SoftNotificationException

Shows a new soft notification or updates the content of previously posted notification. If the application did not specify a valid identification in the notification construction, then new identification will be generated on first call to post(). If previously posted soft notification does not exist, a new one is created and a new identification will be generated. Client needs to set the attributes shown in the soft notification before calling post or the default values will be used. This call does not reset assigned text, image or softkeys.

Notice that identification of the soft notification may change every time the function is called. So when needed, it is recommended to ask the latest id from the notification by using getId() function.

Throws:

SoftNotificationException - Thrown if posting operation fails.

remove

public abstract void remove()
                     throws SoftNotificationException

Removes the posted soft notification from the device home screen. If the soft notification has not been posted or it has already been removed, this call does nothing. Remove is automatically called when the user accepts or dismisses the soft notification.

Throws:

SoftNotificationException - Thrown if removing the note fails.

setListener

public abstract void setListener(SoftNotificationListener listener)

Sets listener for the soft notification. Listener is notified when the user accepts or dismisses the soft notification. Setting a new listener will overwrite the previous listener. Listener can be removed by setting it to null.

Parameters:

listener - Listener for the soft notification.

setText

public abstract void setText(java.lang.String text,
                             java.lang.String groupText)
                      throws SoftNotificationException

Sets the text field to be displayed in the soft notification. The platform may truncate the text to a suitable size to fit into the soft notification. If the text is not set before calling post(), the default value "" is used. An ungrouped soft notification has multiple lines for the text, but a grouped notification has only one line. Therefore the text assigned for a grouped notification should be shorter. Multiple lines can be created by adding a line break (character '\n') inside the string.

A notification supports grouping if groupText is other than null or an empty string ("").

Notice that the modified soft notification data is not visible for the user until post() is called.

Parameters:

text - A text to be displayed in the soft notification when ungrouped soft notification is shown.

groupText - A text be to displayed in the soft notification when there are also other notifications visible (grouped form). The notification will not support grouping if null or an empty string ("") is used.

Throws:

SoftNotificationException - Thrown if setting text fails.

setSoftkeyLabels

public abstract void setSoftkeyLabels(java.lang.String softkey1Label,
                                      java.lang.String softkey2Label)
                               throws SoftNotificationException

Sets the textual labels for the softkeys. The platform may truncate the text to a suitable size to fit to the softkey labels, so a relatively short texts are preferred for the labels. If labels are not provided, then the default softkeys will be used (Show & Exit).

The functionalities of these softkeys remain always the same even if their texts are changed. Softkey 1 (Show) opens up the application and dismisses the soft notification. Softkey 2 (Exit) dismisses the soft notification.

Notice that the modified soft notification data is not visible for the user until post() is called.

Parameters:

softkey1Label - Text for the softkey 1.

softkey2Label - Text for the softkey 2.

Throws:

SoftNotificationException - Thrown if setting softkeys fails.

setImage

public abstract void setImage(byte[] image)
                       throws SoftNotificationException

Sets an image to be displayed in the soft notification. The image can be in any format that the platform's image decoder or SVG engine is able to decode (for example, JPG, GIF, PNG, and SVG (even SVGS and MBM) images may be supported in the platform). Image mask is used when available.

The image is given as a byte array, for example the data may be read directly from the file system or MIDlet JAR package.

Images will be scaled to fit in the soft notification pop-up as the image area of the notification is relatively small. For saving resources in scaling, the size of the image should be kept small (preferably no larger than 300x300 px).

The function can also be used for removing an already set image from the soft notification. This can be done by setting null instead of any actual image.

Notice that the modified soft notification data is not visible for the user until post() is called.

Parameters:

image - image to be displayed in the soft notification or null if any existing image should be removed from the notification.

Throws:

SoftNotificationException - Thrown if setting image fails.