- * 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() - { - OS.MobileDevice_flashLights( - Internal_PackageSupport.initializeMobileDevice( - Internal_PackageSupport.getDisplayInstance()),duration); - } - }); - } - } - - } - - /** - * 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()
- {
- vibraSupported = OS.MobileDevice_vibration(
- Internal_PackageSupport.initializeMobileDevice(
- Internal_PackageSupport.getDisplayInstance()),vibraDuration);
- }
- });
- }
- 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);
- }
- });
- }
- }
- }
-
-}
-
-