Orientation in C

Orientation is an important feature of most applications. You need to consider the purpose of your application when choosing which orientation(s) to support. Portrait view for applications such as e-readers can make it easier to digest the displayed information. Landscape view for applications such as movies or games can offer distinct benefits and provide a better experience for all-touch device users. Depending on your application, you may want to support both portrait and landscape views and provide a different user experience for each view.

The navigator service on the BlackBerry 10 OS handles the entire application window lifecycle and matches the application's orientation with the device orientation. Orientation changes are reported as events that contain both direction and angular measurement attributes. Usually, you will want to 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 application starts is portrait for a smartphone and landscape for a tablet.

You can specify which types of orientation you want to support in the BAR application descriptor file, bar-descriptor.xml. The navigator service sends your app rotation events based on what you specified in bar-descriptor.xml. If you specified only portrait or landscape, the navigator service will not send any orientation change events. If you configure your application to support orientation changes, your app needs to listen for change events from the BlackBerry 10 OS and respond to them.

There are three key components when managing the orientation of your device.

  • bps/bps.h

    Use the BPS library to set up events and listen for events. You must initialize BPS before you can request events.

    Not applicable

    Not applicable

    Add the following header files and function call to your application:

    #include <bps/bps.h>   // for initializing the BPS service
    #include <bps/event.h> // for creating and/or querying events
    bps_initialize();      // initialize BPS; allows application to call BPS functions
  • bps/navigator.h

    Use the navigator service to determine the current orientation of the device. The navigator service informs the application when it needs to rotate and initiates the rotation sequence by sending the application a rotate event (NAVIGATOR_ORIENTATION_CHECK).

  • screen/screen.h

    Use the screen service along with the BPS library to coordinate orientation events with the display.

Last modified: 2015-07-24

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

comments powered by Disqus