/*

Feathers UI

Copyright 2026 Bowler Hat LLC. All Rights Reserved.

This program is free software. You can redistribute and/or modify it in

accordance with the terms of the accompanying license agreement.

*/

package feathers.controls;

import feathers.controls.supportClasses.BaseScrollContainer;

import feathers.controls.supportClasses.TextFieldViewPort;

import feathers.core.IStageFocusDelegate;

import feathers.core.IStateContext;

import feathers.core.IStateObserver;

import feathers.core.ITextControl;

import feathers.core.InvalidationFlag;

import feathers.core.PopUpManager;

import feathers.events.FeathersEvent;

import feathers.text.TextFormat;

import feathers.utils.AbstractDisplayObjectFactory;

import feathers.utils.DisplayObjectFactory;

import openfl.display.DisplayObject;

import openfl.display.InteractiveObject;

import openfl.events.Event;

import openfl.events.FocusEvent;

import openfl.events.KeyboardEvent;

import openfl.text.AntiAliasType;

import openfl.text.GridFitType;

import openfl.text.TextField;

/**

A text entry control that allows users to enter and edit multiple lines of

uniformly-formatted text with the ability to scroll.

The following example sets the text in a text area, selects the text, and

listens for when the text value changes:

```haxe

var textArea = new TextArea();

textArea.text = "Hello\nWorld"; //it's multiline!

textArea.selectRange(0, textArea.text.length);

textArea.addEventListener(Event.CHANGE, textArea_changeHandler);

this.addChild( textArea );

```

@event openfl.events.Event.CHANGE Dispatched when `TextArea.text` changes.

@see [Tutorial: How to use the TextArea component](https://feathersui.com/learn/haxe-openfl/text-area/)

@since 1.0.0

**/

@:event(openfl.events.Event.CHANGE)

@defaultXmlProperty("text")

@:styleContext

class TextArea extends BaseScrollContainer implements IStateContext<TextInputState> implements ITextControl implements IStageFocusDelegate {

private static final INVALIDATION_FLAG_ERROR_CALLOUT_FACTORY = InvalidationFlag.CUSTOM("errorCalloutFactory");

/**

The variant used to style the error string `TextCallout` child component

in a theme.

To override this default variant, set the

`TextArea.customErrorCalloutVariant` property.

@see `TextArea.customErrorCalloutVariant`

@see `feathers.style.IVariantStyleObject.variant`

@see [Feathers UI User Manual: Themes](https://feathersui.com/learn/haxe-openfl/themes/)

@since 1.0.0

**/

public static final CHILD_VARIANT_ERROR_CALLOUT = "textArea_errorCallout";

private static final defaultErrorCalloutFactory = DisplayObjectFactory.withClass(TextCallout);

/**

Creates a new `TextArea` object.

@since 1.0.0

**/

public function new(text:String = "", ?prompt:String, ?changeListener:(Event) -> Void) {

initializeTextAreaTheme();

super();

this.text = text;

this.prompt = prompt;

this.tabEnabled = true;

this.tabChildren = false;

this.focusRect = null;

if (this.viewPort == null) {

this.textFieldViewPort = new TextFieldViewPort();

this.textFieldViewPort.wordWrap = true;

this.textFieldViewPort.multiline = true;

this.textFieldViewPort.addEventListener(Event.CHANGE, textArea_viewPort_changeHandler);

this.addChild(this.textFieldViewPort);

this.viewPort = this.textFieldViewPort;

}

this.addEventListener(FocusEvent.FOCUS_IN, textArea_focusInHandler);

this.addEventListener(FocusEvent.FOCUS_OUT, textArea_focusOutHandler);

if (changeListener != null) {

this.addEventListener(Event.CHANGE, changeListener);

}

}

private var textFieldViewPort:TextFieldViewPort;

private var promptTextField:TextField;

private var errorStringCallout:TextCallout;

private var _previousTextFormat:TextFormat = null;

private var _previousSimpleTextFormat:openfl.text.TextFormat = null;

private var _previousPrompt:String = null;

private var _previousPromptTextFormat:TextFormat = null;

private var _previousPromptSimpleTextFormat:openfl.text.TextFormat = null;

private var _updatedPromptStyles = false;

private var _promptTextMeasuredWidth:Float;

private var _promptTextMeasuredHeight:Float;

#if (flash && haxe_ver < 4.3) @:getter(tabEnabled) #end

override private function get_tabEnabled():Bool {

return this._enabled && this.rawTabEnabled;

}

private var _editable:Bool = true;

/**

Indicates if the text area is editable.

The following example disables editing:

```haxe

textArea.editable = false;

```

@since 1.0.0

**/

public var editable(get, set):Bool;

private function get_editable():Bool {

return this._editable;

}

private function set_editable(value:Bool):Bool {

if (this._editable == value) {

return this._editable;

}

this._editable = value;

this.setInvalid(STATE);

return this._editable;

}

private var _selectable:Bool = true;

/**

Indicates if the text can be selected.

The following example disables selection:

```haxe

textArea.selectable = false;

```

@since 1.0.0

**/

public var selectable(get, set):Bool;

private function get_selectable():Bool {

return this._selectable;

}

private function set_selectable(value:Bool):Bool {

if (this._selectable == value) {

return this._selectable;

}

this._selectable = value;

this.setInvalid(DATA);

return this._selectable;

}

private var _currentState:TextInputState = ENABLED;

/**

The current state of the text area.

@see `feathers.controls.TextInputState`

@see `FeathersEvent.STATE_CHANGE`

@since 1.0.0

**/

@:bindable("stateChange")

public var currentState(get, never):#if flash Dynamic #else TextInputState #end;

private function get_currentState():#if flash Dynamic #else TextInputState #end {

return this._currentState;

}

