Flex SDK Wiki

# Spark TextInput and TextArea - Functional and Design Specification ---- \\ ## Glossary ---- The Glossary in the [Spark Text Primitives](Spark%20Text%20Primitives) spec is useful for understanding this spec. **RichEditableText** - A new Spark text primitive, covered in the [Spark Text Primitives](Spark%20Text%20Primitives) spec, which is used in skins for the Spark TextInput and TextArea. It provides a scrollable but chromeless rectangle of editable rich text, without background, border, or scrollbars. TextView is based on FTE and TLF, so it takes advantage of the new text capabilities in Flash Player 10. RichEditableText does most of the work for the Spark TextInput and TextArea, so understanding it first is very important. **TextBase** - A new Spark base class for skinnable components whose skins contain a RichEditableText, such as TextInput and TextArea. It extends SkinnableComponent, the base class for all Spark-skinnable components, which is described in the [Spark Skinning](Spark%20Skinning) spec. ## Summary and Background ---- ### TextInput The new Spark TextInput allows the user to enter and edit a single line of single-styled text. It extends TextBase and uses a RichEditableText primitive in its skin to display the editable text. The background and border are provided by a Rect in the skin. TextInput autoscrolls horizontally but does not have scrollbars. It displays only single-format text. It is very similar to the Halo TextInput, but it uses the Text Layout Framework rather than TextField to display and edit text. ### TextArea The new Spark TextArea allows the user to enter and edit multiple lines of rich, scrollable text. Like TextInput, it extends TextBase and uses a RichEditableText primitive in its skin to display the editable text. The background and border are provided by a Rect in the skin, and horizontal and vertical scrollbars are provided by a Scroller. The displayed content of a TextArea is "rich", meaning that it can use all of TLF's formatting capabilities: multiple divs, paragraphs, spans, inline graphics, etc., each with their own format. The formatting is "preserved" as you edit; if you click inside some red text and type, the inserted text will be red. However, TextArea does not include any UI for changing the formatting; it can only be changed programmatically. It is very similar to the Halo TextArea, but it uses the Text Layout Framework rather than TextField to display and edit text. Spark does not include a replacement for Halo's RichTextEditor component. ## Usage Scenarios ---- The Spark TextInput is used in the same way as the Halo TextInput: when you need a single line of editable text, such as for entering a username. The Spark TextArea is used in the same way as the Halo TextArea: when you need multiple lines of editable text, such as for composing a haiku. ## Detailed Description ---- ### TextBase TextBase is the base class for skinnable Gumbo components whose skin contains a RichEditableText, such as TextInput and TextArea. It extends SkinnableComponent, the base class for all Gumbo-skinnable components. The RichEditableText is available via the `textView` property. TextBase facades some of RichEditableText's APIs for convenience. If you need other RichEditableText functionality, access it through `textView`. TextBase has a `text` property, but does not support a `content` property for rich text. (Nobody needs a single-line rich text editor, do they?) It supports the same text formatting styles as RichEditableText, which provide all of TLF's formatting capabilities. (These are actually declared on FxComponent.) It exposes `insertText()` and `appendText()` methods. For selection, it exposes `selectionActivePosition` and `selectionAnchorPosition` read-only properties and a `setSelection()` method. TextInput redispatches its RichEditableText's `selectionChange`, `changing`, and `change` events. ### TextInput The default skin for a Spark TextInput includes a RichEditableText as a required \[SkinPart\] named `textView`. A typical skin for TextInput will also draw a border and opaque background using `<rect>` tags. Be sure to read about what TextInput inherits from TextBase. In addition… TextInput determines its `measuredWidth` using a `widthInChars` property rather than measuring the text assigned to it, because the text frequently starts out empty. Its `measuredHeight` is determined by the height of the font. TextInput redispatches its RichEditableText's `enter` event. ### TextArea The default skin for a Spark TextArea includes a RichEditableText as a required \[SkinPart\] named `textView`. A typical skin for TextArea will also draw a border and opaque background using `<rect>` tags, and use a `<scroller>` to provide horizontal and vertical scrollbars. Be sure to read about what TextArea inherits from TextBase. In addition… TextArea determines its `measuredWidth` and `measuredHeight` using the `widthInChars` and `heightInLines` properties rather than measuring the text assigned to it, because the text frequently starts out empty. TextArea facades RichEditableText's `content` property so that it can support rich text. It also facades the `getSelectionFormat()`, `setSelectionFormat()`, and `export()` methods. TextArea supports both horizontal and vertical scrolling. It facades Scroller's `horizontalScrollPolicy` and `verticalScrollPolicy` properties. To programmatically scroll, access the `textView`. ## API Description ---- ### Class TextBase package spark.components.supportClasses { //-------------------------------------- // Events //-------------------------------------- /** * Dispached after the selectionAnchorPosition and/or * selectionActivePosition properties have changed * for any reason. */ Event(name="selectionChange", type="mx.events.FlexEvent") /** * Dispatched before a user editing operation occurs. * You can alter the operation, or cancel the event * to prevent the operation from being processed. */ Event(name="changing", type="mx.events.TextOperationEvent") /** * Dispatched after a user editing operation is complete. */ Event(name="change", type="mx.events.TextOperationEvent") //-------------------------------------- // Styles //-------------------------------------- include "AdvancedTextLayoutFormatStyles.as" include "BasicTextLayoutFormatStyles.as" include "SelectionFormatTextStyles.as" /** * @copy spark.components.supportClasses.GroupBase#contentBackgroundColor */ Style(name="contentBackgroundColor", type="uint", format="Color", inherit="yes", theme="spark") /** * @copy spark.components.supportClasses.GroupBase#focusColor */ Style(name="focusColor", type="uint", format="Color", inherit="yes", theme="spark") /** * The base class for skinnable text components * such as TextInput and TextArea whose skin contains a RichEditableText. */ public class TextBase extends SkinnableComponent implements IFocusManagerComponent, IIMESupport { //------------------------------------------------------------------------------ // // Constructor // //------------------------------------------------------------------------------ /** * Constructor. */ public function TextBase() //-------------------------------------- // autoSize //-------------------------------------- /** * Facaded from RichEditableText. */ public function get autoSize():Boolean public function set autoSize(value:Boolean):void //-------------------------------------- // displayAsPassword //-------------------------------------- /** * Facaded from RichEditableText. */ public function get displayAsPassword():Boolean public function set displayAsPassword(value:Boolean):void //-------------------------------------- // editable //-------------------------------------- /** * Facaded from RichEditableText. */ public function get editable():Boolean public function set editable(value:Boolean):void //---------------------------------- // imeMode //---------------------------------- /** * Implements IIMESupport. */ public function get imeMode():String public function set imeMode(value:String):void //---------------------------------- // maxChars //---------------------------------- /** * Facaded from RichEditableText. */ public function get maxChars():int public function set maxChars(value:int):void //---------------------------------- // restrict //---------------------------------- /** * Facaded from RichEditableText. */ public function get restrict():String public function set restrict(value:String):void //---------------------------------- // selectable //---------------------------------- /** * Facaded from RichEditableText. */ public function get selectable():Boolean public function set selectable(value:Boolean):void //-------------------------------------- // selectionActivePosition //-------------------------------------- Bindable("selectionChange") /** * Facaded from RichEditableText. */ public function get selectionActivePosition():int //-------------------------------------- // selectionAnchorPosition //-------------------------------------- Bindable("selectionChange") /** * Facaded from RichEditableText. */ public function get selectionAnchorPosition():int //---------------------------------- // selectionVisibility //---------------------------------- /** * Facaded from RichEditableText. */ public function get selectionVisibility():String public function set selectionVisibility(value:String):void //-------------------------------------- // text //-------------------------------------- Bindable("change") Bindable("textChanged") /** * Facaded from RichEditableText. */ public function get text():String public function set text(value:String):void //---------------------------------- // textView //---------------------------------- SkinPart(required="true") /** * The RichEditableText that must be present * in any skin assigned to this component. */ public var textView:RichEditableText; //---------------------------------- // widthInChars //---------------------------------- /** * Facaded from RichEditableText. */ public function get widthInChars():Number public function set widthInChars(value:Number):void //-------------------------------------------------------------------------- // // Methods // //-------------------------------------------------------------------------- /** * Facaded from RichEditableText. */ public function insertText(text:String):void /** * Facaded from RichEditableText. */ public function appendText(text:String):void /** * Facaded from RichEditableText. */ public function setSelection(anchorPosition:int = 0, activePosition = int.MAX_VALUE) } } ### Class TextInput package spark.components { //-------------------------------------- // Events //-------------------------------------- /** * Dispatched when the user presses the Enter key. */ Event(name="enter", type="mx.events.FlexEvent") //-------------------------------------- // Other metadata //-------------------------------------- DefaultProperty("text") public class TextInput extends TextBase { //-------------------------------------------------------------------------- // // Constructor // //-------------------------------------------------------------------------- /** * Constructor. */ public function TextInput() //-------------------------------------------------------------------------- // // Properties // //-------------------------------------------------------------------------- //---------------------------------- // widthInChars //---------------------------------- /** * Facaded from RichEditableText. */ public function get widthInChars():int public function set widthInChars(value:int):void } } ## Class TextArea package spark.components { //-------------------------------------- // Styles //-------------------------------------- /** * @copy spark.components.supportClasses.GroupBase#style:symbolColor */ Style(name="symbolColor", type="uint", format="Color", inherit="yes", theme="spark") public class TextArea extends TextBase { //-------------------------------------------------------------------------- // // Constructor // //-------------------------------------------------------------------------- /** * Constructor. */ public function TextArea() //-------------------------------------------------------------------------- // // Properties // //-------------------------------------------------------------------------- //---------------------------------- // content //---------------------------------- /** * Facaded from RichEditableText. */ public function get content():Object public function set content(value:Object):void //---------------------------------- // heightInLines //---------------------------------- /** * Facaded from RichEditableText. */ public function get heightInLines():int public function set heightInLines(value:int):void //---------------------------------- // horizontalScrollPolicy //---------------------------------- /** * Facaded from Scroller */ public function get horizontalScrollPolicy():String public function set horizontalScrollPolicy(value:String):void //---------------------------------- // scroller //---------------------------------- SkinPart(required="false") /** * The optional Scroller used to scroll the RichEditableText. */ public var scroller:Scroller; //---------------------------------- // verticalScrollPolicy //---------------------------------- /** * Facaded from Scroller. */ public function get verticalScrollPolicy():String public function set verticalScrollPolicy(value:String):void //---------------------------------- // widthInChars //---------------------------------- /** * Facaded from RichEditableText. */ public function get widthInChars():int public function set widthInChars(value:int):void //-------------------------------------------------------------------------- // // Methods // //-------------------------------------------------------------------------- /** * Facaded from RichEditableText. */ public function export():XML /** * Facaded from RichEditableText. */ public function getSelectionFormat(names:Array = null):Object /** * Facaded from RichEditableText. */ public function setSelectionFormat(format:Object):void } } ## B Features ---- Implement a `prompt` property and some way to format the prompt. The idea is that you'd set the prompt to something like "Last name" and as soon as you started entering your last name, the prompt would disappear. This allows smaller UIs, especially on mobile devices, because the TextInput doesn't need a descriptive label next to it. ## Examples and Usage ---- <s:textinput widthinchars="5" fontsize="10"> <s:textarea widthinchars="30" heightinrow="5"> ## Additional Implementation Details ---- None. ## Prototype Work ---- None. ## Compiler Work ---- The MXML compiler has been modified to support "mixed content" for TextArea. ## Web Tier Compiler Impact ---- None. ## Flex Feature Dependencies ---- TextInput and TextArea are dependent on RichEditableText. ## Backwards Compatibility ---- ### Syntax changes None. ### Behavior None. ### Warnings/Deprecation None. ## Accessibility ---- See the RichEditableText spec. ## Performance ---- See the RichEditableText spec. ## Globalization ---- See the RichEditableText spec. ## Localization ---- ### Compiler Features None. ### Framework Features None. ## Issues and Recommendations ---- None. ## Documentation ---- None. ## QA ---- Yup. ---- </s:textarea></s:textinput></scroller></rect></rect>