Orientation is an important feature of most apps. You need to consider the purpose of your app when choosing which orientations to support. Portrait orientation for apps such as eReaders can increase the amount of information that's displayed on the screen at one time. Landscape orientation for apps such as movies or games can offer distinct benefits (such as using more screen space for widescreen videos) and can provide a better experience on all-touch devices. Depending on your app, you may want to support both portrait and landscape orientations and provide a different user experience for each one.
It's also important to consider how your UI looks in different orientations and handle orientation changes appropriately. Often, it isn't enough to just resize your UI components to reflect the new screen dimensions. For example, if you create an app with a list, it probably doesn't make sense to have the same UI for both portrait and landscape orientations, as you can see in the following images:
The number of displayed items and the screen space that's used are different for each orientation. When you design an app that works for both portrait and landscape orientations, it's important to think about how the different orientations look and what their strengths are. For example, in a photo browser app, it might make sense to restrict the folders list to portrait orientation only, but you might allow both portrait and landscape orientations when viewing individual photos.
Orientation changes don't apply to devices with a 1:1 aspect ratio (for example, the BlackBerry Q10 smartphone). For more information on how this aspect ratio affects your app, see Handling square screens.
There are two approaches that you can use to manage orientation changes in your apps. You can use Cascades APIs, which are based on C++ and provide a high-level abstraction of orientation events that you can handle. Or you can use C APIs, which are low-level functions that give you additional control over how you handle orientation changes and draw your UI in response.
Handling orientation using Cascades APIs
To specify the orientations that your app supports, force orientation changes, and respond to device orientation changes using Cascades APIs, you use the OrientationSupport class. This class includes three properties that determine how orientation is handled in your app:
- orientation: A read-only property that specifies the current orientation of the UI, either UIOrientation::Portrait or UIOrientation::Landscape
- displayDirection: A read-only property that specifies the angle between the device's natural orientation (with the BlackBerry logo right-side up and the screen facing the user) and the device's current direction
supportedDisplayOrientation: A property that specifies the display orientations that the app supports and restricts the values that orientation and displayDirection can have
You set the display orientations that your app supports by using the supportedDisplayOrientation property. This property can be set to one of the following values:
- SupportedDisplayOrientation::CurrentLocked: All orientation changes are disabled
- SupportedDisplayOrientation::DisplayPortrait: The app supports portrait orientation only
- SupportedDisplayOrientation::DisplayLandscape: The app supports landscape orientation only
- SupportedDisplayOrientation::DeviceNorth: The app supports the device's natural orientation only (with the BlackBerry logo right-side up and the screen facing the user)
- SupportedDisplayOrientation::All: The app supports all display orientations
Handling orientation using C APIs
When you use C APIs to handle orientation changes, the navigator service (which is part of the BlackBerry Platform Services (BPS) library) handles the entire app window life cycle and matches the app's orientation with the device orientation. Orientation changes are reported as events that contain both direction and angular measurement attributes. Usually, you should use the angular measurements to determine when rotation is necessary and ignore the direction. If you haven't specified an orientation, the default orientation when the app starts is portrait.
You can specify which orientations you want to support in the bar-descriptor.xml file of your project, as described in Setting orientation in the bar-descriptor.xml file. The navigator service sends rotation events to your app based on what you specify in this file. If you specify only portrait or landscape orientation, the navigator service doesn't send any orientation change events. If you specify that your app supports orientation changes, your app needs to listen for change events and respond to them.
There are three key components when managing orientation changes using C APIs:
- Use the BPS library to set up an event loop to listen for events. You must initialize the BPS library before you can request events. To learn more about the BPS library and how to use it for event handling, see BlackBerry Platform Services.
- Use the navigator service to determine the current orientation of the device. The navigator service informs the app when it needs to rotate and initiates the rotation sequence by sending the app a rotate event (NAVIGATOR_ORIENTATION_CHECK).
- Use the screen service along with the BPS library to coordinate orientation events and update display properties.
To learn more about how to handle orientation changes in your apps, click the links below.
Last modified: 2015-07-24