The bar-descriptor.xml file

Every BlackBerry 10 application is packaged in a .bar file that is deployed to a device or simulator.

You can configure the appearance and behavior of your application by specifying properties and values in the bar-descriptor.xml file. When you build your application, the bar-descriptor.xml file is automatically included in your .bar file.

The bar-descriptor.xml file is an XML file that is defined by a Document Type Definition (DTD).

The root element in the bar-descriptor.xml file is <qnx>. You must nest all other XML elements within this element.

If you create a bar-descriptor.xml file in your Momentics IDE project, it's 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-nativepackager tool.

The bar-descriptor.xml file specifies parameters and permissions for identifying, installing, and running native applications on the BlackBerry 10 OS. In the bar-descriptor.xml file, you can configure the following settings for your app:

  • General information such as application name, author, icon, and window transparency
  • Application-specific information such as category, orientation, and theme
  • Assets to include in your app and build configurations for your app
  • Information about languages, icons, and splash screens that your app supports

You can view the bar-descriptor.xml file by expanding a project from the Project Explorer view, and double-clicking the bar-descriptor.xml file. Within the file, you can enable features by setting options from the General tab, Application tab, Assets tab, and Localization tab, or by directly editing the XML on the Source tab.

One of the most important functions of the bar-descriptor.xml file is to configure the permissions that your app has on the device. To learn more, see App permissions.

General tab

The General tab shows the content that's applicable to all build configurations for a project.

Screen showing the General tab of the bar-descriptor.xml file in the Momentics IDE.

Explore General tab specifications

Read more

Package Information

The package information uniquely describes your application. Package information includes the following elements:

Package Name (<id>)

This field contains a universally unique application identifier (UUID) that must be unique across all BlackBerry 10 applications. We recommend that you use a reverse DNS-style name for the ID, such as com.example.MyExampleApplication. This identifier name is displayed in the BlackBerry 10 application setup application, and it may have multiple values for each language.

Package Version (<versionNumber>)

This field, combined with the Package Build ID, specifies the full version number for the application. This version number is a series of four numbers separated by decimals (for example 1.0.5.357) in this format: Major.Minor.Revision.Build. The default is 1.0.0.1. This number is interpreted as the minimum API level that your application requires. You must have an installed API level that covers the specified platform version.

The versionNumber specifies the first one, two, or three numbers of the version number. For example, 10, 10.1, or 10.2.1. The buildId is the fourth part of the package version. The first number must be an integer from 1 to 65535, inclusive. The remaining three numbers must be an integer value from 0 to 65535. Leading zeroes are not permitted. For example, 1.0.1.130 is valid, but 1.01.1.130 isn't valid because "01" is not supported.

Package Build ID (<buildId>)

This is an optional field. You can set the Package Build ID field using the Momentics IDE or the blackBerry-nativepackager tool. If you want the Momentics IDE to update this number whenever you perform a build, use the Use internal build number XML element in your bar-descriptor.xml file. You can set this element on the Source tab.

You can also specify the build number using the buildId command-line option when you package your application using the blackberry-nativepackager tool. If you specify a build number in both the bar-descriptor.xml file and the blackberry-nativepackager tool, the value given to the blackberry-nativepackager tool is used.

Use build number file (<buildIdFile>)

Extract the current value of <buildId> into a file named buildnum in the project, and then automatically manage the build ID when packaging .bar files. If there is no <buildId>, then the Momentics IDE sets the initial value to 1. When the build ID is read from a file, the Package Build ID field is disabled. If the file referenced in the <buildIdFile> element doesn't exist, the Momentics IDE displays a warning.

The default is 1.

Author Information

The author information represents the name and identifier information associated with the project for the specified debug token.

Author (<author>)

The name of the author associated with the project. This name is typically the name of the author used for signing, and it must match the developer name of your development certificate.

The default is Example Inc.

Author ID (<authorId>)

The unique ID assigned by the signing authority. Your identifier is the same for all your debug tokens.

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.

Set From Debug Token

Import the name and identifier from a debug token.

API Level

