The baseline measurement of the text, in pixels.

The TextCallout that displays the value of the errorString property. The value may be null if there is no current error string or the text input does not have focus.

For internal use in subclasses.

The currently selected background, based on state.

For internal use in subclasses.

The currently visible icon. The value will be null if there is no currently visible icon.

For internal use in subclasses.

The current state of the text input.

See also

Determines if the entered text will be masked so that it cannot be seen, such as for a password input.

In the following example, the text input's text is displayed as a password:

input.displayAsPassword = true;

The default value is false.

The value added to the styleNameList of the error callout. This variable is protected so that sub-classes can customize the prompt text renderer style name in their constructors instead of using the default style name defined by DEFAULT_CHILD_STYLE_NAME_ERROR_CALLOUT.

To customize the error callout style name without subclassing, see customErrorCalloutStyleName.

See also

Error text to display in a Callout when the input has focus. When this value is not null the input's state is changed to TextInputState.ERROR. An empty string will change the background, but no Callout will appear on focus. To clear an error, the errorString property must be set to null

The following example displays an error string:

input.errorString = "Something is wrong";

The default value is null.

See also

The default IStyleProvider for all TextInput components.

The default value is null.

See also

When the FocusManager isn't enabled, hasFocus can be used instead of FocusManager.focus == textInput to determine if the text input has focus.

Determines if the text input is editable. If the text input is not editable, it will still appear enabled.

In the following example, the text input is not editable:

input.isEditable = false;

The default value is true.

See also

If the isEditable property is set to false, the isSelectable property determines if the text is selectable. If the isEditable property is set to true, the text will always be selectable.

In the following example, the text input is not selectable:

input.isEditable = false;
input.isSelectable = false;

The default value is true.

See also

The maximum number of characters that may be entered. If 0, any number of characters may be entered.

In the following example, the text input's maximum characters is specified:

input.maxChars = 10;

The default value is 0.

A text editor may be an INativeFocusOwner, so we need to return the value of its nativeFocus property. If not, then we return null.

See also

The prompt, hint, or description text displayed by the input when the value of its text is empty.

In the following example, the text input's prompt is updated:

input.prompt = "User Name";

The default value is null.

A function used to instantiate the prompt text renderer. If null, FeathersControl.defaultTextRendererFactory is used instead. The prompt text renderer must be an instance of ITextRenderer. This factory can be used to change properties on the prompt when it is first created. For instance, if you are skinning Feathers components without a theme, you might use this factory to set styles on the prompt.

The factory should have the following function signature:

function():ITextRenderer

If the prompt property is null, the prompt text renderer will not be created.

In the following example, a custom prompt factory is passed to the text input:

input.promptFactory = function():ITextRenderer
{
    return new TextFieldTextRenderer();
};

The default value is null.

See also

An object that stores properties for the input's prompt text renderer sub-component, and the properties will be passed down to the text renderer when the input validates. The available properties depend on which ITextRenderer implementation is returned by messageFactory. Refer to feathers.core.ITextRenderer for a list of available text renderer implementations.

If the subcomponent has its own subcomponents, their properties can be set too, using attribute @ notation. For example, to set the skin on the thumb which is in a SimpleScrollBar, which is in a List, you can use the following syntax:

list.verticalScrollBarProperties.@thumbProperties.defaultSkin = new Image(texture);

Setting properties in a promptFactory function instead of using promptProperties will result in better performance.

In the following example, the text input's prompt's properties are updated (this example assumes that the prompt text renderer is a TextFieldTextRenderer):

input.promptProperties.textFormat = new TextFormat( "Source Sans Pro", 16, 0x333333 );
input.promptProperties.embedFonts = true;

The default value is null.

See also

The value added to the styleNameList of the prompt text renderer. This variable is protected so that sub-classes can customize the prompt text renderer style name in their constructors instead of using the default style name defined by DEFAULT_CHILD_STYLE_NAME_PROMPT.

