javax.microedition.lcdui
Class Notification

java.lang.Object
  javax.microedition.lcdui.Notification

public class Notification
extends java.lang.Object

Represents a small unobtrusive informational note to be shown to the user. All Notifications have a NotificationType that provides the common information for all notifications of the same type, such as a default image and label.

Notifications are used to enable a MIDlet to post notifications to the user, without necessarily taking control of the screen. The Notifications are managed by the implementation, and the only way MIDlets interact with them are by posting and removing Notifications. A typical use of Notification is an email application running in the background, and presenting information about newly arrived messages in a standardized way. Notifications are intended to be used for unobtrusive informational purposes that do not require immediate user attention.

A Notification can exist in one of two logical states : available and removed.

Upon instantiation, a Notification exists in the removed state. A Notification may be created without setting the label and image. If a label and/or image are not provided, the default label and image of the associated NotificationType will be used.

A Notification can have a String label and an Image. The image is used for the visual representation of the notification, with the label optionally being shown by the implementation as a result of the user inspecting the notification. The implementation MAY truncate the label to fit the available size of the displayed text. The image attached to the notification is the primary way that user defined notifications are displayed to the user. The implementation MUST display the image on a best effort basis, depending on what can be done on the particular display. Implementations MAY truncate or scale the icon image based on what's supported by the device. Applications can query the implementation's notification icon size using the Display.getBestImageHeight() and Display.getBestImageWidth() methods using image type Display.NOTIFICATION. A device may show Notifications on multiple displays. In this case, these methods return the values for the primary notification display, and the implementation is expected to handle the other displays in a satisfying way.

A Notification becomes available after a successful call to post(). Depending on the implementation and the NotificationType, the Notification may or may not be directly visible; but the implementation MUST ensure that the user is made aware by visible means that a Notification has been posted. If a NotificationListener is set on a Notification, then after the Notification has been either selected or dismissed by the user, notificationDismissed or notificationSelected is called on the NotificationListener that was set on the Notification.

Implementations SHOULD show the Notification as soon as possible after a post() call, but in the case where many MIDlets post Notifications at the same time, the implementation MAY queue the visual notification for a short time to create a better user experience. A Notification can be updated by calling post() again. This update is then carried out as soon as possible, with the possibility for queuing as described above.

The post(boolean,int) method provides applications with a way to provide a hint to the implementation that the Notification should only be available for a specific length of time (in milliseconds). If the Notification has not been inspected during the requested time, the Notification becomes removed. The specified duration is the time requested by the application for the Notification to be available, and is measured from the time the Notification first became available. Implementations SHOULD use the requested duration but MAY replace it with a system wide preference to better conform to device user experience. A Notification that is posted without specifying a duration, with post(boolean), MUST remain available to the user until it is removed.

The state diagram below defines how Notifications are posted, removed and re-posted (updated), how the events on NotificationListener are triggered, and how Notifications transition between the available and removed states.

A Notification can become removed in the following ways :

• By the implementation, when a Notification is dismissed or selected by the user, before the callbacks (notificationSelected() or notificationDismissed()) are triggered.
• By a MIDlet using the remove() method.
• By the implementation, due to the duration being passed (see below), which will trigger the notificationTimeout() method.

A Notification MUST remain available until removed by application or implementation code in the ways defined above.

Since MIDP may be implemented on devices with a wide range of capabilities, the way that Notifications are shown is implementation specific. Notifications may be shown on the primary display, on secondary displays, in a transparent overlay on the main display, or wherever the implementation decides. The MIDlet has no control of how and where the Notifications are shown.

The following example code creates, posts and updates a Notification.

 Notification n = new Notification(NotificationType.EMAIL);
 n.post();    // notification is made available (no label and image needed,
              // since a notification type provides a default label and image)
 //
 // ... after some time the notification is updated without it being inspected first
 //
 n.setLabel("Unread mail"); //optional to supply a notification-specific label
 n.post(true);
     

The following example code creates and posts two notifications of the same user defined type.

 NotificationType type = new NotificationType("chats", defaultImage);
 Notification n = new Notification(type);

 n.setImage(image);
 n.setLabel("New message from Alice");

 n.post();    // notification is made available (label and image must be set)
 //
 // ... after some time
 //
 Notification n = new Notification(type, "New message from Bob", image);
 n.post(true);
 

Since:

MIDP 3.0

Constructor Summary

Notification(NotificationType type)
Creates a new Notification with the given type.

Notification(NotificationType type, java.lang.String label)
Creates a new Notification with the given type and label.

