System

The System object allows you to get access to system level functions and attributes of the BlackBerry PlayBook.

The System object is static; all of its functions and properties are used directly from the object.


Code Example:
<script type="text/javascript">
// See if we are in coverage
   if (!blackberry.system.hasDataCoverage()) {
       alert("You are not in coverage, we will attempt to send later");
   }

   // Check if we have GPS capability
   if (blackberry.system.hasCapability("location.gps")) {
       alert("This PlayBook has a GPS.");
   }
</script>


Learning Resources:

Sample - Setting the Wallpaper Sample that demonstrates how to use the BlackBerry system.setWallpaper API [BlackBerry on GitHub].
Sample - Recognizing System Language Changes Sample that demonstrates how to work with device region and language changes [BlackBerry on GitHub].

Supported Platform(s)

- BlackBerry OS 5.0+
- BlackBerry PlayBook 1.0+
- BlackBerry 10
- Ripple Emulator
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.system.getCurrentTimezone           Y 
blackberry.system.getFontInfo           YY
blackberry.system.getTimezones           Y 
blackberry.system.hasCapability Y Y Y Y Y YY
blackberry.system.hasDataCoverage Y Y Y Y Y  Y
blackberry.system.hasPermission Y Y Y Y Y YY
blackberry.system.isMassStorageActive Y Y Y Y Y  Y
blackberry.system.setHomeScreenBackground Y Y Y      Y
blackberry.system.setWallpaper           Y 
http://localhost:8472/blackberry/system/get Y Y Y Y Y   
deviceLockedStatus           Y 
hardwareId           Y 
language           YY
model Y Y Y Y Y  Y
name           Y 
region           YY
scriptApiVersion Y Y Y Y Y  Y
softwareVersion Y Y Y Y Y YY
ALLOW Y Y Y Y Y YY
DENY Y Y Y Y Y YY
blackberry.system.batterycritical           Y 
blackberry.system.batterylow           Y 
blackberry.system.batterystatus           Y 
blackberry.system.fontchanged           Y 
blackberry.system.languagechanged           Y 
blackberry.system.perimeterlocked           Y 
blackberry.system.perimeterunlocked           Y 
blackberry.system.regionchanged           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" /> Y Y Y Y Y YY

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.



Properties

String deviceLockedStatus
String hardwareId
String language
String model
String name
String region
String scriptApiVersion
String softwareVersion

Constants

Number ALLOW
Number DENY

URI Functions

JSON of all the properties http://localhost:8472/blackberry/system/get

Functions

static String blackberry.system.getCurrentTimezone ()


Retrieves the time zone currently used by the device.


Supported Platforms
 - BlackBerry 10


Code Example:
function getCurrentTimezone() {
    return blackberry.system.getCurrentTimezone(); // e.g. "America/New_York"
}

static Object blackberry.system.getFontInfo ()


Returns the information of current system font, which is composed of the font family and font size.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator


Return:

Returns the JavaScript Object that contains fontFamily and fontSize properties.



Code Example:
<script type="text/javascript">
// Check system font information
var fontInfo = blackberry.system.getFontInfo();
alert("The font family of current system font is " + fontInfo.fontFamily + "\n" + "The size of current system font is " + fontInfo.fontSize);
</script>

static String[] blackberry.system.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.


Supported Platforms
 - BlackBerry 10

static Boolean blackberry.system.hasCapability (capability : String)


This method will determine if the BlackBerry PlayBook or the BlackBerry Smartphone device is capable of the given service.

hasCapability() returns true if the BlackBerry device is capable of the service; false otherwise.

