Menu
▾
▴
Spark TextInput and TextArea
Spark TextInput and TextArea - Functional and Design Specification
Glossary
The Glossary in the Spark Text Primitives spec is useful for understanding this spec.
RichEditableText - A new Spark text primitive, covered in the Spark Text Primitives 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 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.
*/
<a href="Event%28name%3D%26quot%3BselectionChange%26quot%3B%2C%20type%3D%26quot%3Bmx.events.FlexEvent%26quot%3B%29">Event(name="selectionChange", type="mx.events.FlexEvent")</a>
/**
* Dispatched before a user editing operation occurs.
* You can alter the operation, or cancel the event
* to prevent the operation from being processed.
*/
<a href="Event%28name%3D%26quot%3Bchanging%26quot%3B%2C%20type%3D%26quot%3Bmx.events.TextOperationEvent%26quot%3B%29">Event(name="changing", type="mx.events.TextOperationEvent")</a>
/**
* Dispatched after a user editing operation is complete.
*/
<a href="Event%28name%3D%26quot%3Bchange%26quot%3B%2C%20type%3D%26quot%3Bmx.events.TextOperationEvent%26quot%3B%29">Event(name="change", type="mx.events.TextOperationEvent")</a>
//--------------------------------------
// Styles
//--------------------------------------
include "AdvancedTextLayoutFormatStyles.as"
include "BasicTextLayoutFormatStyles.as"
include "SelectionFormatTextStyles.as"
/**
* @copy spark.components.supportClasses.GroupBase#contentBackgroundColor
*/
<a href="Style%28name%3D%26quot%3BcontentBackgroundColor%26quot%3B%2C%20type%3D%26quot%3Buint%26quot%3B%2C%20format%3D%26quot%3BColor%26quot%3B%2C%20inherit%3D%26quot%3Byes%26quot%3B%2C%20theme%3D%26quot%3Bspark%26quot%3B%29">Style(name="contentBackgroundColor", type="uint", format="Color", inherit="yes", theme="spark")</a>
/**
* @copy spark.components.supportClasses.GroupBase#focusColor
*/
<a href="Style%28name%3D%26quot%3BfocusColor%26quot%3B%2C%20type%3D%26quot%3Buint%26quot%3B%2C%20format%3D%26quot%3BColor%26quot%3B%2C%20inherit%3D%26quot%3Byes%26quot%3B%2C%20theme%3D%26quot%3Bspark%26quot%3B%29">Style(name="focusColor", type="uint", format="Color", inherit="yes", theme="spark")</a>
/**
* 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
//--------------------------------------
<a href="Bindable%28%26quot%3BselectionChange%26quot%3B%29">Bindable("selectionChange")</a>
/**
* Facaded from RichEditableText.
*/
public function get selectionActivePosition():int
//--------------------------------------
// selectionAnchorPosition
//--------------------------------------
<a href="Bindable%28%26quot%3BselectionChange%26quot%3B%29">Bindable("selectionChange")</a>
/**
* 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
//--------------------------------------
<a href="Bindable%28%26quot%3Bchange%26quot%3B%29">Bindable("change")</a>
<a href="Bindable%28%26quot%3BtextChanged%26quot%3B%29">Bindable("textChanged")</a>
/**
* Facaded from RichEditableText.
*/
public function get text():String
public function set text(value:String):void
//----------------------------------
// textView
//----------------------------------
<a href="SkinPart%28required%3D%26quot%3Btrue%26quot%3B%29">SkinPart(required="true")</a>
/**
* 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.
*/
<a href="Event%28name%3D%26quot%3Benter%26quot%3B%2C%20type%3D%26quot%3Bmx.events.FlexEvent%26quot%3B%29">Event(name="enter", type="mx.events.FlexEvent")</a>
//--------------------------------------
// Other metadata
//--------------------------------------
<a href="DefaultProperty%28%26quot%3Btext%26quot%3B%29">DefaultProperty("text")</a>
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
*/
<a href="Style%28name%3D%26quot%3BsymbolColor%26quot%3B%2C%20type%3D%26quot%3Buint%26quot%3B%2C%20format%3D%26quot%3BColor%26quot%3B%2C%20inherit%3D%26quot%3Byes%26quot%3B%2C%20theme%3D%26quot%3Bspark%26quot%3B%29">Style(name="symbolColor", type="uint", format="Color", inherit="yes", theme="spark")</a>
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
//----------------------------------
<a href="SkinPart%28required%3D%26quot%3Bfalse%26quot%3B%29">SkinPart(required="false")</a>
/**
* 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.
Flex SDK Project
Other Projects
Related
Wiki: Flex 4
Wiki: Spark Skinning
Wiki: Spark Text Primitives