override private function set_enabled(value:Bool):Bool {

super.enabled = value;

this.refreshState();

return this._enabled;

}

private var _text:String;

/**

The text displayed by the text area.

When the value of the `text` property changes, the text area will

dispatch an event of type `Event.CHANGE`.

The following example sets the text area's text:

```haxe

textArea.text = "Good afternoon!";

```

@default ""

@see `TextArea.textFormat`

@see [`openfl.events.Event.CHANGE`](https://api.openfl.org/openfl/events/Event.html#CHANGE)

@since 1.0.0

**/

@:bindable("change")

@:inspectable

public var text(get, set):String;

private function get_text():String {

return this._text;

}

private function set_text(value:String):String {

if (value == null) {

// null gets converted to an empty string

if (this._text.length == 0) {

// already an empty string

return this._text;

}

value = "";

}

if (this._text == value) {

return this._text;

}

this._text = value;

this.setInvalid(DATA);

FeathersEvent.dispatch(this, Event.CHANGE);

return this._text;

}

/**

@see `feathers.core.ITextControl.baseline`

**/

public var baseline(get, never):Float;

private function get_baseline():Float {

if (this.textFieldViewPort == null) {

return 0.0;

}

return this.paddingTop + this.textFieldViewPort.baseline;

}

private var _prompt:String;

/**

The text displayed by the text area when the length of the `text`

property is `0`.

The following example sets the text area's prompt:

```haxe

textArea.prompt = "Minimum 8 characters required";

```

@default null

@see `TextArea.promptTextFormat`

@since 1.0.0

**/

@:inspectable

public var prompt(get, set):String;

private function get_prompt():String {

return this._prompt;

}

private function set_prompt(value:String):String {

if (this._prompt == value) {

return this._prompt;

}

this._prompt = value;

this.setInvalid(DATA);

return this._prompt;

}

// for some reason, naming this _restrict fails in hxcpp, and __restrict

// fails in hl/c. how many underscores to work everywhere?

private var ___restrict:String;

/**

Limits the set of characters that may be typed into the `TextArea`.

In the following example, the text area's allowed characters are

restricted:

```haxe

textArea.restrict = "0-9";

```

@default null

@see [`TextField.restrict`](https://api.openfl.org/openfl/text/TextField.html#restrict)

@since 1.0.0

**/

