net.rim.device.api.system
Class Backlight

java.lang.Object
  net.rim.device.api.system.Backlight

public final class Backlight
extends Object

Provides access to the device's backlight(s).

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

Constructor Summary
	Backlight() Deprecated. All members of Backlight are static.

Method Summary
	static void	enable(boolean on) Turns the backlight on or off.
	static void	enable(boolean on, int seconds) Turns the backlight on or off.
	static int	getBrightness() Gets the brightness of the backlight.
	static int	getBrightnessDefault() Gets the default brightness of the backlight.
	static int	getBrightnessIncrement() Retrieves the recommended percentage increment for backlight brightness.
	static int	getTimeoutDefault() Gets the backlight default timeout.
	static boolean	isBrightnessConfigurable() Determines if the brightness of the backlight is configurable.
	static boolean	isEnabled() Determines if the backlight is currently on.
	static void	setBrightness(int brightness) Sets the brightness of the backlight.
	static void	setTimeout(int seconds) Sets the backlight timeout.

Methods inherited from class java.lang.Object

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

Constructor Detail

Backlight

public Backlight()

Deprecated. All members of Backlight are static.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

Method Detail

enable

public static void enable(boolean on)

Turns the backlight on or off.

Parameters:

on - If true, turn the backlight on. The backlight remains on for the duration specified by Backlight.setTimeout(int). User activity while the backlight is on causes the timer to reset.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

enable

public static void enable(boolean on,
                          int seconds)

Turns the backlight on or off. If an application has invoked this method, the application should call this method on exit, passing in the return value of Backlight.getTimeoutDefault().

This function is asynchronous. Wait a short period (such as 100 ms) after invoking enable() before checking if the backlight is on by invoking isEnabled().

Parameters:

on - If true, turn the backlight on. The backlight remains on for the duration specified. User activity while the backlight is on causes the timer to reset to the value specified in Backlight.setTimeout(int).

seconds - Number of seconds to leave the backlight on for Values larger than 255 seconds are reduced to 255 seconds.

Throws:

IllegalArgumentException - If the seconds value is less than 1.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

getBrightness

public static int getBrightness()

Gets the brightness of the backlight.

Returns:

Percentage of maximum capable brightness (i.e. a number between 1 and 100).

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

getBrightnessDefault

public static int getBrightnessDefault()

Gets the default brightness of the backlight.

Returns:

Percentage of default brightness (i.e. a number between 1 and 100).

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.2

getBrightnessIncrement

public static int getBrightnessIncrement()

Retrieves the recommended percentage increment for backlight brightness.

Note: While the the backlight's brightness is a percentage, the range varies between device types. The increment is rounded down to the nearest integer. For example, if the device range is 7, the increment would be 14

Returns:

An increment between 1 and 100. Returns 0 to indicate the platform does not support this method.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

getTimeoutDefault

public static int getTimeoutDefault()

Gets the backlight default timeout.

Parameters:

seconds - Default timeout value (255 seconds is the maximum allowed value).

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.2

isBrightnessConfigurable

public static boolean isBrightnessConfigurable()

Determines if the brightness of the backlight is configurable.

Returns:

True if the brightness of the backlight is configurable; otherwise, false.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

isEnabled

public static boolean isEnabled()

Determines if the backlight is currently on.

Returns:

True if the backlight is currently on; otherwise, false.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

setBrightness

public static void setBrightness(int brightness)

Sets the brightness of the backlight.

Parameters:

brightness - Percentage of maximum capable brightness (i.e. a number between 0 and 100).

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

setTimeout

public static void setTimeout(int seconds)

Sets the backlight timeout. If an application has invoked this method, the application should call this method on exit, passing in the return value of Backlight.getTimeoutDefault().

Parameters:

seconds - Timeout value (255 seconds is the maximum allowed value).

Throws:

IllegalArgumentException - If the seconds value is less than 1 or greater than 255.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0