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

Indicates whether the security restrictions
would cause any display objects to be omitted from the list returned by calling
the DisplayObjectContainer.getObjectsUnderPoint() method
with the specified point point.

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.

Dispatched when the user presses two points of contact over the same InteractiveObject instance on a touch-enabled device (such as presses and releases two fingers over a display object on a mobile phone or tablet with a touch screen).

Dispatched when the user moves a point of contact over the InteractiveObject instance on a touch-enabled device (such as moving a finger from left to right over a display object on a mobile phone or tablet with a touch screen).

Dispatched when the user performs a rotation gesture at a point of contact with an InteractiveObject instance (such as touching two fingers and rotating them over a display object on a mobile phone or tablet with a touch screen).

Dispatched when the user performs a swipe gesture at a point of contact with an InteractiveObject instance (such as touching three fingers to a screen and then moving them in parallel over a display object on a mobile phone or tablet with a touch screen).

Dispatched when the user creates a point of contact with an InteractiveObject instance, then taps on a touch-enabled device (such as placing several fingers over a display object to open a menu and then taps one finger to select a menu item on a mobile phone or tablet with a touch screen).

Dispatched when the user performs a zoom gesture at a point of contact with an InteractiveObject instance (such as touching two fingers to a screen and then quickly spreading the fingers apart over a display object on a mobile phone or tablet with a touch screen).

Dispatched when the user moves an active stylus over this InteractiveObject from outside the object's tree of descendents in the display list (while remaining within the proximity detection threshold of the screen).

Dispatched when a user releases the button on the pointing device after the user first pressed the button over an InteractiveObject instance and then moved the pointing device off of the InteractiveObject instance.

Dispatched when the user moves the point of contact away from InteractiveObject instance on a touch-enabled device (such as drags a finger from one display object to another on a mobile phone or tablet with a touch screen).

Dispatched when the user moves the point of contact over an InteractiveObject instance on a touch-enabled device (such as drags a finger from a point outside a display object to a point over a display object on a mobile phone or tablet with a touch screen).

Dispatched when the user moves the point of contact away from an InteractiveObject instance on a touch-enabled device (such as drags a finger from over a display object to a point outside the display object on a mobile phone or tablet with a touch screen).

Dispatched when the user moves the point of contact over an InteractiveObject instance on a touch-enabled device (such as drags a finger from a point outside a display object to a point over a display object on a mobile phone or tablet with a touch screen).

Dispatched when the user lifts the point of contact over the same InteractiveObject instance on which the contact was initiated on a touch-enabled device (such as presses and releases a finger from a single point over a display object on a mobile phone or tablet with a touch screen).

Styles are either common or associated with a specific theme. If the style is common, it can be used with any theme. If a style is associated with a specific theme, it can only be used if your application uses that 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.

widthInChars

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