public var restrict(get, set):String;

private function get_restrict():String {

return this.___restrict;

}

private function set_restrict(value:String):String {

if (this.___restrict == value) {

return this.___restrict;

}

this.___restrict = value;

this.setInvalid(DATA);

return this.___restrict;

}

private var _displayAsPassword:Bool = false;

/**

Masks the text so that it cannot be read.

In the following example, the text area's text is displayed as a

password:

```haxe

textArea.displayAsPassword = true;

```

@default null

@see [`TextField.displayAsPassword`](https://api.openfl.org/openfl/text/TextField.html#displayAsPassword)

@since 1.0.0

**/

public var displayAsPassword(get, set):Bool;

private function get_displayAsPassword():Bool {

return this._displayAsPassword;

}

private function set_displayAsPassword(value:Bool):Bool {

if (this._displayAsPassword == value) {

return this._displayAsPassword;

}

this._displayAsPassword = value;

this.setInvalid(DATA);

return this._displayAsPassword;

}

/**

An alternate to `focusRectSkin` that is displayed when the text input is

focused and `errorString` is not `null`.

@since 1.3.0

**/

@:style

public var errorFocusRectSkin:DisplayObject = null;

private var _errorStatePriority:Int = 0;

/**

Sets the priority of `TextInputState.ERROR`. If two states are

possible, the state with the higher priority takes precedence. If the

priorities are equal, `TextInputState.FOCUSED` takes the default

precedence.

@since 1.3.0

**/

public var errorStatePriority(get, set):Int;

private function get_errorStatePriority():Int {

return this._errorStatePriority;

}

private function set_errorStatePriority(value:Int):Int {

if (this._errorStatePriority == value) {

return this._errorStatePriority;

}

this._errorStatePriority = value;

this.setInvalid(STATE);

return this._errorStatePriority;

}

private var _focusedStatePriority:Int = 0;

/**

Sets the priority of `TextInputState.FOCUSED`. If two states are

possible, the state with the higher priority takes precedence. If the

priorities are equal, `TextInputState.FOCUSED` takes the default

precedence.

@since 1.3.0

**/

public var focusedStatePriority(get, set):Int;

private function get_focusedStatePriority():Int {

return this._errorStatePriority;

}

private function set_focusedStatePriority(value:Int):Int {

if (this._focusedStatePriority == value) {

return this._focusedStatePriority;

}

this._focusedStatePriority = value;

this.setInvalid(STATE);

return this._focusedStatePriority;

}

private var _errorString:String = null;

/**

Error text to display in a `TextCallout` when the text input has focus.

When this value is not `null` the text area's `currentState` is

changed to `TextInputState.ERROR`.

An empty string will change the background, but no `TextCallout` will

appear on focus.

To clear an error, the `errorString` property must be set to `null`.

The following example displays an error string:

```haxe

texterror.errorString = "Something is wrong";

```

@see `TextArea.currentState`

@since 1.0.0

**/

public var errorString(get, set):String;

private function get_errorString():String {

return this._errorString;

}

private function set_errorString(value:String):String {

if (this._errorString == value) {

return this._errorString;

}

this._errorString = value;

this.refreshState();

this.setInvalid(DATA);

return this._errorString;

}

/**

Indicates if the callout for the `errorString` is currently open or

closed.

@see `TextInput.errorString`

@since 1.0.0

**/

public var errorStringCalloutOpen(get, never):Bool;

private function get_errorStringCalloutOpen():Bool {

return this.errorStringCallout != null && this.errorStringCallout.parent != null;

}

/**

Indicates if scrolling is smooth or strictly by line.

In the following example, smooth scrolling is enabled:

```haxe

textArea.smoothScrolling = true;

```

@since 1.0.0

**/

@:style

public var smoothScrolling:Bool = false;

private var _stateToTextFormat:Map<TextInputState, AbstractTextFormat> = new Map();