Notification(NotificationType type, java.lang.String label, Image image)
Creates a new Notification with the given type, label and image.

Method Summary

long	getTimestamp() Gets the time when the Notification was last posted.
NotificationType	getType() Get the NotificationType associated with this Notification.
void	post(boolean selectable) Posts the Notification.
void	post(boolean selectable, int duration) Posts the Notification with a set limit on how long it should be available.
void	remove() Removes the Notification.
void	setImage(Image image) Sets the Image of the Notification.
void	setLabel(java.lang.String label) Sets the label of the Notification.
void	setListener(NotificationListener listener) Sets the NotificationListener of the Notification, replacing any previous NotificationListener.

Methods inherited from class java.lang.Object

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

Constructor Detail

Notification

public Notification(NotificationType type,
                    java.lang.String label,
                    Image image)

Creates a new Notification with the given type, label and image.

Parameters:

type - the notification type

label - the notification's label

image - the notification's image

Throws:

java.lang.NullPointerException - if the type is null

See Also:

NotificationType

Notification

public Notification(NotificationType type,
                    java.lang.String label)

Creates a new Notification with the given type and label.

Parameters:

type - the Notification type

label - the Notification's label

Throws:

java.lang.NullPointerException - if the type is null

See Also:

NotificationType

Notification

public Notification(NotificationType type)

Creates a new Notification with the given type.

Parameters:

type - the notification type

Throws:

java.lang.NullPointerException - if the type is null

See Also:

NotificationType

Method Detail

getType

public NotificationType getType()

Get the NotificationType associated with this Notification.

Returns:

the notification type

See Also:

NotificationType

setLabel

public void setLabel(java.lang.String label)

Sets the label of the Notification.

Parameters:

label - the label for the Notification.

setImage

public void setImage(Image image)

Sets the Image of the Notification. The Image may be mutable or immutable. If image is mutable, then a snapshot is taken of the image's contents before the call to post() returns. The snapshot is used whenever the contents of the Notification are to be displayed. If image is already the image of this Notification, a new snapshot of image's contents is taken. For example, after painting into a mutable image contained by a Notification, an application may refresh the snapshot by calling post() again. Example :

 notification.setImage(mutableImage);
 //...
 //mutable image is updated.
 //...
 notification.post();
 

The updated image will be displayed only after post is called. If the Notification is visible on the display then the display SHOULD be updated with the new snapshot as soon as it is feasible for the implementation to do so.

Parameters:

image - the Image to set for the Notification; may be null.

setListener

public void setListener(NotificationListener listener)

Sets the NotificationListener of the Notification, replacing any previous NotificationListener. A null reference is allowed and has the effects of :

• removing any existing listener, and
• making the Notification removed, if presently available

Parameters:

listener - the new NotificationListener for the Notification.

post

public void post(boolean selectable)

Posts the Notification. Notifications are not required to have a label and image set. If they are not set, the label and image of the notification type will be used. The time from java.lang.System.currentTimeMillis initializes the value of the Notification.getTimestamp method.

Parameters:

selectable - true if this Notification must be presented in a way that is selectable by the user. If set to false, the NotificationListener.notificationSelected(javax.microedition.lcdui.Notification) method will not be called for any NotificationListener set on the Notification by (@link setListener}.

Throws:

NotificationException - If the post() call fails, due to too many active notifications.

See Also:

NotificationType

post

public void post(boolean selectable,
                 int duration)

Posts the Notification with a set limit on how long it should be available. Notifications are not required to have a label and image set. If they are not set, the label and image of the notification type will be used. The time from java.lang.System.currentTimeMillis initializes the value of the Notification.getTimestamp method.

Parameters:

selectable - true if this Notification must be presented in a way that is selectable by the user. If set to false, the NotificationListener.notificationSelected(javax.microedition.lcdui.Notification) method will not be called for any NotificationListener set on the Notification by (@link setListener}.

duration - the duration of the notification (in milliseconds)

Throws:

NotificationException - If the post() call fails, due to too many active notifications.

java.lang.IllegalArgumentException - If duration is not a positive integer.

See Also:

NotificationType

remove

public void remove()

Removes the Notification.

Throws:

NotificationException - If the Notification could not be removed.

java.lang.IllegalStateException - If the Notification is already in the removed state.

getTimestamp

public long getTimestamp()

Gets the time when the Notification was last posted. The time is in the same format as java.lang.System.currentTimeMillis.

Returns:

the time when the Notification was last posted. If the Notification has not been posted, zero is returned.