To customize the prompt text renderer style name without subclassing, see customPromptStyleName.

See also

The prompt text renderer sub-component.

For internal use in subclasses.

Limits the set of characters that may be entered.

In the following example, the text input's allowed characters are restricted:

input.restrict = "0-9";

The default value is null.

The index of the first character of the selection. If no text is selected, then this is the value of the caret index. This value will always be smaller than selectionEndIndex.

The index of the last character of the selection. If no text is selected, then this is the value of the caret index. This value will always be larger than selectionBeginIndex.

The text displayed by the text input. The text input dispatches Event.CHANGE when the value of the text property changes for any reason.

In the following example, the text input's text is updated:

input.text = "Hello World";

The default value is "".

See also

The text editor sub-component.

For internal use in subclasses.

A function used to instantiate the text editor. If null, FeathersControl.defaultTextEditorFactory is used instead. The text editor must be an instance of ITextEditor. This factory can be used to change properties on the text editor when it is first created. For instance, if you are skinning Feathers components without a theme, you might use this factory to set styles on the text editor.

The factory should have the following function signature:

function():ITextEditor

In the following example, a custom text editor factory is passed to the text input:

input.textEditorFactory = function():ITextEditor
{
    return new TextFieldTextEditor();
};

The default value is null.

See also

An object that stores properties for the input's text editor sub-component, and the properties will be passed down to the text editor when the input validates. The available properties depend on which ITextEditor implementation is returned by textEditorFactory. Refer to feathers.core.ITextEditor for a list of available text editor implementations.

If the subcomponent has its own subcomponents, their properties can be set too, using attribute @ notation. For example, to set the skin on the thumb which is in a SimpleScrollBar, which is in a List, you can use the following syntax:

list.verticalScrollBarProperties.@thumbProperties.defaultSkin = new Image(texture);

Setting properties in a textEditorFactory function instead of using textEditorProperties will result in better performance.

In the following example, the text input's text editor properties are specified (this example assumes that the text editor is a StageTextTextEditor):

input.textEditorProperties.fontName = "Helvetica";
input.textEditorProperties.fontSize = 16;

The default value is null.

See also

The value added to the styleNameList of the text editor. This variable is protected so that sub-classes can customize the text editor style name in their constructors instead of using the default style name defined by DEFAULT_CHILD_STYLE_NAME_TEXT_EDITOR.

To customize the text editor style name without subclassing, see customTextEditorStyleName.

See also

Constructor.

If the component's dimensions have not been set explicitly, it will measure its content and determine an ideal size for itself. If the explicitWidth or explicitHeight member variables are set, those value will be used without additional measurement. If one is set, but not the other, the dimension with the explicit value will not be measured, but the other non-explicit dimension will still need measurement.

Calls saveMeasurements() to set up the actualWidth and actualHeight member variables used for layout.

Meant for internal use, and subclasses may override this function with a custom implementation.

Manually removes focus from the text input control.

Creates and adds the textEditor sub-component and removes the old instance, if one exists.

Meant for internal use, and subclasses may override this function with a custom implementation.

See also

Gets the font styles to be used to display the input's text when the input's currentState property matches the specified state value.

If font styles are not defined for a specific state, returns null.

Parameters

See also

Gets the icon to be used by the text input when the input's currentState property matches the specified state value.

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

Parameters

See also

Gets the font styles to be used to display the input's prompt when the input's currentState property matches the specified state value.

If prompt font styles are not defined for a specific state, returns null.

Parameters

See also

Gets the skin to be used by the text input when the input's currentState property matches the specified state value.

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

Parameters

See also

Positions and sizes the text input's children.

For internal use in subclasses.

Sets the currentBackground property.

For internal use in subclasses.

Sets the currentIcon property.

For internal use in subclasses.

Sets the range of selected characters. If both values are the same, or the end index is -1, the text insertion position is changed and nothing is selected.

