Chapter 4. Mobile Advantage: StageText and StageVideo

With AIR becoming a very real choice when developing for mobile operating systems like iOS and Android, it certainly helps to have the platform features necessary to take advantage of underlying system hardware acceleration and other constructs such as the rich text input frameworks available on a device. AIR 3 extends the integration of the runtime into some of these underlying system functionalities.

StageText Native Text Input UI (Mobile)

The new flash.text.StageText class in AIR 3 allows ActionScript developers to tap directly into the text input mechanisms of the underlying operating system, exposing functionality such as auto-correct, auto-capitalize, and the specific type of virtual keyboard that is presented to the user.

Similar to StageWebView and StageVideo, StageText is not part of the traditional DisplayList and must be dealt with in its own way. Native text input fields created with StageText are always rendered above the DisplayList and will appear over any other content being rendered on the Stage.

Note

Note that StageText does not include a background or border decoration. This must be supplied through the DisplayList as demonstrated below.

To create a StageText instance, we will first draw out any background elements necessary and add them to the DisplayList. In this case, we draw out a simple box using the graphics API. This will provide the user with an indicator which they can tap to provide focus to the overlaying StageText object. We then define a new StageTextInitOptions instance and set our multiline preference to “true” or “false”.

Once that has all been set up, we instantiate a new StageText object and begin to define the properties of this object. Properties can include such things as whether to auto-capitalize the text, make auto-correct available for the user, set the return type label, or even the specific variant of soft keyboard used for this particular field.

Note

flash.text.SoftKeyboardType options include:

SoftKeyboardType.CONTACT
SoftKeyboardType.DEFAULT
SoftKeyboardType.EMAIL
SoftKeyboardType.NUMBER
SoftKeyboardType.PUNCTUATION
SoftKeyboardType.URL

Finally we assign the current Stage to the StageText.stage property and a Rectangle is assigned to the StageText.viewport property to determine positioning and size.

package {
    import flash.display.Sprite;
    import flash.display.StageAlign;
    import flash.display.StageScaleMode;
    import flash.geom.Rectangle;
    import flash.text.ReturnKeyLabel;
    import flash.text.SoftKeyboardType;
    import flash.text.StageText;
    import flash.text.StageTextInitOptions;

    [SWF(backgroundColor="#CCCCCC")]

    public class MobileStageText extends Sprite {

        private var decoration:Sprite;
        private var stageText:StageText;
        private var stageTextInitOptions:StageTextInitOptions;

        public function MobileStageText() {
            super();
            stage.scaleMode = StageScaleMode.NO_SCALE;
            stage.align = StageAlign.TOP_LEFT;

            generateDisplayObjects();
        }

        protected function generateDisplayObjects():void {
            decoration = new Sprite();
            decoration.graphics.lineStyle(4, 0x000000, 1);
            decoration.graphics.beginFill(0xFFFFFF, 1);
            decoration.graphics.drawRect(6, 44, stage.stageWidth-12, 70);
            this.addChild(decoration);

            stageTextInitOptions = new StageTextInitOptions(false);
            stageText = new StageText(stageTextInitOptions);
            stageText.softKeyboardType = SoftKeyboardType.DEFAULT;
            stageText.returnKeyLabel = ReturnKeyLabel.DONE;
            stageText.autoCorrect = true;
            stageText.fontSize = 40;
            stageText.color = 0x440000;
            stageText.fontWeight = "bold";
            stageText.stage = this.stage;
            stageText.viewPort = new Rectangle(10, 50, stage.stageWidth-20, 70);
        }

    }
}

Note

Note that with this example, unlike the other mobile AIR examples in this book, we will set the orientation to “portrait” within our application descriptor file in order to provide the soft keyboard with enough room to exist on the screen along with the StageText instance itself.

<aspectRatio>portrait</aspectRatio>

When this code is compiled to a mobile device, we can see the result of a native text interaction as seen in Figure 4-1.

Native text on Android

Figure 4-1. Native text on Android

Note

To get around some of the complexities associated with using StageText, Christian Cantrell has developed the NativeText wrapper which assists with a lot of the difficulties one can encounter when using these APIs. NativeText can be downloaded from https://github.com/cantrell/StageTextExample.

Get What's New in Adobe AIR 3 now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.