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).
+ * 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.
+ * + *Soft notifications can be displayed for the user in two different appearances: + *
+ * 
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
+ * {@link #setText(String text, String groupText)}
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: + *
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: + *
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, + * {@link 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.
+ * + * + *
+ *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;
+ * }
+ * }
+ */
+public abstract class SoftNotification
+{
+
+ /**
+ * Hidden default constructor.
+ *
+ * @see #newInstance()
+ * @see #newInstance(int notificationId)
+ */
+ protected SoftNotification()
+ {
+ }
+
+ /**
+ * 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 + * {@link #newInstance()}.
+ * + * @param notificationId Identification of previous soft notification. + * @return An instance of SoftNotification class. + * @see #getId() + */ + public static SoftNotification newInstance(int notificationId) + { + return new SoftNotificationImpl(notificationId); + } + + /** + *Returns a new instance of SoftNotification class. This instance's + * identification will be a nonvalid negative value until + * {@link #post()} is called.
+ * + * @return an instance of SoftNotification class. + */ + public static SoftNotification newInstance() + { + return new SoftNotificationImpl(); + } + + /** + *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 {@link #post()} is called.
+ * + * @return Soft notification identification. + * @see #newInstance(int notificationId) + */ + public abstract int getId(); + + /** + *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 {@link #getId()} function.
+ * + * @throws SoftNotificationException Thrown if posting operation fails. + */ + public abstract void post() 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. + */ + public abstract void remove() throws SoftNotificationException; + + /** + *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.
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 {@link #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 {@link #post()} is called.
+ * + * @param text A text to be displayed in the soft notification when ungrouped + * soft notification is shown. + * @param 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 ifnull or an empty string
+ * ("") is used.
+ *
+ * @throws SoftNotificationException Thrown if setting text fails.
+ */
+ public abstract void setText(String text, String groupText)
+ 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 {@link #post()} is called.
+ * + * @param softkey1Label Text for the softkey 1. + * @param softkey2Label Text for the softkey 2. + * + * @throws SoftNotificationException Thrown if setting softkeys fails. + */ + public abstract void setSoftkeyLabels(String softkey1Label, String softkey2Label) + 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 {@link #post()} is called.
+ * + * @param 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.
+ */
+ public abstract void setImage(byte[] image) throws SoftNotificationException;
+
+}