Parameters

Focuses the text input control so that it may be edited, and selects all of its text. Call selectRange() after setFocus() to select a different range.

See also

Sets the font styles to be used to display the input's text when the input's currentState property matches the specified state value.

If font styles are not defined for a specific state, the value of the fontStyles property will be used instead.

Note: if the text editor has been customized with advanced font formatting, it may override the values specified with setFontStylesForState() and properties like fontStyles and disabledFontStyles.

Parameters

See also

Sets the icon to be used by the text input when the input's currentState property matches the specified state value.

If an icon is not defined for a specific state, the value of the defaultIcon property will be used instead.

Parameters

See also

Sets the font styles to be used to display the input's prompt when the input's currentState property matches the specified state value.

If prompt font styles are not defined for a specific state, the value of the promptFontStyles property will be used instead.

Note: if the text renderer has been customized with advanced font formatting, it may override the values specified with setPromptFontStylesForState() and properties like promptFontStyles and promptDisabledFontStyles.

Parameters

See also

Sets the skin to be used by the text input when the input's 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.

Parameters

See also

Dispatched when the text input's text property changes.

The properties of the event object have the following values:

See also

Dispatched when the user presses the Enter key while the text input has focus. This event may not be dispatched at all times. Certain text editors will not dispatch an event for the enter key on some platforms, depending on the values of certain properties. This may include the default values for some platforms! If you've encountered this issue, please see the specific text editor's API documentation for complete details of this event's limitations and requirements.

The properties of the event object have the following values:

Dispatched when the text input receives focus.

The properties of the event object have the following values:

Dispatched when the text input loses focus.

The properties of the event object have the following values:

Dispatched when the soft keyboard is activated by the text editor. Not all text editors will activate a soft keyboard.

The properties of the event object have the following values:

Dispatched when the soft keyboard is about the be activated by the text editor. Not all text editors will activate a soft keyboard.

The properties of the event object have the following values:

Dispatched when the soft keyboard is deactivated by the text editor. Not all text editors will activate a soft keyboard.

The properties of the event object have the following values:

Dispatched when the display object's state changes.

The properties of the event object have the following values:

See also

The location where the text editor is aligned vertically (on the y-axis).

The following example aligns the text editor to the top:

input.verticalAlign = VerticalAlign.TOP;

The default value is feathers.layout.VerticalAlign.MIDDLE.

See also

If not null, the dimensions of the typicalText will be used in the calculation of the text input's full dimensions. If the text input's dimensions haven't been set explicitly, it's calculated dimensions will be at least large enough to display the typicalText. Other children, such as the background skin and the prompt text renderer may also affect the dimensions of the text input, allowing it to, potentially, be bigger than the rendered typicalText.

In the following example, the text input's typical text is updated:

input.text = "We want to allow the text input to show all of this text";

The default value is null.

The font styles used to display the input's prompt text.

In the following example, the font styles are customized:

input.promptFontStyles = new TextFormat( "Helvetica", 20, 0xcc0000 );

Note: The starling.text.TextFormat class defines a number of common font styles, but the text renderer being used may support a larger number of ways to be customized. Use the promptFactory to set more advanced styles on the text renderer.

The default value is null.

See also

The font styles used to display the input's prompt when the input is disabled.

In the following example, the disabled font styles are customized:

input.promptDisabledFontStyles = new TextFormat( "Helvetica", 20, 0x999999 );

Note: The starling.text.TextFormat class defines a number of common font styles, but the text renderer being used may support a larger number of ways to be customized. Use the promptFactory to set more advanced styles on the text renderer.

The default value is null.

See also

The minimum space, in pixels, between the input's left edge and the input's content.

In the following example, the text input's left padding is set to 20 pixels:

input.paddingLeft = 20;

The default value is 0.

See also

The minimum space, in pixels, between the input's bottom edge and the input's content.

