Setting orientation in the bar-descriptor.xml file

By default, an app starts in portrait orientation on a BlackBerry 10 device. You can choose a different orientation for your app to start in, as well as specify whether your app handles orientation changes, by using the orientation setting in the bar-descriptor.xml file of your project.

  1. In the Momentics IDE for BlackBerry, in the Project Explorer view, double-click the bar-descriptor.xml file.
  2. On the Application tab, in the Orientation drop-down list, select an orientation setting.
Screen showing bar-descriptor.xml file

The following table describes the orientation settings that are available:

Orientation setting Description
Default This setting orients your app to the default orientation for the type of device that your app is running on. This default orientation represents the typical position of the device when it's being used, which is usually portrait orientation.
Auto-orient This setting uses the physical position of the device to orient your app. The screen changes the orientation of the displayed app to match the orientation of the device. For example, if you're holding the device in portrait orientation and turn the device 90 degrees to be in landscape orientation, the screen changes to show the app in landscape orientation.
Landscape This setting locks the orientation of your app to landscape. Regardless of the physical position of the device, the app is displayed in landscape orientation only.
Portrait This setting locks the orientation of your app to portrait. Regardless of the physical position of the device, the app is displayed in portrait orientation only.

You can also edit the bar-descriptor.xml file manually by using the Source tab in the Momentics IDE. For example, in the Orientation drop-down list, click Landscape, and then click the Source tab. The bar-descriptor.xml file includes an entry that's similar to the following:

<initialWindow>
    <aspectRatio>landscape</aspectRatio>
    <autoOrients>false</autoOrients>
    <systemChrome>none</systemChrome>
</initialWindow>

You can change the <autoOrients> element to change the behavior of orientation events. If <autoOrients> is set to true:

  • The value of the <aspectRatio> element is ignored and your app receives all orientation change events. If you're using C APIs, the orientation environment variable is set to reflect the current orientation of the device.

If <autoOrients> is set to false:

  • You can specify the orientation that you want your app to run in by using the <aspectRatio> element.
  • If <aspectRatio> is set to portrait or landscape, you receive only in-aspect orientation change events. For example, if you specify landscape, you receive events of 0 to 180 degree transitions.

You can also set the orientation programmatically in your app. To learn how, see Setting orientation programmatically.

Last modified: 2015-07-24



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

comments powered by Disqus