Power API

The Power API provides support for requesting power management related resource states.

For more information on the Power features, see Power Guide.

Since: 2.0

Table of Contents

Summary of Interfaces and Methods

Interface Method
PowerManagerObject
PowerManager
void request (PowerResource resource, PowerState state)
void release (PowerResource resource)
void setScreenBrightness (double brightness)
boolean isScreenOn ()
ScreenStateChangeCallback
void onchanged (PowerScreenState previousState, PowerScreenState changedState)

1. Type Definitions

1.1. PowerResource

Specifies power resources with values aligned with SystemInfo property values. 
  enum PowerResource { "SCREEN", "CPU" };

Since: 2.0

Screen and CPU resources are supported at present. Supported power resource states are provided in PowerScreenState and PowerCpuState enums respectively prefixed by the corresponding resource type.

  • SCREEN - Corresponds to screen power resource.
  • CPU - corresponds to CPU power resource.

1.2. PowerScreenState

Specifies the power state for screen resource. 
  enum PowerScreenState { "SCREEN_OFF", "SCREEN_DIM", "SCREEN_NORMAL" };

Since: 2.0

The supported values are:

  • SCREEN_OFF - This screen state cannot be requested but can only be used in the state change callback.
  • SCREEN_DIM - The minimal screen state is set to DIM and device does not change to OFF state automatically.
  • SCREEN_NORMAL - The minimal screen state is set to NORMAL and device does not change to DIM state automatically.

DIM state refers to the screen that the backlight is turned off. NORMAL state refers to the default screen brightness that a user has configured for the device. Note that the change in brightness does not affect the system brightness setting, i.e., the system brightness value is automatically restored when the resource is released or the process is completed.

1.3. PowerCpuState

Specifies the power state for the CPU resource. 
  enum PowerCpuState { "CPU_AWAKE" };

Since: 2.0

The supported values are:

  • CPU_AWAKE - The CPU state is set to awake and it does not go to SLEEP state automatically.

1.4. PowerState

The supported power states in general. It can be either a PowerScreenState or a PowerCpuState. 
  typedef (PowerScreenState or PowerCpuState) PowerState;

Since: 2.0

2. Interfaces

2.1. PowerManagerObject

The PowerManagerObject interface defines what is instantiated by the Tizen object from the Tizen Platform. 
  [NoInterfaceObject] interface PowerManagerObject {
    readonly attribute PowerManager power;
  };
  Tizen implements PowerManagerObject;

Since: 2.0

There will be a tizen.power object that allows accessing of a functionality of the Power API.

Attributes

  • readonly PowerManager power
    Object representing a power manager.

    Since: 2.0

2.2. PowerManager

The PowerManager interface is used to request resource states. 
  [NoInterfaceObject] interface PowerManager {
    void request(PowerResource resource, PowerState state) raises(WebAPIException);
    void release(PowerResource resource) raises(WebAPIException);
    void setScreenStateChangeListener(ScreenStateChangeCallback listener) raises(WebAPIException);
    void unsetScreenStateChangeListener() raises(WebAPIException);
    double getScreenBrightness() raises(WebAPIException);
    void setScreenBrightness(double brightness) raises(WebAPIException);
    boolean isScreenOn() raises(WebAPIException);
    void restoreScreenBrightness() raises(WebAPIException);
  };

Since: 2.0

However, these requests can be overridden by the system. If the requests are overridden, the application is notified with the provided listener callback.

Methods

request
Requests the minimum-state for a power resource. 
void request(PowerResource resource, PowerState state);

Since: 2.0

Privilege level: public

Privilege: http://tizen.org/privilege/power

Remark: SCREEN_DIM may be ignored if the DIM state is disabled on the platform.

Parameters:

  • resource: Power resource for which the request is made.
  • state: Minimal power state in which the power resource is desired to be.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError in any other error case.

Code example:

tizen.power.request("SCREEN", "SCREEN_NORMAL");
release
Releases the power state request for the given resource. 
void release(PowerResource resource);

Since: 2.0

Parameters:

  • resource: Resource for which requests are to be removed.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type UnknownError in any other error case.

Code example:

