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 methods to control some of the special features available in mobile devices, e.g., vibration, screen (LCD) backlight, and screen saver appearance.

This class is thread safe.

Since:

1.0

Method Summary

static void	flashLights(long duration) Temporarily flashes the lights for a specific length of time given as milliseconds in duration parameter.
static void	setLights(int num, int level) Activates and deactivates the lights on the device; the function can also be used for preventing screen saver appearance.
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 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 value is specified: num value 0 is used for controlling the screen backlight. Parameter level is a value between 0-100, which indicates the brightness of the light. In many implementations, there are only two levels: on or off. Value 0 indicates lights off for monochrome displays or the minimum brightness setting for color displays. All other level values (1-100) are used for turning the lights on, possibly with different brightness levels, depending on the value. A larger value always results in either the same brightness setting as a lower one, or a brighter setting. For many products, 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).

Parameters:

num - is the number or id for light, 0 is used for display backlight, other numbers are currently left unspecified.

level - the lighting level 0-100. 0 means "off" or some other minimum lighting setting. For many devices, a value greater than 0 means "light on".

Throws:

java.lang.IllegalArgumentException - if light num is not supported or level is not between 0-100.

Since:

1.0

flashLights

public static void flashLights(long duration)

Temporarily 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.

This is a generic method for implementing a specific light flashing effect. This could be used as feedback in games, etc. If the device is not capable of handling the effect, the method call silently returns. In most devices, there is at least a screen backlight and different LEDs that could be used for the effect. There might be a maximum limit for the length of time: the effect automatically stops after a maximum length of time has been reached. When the flashing lights effect ends, the implementation sets the lights back to the proper light state. For example, if setLights is called during the lighting for light num with which the flashing effect is created the lights will return to this this value after flashing effect ends. The light flashing effect can be stopped by calling the method again with duration value 0.

Parameters:

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

Throws:

java.lang.IllegalArgumentException - if duration < 0

Since:

1.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. Vibration feedback can be used, for example, as a tactile feedback effect in games. The frequency of the vibration can be controlled with the freq parameter. The frequency is a logical number between 0 and 100, 100 being the maximum frequency. No vibra is always 0, 1 should always have some effect. If a device does not support different frequencies, the frequency that is allowed the by device is used.

The parameter duration is used to indicate the length of time of the vibration in milliseconds. The method will not block for vibration. There is a maximum limit in the implementation for the length of time. Duration values that exceed this limit result in a maximum vibration effect.

If the 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 call 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.

Since:

1.0

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