/**

The font styles used to render the text area's text.

In the following example, the text area's formatting is customized:

```haxe

textArea.textFormat = new TextFormat("Helvetica", 20, 0xcc0000);

```

@see `TextArea.text`

@see `TextArea.getTextFormatForState()`

@see `TextArea.setTextFormatForState()`

@see `TextArea.embedFonts`

@since 1.0.0

**/

@:style

public var textFormat:AbstractTextFormat = null;

/**

The font styles used to render the text area's text when the text area

is disabled.

In the following example, the text area's disabled text formatting is

customized:

```haxe

textArea.enabled = false;

textArea.disabledTextFormat = new TextFormat("Helvetica", 20, 0xee0000);

```

@see `TextArea.textFormat`

@since 1.0.0

**/

@:style

public var disabledTextFormat:AbstractTextFormat = null;

/**

The font styles used to render the text area's prompt text.

In the following example, the text area's prompt formatting is customized:

```haxe

textArea.promptTextFormat = new TextFormat("Helvetica", 20, 0xcc0000);

```

@see `TextArea.prompt`

@since 1.0.0

**/

@:style

public var promptTextFormat:AbstractTextFormat = null;

/**

Determines if an embedded font is used or not.

In the following example, the text area uses embedded fonts:

```haxe

textArea.embedFonts = true;

```

@see `TextArea.textFormat`

@since 1.0.0

**/

@:style

public var embedFonts:Bool = false;

/**

Configures the `alpha` value of the text area's text.

In the following example, the text area's text alpha is customized:

```haxe

textArea.textAlpha = 0.5;

```

@see `TextArea.textFormat`

@see `TextArea.disabledTextAlpha`

@since 1.4.0

**/

@:style

@:inspectable(minValue = "0.0", maxValue = "1.0", verbose = "1")

public var textAlpha:Float = 1.0;

/**

When `disabledTextAlpha` is not `null`, sets the `alpha` property of the

text to this value when the the `enabled` property is set to `false`.

In the following example, the text area's disabled text alpha is customized:

```haxe

textArea.disabledTextAlpha = 0.5;

```

@see `TextArea.textAlpha`

@since 1.4.0

**/

@:style

@:inspectable(minValue = "0.0", maxValue = "1.0", verbose = "1")

public var disabledTextAlpha:Null<Float> = null;

/**

Determines the type of anti-aliasing used for embedded fonts.

In the following example, the text area uses advanced anti-aliasing:

```haxe

textArea.embedFonts = true;

textArea.antiAliasType = ADVANCED;

```

@see `TextArea.embedFonts`

@see `TextArea.gridFitType`

@since 1.4.0

**/

@:style

public var antiAliasType:AntiAliasType = NORMAL;

/**

Determines the type of anti-aliasing used for embedded fonts.

In the following example, the text area uses sub-pixel grid fitting:

```haxe

textArea.embedFonts = true;

textArea.antiAliasType = ADVANCED;

textArea.gridFitType = SUBPIXEL;

```

@see `TextArea.antiAliasType`

@see `TextArea.embedFonts`

@since 1.4.0

**/

@:style

public var gridFitType:GridFitType = PIXEL;

/**

Determines if the text will wrap when reaching the right edge, or if

horizontal scrolling will be required.

In the following example, the text area will not wrap its text:

```haxe

textArea.wordWrap = false;

```

@since 1.0.0

**/

@:style

public var wordWrap:Bool = true;

/**

The minimum space, in pixels, between the view port's top edge and the

text.

In the following example, the text padding is set to 20 pixels on the

top edge:

```haxe

textArea.textPaddingTop = 20.0;

```

@since 1.0.0

**/

@:style

public var textPaddingTop:Float = 0.0;

/**

The minimum space, in pixels, between the view port's right edge and

the text.

In the following example, the text padding is set to 20 pixels on the

right edge:

```haxe

textArea.textPaddingRight = 20.0;

```

@since 1.0.0

**/

@:style

public var textPaddingRight:Float = 0.0;

/**

The minimum space, in pixels, between the view port's bottom edge and

the text.

In the following example, the text padding is set to 20 pixels on the

bottom edge:

```haxe

textArea.textPaddingBottom = 20.0;

```

@since 1.0.0

**/

