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.

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

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

Constructor Detail

SoftNotification

protected SoftNotification()

Hidden default constructor.

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 - 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 - 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 - 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 - to be displayed in the soft notification when ungrouped soft notification is shown.

groupText - 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 - 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 - 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 - 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.