72
|
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 |
|