--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/javauis/nokiauiapi_qt/javasrc/com/nokia/mid/ui/SoftNotification.java Mon Oct 04 00:10:53 2010 +0300
@@ -0,0 +1,339 @@
+/*
+* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description:
+*
+*/
+
+package com.nokia.mid.ui;
+
+
+/**
+ * <p>The <code>SoftNotification</code> 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.</p>
+ *
+ * <p>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.</p>
+ *
+ * <p>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.</p>
+ *
+ * <h3>Grouping soft notifications</h3>
+ *
+ * <p>Soft notifications can be displayed for the user in two different appearances:
+ * <li> <b>Ungrouped</b> soft notification (left figure): 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.
+ * <li> <b>Grouped</b> soft notification (right figure): 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.</p>
+ *
+ * <p><img src="images/ungrouped.jpg" alt="Image of ungrouped soft notification.">
+ * <img src="images/grouped.jpg" alt="Image of grouped soft notification."></p>
+ *
+ * <p>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 <code>groupText</code> is given in
+ * {@link #setText(String text, String groupText)}</p>
+ *
+ * <h3>Persistent notifications</h3>
+ * <p>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:
+ * <li>User accepts the notification,
+ * <li>User dismisses the notification, or
+ * <li>Application removes the notification</p>
+ *
+ * <p>A soft notification stays on the device home screen even if the application
+ * is closed or the device is restarted.</p>
+ *
+ * <p>Accepting (selecting) a soft notification created by an application causes
+ * this application to be activated in the following ways:
+ * <li>If the application was running on the background, it will be set to
+ * the foreground.
+ * <li>If the application was running and had registered a listener
+ * for the notification,
+ * {@link SoftNotificationListener#notificationSelected(SoftNotification)}
+ * is called.
+ * <li>If the application is not running, it will be started and set to the
+ * foreground.</p>
+ *
+ * <p><b>Notice</b> 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.</p>
+ *
+ * <p>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.</p>
+ *
+ * <p>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.</p>
+ *
+ * <p><b>Notice</b> 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.</p>
+ *
+ *
+ * <h3>Example of usage</h3>
+ *
+ * <code style="white-space: pre">
+ *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;
+ * }
+ * }</code>
+ */
+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.
+ *
+ * <p>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()}.</p>
+ *
+ * @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);
+ }
+
+ /**
+ * <p>Returns a new instance of SoftNotification class. This instance's
+ * identification will be a nonvalid negative value until
+ * {@link #post()} is called.</p>
+ *
+ * @return an instance of SoftNotification class.
+ */
+ public static SoftNotification newInstance()
+ {
+ return new SoftNotificationImpl();
+ }
+
+ /**
+ * <p>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.</p>
+ *
+ * <p><b>Notice</b> that identification might change during the lifetime of the
+ * instance if {@link #post()} is called.</p>
+ *
+ * @return Soft notification identification.
+ * @see #newInstance(int notificationId)
+ */
+ public abstract int getId();
+
+ /**
+ * <p>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.</p>
+ *
+ * <p><b>Notice</b> 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.</p>
+ *
+ * @throws SoftNotificationException Thrown if posting operation fails.
+ */
+ public abstract void post() throws SoftNotificationException;
+
+ /**
+ * <p>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.</p>
+ *
+ * @throws SoftNotificationException Thrown if removing the note fails.
+ */
+ public abstract void remove() throws SoftNotificationException;
+
+ /**
+ * <p>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
+ * <code>null</code>.</p>
+ *
+ * @param listener Listener for the soft notification.
+ */
+ public abstract void setListener(SoftNotificationListener listener);
+
+ /**
+ * <p>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 <code>'\n'</code>) inside the string.</p>
+ *
+ * <p>A notification supports grouping if <code>groupText</code> is
+ * other than <code>null</code> or an empty string (<code>""</code>).</p>
+ *
+ * <p><b>Notice</b> that the modified soft notification data is not visible for
+ * the user until {@link #post()} is called.</p>
+ *
+ * @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 if <code>null</code> or an empty string
+ * (<code>""</code>) is used.
+ *
+ * @throws SoftNotificationException Thrown if setting text fails.
+ */
+ public abstract void setText(String text, String groupText)
+ throws SoftNotificationException;
+
+ /**
+ * <p>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).</p>
+ *
+ * <p>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.</p>
+ *
+ * <p><b>Notice</b> that the modified soft notification data is not visible for
+ * the user until {@link #post()} is called.</p>
+ *
+ * @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;
+
+ /**
+ * <p>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. </p>
+ *
+ * <p>The image is given as a byte array, for example the data may be read directly
+ * from the file system or MIDlet JAR package.</p>
+ *
+ * <p>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).</p>
+ *
+ * <p>The function can also be used for removing an already set image from
+ * the soft notification. This can be done by setting <code>null</code> instead
+ * of any actual image.</p>
+ *
+ * <p><b>Notice</b> that the modified soft notification data is not visible for
+ * the user until {@link #post()} is called.</p>
+ *
+ * @param image image to be displayed in the soft notification or
+ * <code>null</code> 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;
+
+}