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