Application tab

Note:

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.

Note:

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"/>

Note:

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.

Note:

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.