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.
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 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.
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 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.
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.