The supported string values for 'capability' are:
input.keyboard.issuretype (returns 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 SD 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.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator


Parameters
capability The capability being checked for.

Return:

Returns true if the device is capable of the given service.


static Boolean blackberry.system.hasDataCoverage ()


This method returns true so long as the device is connected to any network. This can be used in conjunction with the network property to find out what kind of coverage it is in. On the smartphone this can be used in conjunction with blackberry.system.event.onCoverageChange to track changes.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Return:

Returns true if the BlackBerry PlayBook or the BlackBerry Smartphone device has any network interface active, otherwise returns false. Always returns true on the PlayBook simulator. Please note, that on the PlayBook device, there might be a small delay of 2-3 seconds between the time the device connects until the method returns true.


static Number blackberry.system.hasPermission (module : String)


Determines the level of access to the requested module.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator


Parameters
module The BlackBerry WebWorks namespace or class to check for access. For example blackberry.system, blackberry.app.

Return:

The possible return values: 0 - ALLOW 1 - DENY


static Boolean blackberry.system.isMassStorageActive ()


Returns whether USB MassStorage mode is active.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Return:

Always returns false on the BlackBerry PlayBook since Mass Storage Mode is not supported. All memory is presented as a network share when connected by USB and is not blocked.


static void blackberry.system.setHomeScreenBackground (uri : String)


Set the image that appears as the background of the Home screen on a BlackBerry device.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Parameters
uri URI path to an image file that resides in flash memory or a microSD Card.

static void blackberry.system.setWallpaper (filePath : String)


Set the wallpaper using the path to the file provided.


Supported Platforms
 - BlackBerry 10


Parameters
filePath Path to the file to be used as wallpaper.

Events

blackberry.system.batterycritical


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The batterycritical event is triggered whenever the battery level changes to the value lower than 5%.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the batterycritical event

info: An object the pertinent information
info.level: The percentage of the battery charge (0-100).
info.isPlugged: A boolean that represents whether or not the device is receiving a charge.

Code 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."));
}

blackberry.event.addEventListener("batterycritical", onBatteryCritical);

</script>

blackberry.system.batterylow


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The batterylow event is triggered whenever the battery level changes to the value lower than 15%.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the batterylow event

info: An object the pertinent information
info.level: The percentage of the battery charge (0-100).
info.isPlugged: A boolean that represents whether or not the device is receiving a charge.

Code 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."));
}

blackberry.event.addEventListener("batterylow", onBatteryLow);

</script>

blackberry.system.batterystatus


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The batterystatus event is triggered whenever the:

  • battery level changes
  • device starts to receive a charge
  • device stops receiving a charge


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the batterystatus event

info: An object with the pertinent information
info.level: The percentage of the battery charge (0-100).
info.isPlugged: A boolean that represents whether or not the device is receiving a charge.

Code Example:
<script type="text/javascript">

function onBatteryStatusChange(info) {
  alert("The playbook " + info.isPlugged?"is ":"is not " + "plugged in with " + info.level + "% battery remaining");
}

blackberry.event.addEventListener("batterystatus", onBatteryStatusChange);

</script>

blackberry.system.fontchanged


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The fontchanged event is triggered whenever the font setting of the system is changed.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be triggered on the fontchange event.

fontInfo: The Object that contains the information of the new system font.
fontInfo.fontFamily: The font family of the new system font.
fontInfo.fontSize: The font size of the new system font.

Code Example:
<script type="text/javascript">

function onFontChange(fontInfo) {
  alert("The system font has changed to " + fontInfo.fontFamily + " size " + fontInfo.fontSize);
}

blackberry.event.addEventListener("fontchanged", onFontChange);
</script>

blackberry.system.languagechanged


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The languagechanged event is triggered whenever the language setting of the device is changed.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be triggered on the languagechange event.

newLanguage: The new language setting of the device. Its format conforms to BCP47.

Code Example:
<script type="text/javascript">

function onLanguageChange(newLanguage) {
  alert("The laguage has changed to " + newLanguage);
}

blackberry.event.addEventListener("languagechanged", onLanguageChange);
</script>

blackberry.system.perimeterlocked


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The perimeterlocked event is triggered whenever the corporate or enterprise application is locked.
Note: This event is not fired for non-corporate apps.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be triggered on the perimeterlocked event.

Code Example:
<script type="text/javascript">

