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.globalindicators.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 * GlobalIndicators.MAIL_INDICATOR);<P> |
|
46 * if(retVal != GlobalIndicators.INDICATOR_SHOW)<BR> |
|
47 * {<BR> |
|
48 * retVal = GlobalIndicators.setGlobalIndicator(<BR> |
|
49 *   GlobalIndicators.MAIL_INDICATOR,<BR> |
|
50 *   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 } |
|