+ * DeviceControl provides a collection of methods to control some of the special + * features available in mobile devices, e.g., vibrator, screen (LCD) + * backlight, and screen saver appearance. + *
+ * This class is thread safe. + * @version 1.0 + * @since 1.0 + */ + +public class DeviceControl +{ + // error string for negative duration + private static final String ERR_NEGATIVE_DURATION_STRING = + "Negative duration"; + private static int inactivityTime; + private static int vibraDuration; + private static boolean vibraSupported; + + /** + * Private constructor. This class can't be instantiated. + */ + private DeviceControl() + { + } + /** + * Function return the time since the last user activity in seconds. + * @since 1.4 + */ + public static int getUserInactivityTime() + { + synchronized (DeviceControl.class) + { + if (DisplayExtension.getDisplayInstance() != null) + { + Internal_PackageSupport.getDisplayInstance().syncExec(new Runnable() + { + public void run() + { + inactivityTime = OS.MobileDevice_getUserInactivityTime( + Internal_PackageSupport.initializeMobileDevice( + Internal_PackageSupport.getDisplayInstance())); + } + }); + } + } + return inactivityTime; + } + /** + * Function reset user inactivity time. Thus, if the screen saver should be + * wholly disabled, it is needed to call the function repeatedly for example in a + * separate thread. The delay between two calls should be smaller than + * the time-out of the screensaver (the time-out may be for example 15 seconds + * or more depending on the used device). + * @since 1.4 + */ + public static void resetUserInactivityTime() + { + synchronized (DeviceControl.class) + { + if (DisplayExtension.getDisplayInstance() != null) + { + Internal_PackageSupport.getDisplayInstance().syncExec(new Runnable() + { + public void run() + { + OS.MobileDevice_resetUserInactivityTime( + Internal_PackageSupport.initializeMobileDevice( + Internal_PackageSupport.getDisplayInstance())); + } + }); + } + } + } + + /** + * Activates and deactivates lights on the device; the function + * can also be used for preventing screen saver appearance. Parameter + * num indicates the number of the device light to control. + * Currently only one num parameter is specified: + * num value 0 is used for controlling the screen backlight. + * Parameter level is a value between 0-100 + * indicating the light brightness. In many implementations + * there in only two levels: lights on and off. Value 0 indicates + * a setting for lights off (monochrome displays) or other + * minimum brightness setting (color displays), all other level + * values (1-100) are used for setting the lights on, possibly + * with different brightness levels depending on the value. A more + * higher level value always results either the same brightness setting + * as a lower one, or a more brighter setting. For many products + * passing values 1-100 will just turn the lights on. + *
+ * Note: Since in some devices key presses may turn on some device lights, + * the light settings may be changed also by the system. + *
+ * This function may also be used to prevent screen saver appearance + * (supported in S60 devices starting from S60 3rd Ed FP1, + * except for some early FP1 devices). Calling this function once + * will delay the screen saver appearance but does not disable it permanently. + * Thus, if the screen saver should be wholly disabled, + * it is needed to call the function repeatedly for example in a + * separate thread. The delay between two calls should be smaller than + * the time-out of the screensaver (the time-out may be for example 15 seconds + * or more depending on the used device). + * + * @param num is the number or id for light, 0 is used for display + * backlight, other numbers are currently left unspecified + * @param level the lighting level 0-100. 0 means "off" or other + * minimum lighting setting. For many devices greater + * than 0 value just means "light on". + * @throws java.lang.IllegalArgumentException if light num is not + * supported or level is not between 0-100. + * @since 1.0 + */ + public static void setLights(int aNum, int aLevel) + { + synchronized (DeviceControl.class) + { + if (aNum != 0) + { + throw new IllegalArgumentException("Light num is not supported"); + } + if (aLevel < 0 || aLevel > 100) + { + throw(new IllegalArgumentException("Level not between 0 and 100")); + } + final int level = aLevel; + + if (DisplayExtension.getDisplayInstance() != null) + { + Internal_PackageSupport.getDisplayInstance().syncExec(new Runnable() + { + public void run() + { + OS.MobileDevice_setLight(Internal_PackageSupport.initializeMobileDevice( + Internal_PackageSupport.getDisplayInstance()), level); + } + }); + } + } + } + + /** + * Does flashing lights effect for specific duration. + * This is a generic method for doing implementation specific light + * flashing effect. This could be used as feedback e.g. in games. + * If the device is not capable of doing the effect the method call + * silently returns. In most devices there is at least screen backlight + * and different LEDs that could be used for the effect. There might + * be maximum limit in implementation for the duration: implementation + * stops automatically the effect after maximum duration is reached. + * When the flashing lights effect ends the implementation sets the + * lights back to the light state the device was before the + * method call. + * + * @param duration duration in milliseconds the effect should be + * active + * @throws java.lang.IllegalArgumentException if duration < 0 + * @since 1.0 + */ + public static void flashLights(long aDuration) + { + synchronized (DeviceControl.class) + { + if (aDuration < 0) + { + throw new IllegalArgumentException(ERR_NEGATIVE_DURATION_STRING); + } + + final int duration; + if (aDuration > java.lang.Integer.MAX_VALUE) + { + duration = java.lang.Integer.MAX_VALUE; + } + else + { + duration =(int)aDuration; + } + if (DisplayExtension.getDisplayInstance() != null) + { + Internal_PackageSupport.getDisplayInstance().syncExec(new Runnable() + { + public void run() + { + System.out.println("Java Nokia UI API flashLights duration = "+duration); + OS.MobileDevice_flashLights( + Internal_PackageSupport.initializeMobileDevice( + Internal_PackageSupport.getDisplayInstance()),duration); + System.out.println("Java Nokia UI API End flashLights "); + } + }); + } + } + + } + + /** + * Activates the vibra device with given duration and frequency. + * Device vibra feedback can be used, for example, as tactile feedback + * effect e.g. in games. The frequency of the vibra device + * can be controlled with freq parameter. The frequency is a logical + * number between 0 to 100, value 100 being the maximum frequency, + * value 0 always means no vibra, value 1 always needs to give some + * effect. If a device doesn't support different frequencies then + * the just frequency allowed by device is used. + *
+ * Parameter duration is used to indicate duration of vibra + * in milliseconds. Method won't block for the vibra operation. + * There is some maximum limit in implementation for the + * duration. Duration values that exceed this limit result a + * maximum vibration effect. + *
+ * If the method is called during a previous vibra operation activated + * from this method, the previous vibra operation is stopped and the new + * vibra device is activated with the new given parameters. + *
+ * IllegalStateException will be thrown if the freq is not 0 and + * if device doesn't allow vibra to be used, for example, + * it is common that when the device is being charged in desk stand or + * there is incoming call that vibra operation is not allowed. + * IllegalStateException will be thrown if there + * is no vibra capability in the device. + *
+ * Note that if the frequency is 0, and the device doesn't have vibra
+ * capability IllegalStateException is thrown. This means that method
+ * call DeviceControl.doVibra(0,0); can be used to detect
+ * whether vibra is supported (IllegalStateException not thrown)
+ * or not (IllegalStateException thrown) without any vibra operation
+ * being done even if it is supported.
+ * @param freq the frequency of the vibra device. Value 0 can be used
+ * for detection whether there is vibra device or not. 100 means
+ * maximum frequency value of specific system. Value 1 must always
+ * result a minimum non-zero vibra operation.
+ * @param duration in milliseconds the duration the vibra device is
+ * active
+ * @throws java.lang.IllegalStateException For freq values 1-100:
+ * the use of vibra device isn't allowed or the system doesn't have
+ * vibra device. For frequency value 0: the device doesn't have vibra
+ * device.
+ * @throws java.lang.IllegalArgumentException if duration or freq is
+ * < 0, or freq is > 100.
+ * @since 1.0
+ */
+ public static void startVibra(int aFreq, long aDuration)
+ {
+ synchronized (DeviceControl.class)
+ {
+ if ((aFreq < 0) || (aFreq > 100) || (aDuration < 0))
+ {
+ throw new java.lang.IllegalArgumentException();
+
+ }
+ vibraDuration = (int)aDuration;
+ if (aDuration > java.lang.Integer.MAX_VALUE)
+ {
+ vibraDuration = java.lang.Integer.MAX_VALUE;
+ }
+ if (aFreq == 0)
+ {
+ // frequency 0 disables vibration
+ vibraDuration = 0;
+ }
+ if (DisplayExtension.getDisplayInstance() != null)
+ {
+ Internal_PackageSupport.getDisplayInstance().syncExec(new Runnable()
+ {
+ public void run()
+ {
+ System.out.println("Java Nokia UI API start vibra with duration = "+vibraDuration);
+ vibraSupported = OS.MobileDevice_vibration(
+ Internal_PackageSupport.initializeMobileDevice(
+ Internal_PackageSupport.getDisplayInstance()),vibraDuration);
+ System.out.println("Java Nokia UI API End vibra ");
+ }
+ });
+ }
+ if (!vibraSupported)
+ {
+ throw new java.lang.IllegalStateException();
+ }
+ }
+ }
+
+ /**
+ * Stops the vibra device. This method is for manually stopping vibra
+ * operation activated with
+ * {@link DeviceControl#startVibra(int freq, long duration)}
+ * method.
+ * If the vibra device is not active the method silently returns.
+ * @since 1.0
+ */
+ public static void stopVibra()
+ {
+ synchronized (DeviceControl.class)
+ {
+ if (DisplayExtension.getDisplayInstance() != null)
+ {
+ Internal_PackageSupport.getDisplayInstance().syncExec(new Runnable()
+ {
+ public void run()
+ {
+ vibraSupported = OS.MobileDevice_vibration(
+ Internal_PackageSupport.initializeMobileDevice(
+ Internal_PackageSupport.getDisplayInstance()),0);
+ }
+ });
+ }
+ }
+ }
+
+}
+
+