In the following example, the text input's bottom padding is set to 20 pixels:

input.paddingBottom = 20;

The default value is 0.

See also

The minimum space, in pixels, between the input's right edge and the input's content.

In the following example, the text input's right padding is set to 20 pixels:

input.paddingRight = 20;

The default value is 0.

See also

The minimum space, in pixels, between the input's top edge and the input's content.

In the following example, the text input's top padding is set to 20 pixels:

input.paddingTop = 20;

The default value is 0.

See also

Quickly sets all padding properties to the same value. The padding getter always returns the value of paddingTop, but the other padding values may be different.

In the following example, the text input's padding is set to 20 pixels:

input.padding = 20;

The default value is 0.

See also

The location of the icon, relative to the text renderer.

The following example positions the icon to the right of the text renderer:

input.defaultIcon = new Image( texture );
input.iconPosition = RelativePosition.RIGHT;

The default value is feathers.layout.RelativePosition.LEFT.

See also

The space, in pixels, between the icon and the text editor, if an icon exists.

The following example creates a gap of 50 pixels between the icon and the text editor:

button.defaultIcon = new Image( texture );
button.gap = 50;

The default value is 0.

The font styles used to display the input's text.

In the following example, the font styles are customized:

input.fontStyles = new TextFormat( "Helvetica", 20, 0xcc0000 );

Note: The starling.text.TextFormat class defines a number of common font styles, but the text editor being used may support a larger number of ways to be customized. Use the textEditorFactory to set more advanced styles on the text editor.

The default value is null.

See also

The icon used for the input's focused state. If null, then defaultIcon is used instead.

The following example gives the input an icon for the focused state:

button.focusedIcon = new Image( texture );

Alternatively, you may use setIconForState() with TextInputState.FOCUSED to set the same icon:

var icon:Image = new Image( texture );
input.setIconForState( TextInputState.FOCUSED, icon );

The default value is null.

See also

The icon used for the input's error state. If null, then defaultIcon is used instead.

The following example gives the input an icon for the error state:

button.errorIcon = new Image( texture );

Alternatively, you may use setIconForState() with TextInputState.ERROR to set the same icon:

var icon:Image = new Image( texture );
input.setIconForState( TextInputState.ERROR, icon );

The default value is null.

See also

The icon used for the input's enabled state. If null, then defaultIcon is used instead.

The following example gives the input an icon for the enabled state:

button.enabledIcon = new Image( texture );

Alternatively, you may use setIconForState() with TextInputState.ENABLED to set the same icon:

var icon:Image = new Image( texture );
input.setIconForState( TextInputState.ENABLED, icon );

The default value is null.

See also

The icon used for the input's disabled state. If null, then defaultIcon is used instead.

The following example gives the input an icon for the disabled state:

button.disabledIcon = new Image( texture );

Alternatively, you may use setIconForState() with TextInputState.DISABLED to set the same icon:

var icon:Image = new Image( texture );
input.setIconForState( TextInputState.DISABLED, icon );

The default value is null.

See also

The font styles used to display the input's text when the input is disabled.

In the following example, the disabled font styles are customized:

input.disabledFontStyles = new TextFormat( "Helvetica", 20, 0x999999 );

Alternatively, you may use setFontStylesForState() with TextInputState.DISABLED to set the same font styles:

var fontStyles:TextFormat = new TextFormat( "Helvetica", 20, 0x999999 );
input.setFontStylesForState( TextInputState.DISABLED, fontStyles );

Note: The starling.text.TextFormat class defines a number of common font styles, but the text editor being used may support a larger number of ways to be customized. Use the textEditorFactory to set more advanced styles on the text editor.

The default value is null.

See also

The icon used when no other icon is defined for the current state. Intended for use when multiple states should use the same icon.

The following example gives the input a default icon to use for all states when no specific icon is available:

input.defaultIcon = new Image( texture );

The default value is null.

See also

