TextInput is a text-entry control that lets users enter and edit
a single line of uniformly-formatted text.

The TextInput skin for the Spark theme
uses the RichEditableText class. This means that the Spark TextInput control supports
the Text Layout Framework (TLF) library,
which builds on the Flash Text Engine (FTE).
In combination, these layers provide text editing with
high-quality international typography and layout.

The TextInput skin for the mobile theme uses the StyleableStageText class instead
of RichEditableText.
Since StyleableStageText uses native text fields it allows for better text entry and
manipulation experiences on mobile devices however there are
limitations and differences that you should
consider.
The native text controls used by StageText apply different paddings around text.
In order to avoid vertical scrolling, the StageText-based TextInput skin attempts to estimate
this padding and compensate for that.
Because of this and other differences in how native text controls treat text, the default
height of the TextInput control using StageText-based skin will differ from its default height
using the the TextField-based TextInput skin.

You can set the text to be displayed, or get the text that the user
has entered, using the text property.
This property is a String, so if the user enter a numeric value
it will be reported, for example, as "123.45" rather than 123.45.

The text is formatted using CSS styles such as fontFamily
and fontSize.

For the Spark theme you can specify the width of the control using the
widthInChars property which provides a convenient way to specify the width in a
way that scales with the font size or you can use the typicalText property.
Note that if you use typicalText, the widthInChars property is ignored.
For all themes, you can also specify an explicit width in pixels,
a percent width, or use constraints such as left
and right.
You do not normally do anything to specify the height;
the control's default height is sufficient to display
one line of text.

You can use the maxChars property to limit the number
of character that the user can enter, and the restrict
to limit which characters the user can enter.
To use this control for password input, set the
displayAsPassword property to true.

For the mobile theme, the soft-keyboard-specific properties, autoCapitalize,
autoCorrect, returnKeyLabel and softKeyboardType
properties specify keyboard hints.
If a soft-keyboard is present but does not support a feature represented by the
hint, the hint is ignored.
In mobile environments with only hardware keyboards, these hints are ignored.

This control dispatches a FlexEvent.ENTER event
when the user pressed the Enter key rather than inserting a line
break, because this control does not support entering multiple
lines of text. By default, this control has explicit line breaks.

This control is a skinnable control whose default skin contains either a
RichEditableText instance for the Spark theme or a StyleableStageText instance for the
Mobile theme. It handles displaying and editing the text.
(The skin also handles drawing the border and background.)
This RichEditableText or StyleableStageText instance can be accessed as the textDisplay
object. For the mobile theme, if you wish to use the TextField-based skin, rather than the
StageText-based skin, set the skinClass property to
"spark.skins.mobile.TextInputSkin".

For the Spark theme, as a result of its RichEditableText using TLF,
the Spark TextInput control supports displaying left-to-right (LTR) text, such as French,
right-to-left (RTL) text, such as Arabic, and bidirectional text
such as a French phrase inside of an Arabic one.
If the predominant text direction is right-to-left,
set the direction style to rtl.
The textAlign style defaults to start,
which makes the text left-aligned when direction
is ltr and right-aligned when direction
is rtl.
To get the opposite alignment,
set textAlign to end.

Also as a result of using TLF, the Spark TextInput supports
unlimited undo/redo within one editing session.
An editing session starts when the control gets keyboard focus
and ends when the control loses focus.

To use this component in a list-based component, such as a List or DataGrid,
create an item renderer.
For information about creating an item renderer, see
Custom Spark item renderers.

For the Spark theme, the TextInput control has the following default characteristics:

Characteristic

Description

Default size

128 pixels wide by 22 pixels high

Maximum size

10000 pixels wide and 10000 pixels high

Default skin class

spark.skins.spark.TextInputSkin

For the Mobile theme, the TextInput control has the following default characteristics:

A flag that indicates whether this object can receive focus
via the TAB key
This is similar to the tabEnabled property
used by the Flash Player.
This is usually true for components that
handle keyboard input, but some components in controlbars
have them set to false because they should not steal
focus from another component like an editor.

[read-only]
A convenience method for determining the unscaled width
of the component
All of a component's drawing and child layout should be done
within a bounding rectangle of this width, which is also passed
as an argument to updateDisplayList().

Measures the specified HTML text, which can contain HTML tags such
as <font> and <b>,
assuming that it is displayed
in a single-line UITextField using a UITextFormat
determined by the styles of this UIComponent.

A utility method to update the rotation, scale, and translation of the
transform while keeping a particular point, specified in the component's
own coordinate space, fixed in the parent's coordinate space.

Validates the measured size of the component
If the LayoutManager.invalidateSize() method is called with
this ILayoutManagerClient, then the validateSize() method
is called when it's time to do measurements.

Dispatched by the drag initiator (the component that is the source of the data being dragged) when the drag operation completes, either when you drop the dragged data onto a drop target or when you end the drag-and-drop operation without performing a drop.

Required: false Part Type: Static
The IEditableText that may be present
in any skin assigned to this component.
This is RichEditableText for the Spark theme
and StyleableStageText/ScrollableStageText for the Mobile theme.

To skin the component, implement a skin that defines the following states. Although you must implement all skin states, a skin state can be empty. An empty skin state specifies no changes to the default skin state.

An em is a unit of typographic measurement
equal to the point size.
It is not necessarily exactly the width of the "M" character,
but in many fonts the "M" is about one em wide.
The control's fontSize style is used,
to calculate the em unit in pixels.

You would, for example, set this property to 20 if you want
the width of the TextInput to be sufficient
to input about 20 characters of text.

This property will be ignored if you specify an explicit width,
a percent width, or both left and right
constraints.

This property will also be ignored if the typicalText
property is specified.

For the Mobile theme, this is not supported.

The default value is 10.

Implementation public function get widthInChars():Number public function set widthInChars(value:Number):void

The FlexEvent.ENTER constant defines the value of the
type property of the event object for a enter event.

The properties of the event object have the following values:

Property

Value

bubbles

false

cancelable

false

currentTarget

The Object that defines the
event listener that handles the event. For example, if you use
myButton.addEventListener() to register an event listener,
myButton is the value of the currentTarget.

target

The Object that dispatched the event;
it is not always the Object listening for the event.
Use the currentTarget property to always access the
Object listening for the event.

Examples

TextInputExample.mxml

<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- Simple example to demonstrate the Spark TextInput control. -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark">
<s:layout>
<s:BasicLayout />
</s:layout>
<s:Panel title="Spark TextInput Control Example"
horizontalCenter="0" verticalCenter="0">
<s:VGroup left="10" right="10" top="10" bottom="10">
<s:TextInput id="src" text="Hello World!" />
<s:Button label="Copy Text" click="dest.text = src.text" />
<s:TextInput id="dest" />
</s:VGroup>
</s:Panel>
</s:Application>