com.motorola.funlight
Interface Region

public interface Region

Region interface is used to drive a Fun Lights region.
Notes: There is no need for implementing Region interface by MIDlet's developer. For getting object which implements Region interface can be used functions of FunLight class.

Region is an area of phone (display, keypad etc.) that can light or change its color.

Common overview

Region Control

Another applications can uses the hardware regions. To provide correct usage of regions by several applications the concept is control of region. For use the region, the MIDlet shall require of control. If MIDlet has control of region then all requests to change region color will be immediately executed. If MIDlet has not control of region then latest request to change region color will be buffered. When MIDlet obtains region control then buffered request will be immediately completed. To obtain control of region use getControl() method. To release region control use releaseControl() method.

The human factor

Due to Human factor concerns, the refresh rate of the LEDs must be less than 5 Hz. Therefore period between changing of light status for region should be less than 200 milliseconds otherwise request for changing the light status of region will be ignored.

Regions sets

E380 product:

Region's ID	Region Name	Common description	Colors
1	Display	Display region represents display backlight.	The region supports white light that can be turned on/off. When any non-zero value of color will be passed to setColor() method the color will be converted to FunLight.WHITE color which will be set for region, otherwise lights of region will be turned off.
2	Navigation Keypad	Navigation Keypad region represents lights of softkeys, navigation keys, SEND and END keys.	The region supports lights with multiple colors. The color is specified in 0x00RRGGBB format. When 0x00RRGGBB color will be passed to setColor() method the color will be converted to 0x00RGB color which will be set for region. getColor() method returns the color in 0x00RRGGBB format (0x00RGB color will be extended through duplication of R ,G and B components).
3	Numeric Keypad	Numeric Keypad region represents lights of numeric keys.	The region supports white light that can be turned on/off. When any non-zero value of color will be passed to setColor() method the color will be converted to FunLight.WHITE color which will be set for region, otherwise lights of region will be turned off.
4	Sideband	Sideband region represents lights of device's sides	The region supports lights with multiple colors. The color is specified in 0x00RRGGBB format. When 0x00RRGGBB color will be passed to setColor() method the color will be converted to 0x00RGB color which will be set for region. getColor() method returns the color in 0x00RRGGBB format (0x00RGB color will be extended through duplication of R ,G and B components).

V600 product:

Region's ID	Region Name	Common description	Colors
1	Display	Display region represents display backlight.	The region supports white light that can be turned on/off. When any non-zero value of color will be passed to setColor() method the color will be converted to FunLight.WHITE color which will be set for region, otherwise lights of region will be turned off.
2	Keypad & Side Lights	Keypad & Side Lights region represents lights of keypad and lights of sides of device.	The region supports white light that can be turned on/off. When any non-zero value of color will be passed to setColor() method the color will be converted to FunLight.WHITE color which will be set for region, otherwise lights of region will be turned off.
3	Logo	Logo region represents lights of Motorola's logo.	The region supports white light that can be turned on/off. When any non-zero value of color will be passed to setColor() method the color will be converted to FunLight.WHITE color which will be set for region, otherwise lights of region will be turned off.
4	Ring around Logo	Ring around Logo region represents lights of ring around Motorola's logo.	The region supports lights with multiple colors. The color is specified in 0x00RRGGBB format. When 0x00RRGGBB color will be passed to setColor() method the color will be converted to 0x00RGB color which will be set for region. getColor() method returns the color in 0x00RRGGBB format (0x00RGB color will be extended through duplication of R ,G and B components).

E390 product:

Region's ID	Region Name	Common description	Colors
1	Display	Display region represents display backlight.	The region supports white light that can be turned on/off. When any non-zero value of color will be passed to setColor() method the color will be converted to FunLight.WHITE color which will be set for region, otherwise lights of region will be turned off.
2	Keypad	Keypad region represents lights of keypad.	The region supports white light that can be turned on/off. When any non-zero value of color will be passed to setColor() method the color will be converted to FunLight.WHITE color which will be set for region, otherwise lights of region will be turned off.
3	Left Sideband	Left Sideband region represents lights of left side band of the device.	The region supports lights with multiple colors. The color is specified in 0x00RRGGBB format. When 0x00RRGGBB color will be passed to setColor() method the color will be converted to 0x00RGB color which will be set for region. getColor() method returns the color in 0x00RRGGBB format (0x00RGB color will be extended through duplication of R ,G and B components).
4	Right Sideband	Right Sideband region represents lights of right side band of the device.	The region supports lights with multiple colors. The color is specified in 0x00RRGGBB format. When 0x00RRGGBB color will be passed to setColor() method the color will be converted to 0x00RGB color which will be set for region. getColor() method returns the color in 0x00RRGGBB format (0x00RGB color will be extended through duplication of R ,G and B components).