function onPerimeterLocked() {
   alert("The corporate app is locked!");
}

blackberry.event.addEventListener("perimeterlocked", onPerimeterLocked);
</script>

blackberry.system.perimeterunlocked


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The perimeterunlocked event is triggered whenever the corporate or enterprise application is unlocked.
Note 1: When the corporate application is first launched, it is considered unlocked. No message is sent on startup of the application.
Note 2: This event is not fired for non-corporate apps.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be triggered on the perimeterunlocked event.

Code Example:
<script type="text/javascript">

function onPerimeterUnlocked() {
   alert("The corporate app is unlocked!");
}

blackberry.event.addEventListener("perimeterunlocked", onPerimeterUnlocked);
</script>

blackberry.system.regionchanged


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The regionChanged event is triggered whenever the regional setting of the device is changed.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be triggered on the regionchange event.

newRegion: The new regional setting of the device. Its format conforms to BCP47.

Code Example:
<script type="text/javascript">

function onRegionChange(newRegion) {
  alert("The current region has changed to " + newRegion);
}

blackberry.event.addEventListener("regionchanged", onRegionChange);
</script>

Properties

static readonly String deviceLockedStatus


Returns the locked state of the device. The possible states are: passwordLocked, notLocked, or screenLocked.


Supported Platforms
 - BlackBerry 10

static readonly String hardwareId


Returns the hardware identifier for the device.


Supported Platforms
 - BlackBerry 10

static String language


Returns the current UI language for the device. 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.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static readonly String model


Returns the model number of the BlackBerry PlayBook or the BlackBerry Smartphone device.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator

static readonly String name


Returns the name of the device.


Supported Platforms
 - BlackBerry 10

static String region


Returns the current country 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.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static readonly String scriptApiVersion


Returns the current version of the operating system, for example, 1.0.0.0.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator

static readonly String softwareVersion


Returns the current version of the operating system, for example, 1.0.0.0.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

Constants

static Number ALLOW = 0


Returned by hasPermission() indicating that the module requested is accessible.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static Number DENY = 1


Returned by hasPermission() indicating that the module is not accessible.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

URI Functions

http://localhost:8472/blackberry/system/get


The objects in hasPermission will always be ALLOW (0). They will correspond to all the entries in the whitelist. If they are not whitelisted, they are omitted from the list. Similarly, all of the objects in hasCapability will be true, otherwise they will be omitted.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+


Return:
 {
    "data":{
        "hasCapability":[
            "location.gps",
            "media.audio.capture",
            "media.video.capture",
            "media.recording",
            "network.bluetooth",
            "network.wlan"
        ],
        "softwareVersion":"QNX",
        "hasPermission":[
            "blackberry.invoke",
            "blackberry.system",
            "blackberry.app",
            "blackberry.app.event",
            "blackberry.system.event",
            "blackberry.ui.dialog",
            "blackberry.utils"
        ],
        "model":100669958,
        "hasDataCoverage":true,
        "scriptApiVersion":"1.0.0.0",
        "isMassStorageActive":false
    }
} 


Code Example:
<html>
<head>
    <script type="text/javascript" src="js/jquery-1.4.2.js" ></script>
    <script type="text/javascript" src="js/jquery.form.js" ></script>
    <script type="text/javascript" src="js/jquery.populate.js" ></script>

    <script type="text/javascript">
         function getSystemData(){
             $.ajax({
                 type: "get",
                 url: "http://localhost:8472/blackberry/system/get",
                 success: function(msg){
                     $('#mySystemDiv').populate(JSON.parse(msg).data);
                 }
              });
          }
     </script>

</head>
<body>

   <input type="button" onclick="getSystemData();" value="Populate - System"/>
   <div id="mySystemDiv">
       Software Version: <span id="softwareVersion"></span><br/>
       Mass Storage Active: <span id="isMassStorageActive"></span>
   </div>

</body>
</html>
Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:10 GMT-0500 (EST)