@:style

public var textPaddingBottom:Float = 0.0;

/**

The minimum space, in pixels, between the view port's left edge and the

text.

In the following example, the text padding is set to 20 pixels on the

left edge:

```haxe

textArea.textPaddingLeft = 20.0;

```

@since 1.0.0

**/

@:style

public var textPaddingLeft:Float = 0.0;

/**

Indicates if the prompt is shown when the length of the text is `0` and

the text input is focused. Keeping the prompt visible until the user

types something is considered better for usability because the user may

look away for a moment and forget the prompt when they return.

The following example set the prompt to be hidden when focused and the

text is empty:

```haxe

input.showPromptWhenEmptyAndFocused = false;

```

@since 1.1.0

**/

@:style

public var showPromptWhenEmptyAndFocused:Bool = true;

/**

The character position of the anchor part of the selection. If the

selection is changed with the arrow keys, the active index changes and

the anchor index stays fixed. If both the active index and the anchor

index are equal, then no text is selected and both values represent the

position of the caret.

@see `TextArea.selectionActiveIndex`

@see `TextArea.selectRange()`

@see `TextArea.selectAll()`

@since 1.0.0

**/

public var selectionAnchorIndex(get, never):Int;

private function get_selectionAnchorIndex():Int {

return this.textFieldViewPort.selectionAnchorIndex;

}

/**

The character position of the active part of the selection. If the

selection is changed with the arrow keys, the active index changes and

the anchor index stays fixed. If both the active index and the anchor

index are equal, then no text is selected and both values represent the

position of the caret.

@see `TextArea.selectionAnchorIndex`

@see `TextArea.selectRange()`

@see `TextArea.selectAll()`

@since 1.0.0

**/

public var selectionActiveIndex(get, never):Int;

private function get_selectionActiveIndex():Int {

return this.textFieldViewPort.selectionActiveIndex;

}

private var _maxChars:Int = 0;

/**

The maximum number of characters that may be entered into the text

input. If set to `0`, the length of the text is unrestricted.

@default 0

@since 1.0.0

**/

public var maxChars(get, set):Int;

private function get_maxChars():Int {

return this._maxChars;

}

private function set_maxChars(value:Int):Int {

if (this._maxChars == value) {

return this._maxChars;

}

this._maxChars = value;

this.setInvalid(DATA);

return this._maxChars;

}

private var _oldErrorCalloutFactory:DisplayObjectFactory<Dynamic, TextCallout>;

private var _errorCalloutFactory:DisplayObjectFactory<Dynamic, TextCallout>;

/**

Creates the error callout, which must be of type

`feathers.controls.TextCallout`.

In the following example, a custom error callout factory is provided:

```haxe

textArea.errorCalloutFactory = () ->

{

return new TextCallout();

};

```

@see `feathers.controls.TextCallout`

@since 1.3.0

**/

public var errorCalloutFactory(get, set):AbstractDisplayObjectFactory<Dynamic, TextCallout>;

private function get_errorCalloutFactory():AbstractDisplayObjectFactory<Dynamic, TextCallout> {

return this._errorCalloutFactory;

}

private function set_errorCalloutFactory(value:AbstractDisplayObjectFactory<Dynamic, TextCallout>):AbstractDisplayObjectFactory<Dynamic, TextCallout> {

if (this._errorCalloutFactory == value) {

return this._errorCalloutFactory;

}

this._errorCalloutFactory = value;

this.setInvalid(INVALIDATION_FLAG_ERROR_CALLOUT_FACTORY);

return this._errorCalloutFactory;

}

private var _previousCustomErrorCalloutVariant:String = null;

/**

A custom variant to set on the error callout, instead of

`TextArea.CHILD_VARIANT_ERROR_CALLOUT`.

The `customErrorCalloutVariant` will be not be used if the `TextCallout`

already has a variant set.

@see `TextArea.CHILD_VARIANT_ERROR_CALLOUT`

@see `feathers.style.IVariantStyleObject.variant`

@since 1.0.0

**/

