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
- Ripple Emulator
| API | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
|---|---|---|---|---|---|
| deviceBatteryLevelChange | Y | Y | |||
| deviceBatteryStateChange | Y | Y | |||
| onCoverageChange | Y | Y | Y | Y | |
| 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 ID | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
|---|---|---|---|---|---|
| <feature id="blackberry.system.event" /> | Y | Y | Y | Y | Y |
| Permission Elements (PlayBook Only) |
|---|
| This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application. |
API Summary
deviceBatteryLevelChange
| static void deviceBatteryLevelChange(onBatteryLevelChange : function) |
Supported Platform(s)
- BlackBerry PlayBook- Ripple Emulator
Description
Assigns a listener for when the battery level changes. Battery level is a percentage value.
| Parameter | Type | Description |
|---|---|---|
| onBatteryLevelChange | function(level : Number) |
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(s)
<script type="text/javascript">
function onBatteryLevelChange(level) {
alert("Battery Level: " + level);
}
function notifyOnBatteryLevelChange(batteryLevelChangeCb) {
blackberry.system.event.deviceBatteryLevelChange(batteryLevelChangeCb);
}
notifyOnBatteryLevelChange(onBatteryLevelChange);
</script>
deviceBatteryStateChange
| static void deviceBatteryStateChange(onBatteryStateChange : function) |
Supported Platform(s)
- BlackBerry PlayBook- Ripple Emulator
Description
Assigns a listener for when the battery state changes.
States are defined asUNKNOWN = 0;
FULL = 1;
CHARGING = 2;
UNPLUGGED = 3;
| Parameter | Type | Description |
|---|---|---|
| onBatteryStateChange | function(state : Number) |
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 |
onCoverageChange
| static void onCoverageChange(onSystemEvent : function) |
Supported Platform(s)
- BlackBerry OS 5.0+- Ripple Emulator
Description
Assigns a listener for when the coverage status changes.
| Parameter | Type | Description |
|---|---|---|
| onSystemEvent | function() | 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. |
onHardwareKey
| static void onHardwareKey(key : Number, onSystemEvent : function) |
Supported Platform(s)
- BlackBerry OS 5.0+Description
Assigns a listener for the click of one of the hardware buttons on the device.
| Parameter | Type | Description |
|---|---|---|
| key | Number | Hardware key to listen for. A list of constants allowed for these keys is shown above. |
| onSystemEvent | function() | 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(s)
<script type="text/javascript">
function trapForBackKey() {
blackberry.system.event.onHardwareKey(blackberry.system.event.KEY_BACK, handleBack);
}
function handleBack() {
alert("handle back button");
}
</script>
Constants:
| Property | Type | Description | Supported Platform(s) |
|---|---|---|---|
| KEY_BACK | Number |
Constant representing the back button.
|
- BlackBerry OS 5.0+
- Ripple Emulator |
| KEY_MENU | Number |
Constant representing the menu button.
|
- BlackBerry OS 5.0+
- Ripple Emulator |
| KEY_CONVENIENCE_1 | Number |
Constant representing the first convenience button.
|
- BlackBerry OS 5.0+
- Ripple Emulator |
| KEY_CONVENIENCE_2 | Number |
Constant representing the second convenience button.
|
- BlackBerry OS 5.0+
- Ripple Emulator |
| KEY_STARTCALL | Number |
Constant representing the call button.
|
- BlackBerry OS 5.0+
- Ripple Emulator |
| KEY_ENDCALL | Number |
Constant representing the end call button.
|
- BlackBerry OS 5.0+
- Ripple Emulator |
| KEY_VOLUMEDOWN | Number |
Constant representing the volume down button.
|
- BlackBerry OS 5.0+
- Ripple Emulator |
| KEY_VOLUMEUP | Number |
Constant representing the volume up button.
|
- BlackBerry OS 5.0+
- Ripple Emulator |
Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 13:31:17 GMT-0500 (EST)