com.vodafone.v10.system.device
Class DeviceControl

java.lang.Object
  |
  +--com.vodafone.v10.system.device.DeviceControl

public class DeviceControl

extends java.lang.Object

The DeviceControl class provides functionality to control features specific to the device. These functions include the following:

• Getting information on key pressed state, remaining battery capacity, field intensity, etc.
• LCD backlight control
• Vibrator control
• Key auto-repeat control
• Getting location information as detected in the handset
• Registering listeners for events such as incoming voice calls, ringing interruption, mail arrival, and scheduled alarms.

Use the DeviceControl class static method getDefaultDeviceControl() to get DeviceControl objects. Each of the functions provided by the DeviceControl class is explained below.

• 1. Device state acquisition
• 2. LCD backlight control
• 3. Vibrator control
• 4. Key auto-repeat setting
• 5. Eight-direction key state acquisition
• 6. Listener registration

1. Device State Acquisition

The getDeviceState() method is used to get a device state. A parameter is designated in the getDeviceState() method identifying the type of information to be acquired. The parameters that can be designated and the acquired state information are summarized in the table below.

Table 1. Information Acquired by getDeviceState()

Parameter
Information returned by getDeviceState(int)
DeviceControl.BATTERY	Remaining battery capacity (�“)
DeviceControl.FIELD_INTENSITY	Field intensity as detected by the handset(�“)
DeviceControl.KEY_STATE	Value of bit allocated to each key. If pressed, the key's bit is 1. Can be used to detect overlapping key operations, etc.

2. LCD Backlight Control

LCD backlight control can be performed either by turning the backlight on with the setDeviceActive() method or by blinking it with the blink() method.

• When the setDeviceActive() method is used, DeviceControl.BACK_LIGHT is designated in the deviceNo parameter. The active parameter in this method is then set to true to turn the backlight on, or to false to return to the device setting state.

• Parameters are designated with the blink() method to set the length of on and off blinking intervals and number of repetitions. After the blink() method is called to start blinking, do not call this method again until blinking stops, else an IllegalStateException exception will be thrown. If blinking has been started with the blink() method and the setDeviceActive() method for LCD control has been called, only after blinking set by the blink() method has stopped will the setting by the setDeviceActive() method take effect.

3. Vibrator Control

The handset vibrator is controlled by designating DeviceControl.VIBRATION as the deviceNo parameter of the setDeviceActive() method. The vibrator is activated by setting the active parameter in this method to true, and is stopped by setting it to false.

4. Key Auto-Repeat Setting

The setKeyRepeatState() method is used to designate whether an auto-repeat event is to be issued for individual keys. Use the key codes specified for the Canvas class to designate keys. The getKeyRepeatState() method is called to check the auto-repeat setting for individual keys.

5. Eight-Direction Key State Acquisition

By setting the deviceNo parameter of the setDeviceActive() method to EIGHT_DIRECTIONS and the active parameter to true or false, "eight-direction key state acquisition" can be turned on or off. When "eight-direction key state acquisition" is on and KEY_STATE is designated in the getDeviceState() method, the bits corresponding to cursor keys in all eight directions, including diagonal (Upper Right, Upper Left, Lower Left and Lower Right keys), are valid in the obtained key states. When "eight-direction key state acquisition" is off, only the Up, Down, Left, and Right cursor key states are valid.

In the initial state, "eight-direction key state acquisition" is off.

When "Eight-Direction Key State Acquisition" Is On

Handset not equipped with diagonal cursor keys

getDeviceState(KEY_STATE) reports key states based on combinations of Up, Down, Left, and Right keys, as in Table 2.
s

Table 2. Synthesis of Diagonal Key States

Pressed keys	Pressed keys as returned by getDeviceState()
Right, Up	Upper Right
Up, Left	Upper Left
Left, Down	Lower Left
Down, Right	Lower Right
Right, Up, Left	Upper Right, Upper Left
Up, Left, Down	Upper Left, Lower Left
Left, Down, Right	Lower Left, Lower Right
Down, Right, Up	Lower Right, Upper Right
Right, Up, Left, Down	Upper Right, Upper Left, Lower Left, Lower Right

Which of the above combinations are physically possible depends on the handset.

Handset equipped with diagonal cursor keys

The actual key states are reported.

When "Eight-Direction Key State Acquisition" Is Off