@:style

public var customErrorCalloutVariant:String = null;

private var _ignoreViewPortTextChange = false;

override private function get_measureViewPort():Bool {

return false;

}

@:dox(hide)

public var stageFocusTarget(get, never):InteractiveObject;

private function get_stageFocusTarget():InteractiveObject {

return this.textFieldViewPort;

}

private var _stateToSkin:Map<TextInputState, DisplayObject> = new Map();

/**

Gets the skin to be used by the text area when its `currentState`

property matches the specified state value.

If a skin is not defined for a specific state, returns `null`.

@see `TextArea.setSkinForState()`

@see `TextArea.backgroundSkin`

@see `TextArea.currentState`

@see `feathers.controls.TextInputState`

@since 1.0.0

**/

public function getSkinForState(state:TextInputState):DisplayObject {

return this._stateToSkin.get(state);

}

/**

Set the skin to be used by the text area when its `currentState`

property matches the specified state value.

If a skin is not defined for a specific state, the value of the

`backgroundSkin` property will be used instead.

@see `TextArea.getSkinForState()`

@see `TextArea.backgroundSkin`

@see `TextArea.currentState`

@see `feathers.controls.TextInputState`

@since 1.0.0

**/

@style

public function setSkinForState(state:TextInputState, skin:DisplayObject):Void {

if (!this.setStyle("setSkinForState", state)) {

return;

}

var oldSkin = this._stateToSkin.get(state);

if (oldSkin != null && oldSkin == this._currentBackgroundSkin) {

this.removeCurrentBackgroundSkin(oldSkin);

this._currentBackgroundSkin = null;

}

if (skin == null) {

this._stateToSkin.remove(state);

} else {

this._stateToSkin.set(state, skin);

}

this.setInvalid(STYLES);

}

/**

Gets the text format to be used by the text area when its `currentState`

property matches the specified state value.

If a text format is not defined for a specific state, returns `null`.

@see `TextArea.setTextFormatForState()`

@see `TextArea.textFormat`

@see `TextArea.currentState`

@see `feathers.controls.TextInputState`

@since 1.0.0

**/

public function getTextFormatForState(state:TextInputState):AbstractTextFormat {

return this._stateToTextFormat.get(state);

}

/**

Set the text format to be used by the text area when its `currentState`

property matches the specified state value.

If a text format is not defined for a specific state, the value of the

`textFormat` property will be used instead.

@see `TextArea.getTextFormatForState()`

@see `TextArea.textFormat`

@see `TextArea.currentState`

@see `feathers.controls.TextInputState`

@since 1.0.0

**/

@style

public function setTextFormatForState(state:TextInputState, textFormat:AbstractTextFormat):Void {

if (!this.setStyle("setTextFormatForState", state)) {

return;

}

if (textFormat == null) {

this._stateToTextFormat.remove(state);

} else {

this._stateToTextFormat.set(state, textFormat);

}

this.setInvalid(STYLES);

}

/**

Selects the specified range of characters.

The following example selects the first three characters:

```haxe

input.selectRange(0, 3);

```

@see `TextArea.selectAll()`

@see `TextArea.selectionAnchorIndex`

@see `TextArea.selectionActiveIndex`

@since 1.0.0

**/

public function selectRange(anchorIndex:Int, activeIndex:Int):Void {

this.textFieldViewPort.selectRange(anchorIndex, activeIndex);

}

/**

Selects all of the text displayed by the text area.

@see `TextArea.selectRange()`

@see `TextArea.selectionAnchorIndex`

@see `TextArea.selectionActiveIndex`

@since 1.0.0

**/

public function selectAll():Void {

this.textFieldViewPort.selectRange(0, this._text.length);

}

/**

Sets all four text padding properties to the same value.

@see `TextArea.textPaddingTop`

@see `TextArea.textPaddingRight`

@see `TextArea.textPaddingBottom`

@see `TextArea.textPaddingLeft`

@since 1.0.0

**/