/*

* 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;

}