orientation and deviceOrientation in Flex Mobile apps

So you want to build a mobile app and tap into the 30+ billion app downloads that are estimated to happen in the next 5 years? Well, one of the first things you’ll have to think about is screen orientation: unlike in a desktop application, the user can rotate the screen through portrait and landscape orientations, both before and while your application is being used. This can be a great thing since your application can take advantage of the different screen dimensions to provide specialized UI but it also means you need to make some decisions about how your app is going to handle these situations.

In general, the default configuration for Flex typically does the right thing, especially if you use constraint-based layout settings so that your controls change size and position correctly regardless of how the application is oriented and the screen is sized. However, if you have a need to take more control over how your application reacts to device orientation changes, Flex gives you the control you need.

First, some quick definitions:

  • Portrait: mode where the display is taller than it is wide
  • Landscape: mode where the display is wider than it is tall

Figure 1: iPad, in its default portrait orientation; Motorola Xoom, by default in landscape orientation

What layout makes sense? Perhaps you’re making a game where the application should be in landscape all the time, or maybe you are developing an application where you want the UI to accommodate the user’s usage and always stay oriented correctly regardless of whether they are holding it in portrait or landscape form. Some apps go a step further and re-organize the layout to take better advantage of the format, e.g. going from a 2-page master-detail navigation application while in portrait mode to a side-by-side master-detail format in landscape.

Figure 2: Single-pane layout in portrait orientation; dual-pane layout in landscape orientation

Once you have designed your ideal orientation behavior you can then set your Flex configuration to support it. The following four properties are the keys to configuring your app:

  • aspectRatio
  • autoOrients
  • Stage.orientation
  • Stage.deviceOrientation

In your application’s app.xml file you will find the following section:

        <!-- The initial aspect ratio of the app when launched (either "portrait" or "landscape"). Optional. Mobile only. Default is the natural orientation of the device -->
 
        <!-- <aspectRatio></aspectRatio> -->
 
        <!-- Whether the app will begin auto-orienting on launch. Optional. Mobile only. Default false -->
 
        <!-- <autoOrients></autoOrients> -->

As the section comments state, these two control your initial aspect ratio and whether or not your application will automatically rotate as the screen is rotated. So, for example, in my first-person racing game that is always in landscape mode I would set aspectRatio to “landscape” and “autoOrients” to false. By default, Flash Builder will set autoOrients to “true” and no specified “aspectRatio”, so your application will start in the device’s natural orientation.

The other two properties you need to be aware of are Stage.orientation and Stage.deviceOrientation:

  • orientation : String
    [read-only] The current orientation of the stage.
  • deviceOrientation : String
    [read-only] The physical orientation of the device.

Here is a subtle but important distinction to note: the deviceOrientation tells you which way the device is rotated relative to the ground/gravity/sky, while the orientation tells you which way the screen is rotated relative to the device’s default orientation. For example, if my device’s default configuration is portrait mode and it is upright, and my application’s autoOrients property is true, then the orientation and deviceOrientation will both be equal to StageOrientation.DEFAULT.

If the user then rotates the device counter-clockwise 90 degrees, the deviceOrientation property will now be StageOrientation.ROTATED_LEFT. However, because autoOrients is true Stage.orientation will be StageOrientation.ROTATED_RIGHT since the application will automatically rotate right 90 degrees to compensate and keep the screen’s “up” in line with what the user sees as “up.” Understanding the difference between deviceOrientation and Stage.orientation is important or your application may be upside-down half the time and you won’t understand why.

View Source

Once you understand these properties you can override them as needed using Stage.setAspectRatio() and Stage.setOrientation(). For example, if you want your screen to start in portrait and not respond to orientation changes, in your application’s app.xml file you can set aspectRatio to “portrait” and autoOrients to false. Then later, if you need landscape mode (e.g. for showing a widescreen video), you can call Stage.setAspectRatio(StageAspectRatio.LANDSCAPE) to force the application into landscape mode. You can also use Stage.setOrientation(), but keep in mind that not all devices support programmatically selecting all orientations; you can check Stage.supportedOrientations to determine which rotation directions you are allowed to use.

To programmatically determine what orientation the device is currently in, add event listeners to the stage for StageOrientationEvents, e.g.

stage.addEventListener(StageOrientationEvent.ORIENTATION_CHANGE, orientationChangeHandler);
// …
protected function orientationChangeHandler(event:StageOrientationEvent):void
{
    trace(“Device orientation: “ + stage.deviceOrientation);
    trace(“Screen orientation: “ + stage.orientation);
}

Some other references you might find useful:

Note: This sample requires Flex SDK 4.5.1 or higher. You can get the latest SDK builds from opensource.adobe.com.

7 thoughts on “orientation and deviceOrientation in Flex Mobile apps”

  1. I find this works well… so far:

    stage.stageHeight)
    {
    currentState = "landscape";
    }
    else
    {
    currentState = "portrait";
    }
    }

    ]]>

  2. Hi

    i have been trying to make a simple flex 3 screen application for 5 months now but i cant. i am using adobe flex 4.6. My app is simple one login screen, one video list, one video player screen.

    No matter how i try, when i change orientation to landscape to play the video it works ok first time. now if i press back button and try to come back to my portrait video , flash says orientation complete buy my screen hangs with the video player on it for about 3-5 seconds before showing the list again.

    Its been 5 months, i will really appreciate some help. the community is dying , not getting any help anywhere.

  3. HI,

    How can i forced my application to always open/behave in landscape mode and never reorient to portrait mode?.

    Note: My application is for Ipad.

    Thanks.

  4. Tahir Alvi
    It says in the example above to do this :
    stage.setAspectRatio( StageAspectRatio.LANDSCAPE );

Comments are closed.