StageAspectRatio Enhancements in AIR 3.3

One must have come across many mobile applications(mostly games) that remain in landscape orientation across their lifetime. They start in landscape orientations and remain in landscape orientations irrespective of the orientation in which the device is held or moved. A landscape only application should ideally support both landscape orientations namely Landscape_Left and Landscape_Right and should not auto rotate to any portrait orientation if the device is held in one of the portrait orientations.

Prior to AIR 3.3, StageAspectRatio supported two public constants PORTRAIT and LANDSCAPE. Using one of these values in the aspectRatio tag in the application descriptor would only lead to the application opening up in PORTRAIT or LANDSCAPE orientation respectively. However, the Stage would re-orient in all orientations as per the new device orientation. For example:- with StageAspectRatio set to PORTRAIT, an app would open in PORTRAIT orientation but would reorient to LANDSCAPE_LEFT orientation when device orientation was changed to LANDSCAPE_LEFT.

In order to develop a LANDSCAPE(or PORTRAIT) only mobile application, one was expected to cancel the automatic reorientation by adding a listener to orientationChanging event in the Stage Object by calling preventDefault() method when afterOrientation values were PORTRAIT (or LANDSCAPE).

From AIR.3.3 onwards, developing LANDSCAPE (or PORTRAIT) only applications has been made easier. With the aspectRatio set to  LANDSCAPE(or PORTRAIT) and autoOrients set to true the application descriptor,the stage would automatically reorient only in LANDSCAPE (or PORTRAIT) orientations. Handling orientationChanging events and calling preventDefault() is no longer required to achieve this behavior. One can also change the StageAspectRatio at the runtime by calling  the Stage.setAspectRatio() with the desired aspect ratio.

 

ANY – The new AspectRatio Constant

A new StageAspectRatio constant “ANY” is introduced in AIR 3.3 to assist you in creating applications that should automatically reorient as per the device orientation. Setting the aspectRatio tag in application descriptor to “ANY” would lead to application launching as per the orientation in which the device is held. Such an application would reorient as per the device orientation.

To summarize, Stage orientation is always in sync with the StageAspectRatio set in application descriptor or programmatically in ActionScript unless set otherwise using Stage.setOrientation(). Following table summarizes the supported Stage orienatations as per the device orientation.

StageAspectRatio         Supported Stage Orientations
 ANY PORTRAIT, UPSIDE_DOWN, LANSCAPE_LEFT & LANDSCAPE_RIGHT   
 PORTRAIT PORTRAIT & UPSIDE_DOWN
 LANDSCAPE LANSCAPE_LEFT & LANDSCAPE_RIGHT

Please Note:-

  1. The new behavior can be seen only when the swf-version is set to 16 in the ActionScript compiler settings (<Project->Properties->ActionScript Compiler->Additional compiler arguments).
  2. Stage.autoOrients needs to be set to true in application descriptor or programmatically using autoOrients property in the Stage class to reorient the Stage automatically as per the device orientation.

11 Responses to StageAspectRatio Enhancements in AIR 3.3

  1. Cliff Hall says:

    The statement “With the aspectRatio set to LANDSCAPE(or PORTRAIT) and autoOrients set to true the application descriptor,the stage would automatically reorient only in LANDSCAPE (or PORTRAIT) orientations.” is not true.

    On an iPad, our app is supposed to support only Landscape, but when compiled with the following in the -app.xml file:

    true
    landscape

    I end up with an app that flips between landscape and portrait as you reorient the device. My understanding of the above is that it should always stay in Landscape and only flip upside down if I rotate the device 180 degrees. If I wanted to support portrait AND landscape, I should do this:

    true
    any

    Where am I going wrong?
    -=Cliff>

    • Cliff Hall says:

      BTW, the blog stripped the autoOrients and aspectRatio tags from my comment above, they are the tags for the settings shown respectively, e.g., autoOrients = true, aspectRatio = landscape.

    • Cliff Hall says:

      Thanks Varun, for pointing out I needed to set the appropriate swf-version.

      For anyone else out there who has downloaded the AIR 3.3 SDK, you’ll notice in the frameworks/airmobile-config.xml that strangely, Adobe has seen fit to leave that specifying Flash Player 11.1 and swf-version 14.

      Why they would do this I have no idea, but you’ll need to change it if you expect this wonderful new orientation stuff to actually work.

  2. Cliff Hall says:

    BTW, it’s swf-version=16, target-player=11.3 that you need.

  3. Varun Bhatia says:

    The new behavior can be seen only when the swf-version is set to 16 in the ActionScript compiler settings

  4. Varun Bhatia says:

    Also, the frameworks/airmobile-config.xml is part of Flash builder and not AIR SDK. Since AIR 3.3 SDK got released after the installed version of Flash Builder, hence frameworks/airmobile-config.xml is not updated in your machine. AIR however supports the new swf versions.

  5. Peter says:

    how can i listen to changes in the orientation, but no let the app change the orientation?

  6. Varun Bhatia says:

    you can listen to orientation events only by setting auto orients to true and subscribing for orientation_changing and orientation_change events. You can prevent the app from changing its orientation by calling preventDefault in orientation_changing event. Can you tell the use case where you would only be interested in only orientation event however you wont be interested in changing the app’s orientation.

  7. i have written few lines to handle this… might helpfull to u.. :)

    protected function creationCompleteHandler(event:FlexEvent):void
    { stage.addEventListener(StageOrientationEvent.ORIENTATION_CHANGING,orientationChaningHandler);
    }

    private function orientationChaningHandler(e:StageOrientationEvent):void {
    if(e.afterOrientation == StageOrientation.DEFAULT || e.afterOrientation == StageOrientation.UPSIDE_DOWN)
    {
    e.preventDefault();
    }
    }

  8. Kudo Bass says:

    In response to: “Can you tell the use case where you would only be interested in orientation events, however you wont be interested in changing the app’s orientation.”

    I’m building an app which is to stay in portrait mode, but occasionally it plays a full-screen style video. When showing these videos, I want to know about orientation changes to I can show the video wide-screen in landscape mode. Hidden underneath the video, the UI stays in portrait mode.