The API Level identifies which platform version is used when you package your application. There are two options:

Use the API level from the project settings (recommended)
Specifies that your application is compatible with the API level that you set globally or in the project properties.
Explicitly set the platform version.
Specifies the minimum platform version. It can be one to four numeric segments, such as 10.2.0. You must have an installed API level that targets the specified platform version.

Problems

The problems area identifies the number of warnings and errors in the bar-descriptor.xml file.

Related Settings and Actions

The Related Settings and Actions area has links to wizards to help you configure the Momentics IDE, targets, package signing, and debug tokens.

Application tab

The Application tab maintains the attributes for the application entry point. Some items such as entry point name, description, icon, and splash screen may be localized for different languages. You can edit language-specific versions of these items on the Localization tab.

This tab also allows you to specify permissions that are required for accessing certain features on the device, such as the camera or file system. To learn about the permissions that you can specify, see App permissions.

You can also specify app icons and splash screens for BlackBerry 10 devices with different resolutions.

You can specify the theme of your app (dark, bright, default) by using the Theme drop-down list on the Application tab. The theme settings decide the look and feel of your visual elements, including font color, background color, and shading.

10.3 If you are using an API level of 10.3 or later, you can also specify customized colors for your theme by using the Primary color and Primary base color fields. For more information about setting themes, see Themes.

Screen showing the Application tab of the bar-descriptor.xml file in the Momentics IDE.

Explore Application tab specifications

Read more

General

The general information describes your application.

Category (<category>)

Optional. Specifies how to categorize your app. This value is no longer used for devices that are running BlackBerry 10 OS. The value can be one of:

  • (Uncategorized): Your application appears under the All category.
  • Games (core.games): Your application appears under the Games category on the BlackBerry 10 OS home screen.
  • Media (core.media): Your application appears under the Media category on the BlackBerry 10 OS home screen.

You can specify only one element of this type in your bar-descriptor.xml configuration file. By default, if no category is specified (Uncategorized), your application appears under the All category.

Orientation (<autoOrients>, <aspectRatio>)

Set the orientation for the application according to the physical orientation of the device or explicitly fixed in a particular orientation. This orientation option lets you control the rotation of the content on the screen so that it's easier to view on the device:

  • Default: Use the default orientation for the device.
  • Auto-orient: The screen orientation changes according to the orientation of the BlackBerry device. By default, if you don't specify the orientation element, don't specify it with any attributes, or specify it incorrectly, the orientation is set to auto. To set this value, use <autoOrients>true</autoOrients>.
  • Landscape: The screen orientation remains in landscape orientation, regardless of the orientation of the device. To set this value, use <aspectRatio>landscape</aspectRatio>.
  • Portrait: The screen orientation remains in portrait orientation, regardless of the orientation of the device. To set this value, use <aspectRatio>portrait</aspectRatio>.
Chrome (<initialWindow>, <systemChrome>)

Optional. The type of system chrome to use (such as the borders, title bar, menu bar, and window control buttons). You can specify:

  • standard: Your application uses the standard system chrome elements. A window that uses system chrome is always opaque.
  • none: Your application is transparent. The application must provide its own mechanisms for controlling the window and its background.

The default is none if nothing is specified.

Theme Settings

Theme Settings allow you to force your app to use a particular visual style.

Theme

You can specify the theme of your app by using the Theme drop-down list on the Application tab or you can manually edit the bar-descriptor.xml file to add an environment variable that specifies the theme that you want. The environment variable is called CASCADES_THEME and you can set it to either bright or dark. Here's the bar-descriptor configuration to force your app to use a dark style:

<env var="CASCADES_THEME" value="dark"/>
Primary color and Primary base color

If you are using an API level of 10.3 or later, you can specify customized colors for your theme by using the Primary color and Primary base color fields or you can manually edit the bar-descriptor.xml file to add an environment variable that specifies the primary and primary base that you want. The environment variable is called CASCADES_THEME and it's also used to specify the visual style for the app. Primary and primary base colors are specified using hex values. Here's the bar-descriptor.xml configuration to use the default theme with a primary color and primary base color:

<env var="CASCADES_THEME" value="default?primaryColor=0xDE5A5A&amp;primaryBase=0xCC0000"/>

Here's the bar-descriptor.xml configuration to force a bright theme and use a primary color with no primary base color:

<env var="CASCADES_THEME" value="bright?primaryColor=0xDE5A5A"/>

Permissions (<permission>)

The BlackBerry 10 device contains functionality that can capture rich information from its environment. To help protect against potentially malicious code, users must grant your application access to the functionality. For example, the user must grant your application permission to use the GPS or the microphone.

Permissions allow you to specify the device capabilities that your application needs to access.

Permission to run native code, which is required for all applications created using the BlackBerry 10 Native SDK, is set by default with this entry in the bar-descriptor.xml file: <permission system="true">run_native</permission>

For more information about the available application permissions, see App permissions.

Entry-Point Text and Images

Text and graphics that the BlackBerry 10 OS Navigator uses to represent your application.

Name (<name>)

The name that's displayed in the BlackBerry 10 OS application setup application. The name might have multiple values for each language.

By default, the name is set to the file name associated with your project for your application.

Description (<description>)

A brief description of your application. By default, the description is set to the description you initially assigned to your project.

Icon (<icon>, <image>)

The icon to display for your application in the BlackBerry 10 OS home screen. The icon must be listed as an asset in your .bar file, and can be a .png, .jpg, .jpeg, .gif, or .bmp file. You can specify icons with different sizes for specific device resolutions.

You specify the file name for the icon within the <image> element (for example, <icon><image>icon.png</image></icon>). For more information about designing application icons, see Application icons in the BlackBerry UI Guidelines.

You can locate an icon that the system uses for the application by using the Add button. The icon for your project can be a .png, .jpg, .jpeg, .gif, or .bmp file. You can also drag the icon asset from the Project Explorer or from the file browser on your computer, and then drop it onto the Icon field.

Splash Screens (<splashScreens>)

The image to display while the device loads your application. You can specify up to two files (used if your application supports rotation; one for each portrait and landscape orientation). If you specify one file, the device displays the file in a landscape orientation. If you specify two files, the first file is used when the device is in landscape orientation, and the second file is used when the device is in portrait orientation. The image for your splash screen must be included in your .bar file and can be a .png, .jpg, .jpeg, .gif, or .bmp file.

The screen resolution of your device can be found in Different screen sizes in the BlackBerry UI Guidelines. Your splash screen should be the entire resolution size to fill the screen.

You can drag the splash screen assets from the Project Explorer or from the file browser on your computer, and then drop it onto the Splash Screens field.

Assets tab

The Assets tab lets you manage the assets packaged in the application's.bar file. Assets can be configuration-specific, meaning that each different build configuration (Device-Debug, Device-Release, Device-Profile, Simulator-Debug) can use a unique set of assets. Using the Assets tab to manage assets is not as flexible as the Source editor because:

  • The primary purpose of build configurations is the packaging of different variants of the application code and data assets, such as for debugging or for different target architectures. Other application metadata, such as the name, icon, window characteristics, permissions, and other entry-point attributes, are configuration-independent.
  • If you require specific configuration details, the Source tab provides full access to the bar-descriptor.xml file. The Assets tab might not include configuration-specific data; in this case the page displays warning annotations.

You can change the assets by updating your bar-descriptor.xml file, or you can update assets by using a command-line option when you package an application using the blackberry-nativepackager tool. If you specify assets in both the bar-descriptor.xml file and by using the blackberry-nativepackager tool, the assets packaged using the blackberry-nativepackager tool are used.

Screen showing the Assets tab of the bar-descriptor.xml file in the Momentics IDE.

Add assets for the application to use at runtime

Read more
  1. Select and expand a project in the Project Explorer view, and then double-click bar-descriptor.xml in your project.
  2. In the bar-descriptor.xml, click Assets then click (All Configurations).
  3. In the Assets section, click Add.
  4. In the dialog box, click Workspace and select the file you want to the application to use.
  5. Click OK and then Save.