A style name to add to the text input's text editor sub-component. Typically used by a theme to provide different styles to different text inputs.

In the following example, a custom text editor style name is passed to the text input:

input.customTextEditorStyleName = "my-custom-text-input-text-editor";

In your theme, you can target this sub-component style name to provide different styles than the default:

getStyleProviderForClass( StageTextTextEditor ).setFunctionForStyleName( "my-custom-text-input-text-editor", setCustomTextInputTextEditorStyles );

The default value is null.

See also

A style name to add to the text input's prompt text renderer sub-component. Typically used by a theme to provide different styles to different text inputs.

In the following example, a custom prompt text renderer style name is passed to the text input:

input.customPromptStyleName = "my-custom-text-input-prompt";

In your theme, you can target this sub-component style name to provide different styles than the default:

getStyleProviderForClass( BitmapFontTextRenderer ).setFunctionForStyleName( "my-custom-text-input-prompt", setCustomTextInputPromptStyles );

The default value is null.

See also

A style name to add to the text input's error callout sub-component. Typically used by a theme to provide different styles to different text inputs.

In the following example, a custom error callout style name is passed to the text input:

input.customErrorCalloutStyleName = "my-custom-text-input-error-callout";

In your theme, you can target this sub-component style name to provide different styles than the default:

getStyleProviderForClass( Callout ).setFunctionForStyleName( "my-custom-text-input-error-callout", setCustomTextInputErrorCalloutStyles );

The default value is null.

See also

The skin used when no other skin is defined for the current state. Intended for use when multiple states should use the same skin.

The following example gives the input a default skin to use for all states when no specific skin is available:

input.backgroundSkin = new Image( texture );

The default value is null.

See also

The skin used for the input's focused state. If null, then backgroundSkin is used instead.

The following example gives the input a skin for the focused state:

input.backgroundFocusedSkin = new Image( texture );

Alternatively, you may use setSkinForState() with TextInputState.FOCUSED to set the same skin:

var skin:Image = new Image( texture );
input.setSkinForState( TextInputState.FOCUSED, skin );

The default value is null.

See also

The skin used for the input's error state. If null, then backgroundSkin is used instead.

The following example gives the input a skin for the error state:

input.backgroundErrorSkin = new Image( texture );

Alternatively, you may use setSkinForState() with TextInputState.ERROR to set the same skin:

var skin:Image = new Image( texture );
input.setSkinForState( TextInputState.ERROR, skin );

The default value is null.

See also

The skin used for the input's enabled state. If null, then backgroundSkin is used instead.

The following example gives the input a skin for the enabled state:

input.backgroundEnabledSkin = new Image( texture );

Alternatively, you may use setSkinForState() with TextInputState.ENABLED to set the same skin:

var skin:Image = new Image( texture );
input.setSkinForState( TextInputState.ENABLED, skin );

The default value is null.

See also

The skin used for the input's disabled state. If null, then backgroundSkin is used instead.

The following example gives the input a skin for the disabled state:

input.backgroundDisabledSkin = new Image( texture );

Alternatively, you may use setSkinForState() with TextInputState.DISABLED to set the same skin:

var skin:Image = new Image( texture );
input.setSkinForState( TextInputState.DISABLED, skin );

The default value is null.

See also

An alternate style name to use with TextInput to allow a theme to give it a search input style. If a theme does not provide a style for the search text input, the theme will automatically fal back to using the default text input style.

An alternate style name should always be added to a component's styleNameList before the component is initialized. If the style name is added later, it will be ignored.

In the following example, the search style is applied to a text input:

var input:TextInput = new TextInput();
input.styleNameList.add( TextInput.ALTERNATE_STYLE_NAME_SEARCH_TEXT_INPUT );
this.addChild( input );

See also

The default value added to the styleNameList of the error callout.

See also

The default value added to the styleNameList of the prompt text renderer.

See also

The default value added to the styleNameList of the text editor.

See also