Handset not equipped with diagonal cursor keys

The actual key states are reported. Diagonal cursor keys are always reported in getDeviceState(KEY_STATE) as not pressed.

Handset equipped with diagonal cursor keys

Diagonal cursor key input is interpreted as Up-Down-Left-Right key input.
If, for example, the Upper Right key is pressed, then in the key states reported in getDeviceState(KEY_STATE), bit 1 is raised for the Up key and Right key, but the Upper Right key bit is 0.
If both a diagonal cursor key and another Up-Down-Left-Right key are pressed, the two key components of the diagonal cursor key are reported as being pressed, as well as the actually pressed Up-Down-Left-Right key. For example, suppose the Upper Right key, Up key, and Upper Left are all pressed. The Left key, Up key, and Right key bits will be raised to 1, while the Upper Right key and Upper Left key bits will be 0.

Key Event Acquisition and Eight-Direction Key State Acquisition

The Canvas subclass keyPressed() method and keyReleased() method can receive direction keys only in the four directions LEFT, RIGHT, UP, and DOWN. Diagonal cursor key pressed events are not notified. To enable detection of diagonal cursor key events, the DeviceControl class setDeviceActive() method must be called setting "eight-direction key state acquisition" to On. Then, whenever a change is detected in any of the LEFT, RIGHT, UP, or DOWN keys with keyPressed() or keyReleased(), use the DeviceControl class getDeviceState(KEY_STATE) to check the state of diagonal cursor keys.

6. Listener Registration

The DeviceControl class has methods for setting listeners for the various events specific to the handset. The provided methods are listed in the table below. With each method, events are notified to the most recently registered listener.

Table 3. Methods for Registering Event Listeners

Method
Function
setMailListener()	Registers a listener implementing the MailListener interface to wait for mail arrival, etc.
setScheduledAlarmListener()	Registers a listener implementing the ScheduledAlarmListener interface to wait for scheduled alarms.
setTelephonyListener()	Registers a listener implementing the TelephonyListener interface to wait for incoming calls, etc.
setRingStateListener()	Registers a listener implementing the RingStateListener interface to wait for the start and end of ringing in the platform.

Field Summary

static int	BACK_LIGHT Backlight lit.
static int	BATTERY Battery.
static int	EIGHT_DIRECTIONS Use of eight-direction keys.
static int	FIELD_INTENSITY Field intensity.
static int	KEY_STATE Key pressed state.
static int	VIBRATION Vibration function.

Method Summary

void	blink(int lighting, int extinction, int repeat) Blinks the backlight.
static DeviceControl	getDefaultDeviceControl() Gets the default DeviceControl instance.
int	getDeviceState(int deviceNo) Gets device states.
boolean	getKeyRepeatState(int key) Gets the key auto-repeat function setting.
boolean	isDeviceActive(int deviceNo) Checks whether a device is active.
boolean	setDeviceActive(int deviceNo, boolean active) Sets the device active state.
boolean	setKeyRepeatState(int key, boolean state) Sets the key auto-repeat function.
static void	setMailListener(MailListener listener) Registers a MailListener.
static void	setRingStateListener(RingStateListener listener) Registers a RingStateListener.
static void	setScheduledAlarmListener(ScheduledAlarmListener listener) Registers a ScheduledAlarmListener.
static void	setTelephonyListener(TelephonyListener listener) Registers a TelephonyListener.

Methods inherited from class java.lang.Object

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

Field Detail

BATTERY

public static final int BATTERY

Battery. BATTERY is set to 1.

FIELD_INTENSITY

public static final int FIELD_INTENSITY

Field intensity. FIELD_INTENSITY is set to 2.

KEY_STATE

public static final int KEY_STATE

Key pressed state. KEY_STATE is set to 3.

VIBRATION

public static final int VIBRATION

Vibration function. VIBRATION is set to 4.

BACK_LIGHT

public static final int BACK_LIGHT

Backlight lit. BACK_LIGHT is set to 5.

EIGHT_DIRECTIONS

public static final int EIGHT_DIRECTIONS

Use of eight-direction keys. EIGHT_DIRECTIONS is set to 6.

Method Detail

getDefaultDeviceControl

public static final DeviceControl getDefaultDeviceControl()

Gets the default DeviceControl instance.

Returns:

The default DeviceControl instance.