Copy files from your device or simulator to your project

Read more
  1. Establish a connection to your device or simulator.
  2. Open the QNX System Perspective (select Window > Open Perspective > Other, and then select QNX System Information). Or open the Target File System Navigator view directly (select Window > Show View > Other, and then type Target File System Navigator to select it from the list).
  3. On the left in the Target File System Navigator view, select and expand the target device or simulator you want to use.

    If the selected target for your device or simulator indicates that it is not currently connected, from the Target Navigator view, right-click on your target and select Connect.

  4. Navigate to the folder that you want to copy files from.
  5. Drag and drop any required assets from the target to a location on your computer. Or use the Copy To command to copy assets (In the Target File System Navigator view, right-click a file, then select Copy To > File System, and the use the Browse For Folder dialog box to specify the location to copy to.)

    For information about the folders (such as Sandbox, Shared, Developer, and System), see Accessing the file system .

Explore Asset tab specifications

Read more

Build Configurations (<configuration>)

Select the build configuration to specify assets for.

  • (All Configurations) — All configurations
  • Device-Debug — Create a debug version of your application for the device for debugging purposes.
  • Device-Release — Create a release version of your application for the device; as small an executable as possible, without any debug code. You must use this configuration when you are preparing your app for distribution in BlackBerry World.
  • Device-Profile — Create a version of your application for the device for profiling purposes.
  • Simulator-Debug — Create a version of your application to use on the simulator.

To create a build configuration, click Add. Normally, build configurations are created for you when you select a launch mode and a launch Configuration and click Launch on the toolbar.

To create a duplicate build configuration based on the configuration type selected from the Build Configurations list, click Duplicate. The new configuration is created as <configuration name="New_Configuration_Name">.

To remove the selected build configuration from the list, click Remove.

To open a dialog box that allows you to create, remove, or rename build configurations, click Edit.

Assets (<asset>)

Update the table of assets by selecting assets from anywhere inside and outside of the workspace, and then assign types to indicate their runtime and packaging semantics. Additionally, where appropriate, you can move or copy selected assets from the workspace or your computer's filesystem by using drag-and-drop.

The asset is created as: <asset path="Asset_Location">.

  • Source Path — the source location and source file name used for an asset.
  • Target Path — the target file name to be used for an asset.
  • Type — the corresponding type for an asset, such as Entry-point or Other.

An asset that can't be resolved to a file on disk is annotated with a warning icon and a tooltip gives an overview of the problem. A problem marker in the Problems view also reports the error, with the text marker attributes that link to the particular <asset> element in the Source view of the XML file.

To add an asset to the project, click Add Files or Add Folders.

To delete an asset from the project, click Remove.

Hide assets common to all configurations

Hides the display of assets from the Assets list that are common to and included in all of the configurations listed in the (All Configurations) list.

Related Settings

Provides a direct link to the C/C++ Build Settings, which are critical to the generation of the assets included in the package.

Localization tab

The Localization tab shows the options for localization support.

When you click Add, the Add Localizations dialog box includes all of the locales supported by the BlackBerry 10 OS. The simplest mode of operation is one that is untranslated, in which you type the name, description, or image asset path without selecting a language. In the bar-descriptor.xml file, this technique generates an element such as <name> that contains a single string. For translated content, you specify the text or asset for each language annotated by the language code. The result in the bar-descriptor.xml file looks like the following for US English and German:

<name>
<text xml:lang="en_US">...</text>
<text xml:lang="de_DE">...</text>
</name> 
Screen showing the Localization tab of the bar-descriptor.xml file in the Momentics IDE.

Explore Localization tab specifications

Read more

Language (<packageLocale>)

Sets the languages used to localize your application. The language is set as: <packageLocale> Language_Code1,...,Language_CodeN </packageLocale>.

To open the Add Localizations dialog box from which you can select the languages that are supported by the target OS version, click Add.

To delete the selected language from the list, click Remove.

To specify an extra locale that doesn't currently appear in the Add Locations dialog box, use the Other field and click Add.

