1 /*

     2 * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Public interface of the GlobalIndicator API.

    15  *

    16 */

    17 

    18 package com.nokia.mid.ui;

    19 

    20 import com.nokia.mj.impl.nokiauiapi.GlobalIndicatorsImpl;

    21 

    22 /**

    23  * The <code>GlobalIndicators</code> is a class to handle the device global

    24  * indicators. Global indicators are small icons that appear to the device

    25  * status indicator area indicating for example the arrival of a new email or

    26  * chat message. These indicators remain in the status indicator area even if

    27  * the midlet is closed but rebooting the device will remove them, so the

    28  * indicators are not fully persistent.<P>

    29  *

    30  * These global indicators are common and also used by the native applications.

    31  * This means that at any time it is possible for any application to turn an

    32  * indicator on or off. For that reason it is good practice to query the state

    33  * of the indicator before setting the value.<P>

    34  *

    35  * There are also other indicators besides these <code>MAIL_INDICATOR</code> or

    36  * <code>CHAT_INDICATOR</code> defined in this API. GlobalIndicators API allows

    37  * to access those indicators too but the exact values of both the indicator and

    38  * its value need to be given as accurate integer parameters (as some of those

    39  * more complex indicators support a larger range of input parameters than just

    40  * <code>INDICATOR_HIDE</code> or <code>INDICATOR_SHOW</code>).<P>

    41  *

    42  * Example of API usage:<P>

    43  * <code>

    44  * int retVal = GlobalIndicators.getGlobalIndicator(<BR>

    45  * &nbsp;&nbsp;&nbsp;&nbsp;GlobalIndicators.MAIL_INDICATOR);<P>

    46  * if(retVal != GlobalIndicators.INDICATOR_SHOW)<BR>

    47  * &nbsp;&nbsp;&nbsp;&nbsp;{<BR>

    48  * &nbsp;&nbsp;&nbsp;&nbsp;retVal = GlobalIndicators.setGlobalIndicator(<BR>

    49  * &nbsp;&nbsp;&nbsp;&nbsp&nbsp;&nbsp;&nbsp;&nbsp;GlobalIndicators.MAIL_INDICATOR,<BR>

    50  * &nbsp;&nbsp;&nbsp;&nbsp&nbsp;&nbsp;&nbsp;&nbsp;GlobalIndicators.INDICATOR_SHOW);<BR>

    51  *     }

    52  * </code>

    53  */

    54 public final class GlobalIndicators

    55 {

    56 

    57     private static GlobalIndicatorsImpl sInstance;

    58 

    59     static

    60     {

    61         sInstance = GlobalIndicatorsImpl.getInstance();

    62     }

    63 

    64     /**

    65      * A constant for email indicator.

    66      */

    67     public static final int MAIL_INDICATOR = 274;

    68 

    69     /**

    70      * A constant for chat message indicator.

    71      */

    72     public static final int CHAT_INDICATOR = 260;

    73 

    74     /**

    75      * A constant for indicator's default value uninitialized.

    76      */

    77     public static final int INDICATOR_UNINITIALIZED = 0;

    78 

    79     /**

    80      * A constant for indicator's value when the indicator is hidden.

    81      */

    82     public static final int INDICATOR_HIDE = 1;

    83 

    84     /**

    85      * A constant for indicator's value when the indicator is displayed.

    86      */

    87     public static final int INDICATOR_SHOW = 2;

    88 

    89     /**

    90      * Private constructor.

    91      */

    92     private GlobalIndicators()

    93     {

    94     }

    95 

    96     /**

    97      * Sets the value of the given global indicator.

    98      *

    99      * @param indicator <code>MAIL_INDICATOR</code>,

   100      * <code>CHAT_INDICATOR</code> or a specific other indicator given as

   101      * an integer.

   102      *

   103      * @param value the value to set: <code>INDICATOR_SHOW</code>,

   104      * <code>INDICATOR_HIDE</code> or a specific other value given as

   105      * an integer.

   106      *

   107      * @return the value that is currently set for the indicator:

   108      * <code>INDICATOR_UNINITIALIZED</code>, <code>INDICATOR_SHOW</code> or

   109      * <code>INDICATOR_HIDE</code>. For the other specific indicators the

   110      * return value is the integer value that is set for that indicator.

   111      *

   112      * @throws GlobalIndicatorsException if the given indicator or the

   113      * given value is not supported, or there occurs an error while trying to

   114      * access the indicator.

   115      */

   116     public static int setGlobalIndicator(int indicator, int value)

   117     throws GlobalIndicatorsException

   118     {

   119         return sInstance.setGlobalIndicator(indicator, value);

   120     }

   121 

   122     /**

   123      * Gets the value of the given global indicator.

   124      *

   125      * @param indicator <code>MAIL_INDICATOR</code>,

   126      * <code>CHAT_INDICATOR</code> or a specific other indicator given as

   127      * an integer.

   128      *

   129      * @return the value that is currently set for the indicator:

   130      * <code>INDICATOR_UNINITIALIZED</code>, <code>INDICATOR_SHOW</code> or

   131      * <code>INDICATOR_HIDE</code>. For the other specific indicators the

   132      * return value is the integer value that is currently set for that

   133      * indicator.

   134      *

   135      * @throws GlobalIndicatorsException if there occurs an error while trying

   136      * to access the indicator.

   137      */

   138     public static int getGlobalIndicator(int indicator)

   139     throws GlobalIndicatorsException

   140     {

   141         return sInstance.getGlobalIndicator(indicator);

   142     }

   143 }