com.nokia.mid.ui
Class DeviceControl

java.lang.Object
  com.nokia.mid.ui.DeviceControl

public class DeviceControl

extends java.lang.Object

DeviceControl provides a collection of static methods to control device features such as vibra, backlights, and active cover lights.

Method Summary

static void	flashLights(long duration) Flashes the lights for a specific length of time given as milliseconds in duration parameter.
static int	getUserInactivityTime() Function return the time since the last user activity in seconds.
static void	resetUserInactivityTime() Function reset user inactivity time.
static void	setLights(int num, int level) Activates and deactivates the lights on the device.
static void	startVibra(int freq, long duration) Activates vibration for a given length of time and frequency.
static void	stopVibra() Stops any vibration.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setLights

public static void setLights(int num,
                             int level)

Activates and deactivates the lights on the device. Parameter num indicates the number of the device light to control. Currently values 0 and 1 are specified. Num value 0 is used for controlling the screen backlight and value 1 is used for controlling light extensions like active cover or cover lights. Light extensions are not supported by all products. For backlight the parameter level is a value between 0-100, which indicates the brightness of the light. For extension lights, the range of valid values for parameter level depends on the type of lighting extension, and the specific product features.

Parameters:

num - light target. 0 is used for display backlight, and 1 for light extensions like active covers

level - lighting level for backlights target, or sequence number for lighting extension

Throws:

java.lang.IllegalArgumentException - if num or level are not supported.

flashLights

public static void flashLights(long duration)

Flashes the lights for a specific length of time given as milliseconds in duration parameter. If no exception is thrown this method will return immediately and thus will not block the calling thread during the effect.

Parameters:

duration - length of time in milliseconds that the effect should be active

Throws:

java.lang.IllegalArgumentException - if duration < 0

startVibra

public static void startVibra(int freq,
                              long duration)

Activates vibration for a given length of time and frequency. If no exception is thrown this method will return immediately and thus will not block the calling thread during the vibration. The parameter duration is used to indicate the length of time of vibration in milliseconds. The method will not block for vibra. There is a maximum limit in the implementation for the length of time. Duration values that exceed this limit result in maximum vibration effect. If method is called during a previously called vibration that has been activated from this method, the previous vibration is stopped and the new one is activated using the new set of parameters. IllegalStateException will be thrown if freq is not 0 and if the device does not allow vibration; for example, it is common that vibration is not allowed when the device is being recharged in a desk stand or there is an incoming call. IllegalStateException will be thrown if there is no vibration capability in the device. Note that if the frequency is 0, and the device does not have vibration, IllegalStateException is thrown. This means that the method DeviceControl.startVibra(0,0); can be used to detect whether vibration is supported (IllegalStateException not thrown) or not (IllegalStateException thrown) without any vibration occuring even if it is supported.

Parameters:

freq - the frequency of the vibra device. Value 0 can be used for detecting whether or not there is a vibration device. 100 means the maximum frequency value of a specific system. 1 must always result in a minimum non-zero vibration.

duration - the length of time in milliseconds the vibration is active.

Throws:

java.lang.IllegalStateException - For freq values 1-100: the use of vibration is not allowed or the system does not have vibration support. For frequency value 0: the device does not have vibration.

java.lang.IllegalArgumentException - if duration or freq is < 0, or freq is > 100.

stopVibra

public static void stopVibra()

Stops any vibration. This method is for manually stopping the vibration activated with startVibra(int freq, long duration). If vibration is not active, the method silently returns.

Since:

1.0

getUserInactivityTime

public static int getUserInactivityTime()

Function return the time since the last user activity in seconds.

Returns:

the time since the last user activity in seconds. -1 if unsupported.

Since:

1.4

resetUserInactivityTime

public static void resetUserInactivityTime()

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