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.

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.

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);
        }

    }
}

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.