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., vibrator, screen (LCD) backlight, and screen saver appearance.

This class is thread safe.

Since:

1.0

Method Summary

static void	flashLights(long duration) Does flashing lights effect for specific duration.
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 lights on the device; the function can also be used for preventing screen saver appearance.
static void	startVibra(int freq, long duration) Activates the vibra device with given duration and frequency.
static void	stopVibra() Stops the vibra device.

Methods inherited from class java.lang.Object

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

Method Detail

getUserInactivityTime

public static int getUserInactivityTime()

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

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

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

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

flashLights

public static void flashLights(long duration)

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.

Parameters:

duration - duration in milliseconds 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 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.

Parameters:

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.

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.

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

Since:

1.0

stopVibra

public static void stopVibra()

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

Since:

1.0