If the name you specify doesn't conform to an IETF BCP 47 language tag, you receive a warning icon to the left of the field.

Entry-Point Text and Images

Information and images to provide to the device for the selected locale of your specific application.

Name (<name>)

The name displayed in the application setup application for the selected locale. The name might have multiple values for each language. The name is set as: <name> my_app_name <text xml:lang="language_code"></name>

By default, the name is set to the file name associated with your project for your application.

Description (<description>)

A brief description about your application for the selected locale. The description is set as: <description> my_app_name <text xml:lang="language_code"></description>

By default, the description is set to the description you initially assigned to your project.

Icon (<icon>, <image>)

The icon to display for the selected language in the BlackBerry 10 OS home screen. The icon must be included in your .bar file, and can be a .png, .jpg, .jpeg, .gif, or .bmp file. You can specify icons with different sizes for specific device resolutions.

You specify the file name for the icon within the <image> element (for example, <icon> <image> Image_Name <text xml:lang="Language_Code"></image></icon>). For more information about designing application icons, see Application icons in the BlackBerry UI Guidelines.

You can locate an icon that the system uses for the application by using the Add button. The icon for your project can be a .png, .jpg, .jpeg, .gif, or .bmp file. You can also drag the icon asset from the Project Explorer or from the file browser on your computer, and then drop it onto the Icon field.

Splash Screens (<splashScreens>)

The image to display while the device loads your application for the selected language. You can specify up to two files (used if your application supports rotation; one for each portrait and landscape orientation). If you specify one file, the device displays the file in a landscape orientation. If you specify two files, the first file is used when the device is in landscape orientation, and the second file is used when the device is in portrait orientation. The image for your splash screen must be included in your .bar file and can be a .png, .jpg, .jpeg, .gif, or .bmp file.

The screen resolution of your device can be found in Different screen sizes in the BlackBerry UI Guidelines. Your splash screen should be the entire resolution size to fill the screen.

You can drag the splash screen assets from the Project Explorer or from the file browser on your computer, and then drop it onto the Splash Screens field.

Source tab

The Source tab provides a text editor to access the contents of the bar-descriptor.xml file for advanced editing purposes. You can copy and paste options from external sources, and access elements that aren't displayed on the General, Application, Assets, and Localization tabs (such as comments).

This tab offers syntax highlighting, content assist (based on the XML schema), validation, and problem markers and annotations. Changes made on the Source tab are automatically updated in the contents of the other tabs. In addition, changes made on the General, Application, and Asset tabs are also immediately reflected on the Source tab.

For more details, see The application descriptor file DTD.

Screen showing the Source tab of the bar-descriptor.xml file in the Momentics IDE.

Validating your bar-descriptor.xml file

It's a good idea to validate your bar-descriptor.xml file to make sure that your app deploys correctly. You can validate the contents of your bar-descriptor.xml file using the following techniques:

  • The Problems view links to the XML elements in the Source tab. These identifiers are created by a validation builder for BlackBerry projects. You can scroll through the errors, warnings, or information to find problems in your bar-descriptor.xml file. You can also use a filter to show only problems in the bar-descriptor.xml file. To open the Problems view click Window > Show View > Problems.

    Screen showing the Problems view when there are errors in the bar-descriptor.xml file.

  • If there are problems in your bar-descriptor.xml file, the General tab displays a warning icon and a tooltip with the number of problems in the Problems area.

    Screen showing the Problems area in the General tab of the bar-descriptor.xml file when there are errors.

  • Annotations are automatically generated as you edit and change the bar-descriptor.xml file. Incorrect data is annotated in place. For example, an unresolved asset in the Assets tab can result in an annotation of the Assets tab header.

    Screen showing the warning displayed in the header of the Assets tab of the bar-descriptor.xml file when there are errors.

  • On the Application tab or Localization tab, missing icons or splash screens are highlighted with a warning icon beside the Device Icon Sizes or Device Splash Screen Sizes links. When you click the link, a dialog box shows you which images are missing and which images are incorrectly sized.

    Screen showing missing or incorrectly sized icons in the bar-descriptor.xml file.

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus