|
1 /* |
|
2 * Copyright (c) 2006-2007 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: Provides methods for controlling vibrator and screen backlight. |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 package com.nokia.mid.ui; |
|
20 |
|
21 import org.eclipse.swt.internal.qt.OS; |
|
22 import org.eclipse.swt.widgets.Internal_PackageSupport; |
|
23 import org.eclipse.swt.internal.extension.DisplayExtension; |
|
24 |
|
25 /** |
|
26 * <p> |
|
27 * DeviceControl provides a collection of methods to control some of the special |
|
28 * features available in mobile devices, e.g., vibrator, screen (LCD) |
|
29 * backlight, and screen saver appearance. |
|
30 * <p> |
|
31 * This class is thread safe. |
|
32 * @version 1.0 |
|
33 * @since 1.0 |
|
34 */ |
|
35 |
|
36 public class DeviceControl |
|
37 { |
|
38 // error string for negative duration |
|
39 private static final String ERR_NEGATIVE_DURATION_STRING = |
|
40 "Negative duration"; |
|
41 private static int inactivityTime; |
|
42 private static int vibraDuration; |
|
43 private static boolean vibraSupported; |
|
44 |
|
45 /** |
|
46 * Private constructor. This class can't be instantiated. |
|
47 */ |
|
48 private DeviceControl() |
|
49 { |
|
50 } |
|
51 /** |
|
52 * Function return the time since the last user activity in seconds. |
|
53 * @since 1.4 |
|
54 */ |
|
55 public static int getUserInactivityTime() |
|
56 { |
|
57 synchronized (DeviceControl.class) |
|
58 { |
|
59 if (DisplayExtension.getDisplayInstance() != null) |
|
60 { |
|
61 Internal_PackageSupport.getDisplayInstance().syncExec(new Runnable() |
|
62 { |
|
63 public void run() |
|
64 { |
|
65 inactivityTime = OS.MobileDevice_getUserInactivityTime( |
|
66 Internal_PackageSupport.initializeMobileDevice( |
|
67 Internal_PackageSupport.getDisplayInstance())); |
|
68 } |
|
69 }); |
|
70 } |
|
71 } |
|
72 return inactivityTime; |
|
73 } |
|
74 /** |
|
75 * Function reset user inactivity time. Thus, if the screen saver should be |
|
76 * wholly disabled, it is needed to call the function repeatedly for example in a |
|
77 * separate thread. The delay between two calls should be smaller than |
|
78 * the time-out of the screensaver (the time-out may be for example 15 seconds |
|
79 * or more depending on the used device). |
|
80 * @since 1.4 |
|
81 */ |
|
82 public static void resetUserInactivityTime() |
|
83 { |
|
84 synchronized (DeviceControl.class) |
|
85 { |
|
86 if (DisplayExtension.getDisplayInstance() != null) |
|
87 { |
|
88 Internal_PackageSupport.getDisplayInstance().syncExec(new Runnable() |
|
89 { |
|
90 public void run() |
|
91 { |
|
92 OS.MobileDevice_resetUserInactivityTime( |
|
93 Internal_PackageSupport.initializeMobileDevice( |
|
94 Internal_PackageSupport.getDisplayInstance())); |
|
95 } |
|
96 }); |
|
97 } |
|
98 } |
|
99 } |
|
100 |
|
101 /** |
|
102 * Activates and deactivates lights on the device; the function |
|
103 * can also be used for preventing screen saver appearance. Parameter |
|
104 * num indicates the number of the device light to control. |
|
105 * Currently only one num parameter is specified: |
|
106 * num value 0 is used for controlling the screen backlight. |
|
107 * Parameter level is a value between 0-100 |
|
108 * indicating the light brightness. In many implementations |
|
109 * there in only two levels: lights on and off. Value 0 indicates |
|
110 * a setting for lights off (monochrome displays) or other |
|
111 * minimum brightness setting (color displays), all other level |
|
112 * values (1-100) are used for setting the lights on, possibly |
|
113 * with different brightness levels depending on the value. A more |
|
114 * higher level value always results either the same brightness setting |
|
115 * as a lower one, or a more brighter setting. For many products |
|
116 * passing values 1-100 will just turn the lights on. |
|
117 * <p> |
|
118 * Note: Since in some devices key presses may turn on some device lights, |
|
119 * the light settings may be changed also by the system. |
|
120 * <p> |
|
121 * This function may also be used to prevent screen saver appearance |
|
122 * (supported in S60 devices starting from S60 3rd Ed FP1, |
|
123 * except for some early FP1 devices). Calling this function once |
|
124 * will delay the screen saver appearance but does not disable it permanently. |
|
125 * Thus, if the screen saver should be wholly disabled, |
|
126 * it is needed to call the function repeatedly for example in a |
|
127 * separate thread. The delay between two calls should be smaller than |
|
128 * the time-out of the screensaver (the time-out may be for example 15 seconds |
|
129 * or more depending on the used device). |
|
130 * |
|
131 * @param num is the number or id for light, 0 is used for display |
|
132 * backlight, other numbers are currently left unspecified |
|
133 * @param level the lighting level 0-100. 0 means "off" or other |
|
134 * minimum lighting setting. For many devices greater |
|
135 * than 0 value just means "light on". |
|
136 * @throws java.lang.IllegalArgumentException if light num is not |
|
137 * supported or level is not between 0-100. |
|
138 * @since 1.0 |
|
139 */ |
|
140 public static void setLights(int aNum, int aLevel) |
|
141 { |
|
142 synchronized (DeviceControl.class) |
|
143 { |
|
144 if (aNum != 0) |
|
145 { |
|
146 throw new IllegalArgumentException("Light num is not supported"); |
|
147 } |
|
148 if (aLevel < 0 || aLevel > 100) |
|
149 { |
|
150 throw(new IllegalArgumentException("Level not between 0 and 100")); |
|
151 } |
|
152 final int level = aLevel; |
|
153 |
|
154 if (DisplayExtension.getDisplayInstance() != null) |
|
155 { |
|
156 Internal_PackageSupport.getDisplayInstance().syncExec(new Runnable() |
|
157 { |
|
158 public void run() |
|
159 { |
|
160 OS.MobileDevice_setLight(Internal_PackageSupport.initializeMobileDevice( |
|
161 Internal_PackageSupport.getDisplayInstance()), level); |
|
162 } |
|
163 }); |
|
164 } |
|
165 } |
|
166 } |
|
167 |
|
168 /** |
|
169 * Does flashing lights effect for specific duration. |
|
170 * This is a generic method for doing implementation specific light |
|
171 * flashing effect. This could be used as feedback e.g. in games. |
|
172 * If the device is not capable of doing the effect the method call |
|
173 * silently returns. In most devices there is at least screen backlight |
|
174 * and different LEDs that could be used for the effect. There might |
|
175 * be maximum limit in implementation for the duration: implementation |
|
176 * stops automatically the effect after maximum duration is reached. |
|
177 * When the flashing lights effect ends the implementation sets the |
|
178 * lights back to the light state the device was before the |
|
179 * method call. |
|
180 * |
|
181 * @param duration duration in milliseconds the effect should be |
|
182 * active |
|
183 * @throws java.lang.IllegalArgumentException if duration < 0 |
|
184 * @since 1.0 |
|
185 */ |
|
186 public static void flashLights(long aDuration) |
|
187 { |
|
188 synchronized (DeviceControl.class) |
|
189 { |
|
190 if (aDuration < 0) |
|
191 { |
|
192 throw new IllegalArgumentException(ERR_NEGATIVE_DURATION_STRING); |
|
193 } |
|
194 |
|
195 final int duration; |
|
196 if (aDuration > java.lang.Integer.MAX_VALUE) |
|
197 { |
|
198 duration = java.lang.Integer.MAX_VALUE; |
|
199 } |
|
200 else |
|
201 { |
|
202 duration =(int)aDuration; |
|
203 } |
|
204 if (DisplayExtension.getDisplayInstance() != null) |
|
205 { |
|
206 Internal_PackageSupport.getDisplayInstance().syncExec(new Runnable() |
|
207 { |
|
208 public void run() |
|
209 { |
|
210 System.out.println("Java Nokia UI API flashLights duration = "+duration); |
|
211 OS.MobileDevice_flashLights( |
|
212 Internal_PackageSupport.initializeMobileDevice( |
|
213 Internal_PackageSupport.getDisplayInstance()),duration); |
|
214 System.out.println("Java Nokia UI API End flashLights "); |
|
215 } |
|
216 }); |
|
217 } |
|
218 } |
|
219 |
|
220 } |
|
221 |
|
222 /** |
|
223 * Activates the vibra device with given duration and frequency. |
|
224 * Device vibra feedback can be used, for example, as tactile feedback |
|
225 * effect e.g. in games. The frequency of the vibra device |
|
226 * can be controlled with freq parameter. The frequency is a logical |
|
227 * number between 0 to 100, value 100 being the maximum frequency, |
|
228 * value 0 always means no vibra, value 1 always needs to give some |
|
229 * effect. If a device doesn't support different frequencies then |
|
230 * the just frequency allowed by device is used. |
|
231 * <p> |
|
232 * Parameter duration is used to indicate duration of vibra |
|
233 * in milliseconds. Method won't block for the vibra operation. |
|
234 * There is some maximum limit in implementation for the |
|
235 * duration. Duration values that exceed this limit result a |
|
236 * maximum vibration effect. |
|
237 * <p> |
|
238 * If the method is called during a previous vibra operation activated |
|
239 * from this method, the previous vibra operation is stopped and the new |
|
240 * vibra device is activated with the new given parameters. |
|
241 * <p> |
|
242 * IllegalStateException will be thrown if the freq is not 0 and |
|
243 * if device doesn't allow vibra to be used, for example, |
|
244 * it is common that when the device is being charged in desk stand or |
|
245 * there is incoming call that vibra operation is not allowed. |
|
246 * IllegalStateException will be thrown if there |
|
247 * is no vibra capability in the device. |
|
248 * <p> |
|
249 * Note that if the frequency is 0, and the device doesn't have vibra |
|
250 * capability IllegalStateException is thrown. This means that method |
|
251 * call <code>DeviceControl.doVibra(0,0);</code> can be used to detect |
|
252 * whether vibra is supported (IllegalStateException not thrown) |
|
253 * or not (IllegalStateException thrown) without any vibra operation |
|
254 * being done even if it is supported. |
|
255 * @param freq the frequency of the vibra device. Value 0 can be used |
|
256 * for detection whether there is vibra device or not. 100 means |
|
257 * maximum frequency value of specific system. Value 1 must always |
|
258 * result a minimum non-zero vibra operation. |
|
259 * @param duration in milliseconds the duration the vibra device is |
|
260 * active |
|
261 * @throws java.lang.IllegalStateException For freq values 1-100: |
|
262 * the use of vibra device isn't allowed or the system doesn't have |
|
263 * vibra device. For frequency value 0: the device doesn't have vibra |
|
264 * device. |
|
265 * @throws java.lang.IllegalArgumentException if duration or freq is |
|
266 * < 0, or freq is > 100. |
|
267 * @since 1.0 |
|
268 */ |
|
269 public static void startVibra(int aFreq, long aDuration) |
|
270 { |
|
271 synchronized (DeviceControl.class) |
|
272 { |
|
273 if ((aFreq < 0) || (aFreq > 100) || (aDuration < 0)) |
|
274 { |
|
275 throw new java.lang.IllegalArgumentException(); |
|
276 |
|
277 } |
|
278 vibraDuration = (int)aDuration; |
|
279 if (aDuration > java.lang.Integer.MAX_VALUE) |
|
280 { |
|
281 vibraDuration = java.lang.Integer.MAX_VALUE; |
|
282 } |
|
283 if (aFreq == 0) |
|
284 { |
|
285 // frequency 0 disables vibration |
|
286 vibraDuration = 0; |
|
287 } |
|
288 if (DisplayExtension.getDisplayInstance() != null) |
|
289 { |
|
290 Internal_PackageSupport.getDisplayInstance().syncExec(new Runnable() |
|
291 { |
|
292 public void run() |
|
293 { |
|
294 System.out.println("Java Nokia UI API start vibra with duration = "+vibraDuration); |
|
295 vibraSupported = OS.MobileDevice_vibration( |
|
296 Internal_PackageSupport.initializeMobileDevice( |
|
297 Internal_PackageSupport.getDisplayInstance()),vibraDuration); |
|
298 System.out.println("Java Nokia UI API End vibra "); |
|
299 } |
|
300 }); |
|
301 } |
|
302 if (!vibraSupported) |
|
303 { |
|
304 throw new java.lang.IllegalStateException(); |
|
305 } |
|
306 } |
|
307 } |
|
308 |
|
309 /** |
|
310 * Stops the vibra device. This method is for manually stopping vibra |
|
311 * operation activated with |
|
312 * {@link DeviceControl#startVibra(int freq, long duration)} |
|
313 * method. |
|
314 * If the vibra device is not active the method silently returns. |
|
315 * @since 1.0 |
|
316 */ |
|
317 public static void stopVibra() |
|
318 { |
|
319 synchronized (DeviceControl.class) |
|
320 { |
|
321 if (DisplayExtension.getDisplayInstance() != null) |
|
322 { |
|
323 Internal_PackageSupport.getDisplayInstance().syncExec(new Runnable() |
|
324 { |
|
325 public void run() |
|
326 { |
|
327 vibraSupported = OS.MobileDevice_vibration( |
|
328 Internal_PackageSupport.initializeMobileDevice( |
|
329 Internal_PackageSupport.getDisplayInstance()),0); |
|
330 } |
|
331 }); |
|
332 } |
|
333 } |
|
334 } |
|
335 |
|
336 } |
|
337 |
|
338 |