System
The System object allows you access system level functions and attributes of the BlackBerry Device.
Since: BlackBerry WebWorks 2.0
The System object is static; all of its functions and properties are used directly from the object.
Installation:
To use this API in your project, add the system plugin:
webworks plugin add com.blackberry.system
Learning Resources:
Sample - Set Wallpaper Sample that demonstrates how to use the BlackBerry system.setWallpaper API [BlackBerry on GitHub].
Sample - Localization Sample that demonstrates how to work with device region and language changes [BlackBerry on GitHub].
Function Type | Function Name |
---|---|
String | getCurrentTimezone() |
Object | getFontInfo() |
String[] | getTimezones() |
Boolean | hasCapability() (deprecated) |
void | setWallpaper() |
Events |
---|
batterycritical |
batterylow |
batterystatus |
datalockstatechanged (new in 2.2) |
fontchanged |
languagechanged |
perimeterlocked |
perimeterunlocked |
regionchanged |
Property Type | Property Name |
---|---|
String | dataLockState (new in 2.2) |
String | dataLockTime (new in 2.2) |
String | deviceLockedStatus |
String | hardwareId |
String | language |
String | name |
String | region |
String | softwareVersion |
getCurrentTimezone()
Retrieves the time zone currently used by the device.
Synopsis:
String blackberry.system.getCurrentTimezone()
Returns:
- The time zone used by the device.
- Type: String
Example:
<script type="text/javascript"> function getCurrentTimezone() { return blackberry.system.getCurrentTimezone(); // e.g. "America/New_York" } </script>
getFontInfo()
Returns the information of current system font, which is composed of the font family and font size.
Synopsis:
Object blackberry.system.getFontInfo()
Returns:
- Returns a JavaScript Object that contains fontFamily and fontSize properties.
-
Type: Object
- fontFamily
- Type: String
The name of the font family.
- fontSize
- Type: Number
The font size.
Example:
<script type="text/javascript"> // Check system font information var fontInfo = blackberry.system.getFontInfo(); console.log("The font family of current system font is " + fontInfo.fontFamily + "\nThe size of current system font is " + fontInfo.fontSize); </script>
getTimezones()
Retrieves the list of all time zones supported by the device. The time zones are based on the Olson time zone database. For more information, refer to IANA.
Synopsis:
String[] blackberry.system.getTimezones()
Returns:
- The list of time zones supported by the device.
- Type: String[]
hasCapability()
This function determines whether the BlackBerry device is capable of the given service.
Deprecation Notice: This function is deprecated. In BlackBerry WebWorks 2.0, it returned a hard-coded list of values. It has been unavailable since BlackBerry WebWorks 2.1.
Synopsis:
Boolean blackberry.system.hasCapability(capability)
Parameters:
- capability
- Type: String
The capability being checked for.
The supported string values for 'capability' are:
- input.keyboard.issuretype (returns true if the user is currently using SureType),
- input.touch,
- media.audio.capture,
- media.video.capture,
- media.recording,
- location.gps,
- location.maps,
- storage.memorycard (checks for an EXTERNAL media card only),
- network.bluetooth,
- network.wlan (WLAN wireless family includes 802.11, 802.11a, 802.11b, 802.11g),
- network.3gpp (3GPP wireless family includes GPRS, EDGE, UMTS, GERAN, UTRAN, and GAN),
- network.cdma (CDMA wireless family includes CDMA1x and EVDO),
- and network.iden.
Returns:
- Returns true if the device is capable of the given service.
- Type: Boolean
setWallpaper()
Set the wallpaper using the path to the file provided.
Synopsis:
void blackberry.system.setWallpaper()
Parameters:
- filepath
- Type: String
Path to the file to be used as wallpaper.
batterycritical
This event is fired by the system. If you want to listen to the event you can do so using the document.addEventListener function and remove the listener using the document.removeEventListener function. The batterycritical event is triggered whenever the battery level changes to a value lower than 5%.
Synopsis:
Event
Parameters:
- yourCallbackFunction(info)
-
The callback function that will be invoked on the batterycritical event.
- info
- Type: JSON
An object with the pertinent information.
- level
- Type: Number
The percentage of the battery charge (0-100).
- isPlugged
- Type: Boolean
A boolean that represents whether or not the device is receiving a charge.
Example:
<script type="text/javascript"> function onBatteryCritical(info) { alert("The battery level is critical: " + info.level + (info.isPlugged ? "." : " and will shutdown soon. Save your work or connect device to a charging source.")); } document.addEventListener("batterycritical", onBatteryCritical); </script>
batterylow
This event is fired by the system. If you want to listen to the event you can do so using the document.addEventListener function and remove the listener using the document.removeEventListener function. The batterylow event is triggered whenever the battery level changes to a value lower than 15%.
Synopsis:
Event
Parameters:
- yourCallbackFunction(info)
-
The callback function that will be invoked on the batterylow event.
- info
- Type: JSON
An object with the pertinent information.
- level
- Type: Number
The percentage of the battery charge (0-100).
- isPlugged
- Type: Boolean
A boolean that represents whether or not the device is receiving a charge.
Example:
<script type="text/javascript"> function onBatteryLow(info) { alert("The battery level is low: " + info.level + (info.isPlugged ? "." : ". Consider connecting your device to a charging source.")); } document.addEventListener("batterylow", onBatteryLow); </script>
batterystatus
This event is fired by the system. If you want to listen to the event you can do so using the document.addEventListener function and remove the listener using the document.removeEventListener function. The batterystatus event is triggered whenever the battery level changes, device starts to receive a charge, or device stops receiving a charge.
Synopsis:
Event
Parameters:
- yourCallbackFunction(info)
-
The callback function that will be invoked on the batterystatus event.
- info
- Type: JSON
An object with the pertinent information.
- level
- Type: Number
The percentage of the battery charge (0-100).
- isPlugged
- Type: Boolean
A boolean that represents whether or not the device is receiving a charge.
Example:
<script type="text/javascript"> function onBatteryStatusChange(info) { console.log("The device " + (info.isPlugged?"is ":"is not ") + "plugged in with " + info.level + "% battery remaining"); } document.addEventListener("batterystatus", onBatteryStatusChange); </script>
datalockstatechanged
This event is fired by the system. If you want to listen for the event, you can do so using the document.addEventListener function. To remove the listener, use the document.removeEventListener function. The datalockstatechanged event is triggered whenever the data lock state changes. If advanced data at rest protection is not enabled, then this event is never fired.
For more information about advanced data at rest protection, see Creating apps that are data lock aware.
Synopsis:
Event
Parameters:
- yourCallbackFunction(info)
-
The callback function that will be invoked on the batterystatus event.
- info
- Type: JSON
An object with the pertinent information.
- state
- Type: String
The current Data Lock state. Possible values are "notLocked", "lockPending", "dataLocked", and "startupLocked".
- lockTime
- Type: Number
The time stamp when the data lock state will switch from "lockPending" to "dataLocked". If the current state is not "lockPending", this value is zero.
fontchanged
This event is fired by the system. If you want to listen to the event you can do so using the document.addEventListener function and remove the listener using the document.removeEventListener function. The fontchanged event is triggered whenever the font setting of the system is changed.
Synopsis:
Event
Parameters:
- yourCallbackFunction(fontInfo)
-
The callback function that will be triggered on the fontchange event.
- fontInfo
- Type: JSON
The Object that contains the information of the new system font.
- fontFamily
- Type: String
The font family of the new system font.
- fontSize
- Type: String
The font size of the new system font.
Example:
<script type="text/javascript"> function onFontChange(fontInfo) { console.log("The system font has changed to " + fontInfo.fontFamily + " size " + fontInfo.fontSize); } document.addEventListener("fontchanged", onFontChange); </script>
languagechanged
This event is fired by the system. If you want to listen to the event you can do so using the document.addEventListener function and remove the listener using the document.removeEventListener function. The languagechanged event is triggered whenever the language setting of the device is changed.
Synopsis:
Event
Parameters:
- yourCallbackFunction(newLanguage)
-
The callback function that will be triggered on the languagechange event.
- newLanguage
- Type: String
The new language setting of the device. Its format conforms to BCP47.
Example:
<script type="text/javascript"> function onLanguageChange(newLanguage) { console.log("The language has changed to " + newLanguage); } document.addEventListener("languagechanged", onLanguageChange); </script>
perimeterlocked
This event is fired by the system. If you want to listen to the event you can do so using the document.addEventListener function and remove the listener using the document.removeEventListener function. The perimeterlocked event is triggered whenever the work perimeter (work space) is locked. Note: This event is not fired for non-corporate apps.
When the work perimeter is locked:
- Individual apps running in the work perimeter are locked and their active frames are replaced with a lock graphic, hiding their content.
- Apps that appear in both the work and personal perimeters stop exposing work perimeter content (for example, work email).
- Tapping a locked work app calls the unlock prompt. The app is not visible until the work perimeter password is entered. Users can synchronize their device password with their work perimeter password, so one password can unlock both the device and the work perimeter.
Synopsis:
Event
Parameters:
- yourCallbackFunction( )
-
The callback function that will be triggered on the perimeterlocked event.
Example:
<script type="text/javascript"> function onPerimeterLocked() { alert("The corporate app is locked!"); } document.addEventListener("perimeterlocked", onPerimeterLocked); </script>
perimeterunlocked
This event is fired by the system. If you want to listen to the event you can do so using the document.addEventListener function and remove the listener using the document.removeEventListener function.
The perimeterunlocked event is triggered whenever the corporate or enterprise app is unlocked. Note 1: When the corporate app is first launched, it is considered unlocked. No message is sent on startup of the app. Note 2: This event is not fired for non-corporate apps.
Synopsis:
Event
Parameters:
- yourCallbackFunction( )
-
The callback function that will be triggered on the perimeterunlocked event.
Example:
<script type="text/javascript"> function onPerimeterUnlocked() { console.log("The corporate app is unlocked!"); } document.addEventListener("perimeterunlocked", onPerimeterUnlocked); </script>
regionchanged
This event is fired by the system. If you want to listen to the event, you can do so using the document.addEventListener function. You can remove the listener using the document.removeEventListener function. The regionChanged event is triggered whenever the regional setting of the device is changed.
Synopsis:
Event
Parameters:
- yourCallbackFunction(newRegion)
-
The callback function that will be triggered on the regionchanged event.
- newRegion
- Type: String
The new regional setting of the device. Its format conforms to BCP47.
Example:
<script type="text/javascript"> function onRegionChange(newRegion) { console.log("The current region has changed to " + newRegion); } document.addEventListener("regionchanged", onRegionChange); </script>
dataLockState
Returns the data lock state of the device. The possible states are: "dataLocked", "lockPending", "notLocked", and "startupLocked".
For more information about data lock states and advanced data at rest protection, see Creating apps that are data lock aware.
Synopsis:
read-only String blackberry.system.dataLockState
dataLockTime
Returns the time stamp when the dataLockState will change from "lockPending" to "dataLocked". If the current state is not "lockPending", the value returned is 0.
For more information about advanced data at rest protection, see Creating apps that are data lock aware.
Synopsis:
read-only number blackberry.system.dataLockTime
deviceLockedStatus
Returns the locked state of the device. The possible states are: "passwordLocked", "notLocked", or "screenLocked".
Synopsis:
read-only String blackberry.system.deviceLockedStatus
hardwareId
Returns the hardware identifier for the device.
Synopsis:
read-only String blackberry.system.hardwareId
language
Returns the current UI language for the device. Examples of possible values include, but are not limited to "fr-FR", "en-US", and "es-ES". The format of the response conforms to BCP47.
Synopsis:
read-only String blackberry.system.language
name
Returns "RIM BlackBerry Device".
Synopsis:
read-only String blackberry.system.name
region
Returns the current region setting for the device. The region determines the format of items such as the date, time, numbers, and the calendar. Examples of possible values include, but are not limited to "fr-CA", "en-CA", "en-US", and "es-ES". The format of the response conforms to BCP47.
Synopsis:
read-only String blackberry.system.region
softwareVersion
Returns the current version of the operating system, for example, 10.2.1.537.
Synopsis:
read-only String blackberry.system.softwareVersion
Last modified: 2014-11-07
Got questions about leaving a comment? Get answers from our Disqus FAQ.
comments powered by Disqus