getDeviceState

public int getDeviceState(int deviceNo)

Gets device states.

Parameters:

deviceNo - Device number (BATTERY Remaining battery capacity (%), FIELD_INTENSITY Field intensity (%), KEY_STATE Key pressed state)

Returns:

int - Device state.
In the return values when KEY_STATE is designated, each bit corresponds to a key, and when the bit is raised to 1, its key is pressed. The mapping of bits to keys is as shown below.

bits	Key		bits	Key		bits	Key		bits	Key
31	Reserved		23	Lower Left		15	Down key		7	7key
30	Reserved		22	Lower Right		14	Right key		6	6 key
29	Reserved		21	Upper Left		13	Left key		5	5 key
28	Reserved		20	Upper Right		12	Up key		4	4 key
27	Reserved		19	Softkey 3		11	# key		3	3 key
26	Reserved		18	Softkey 2		10	* key		2	2 key
25	Reserved		17	Softkey 1		9	9 key		1	1 key
24	Reserved		16	Select key		8	8 key		0	0 key

Throws:

IllegalArgumentException - if a value other than BATTERY, FIELD_INTENSITY, or KEY_STATE is designated for deviceNo.

isDeviceActive

public boolean isDeviceActive(int deviceNo)

Checks whether a device is active.

Parameters:

deviceNo - Device number (VIBRATION Vibration function, BACK_LIGHT Backlight ON/OFF, EIGHT_DIRECTIONS Use of eight-directions keys)

Returns:

int - Device state (true: Active)

Throws:

IllegalArgumentException - if a value other than BATTERY, FIELD_INTENSITY, or KEY_STATE is designated for deviceNo.

setDeviceActive

public boolean setDeviceActive(int deviceNo,
                               boolean active)

Sets the device active state. Note that when BACK_LIGHT is set to OFF, the state set in the handset is returned, but the backlight is not necessarily turned off.

Parameters:

deviceNo - Device number (VIBRATION Vibration function, BACK_LIGHT Backlight ON/OFF, EIGHT_DIRECTIONS Use of eight-directions keys)

active - Device state (true: Active)

Returns:

boolean - If the control succeeds, true is returned, else false.

Throws:

IllegalArgumentException - if a value other than BATTERY, FIELD_INTENSITY, or KEY_STATE is designated for deviceNo.

RuntimeException - if the Java application for which the control is intended is executing, accepting an incoming call, or governed by a schedule when this method is called.

blink

public void blink(int lighting,
                  int extinction,
                  int repeat)

Blinks the backlight. The backlight blinks on and off for the designated lit/off intervals and number of iterations. If backlight control is performed by setDeviceActive() while blinking is being controlled by blink(), blinking is stopped.

Parameters:

lighting - Lit interval (in millseconds). The maximum is 1000.

extinction - off interval (in millseconds).

repeat - Number of repetitions

Throws:

IllegalArgumentException - if a negative value or value above 1000 is designated for lighting, or if a negative value is designated for extinction or repeat.

IllegalStateException - if called while already blinking.

RuntimeException - if the Java application for which the control is intended is executing, accepting an incoming call, or governed by a schedule when this method is called.

setKeyRepeatState

public boolean setKeyRepeatState(int key,
                                 boolean state)

Sets the key auto-repeat function.

Parameters:

key - Key code

state - The auto-repeat setting. Designate true for On, or false for Off.

Returns:

boolean - True is returned if the setting succeeds, or false if it fails.

getKeyRepeatState

public boolean getKeyRepeatState(int key)

Gets the key auto-repeat function setting.

Parameters:

key - Key code

Returns:

boolean - Auto-repeat setting. True is returned for On, or false for Off.

setMailListener

public static void setMailListener(MailListener listener)

Registers a MailListener.

Parameters:

listener - The new MailListener

setScheduledAlarmListener

public static void setScheduledAlarmListener(ScheduledAlarmListener listener)

Registers a ScheduledAlarmListener.

Parameters:

listener - The new ScheduledAlarmListener

setTelephonyListener

public static void setTelephonyListener(TelephonyListener listener)

Registers a TelephonyListener.

Parameters:

listener - The new TelephonyListener

setRingStateListener

public static void setRingStateListener(RingStateListener listener)

Registers a RingStateListener.

Parameters:

listener - The new RingStateListener