System Event

The System Event object allows you to get access to events triggered by system events on the BlackBerry device.


Supported Platform(s)

- BlackBerry OS 5.0+
- BlackBerry PlayBook 1.0+
- Ripple Emulator
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.system.event.deviceBatteryLevelChange       Y Y  Y
blackberry.system.event.deviceBatteryStateChange       Y Y  Y
blackberry.system.event.onCoverageChange Y Y Y      Y
blackberry.system.event.onHardwareKey Y Y Y       
KEY_BACK Y Y Y      Y
KEY_MENU Y Y Y      Y
KEY_CONVENIENCE_1 Y Y Y      Y
KEY_CONVENIENCE_2 Y Y Y      Y
KEY_STARTCALL Y Y Y      Y
KEY_ENDCALL Y Y Y      Y
KEY_VOLUMEDOWN Y Y Y      Y
KEY_VOLUMEUP Y Y Y      Y

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.system.event" /> Y Y Y Y Y  Y

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.


Constants

Functions

static void blackberry.system.event.deviceBatteryLevelChange (onBatteryLevelChange: function(level : Number))

BB10 API Changes

This function has been migrated to blackberry.system.event:batterystatus, blackberry.system.event:batterylow, and blackberry.system.event:batterycritical in BlackBerry 10.


Assigns a listener for when the battery level changes. Battery level is a percentage value. This API is currently designed where it will immediately announce the initial battery level, then it will announce any percentage change afterwards


Supported Platforms
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
onBatteryLevelChange Function to be called when the battery level changes. The level is passed as its only argument.

level: battery level of the device ranging from 0 to 100

Code Example:
<script type="text/javascript">
 function foobar(level) { //This is just the callback function to be able to access the battery level. If you want it to alert you at a different interval, you just change this specific callback function to alert you at a different interval. 
   alert("Battery Level: " + level);
 }

 function notifyOnBatteryLevelChange(callBackFunction) {
   blackberry.system.event.deviceBatteryLevelChange(callBackFunction);
 }

 notifyOnBatteryLevelChange(foobar);
</script>

static void blackberry.system.event.deviceBatteryStateChange (onBatteryStateChange: function(state : Number))

BB10 API Changes

This function has been migrated to blackberry.system.event:batterystatus, blackberry.system.event:batterylow, and blackberry.system.event:batterycritical in BlackBerry 10.


Assigns a listener for when the battery state changes. When called, this API will immediately return the current battery state (whether it is charging or unplugged etc.) and will return the value when it reaches a new battery state.

States are defined as the following:
UNKNOWN = 0;
FULL = 1;
CHARGING = 2;
UNPLUGGED = 3;


Supported Platforms
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
onBatteryStateChange Function to be called when the battery charge state changes. The new state is passed as its only argument.

state: battery state of the device

Code Example:
<script type="text/javascript">
 function foo(state) { //This is just the callback function to be able to access the battery state when there is a change. 
   alert("Battery state: " + state);
 }

 function notifyStateChange(callBackFunction) {
   blackberry.system.event.deviceBatteryStateChange(callBackFunction);
 }

 notifyStateChange(foo);
</script>

static void blackberry.system.event.onCoverageChange (onSystemEvent: function())


Assigns a listener for when the coverage status changes.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Parameters
onSystemEvent Function to be called when coverage changes. Only one function can be assigned to this event. To unregister the callback, call the onCoverageChange method and pass in null for the callback parameter.

static void blackberry.system.event.onHardwareKey (key : Number, onSystemEvent: function())


Assigns a listener for the click of one of the hardware buttons on the device.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
key Hardware key to listen for. A list of constants allowed for these keys is shown above.
onSystemEvent Function to be called when the key is clicked - this function takes no parameters and no return value is required. If you attempt to subscribe more than one callback function to a particular key, only the newest callback will be used when the key is pressed. To remove the callback simply call the onHardwareKey with null as the callback parameter.

Code Example:
<script type="text/javascript">
  function trapForBackKey() {
    blackberry.system.event.onHardwareKey(blackberry.system.event.KEY_BACK, handleBack);
  }

  function handleBack() {
    alert("handle back button");
  }
</script>

Constants

static Number KEY_BACK


Constant representing the back button.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number KEY_MENU


Constant representing the menu button.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number KEY_CONVENIENCE_1


Constant representing the first convenience button.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number KEY_CONVENIENCE_2


Constant representing the second convenience button.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number KEY_STARTCALL


Constant representing the call button.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number KEY_ENDCALL


Constant representing the end call button.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number KEY_VOLUMEDOWN


Constant representing the volume down button.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number KEY_VOLUMEUP


Constant representing the volume up button.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:06 GMT-0500 (EST)