The bar-descriptor.xml file

As of BlackBerry Tablet OS SDK version 2.0 Beta, the blackberry-tablet.xml has been renamed to bar-descriptor.xml.

You can configure the appearance and behavior of your application in the BlackBerry Tablet OS by specifying XML elements and values in the bar-descriptor.xml file. If you create an XML configuration file in your Adobe Flash Builder project, it is automatically included in your BAR file. If you package your application from the command line, be sure to specify the bar-descriptor.xml file when you run the blackberry-airpackager tool.

The following table describes the elements of the configuration file:

XML element

Description

action

Specifies the device capability to which your application requires access. For example, the user must grant your application permission to use the GPS or the microphone. The BlackBerry Tablet OS prompts the user to allow your application to use any device capability you specify in this element. You can specify one action element per capability.

For a list of device capabilities, see Accessing restricted functionality.

author

Specify a value for this element when you intend to run your application on a device using a debug token. This value should match the Author value from your debug token.

For more information about how to use this element, see Using debug tokens.

authorId

Specify a value for this element when you intend to run your application on a device using a debug token. This value should match the Author Id value from your debug token.

For more information about how to use this element, see Using debug tokens.

buildId

Specifies the fourth segment of the version number for an application. This value must be between 0 - 65535. For more information about version numbers, see Assigning a version number to your application.

category

Specifies the BlackBerry Tablet OS Home screen category in which your application should appear. The value must be one of:

  • core.games
  • core.media

This element is optional. You can specify one element of this type in your bar-descriptor.xml configuration file. All applications appear in the All category by default. Your application appears in the category you specified using this element and the All category.

icon

Specifies the icon to display in the BlackBerry Tablet OS Home screen. Your icon should be 86-by-86 pixels. An icon that is larger than 86-by-86 pixels will not display on the screen.

The icon must be included in your BAR file and can be a PNG file or JPG file. You specify the file name for the icon within an XML element named image.

<icon>
    <image>my_icon_image_file.png</image>
</icon>

platformVersion

Specifies the minimum version of the BlackBerry Tablet OS required to run the application. The default is 1.0.0.0.

qnx

Specifies a BlackBerry Tablet OS configuration file. This is the root XML element in bar-descriptor.xml. Nest all other elements in this table within this element.

splashscreen

Specifies the images to display while the BlackBerry Tablet OS loads your application. You can specify up to two files separated by a colon (":"). If you specify one file, the BlackBerry Tablet OS displays the file in a landscape orientation. If you specify two files, the first file is used when the tablet is in a landscape orientation, and the second file is used when the tablet is in a portrait orientation.

The image for your splash screen must be included in your BAR file and can be a PNG file or JPG file. The screen resolution of the BlackBerry PlayBook tablet is 1024 by 600 pixels in default, landscape orientation. Your splash screen should be this size to fill the screen.

Sample bar-descriptor.xml file

<qnx>
    <icon>
        <image>my_icon.png</image>
    </icon>
    <author>My Company</author>
    <authorId>gYAAgIqK0RLL5u4I9NanyxBUuCI</authorId>
    <category>core.games</category>
    <splashscreen>img/splash_landscape.jpg:img/splash_portrait.jpg</splashscreen>
    <action>use_camera</action>
    <action>read_geolocation</action>
    <action>play_audio</action>
    <buildId>349</buildId>
    <platformVersion>1.0.0.0</platformVersion>
</qnx>

Localization

You can manage multiple regions and languages by localizing attributes in the bar-descriptor.xml and <myApplication>-app.xml files. The following attributes can be localized.

In the <myApplication>-app.xml file:

  • name
  • description

In the bar-descriptor.xml file:

  • image
  • splashscreen

Sample localization syntax in <myApplication>-app.xml

<name>
<text xml:lang="en-US">localization</text>
<text xml:lang="fr-FR">localisation</text>
<text xml:lang="de-DE">lokalisation</text>
</name>