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. The bar-descriptor.xml specifies parameters for identifying, installing, and running applications on the BlackBerry 10 OS and is also used to specify permissions. When you build your application, the bar-descriptor.xml file is automatically included in your .bar file.

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

You can view the bar-descriptor.xml file for your own project by expanding the project in the Project Explorer view and double-clicking the bar-descriptor.xml file. You can switch pages by clicking the tabs at the bottom of the editor. In the file, you can enable features by setting options from the General page, Application page, Assets page, and Localization page, or by directly changing the bar-descriptor.xml options on the Source page.

For details about the individual configuration settings, see Configure your project and Configure bar-descriptor.

General page

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

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

Application page

The Application page maintains the attributes for the application entry point. Because you can localize the entry point name, description, icon, and splash image, they appear in a detail view that's determined by your language selection on the Localization page.

This page 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.

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

Assets page

The Assets page lets you manage the assets packaged in the application' file. Assets can be configuration-specific, meaning that each different build configuration (Device-Debug, Device-Release, Simulator-Debug) can use a unique set of assets. Using the Assets page 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 page provides full access to the bar-descriptor.xml file. The Assets page might not include configuration-specific data; in this case the page displays warning annotations.
Screen showing the Assets page of the bar-descriptor.xml file in the Momentics IDE.

Localization page

The Localization page shows the options for localization support.

When you click Add, the Add Localizations drop-down list 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 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:

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

Source page

The Source page 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 pages (such as comments).

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

For more details, see The application descriptor file DTD.

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

Last modified: 2014-01-23

comments powered by Disqus