TextInput control

The Spark TextInput control is a single-line text field that is optionally editable. This control supports TLF. The text is rendered by a RichEditableText subcomponent in its skin class.

For complete reference information, see the ActionScript 3.0 Reference for the Adobe Flash Platform.

To create a multiline, editable text field, use a TextArea control. For more information, see TextArea control. To create noneditable text fields, use the Label or RichText controls. For more information, see Label control and RichText control.

The TextInput control does not include a label, but you can add one by using a Label control or by nesting the TextInput control in a FormItem container in a Form layout container. Spark TextInput controls dispatch all these events except the dataChange event.

To change the disabled color for the Spark TextInput control, you must edit the TextInputSkin class. The following example shows the differences between the enabled and disabled versions of the Spark and MX TextInput controls:
<?xml version="1.0"?>
<!-- sparktextcontrols/TextInputDisabledColors.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark">
  
    <s:VGroup>
        <mx:TextInput enabled="false" text="disabled MX"/>
        <mx:TextInput enabled="true" text="enabled MX"/>

        <s:TextInput enabled="false" text="disabled Spark"/>
        <s:TextInput enabled="true" text="enabled Spark"/>
    </s:VGroup>

</s:Application>

The executing SWF file for the previous example is shown below:

You can set a TextInput control’s editable property to false to prevent users from editing the text. You can set a TextInput control’s displayAsPassword property to conceal the input text by displaying characters as asterisks.

Creating a TextInput control

You define a TextInput control in MXML by using the <s:TextInput> tag, as the following example shows. Specify an id value if you intend to refer to a control elsewhere in your MXML, either in another tag or in an ActionScript block.
<?xml version="1.0"?>
<!-- sparktextcontrols/SparkTextInputControl.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark">

  <s:TextInput id="text1" width="100"/>

</s:Application>

The executing SWF file for the previous example is shown below:

You can use the text property to specify a string of raw text in the TextInput control.

Sizing a TextInput control

If you do not specify a width, the TextInput control automatically resizes when you change the text. It does not resize in response to typed user input.

The TextInput control determines the value of its measuredWidth property by using a widthInChars property rather than measuring the text assigned to it, because the text frequently starts out empty. The value of its measuredHeight property is determined by the height of the font.

Binding to a TextInput control

In some cases, you might want to bind a variable to the text property of a TextInput control so that the control represents a variable value, as the following example shows:
<?xml version="1.0"?>
<!-- sparktextcontrols/SparkBoundTextInputControl.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark">

  <fx:Script><![CDATA[
     [Bindable]
     public var myProp:String="This is the initial String myProp.";
  ]]></fx:Script>

  <s:TextInput text="{myProp}"/> 

</s:Application>

The executing SWF file for the previous example is shown below:

In this example, the TextInput control displays the value of the myProp variable. Remember that you must use the [Bindable] metadata tag if the variable changes value and the control must track the changed values; also, the compiler generates warnings if you do not use this metadata tag.

Using TLF with the TextInput control

You can use TLF with a TextInput control by accessing the textDisplay property. This property points to the underlying RichEditableText object that renders the text in the TextInput control. The RichEditableText object is a subcomponent that is defined in the TextInput control’s skin class.

The following example defines a TextFlow as XML, and assigns that to the TextInput control’s textDisplay:
<?xml version="1.0"?>
<!-- sparktextcontrols/TextInputTLF.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="initApp()">

    <fx:Declarations>
        <fx:XML id="myXML">
            <div>            
                <p>Hello <span fontWeight='bold'>world</span>!</p>
            </div>
        </fx:XML>    
    </fx:Declarations>

    <fx:Script>
        import spark.utils.TextFlowUtil;

        private function initApp():void {
            text1.textDisplay.textFlow = TextFlowUtil.importFromXML(myXML);
        }
    
    </fx:Script>

    <s:TextInput id="text1" width="100"/>

</s:Application>

The executing SWF file for the previous example is shown below:

For more information about using TLF with Spark text controls, see Using Text Layout Framework.