Blank Region

Blank region was designed for ignoring attempt to access to non-existing regions. For example, following code illustrates this:
(Code 1: turn on Display Region for E380 device):
Region display = FunLight.getRegion(1);
display.setColor(FunLight.ON);
display.getControl();
(Code 2: turn on Navigation Keypad Region for E380 device):
Region keypad = FunLight.getRegion(2);
keypad.setColor(FunLight.ON);
keypad.getControl();

Product E380 has both Display and Navigation Keypad regions and both of these codes will be successfully executed.
V300 does not support Fun Lights feature, therefore FunLight.getRegion(1) and FunLight.getRegion(2) will return region object with following attribute:

Region's ID	Region Name	Common description	Colors
0	Blank	Blank region represents non-existing region.	FunLight.BLACK

All methods applyed to Blank region will do nothing, and will not throw any exceptions.

Method Summary

int	getColor() Gets color of the region.
int	getControl() Tries to occupy region's control.
int	getID() Gets region's ID.
void	releaseControl() Releases region's control.
int	setColor(byte red, byte green, byte blue) Sets the color of region.
int	setColor(int color) Sets the color of region.
java.lang.String	toString() This method returns a string which contain the region name.

Method Detail

getColor

public int getColor()

Gets color of the region.
The color will be returned in accordance with rules described in Regions sets.

Returns:

Region's color in 0x00RRGGBB format.

Throws:

FunLightException - if setColor method was not called before calling this method except Blank region.

getControl

public int getControl()

Tries to occupy region's control.

Note. This method does nothing for Blank region and returns QUEUED.

Returns:

SUCCESS - if region's control has been occupied successfully.

QUEUED - if region's control has not been occupied and request of obtaining of region's control has been queued. In this case MIDlet will obtained region's control when higher priority applications will released the region's control.

IGNORED - ignored will be returned in the following cases:
Case 1. Previous successful or queued obtaining of region's control was less than 200 milliseconds ago.
Case 2. Lastest successful or queued update of region's color was less than 200 milliseconds ago and the following conditions are satisfied:
Condition 1: Region's control has been successfully obtained or request has been queued.
Condition 2: Region's control has not been released yet.

getID

public int getID()

Gets ID of the region.
List of IDs for regions are described in Regions sets.

Returns:

Region's ID.

releaseControl

public void releaseControl()

Releases region's control.

Note. This method does nothing if region's control has not been requested.

Note. This method does nothing for Blank region.

setColor

public int setColor(int color)

Sets the color of region. This method convertes the inquired color to the color that region can shine in accordance with rules described in Regions sets.

Note. This method does nothing for Blank region and returns QUEUED.

Parameters:

color - color in RGB format (0x00RRGGBB). The high order byte of this value is ignored.

Returns:

SUCCESS - if the color has been set.

QUEUED - if the color has not been set and request of color setting has been queued. In this case the color will be set when MIDlet will obtain region's control. Note. Only latest request about color setting will be executed when MIDlet will obtain region's control.

IGNORED - ignored will be returned in the following cases:
Case 1. Previous successful or queued obtaining of region's control was less than 200 milliseconds ago.
Case 2. Lastest successful or queued update of region's color was less than 200 milliseconds ago and the following conditions are satisfied:
Condition 1: Region's control has been successfully obtained or request has been queued.
Condition 2: Region's control has not been released yet.

setColor

public int setColor(byte red,
                    byte green,
                    byte blue)

Sets the color of region. This method is equivalent to setColor(int color) method.

Note. This method does nothing for Blank region and returns QUEUED.

Parameters:

red - Red component of color.

green - Green component of color.

blue - Blue component of color.

Returns:

SUCCESS - if the color has been set.

QUEUED - if the color has not been set and request of color setting has been queued. In this case the color will be set when MIDlet will obtain region's control. Note. Only latest request about color setting will be executed when MIDlet will obtain region's control.

IGNORED - ignored will be returned in the following cases:
Case 1. Previous successful or queued obtaining of region's control was less than 200 milliseconds ago.
Case 2. Lastest successful or queued update of region's color was less than 200 milliseconds ago and the following conditions are satisfied:
Condition 1: Region's control has been successfully obtained or request has been queued.
Condition 2: Region's control has not been released yet.

toString

public java.lang.String toString()

This method returns a string with the region's name.

List of names for regions are described in Regions sets.

Overrides:

toString in class java.lang.Object

Returns:

the string representation of the object