/* Releases SCREEN resource. */
tizen.power.release("SCREEN");
setScreenStateChangeListener
Sets the screen state change callback and monitors its state changes. 
void setScreenStateChangeListener(ScreenStateChangeCallback listener);

Since: 2.0

Parameters:

  • listener: Screen state change callback.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type UnknownError in any other error case.

Code example:

function onScreenStateChanged(previousState, changedState)
{
  console.log("Screen state changed from " + previousState + " to " + changedState);
}

/* Sets the screen state change listener. */
tizen.power.setScreenStateChangeListener(onScreenStateChanged);
unsetScreenStateChangeListener
Unsets the screen state change callback and stop monitoring it. 
void unsetScreenStateChangeListener();

Since: 2.0

Calling this function has no effect if listener is not set.

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError in any other error case.

Code example:

/* Unsets the screen state change listener. */
tizen.power.unsetScreenStateChangeListener();
getScreenBrightness
Gets the screen brightness level of an application, from 0 to 1. 
double getScreenBrightness();

Since: 2.0

Return value:

    double: Current screen brightness value.

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError in any other error case.

Code example:

/* Gets the current screen brightness value. */
var screenBrightness = tizen.power.getScreenBrightness();
setScreenBrightness
Sets the screen brightness level, from 0 to 1. 
void setScreenBrightness(double brightness);

Since: 2.0

An approximation is made for best effort when the given value is not exactly applicable by the hardware or system.

Privilege level: public

Privilege: http://tizen.org/privilege/power

Parameters:

  • brightness: The screen brightness value to set.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError in any other error case.

Code example:

/* Sets the screen brightness value for the application. */
tizen.power.setScreenBrightness(1);
isScreenOn
Checks whether the screen is on. 
boolean isScreenOn();

Since: 2.0

Return value:

    boolean: true if screen is on, otherwise false if the screen is off.

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError in any other error case.

Code example:

/* Checks whether the screen is on or off. */
var isScreenOn = tizen.power.isScreenOn();
restoreScreenBrightness
Restores the screen brightness to the system default setting value. 
void restoreScreenBrightness();

Since: 2.0

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError in any other error case.

Code example:

/* Restores the screen brightness value to the system default setting value. */
tizen.power.restoreScreenBrightness();

2.3. ScreenStateChangeCallback

The ScreenStateChangeCallback callback interface defines notification for the screen state changes. 
  [Callback=FunctionOnly, NoInterfaceObject] interface ScreenStateChangeCallback {
    void onchanged(PowerScreenState previousState, PowerScreenState changedState);
  };

Since: 2.0

Methods

onchanged
Called on screen state change. 
void onchanged(PowerScreenState previousState, PowerScreenState changedState);

Since: 2.0

Parameters:

  • previousState: Previous screen state.
  • changedState: Changed screen state.

3. Related Feature

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

To guarantee that the application runs on a device which allows screen state changing, declare the following feature requirement in the config file:

  • http://tizen.org/feature/display.state

    • For more information, see Application Filtering.

    4. Full WebIDL

    module Power {
  typedef (PowerScreenState or PowerCpuState) PowerState;
  enum PowerResource { "SCREEN", "CPU" };
  enum PowerScreenState { "SCREEN_OFF", "SCREEN_DIM", "SCREEN_NORMAL" };
  enum PowerCpuState { "CPU_AWAKE" };
  Tizen implements PowerManagerObject;
  [NoInterfaceObject] interface PowerManagerObject {
    readonly attribute PowerManager power;
  };
  [NoInterfaceObject] interface PowerManager {
    void request(PowerResource resource, PowerState state) raises(WebAPIException);
    void release(PowerResource resource) raises(WebAPIException);
    void setScreenStateChangeListener(ScreenStateChangeCallback listener) raises(WebAPIException);
    void unsetScreenStateChangeListener() raises(WebAPIException);
    double getScreenBrightness() raises(WebAPIException);
    void setScreenBrightness(double brightness) raises(WebAPIException);
    boolean isScreenOn() raises(WebAPIException);
    void restoreScreenBrightness() raises(WebAPIException);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface ScreenStateChangeCallback {
    void onchanged(PowerScreenState previousState, PowerScreenState changedState);
  };
};
    Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
    For details, see the Content License.