diff -r 1f0034e370aa -r 71ad690e91f5 javauis/nokiauiapi_qt/javasrc/com/nokia/mid/ui/GlobalIndicators.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/javauis/nokiauiapi_qt/javasrc/com/nokia/mid/ui/GlobalIndicators.java Mon Oct 04 11:29:25 2010 +0300 @@ -0,0 +1,143 @@ +/* +* Copyright (c) 2008 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: Public interface of the GlobalIndicator API. + * +*/ + +package com.nokia.mid.ui; + +import com.nokia.mj.impl.nokiauiapi.GlobalIndicatorsImpl; + +/** + * The GlobalIndicators is a class to handle the device global + * indicators. Global indicators are small icons that appear to the device + * status indicator area indicating for example the arrival of a new email or + * chat message. These indicators remain in the status indicator area even if + * the midlet is closed but rebooting the device will remove them, so the + * indicators are not fully persistent.

+ * + * These global indicators are common and also used by the native applications. + * This means that at any time it is possible for any application to turn an + * indicator on or off. For that reason it is good practice to query the state + * of the indicator before setting the value.

+ * + * There are also other indicators besides these MAIL_INDICATOR or + * CHAT_INDICATOR defined in this API. GlobalIndicators API allows + * to access those indicators too but the exact values of both the indicator and + * its value need to be given as accurate integer parameters (as some of those + * more complex indicators support a larger range of input parameters than just + * INDICATOR_HIDE or INDICATOR_SHOW).

+ * + * Example of API usage:

+ * + * int retVal = GlobalIndicators.getGlobalIndicator(
+ *     GlobalIndicators.MAIL_INDICATOR);

+ * if(retVal != GlobalIndicators.INDICATOR_SHOW)
+ *     {
+ *     retVal = GlobalIndicators.setGlobalIndicator(
+ *         GlobalIndicators.MAIL_INDICATOR,
+ *         GlobalIndicators.INDICATOR_SHOW);
+ *     } + *
+ */ +public final class GlobalIndicators +{ + + private static GlobalIndicatorsImpl sInstance; + + static + { + sInstance = GlobalIndicatorsImpl.getInstance(); + } + + /** + * A constant for email indicator. + */ + public static final int MAIL_INDICATOR = 274; + + /** + * A constant for chat message indicator. + */ + public static final int CHAT_INDICATOR = 260; + + /** + * A constant for indicator's default value uninitialized. + */ + public static final int INDICATOR_UNINITIALIZED = 0; + + /** + * A constant for indicator's value when the indicator is hidden. + */ + public static final int INDICATOR_HIDE = 1; + + /** + * A constant for indicator's value when the indicator is displayed. + */ + public static final int INDICATOR_SHOW = 2; + + /** + * Private constructor. + */ + private GlobalIndicators() + { + } + + /** + * Sets the value of the given global indicator. + * + * @param indicator MAIL_INDICATOR, + * CHAT_INDICATOR or a specific other indicator given as + * an integer. + * + * @param value the value to set: INDICATOR_SHOW, + * INDICATOR_HIDE or a specific other value given as + * an integer. + * + * @return the value that is currently set for the indicator: + * INDICATOR_UNINITIALIZED, INDICATOR_SHOW or + * INDICATOR_HIDE. For the other specific indicators the + * return value is the integer value that is set for that indicator. + * + * @throws GlobalIndicatorsException if the given indicator or the + * given value is not supported, or there occurs an error while trying to + * access the indicator. + */ + public static int setGlobalIndicator(int indicator, int value) + throws GlobalIndicatorsException + { + return sInstance.setGlobalIndicator(indicator, value); + } + + /** + * Gets the value of the given global indicator. + * + * @param indicator MAIL_INDICATOR, + * CHAT_INDICATOR or a specific other indicator given as + * an integer. + * + * @return the value that is currently set for the indicator: + * INDICATOR_UNINITIALIZED, INDICATOR_SHOW or + * INDICATOR_HIDE. For the other specific indicators the + * return value is the integer value that is currently set for that + * indicator. + * + * @throws GlobalIndicatorsException if there occurs an error while trying + * to access the indicator. + */ + public static int getGlobalIndicator(int indicator) + throws GlobalIndicatorsException + { + return sInstance.getGlobalIndicator(indicator); + } +}