com.facebook.litho.widget

Class TextInput

java.lang.Object

com.facebook.litho.ComponentLifecycle

com.facebook.litho.Component

com.facebook.litho.widget.TextInput

All Implemented Interfaces:

Equivalence<Component>, EventDispatcher, EventTriggerTarget, HasEventDispatcher, HasEventTrigger, Cloneable

public final class TextInput
extends Component

Component that renders an editable text input using an android EditText. It is measured based on the input text String representation.

Performance is critical for good user experience. Follow these tips for good performance:

• Avoid changing props at all costs as it forces expensive EditText reconfiguration.
• Avoid updating state, use Event trigger OnTrigger to update text, request view focus or set selection. TextInput.setText(c, key, text).
• Using custom inputFilters take special care to implement equals correctly or the text field must be reconfigured on every mount. (Better yet, store your InputFilter in a static or LruCache so that you're not constantly creating new instances.)

Because this component is backed by android EditText many native capabilities are applicable:

• Use InputFilter to set a text length limit or modify text input.
• Remove android EditText underline by removing background.
• Change the input representation by passing one of the InputType constants.

It is also treated by the system as an android EditText:

• When EditText receives focus, a system keyboard is shown.
• When the user opens the screen and android EditText is the first element in the View hierarchy, it gains focus.

Example of multiline editable text with custom text color, text length limit, removed underline drawable, and sentence capitalisation:

 private static final InputFilter lenFilter = new InputFilter.LengthFilter(maxLength);
 TextInput.create(c)
   .initialText(text)
   .textColorStateList(ColorStateList.valueOf(color))
   .multiline(true)
   .inputFilter(lenFilter)
   .backgroundColor(Color.TRANSPARENT)
   .inputType(InputType.TYPE_CLASS_TEXT | InputType.TYPE_TEXT_FLAG_CAP_SENTENCES)
   .build();
 

See Also:

com.facebook.litho.widget.TextInputSpec

Optional Props

cursorDrawableRes

Drawable to set as an edit text cursor.

Type:

int

editable

If set, allows the text to be editable.

Type:

boolean

ellipsize

If set, specifies the position of the text to be ellipsized. See android documentation for behavior description.

Type:

android.text.TextUtils.TruncateAt

error

Sets the right-hand compound drawable of the TextView to the "error" icon and sets an error message that will be displayed in a popup when the TextView has focus. The icon and error message will be reset to null when any key events cause changes to the TextView's text. If the error is null, the error message and icon will be cleared. See https://developer.android.com/reference/android/widget/TextView.html#setError for more details.

Type:

java.lang.CharSequence

errorDrawable

Will show along with the error message when a message is set. @see {@link EditText}

Type:

android.graphics.drawable.Drawable

gravity

Gravity for the text within its container.

Type:

int

highlightColor

Color for selected text.

Type:

java.lang.Integer

hint

Hint text to display.

Type:

java.lang.CharSequence

hintColorStateList

Type:

android.content.res.ColorStateList

imeOptions

Type of data in the text field, reported to an IME when it has focus.

Type:

int

initialText

Initial text to display. If set, the value is set on the EditText exactly once: on initial mount. From then on, the EditText's text property is not modified.

Type:

java.lang.CharSequence

inputBackground

The background of the EditText itself; this is subtly distinct from the Litho background prop. The padding of the inputBackground drawable will be applied to the EditText itself, insetting the cursor and text field.

Type:

android.graphics.drawable.Drawable

inputFilters

Used to filter the input to e.g. a max character count.

Type:

java.util.List

inputType

Type of data being placed in a text field, used to help an input method decide how to let the user enter text. To add multiline use multiline(true) method.

Type:

int

maxLines

Maximum number of lines to show.

Type:

int

minLines

Minimum number of lines to show.

Type:

int

movementMethod

Used to set cursor positioning, scrolling and text selection functionality in EditText

Type:

android.text.method.MovementMethod

multiline

If set to true, type of the input will be changed to multiline TEXT. Because passwords or numbers couldn't be multiline by definition.

Type:

boolean

shadowColor

Color for the shadow underneath the text.

Type:

int

shadowDx

Horizontal offset of the shadow.

Type:

float

shadowDy

Vertical offset of the shadow.

Type:

float

shadowRadius

Blur radius of the shadow.

Type:

float

textAlignment

Alignment of the text within its container. This only has effect on API level 17 and above; it's up to you to handle earlier API levels by adjusting gravity.

Type:

int

textColorStateList

ColorStateList of the text.

Type:

android.content.res.ColorStateList

textSize

Size of the text.

Type:

int

textWatchers

Used to register text watchers e.g. mentions detection.

Type:

java.util.List

typeface

Typeface for the text.

Type:

android.graphics.Typeface

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TextInput.Builder

Nested classes/interfaces inherited from class com.facebook.litho.Component

Component.ContainerBuilder<T extends Component.ContainerBuilder<T>>

Nested classes/interfaces inherited from class com.facebook.litho.ComponentLifecycle

ComponentLifecycle.MountType, ComponentLifecycle.RenderData, ComponentLifecycle.TransitionContainer

Method Summary

Modifier and Type	Method and Description
Object	acceptTriggerEvent(EventTrigger eventTrigger, Object eventState, Object[] params)
protected boolean	canMeasure() Whether this ComponentLifecycle is able to measure itself according to specific size constraints.
protected boolean	canPreallocate()
static void	clearFocus(ComponentContext c, Handle handle)
static void	clearFocus(ComponentContext c, String key)
static void	clearFocus(EventTrigger trigger)
static EventTrigger	clearFocusTrigger(ComponentContext c, String key) Deprecated.
static TextInput.Builder	create(ComponentContext context)
static TextInput.Builder	create(ComponentContext context, int defStyleAttr, int defStyleRes)
protected void	createInitialState(ComponentContext c)
static void	dispatchKey(ComponentContext c, Handle handle, KeyEvent keyEvent)
static void	dispatchKey(ComponentContext c, String key, KeyEvent keyEvent)
static void	dispatchKey(EventTrigger trigger, KeyEvent keyEvent)
static EventTrigger	dispatchKeyTrigger(ComponentContext c, String key) Deprecated.
static EventHandler	getEditorActionEventHandler(ComponentContext context)
static EventHandler	getInputConnectionEventHandler(ComponentContext context)
static EventHandler	getKeyPreImeEventHandler(ComponentContext context)
static EventHandler	getKeyUpEventHandler(ComponentContext context)
ComponentLifecycle.MountType	getMountType() This indicates the type of the Object that will be returned by ComponentLifecycle.mount(com.facebook.litho.ComponentContext, java.lang.Object).
static EventHandler	getSelectionChangedEventHandler(ComponentContext context)
static EventHandler	getSetTextEventHandler(ComponentContext context)
protected StateContainer	getStateContainer()
static CharSequence	getText(ComponentContext c, Handle handle)
static CharSequence	getText(ComponentContext c, String key)
static CharSequence	getText(EventTrigger trigger)
static EventHandler	getTextChangedEventHandler(ComponentContext context)
static EventTrigger	getTextTrigger(ComponentContext c, String key) Deprecated.
protected boolean	hasState()
boolean	isEquivalentTo(Component other) Compares this component to a different one to check if they are the same
boolean	isPureRender()
TextInput	makeShallowCopy()
protected void	onBind(ComponentContext c, Object editText)
protected Object	onCreateMountContent(Context c) Create the object that will be mounted in the LithoView.
protected void	onLoadStyle(ComponentContext c)
protected void	onMeasure(ComponentContext c, ComponentLayout layout, int widthSpec, int heightSpec, Size size)
protected void	onMount(ComponentContext c, Object editText) Deploy all UI elements representing the final bounds defined in the given ComponentLayout.
protected void	onUnbind(ComponentContext c, Object editText)
protected void	onUnmount(ComponentContext c, Object editText) Unload UI elements associated with this component.
protected int	poolSize()
void	recordEventTrigger(EventTriggersContainer container)
protected static void	remeasureForUpdatedText(ComponentContext c)
protected static void	remeasureForUpdatedTextAsync(ComponentContext c)
protected static void	remeasureForUpdatedTextSync(ComponentContext c)
static void	requestFocus(ComponentContext c, Handle handle)
static void	requestFocus(ComponentContext c, String key)
static void	requestFocus(EventTrigger trigger)
static EventTrigger	requestFocusTrigger(ComponentContext c, String key) Deprecated.
static void	setSelection(ComponentContext c, Handle handle, int start, int end)
static void	setSelection(ComponentContext c, String key, int start, int end)
static void	setSelection(EventTrigger trigger, int start, int end)
static EventTrigger	setSelectionTrigger(ComponentContext c, String key) Deprecated.
static void	setText(ComponentContext c, Handle handle, CharSequence text)
static void	setText(ComponentContext c, String key, CharSequence text)
static void	setText(EventTrigger trigger, CharSequence text)
static EventTrigger	setTextTrigger(ComponentContext c, String key) Deprecated.
protected boolean	shouldUpdate(Component _prevAbstractImpl, Component _nextAbstractImpl) Whether the component needs updating.
protected void	transferState(StateContainer _prevStateContainer, StateContainer _nextStateContainer) Call this to transfer the State annotated values between two Component with the same global scope.

Methods inherited from class com.facebook.litho.Component

bindDynamicProp, canResolve, clearCachedLayout, copyInterStageImpl, getCommonProps, getDynamicProps, getEventDispatcher, getHandle, getId, getKey, getScopedContext, getSimpleName, getSimpleNameDelegate, hasBackgroundSet, hasClickHandlerSet, measure, measureMightNotCacheInternalNode, registerWorkingRange, retrieveValue, setScopedContext, updateInternalChildState, willRender

Methods inherited from class com.facebook.litho.ComponentLifecycle

applyPreviousRenderData, callsShouldUpdateOnMount, createMountContent, dispatchErrorEvent, dispatchErrorEvent, dispatchOnEnteredRange, dispatchOnEvent, dispatchOnExitedRange, getEventTrigger, getEventTrigger, getExtraAccessibilityNodeAt, getExtraAccessibilityNodesCount, getTreePropsForChildren, hasAttachDetachCallback, hasChildLithoViews, implementsAccessibility, implementsExtraAccessibilityNodes, isLayoutSpecWithSizeSpecCheck, isMountSizeDependent, needsPreviousRenderData, newEventHandler, newEventTrigger, onAttached, onBoundsDefined, onCreateLayout, onCreateLayoutWithSizeSpec, onCreateMountContentPool, onCreateTransition, onDetached, onError, onMeasureBaseline, onPopulateAccessibilityNode, onPopulateExtraAccessibilityNode, onPrepare, onShouldCreateLayoutWithNewSizeSpec, populateTreeProps, recordRenderData, resolve, shouldAlwaysRemeasure, shouldUseGlobalPool

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getStateContainer

protected StateContainer getStateContainer()

Overrides:

getStateContainer in class Component

isEquivalentTo

public boolean isEquivalentTo(Component other)

Description copied from class: Component

Compares this component to a different one to check if they are the same

This is used to be able to skip rendering a component again. We avoid using the Object.equals(Object) so we can optimize the code better over time since we don't have to adhere to the contract required for a equals method.

Specified by:

isEquivalentTo in interface Equivalence<Component>

Overrides:

isEquivalentTo in class Component

Parameters:

other - the component to compare to

Returns:

true if the components are of the same type and have the same props

makeShallowCopy

public TextInput makeShallowCopy()

Overrides:

makeShallowCopy in class Component

createInitialState

protected void createInitialState(ComponentContext c)

Overrides:

createInitialState in class ComponentLifecycle

onLoadStyle

protected void onLoadStyle(ComponentContext c)

Overrides:

onLoadStyle in class ComponentLifecycle

onMeasure

protected void onMeasure(ComponentContext c,
                         ComponentLayout layout,
                         int widthSpec,
                         int heightSpec,
                         Size size)

Overrides:

onMeasure in class ComponentLifecycle

canMeasure

protected boolean canMeasure()

Description copied from class: ComponentLifecycle

Whether this ComponentLifecycle is able to measure itself according to specific size constraints.

Overrides:

canMeasure in class ComponentLifecycle

shouldUpdate

protected boolean shouldUpdate(Component _prevAbstractImpl,
                               Component _nextAbstractImpl)

Description copied from class: ComponentLifecycle

Whether the component needs updating.

For layout components, the framework will verify that none of the children of the component need updating, and that both components have the same number of children. Therefore this method just needs to determine any changes to the top-level component that would cause it to need to be updated (for example, a click handler was added).

For mount specs, the framework does nothing extra and this method alone determines whether the component is updated or not.

Overrides:

shouldUpdate in class ComponentLifecycle

Parameters:

_prevAbstractImpl - the previous component to compare against.

_nextAbstractImpl - the component that is now in use.

Returns:

true if the component needs an update, false otherwise.

onCreateMountContent

protected Object onCreateMountContent(Context c)

Description copied from class: ComponentLifecycle

Create the object that will be mounted in the LithoView.

Overrides:

onCreateMountContent in class ComponentLifecycle

Parameters:

c - The Context to be used to create the content.

Returns:

an Object that can be mounted for this component.

onMount

protected void onMount(ComponentContext c,
                       Object editText)

Description copied from class: ComponentLifecycle

Deploy all UI elements representing the final bounds defined in the given ComponentLayout. Return either a Drawable or a View or null to be mounted.

Overrides:

onMount in class ComponentLifecycle

Parameters:

c - The ComponentContext to mount the component into.

onBind

protected void onBind(ComponentContext c,
                      Object editText)

Overrides:

onBind in class ComponentLifecycle

onUnmount

protected void onUnmount(ComponentContext c,
                         Object editText)

Description copied from class: ComponentLifecycle

Unload UI elements associated with this component.

Overrides:

onUnmount in class ComponentLifecycle

Parameters:

c - The Context for this mount operation.

editText - The Drawable or View mounted by this component.

onUnbind

protected void onUnbind(ComponentContext c,
                        Object editText)

Overrides:

onUnbind in class ComponentLifecycle

getMountType

public ComponentLifecycle.MountType getMountType()

Description copied from class: ComponentLifecycle

This indicates the type of the Object that will be returned by ComponentLifecycle.mount(com.facebook.litho.ComponentContext, java.lang.Object).

Overrides:

getMountType in class ComponentLifecycle

Returns:

one of ComponentLifecycle.MountType

poolSize

protected int poolSize()

Overrides:

poolSize in class ComponentLifecycle

canPreallocate

protected boolean canPreallocate()

Overrides:

canPreallocate in class ComponentLifecycle

Returns:

true if this component can be preallocated.

isPureRender

public boolean isPureRender()

Overrides:

isPureRender in class ComponentLifecycle

getTextChangedEventHandler

public static EventHandler getTextChangedEventHandler(ComponentContext context)

getSelectionChangedEventHandler

public static EventHandler getSelectionChangedEventHandler(ComponentContext context)

getKeyUpEventHandler

public static EventHandler getKeyUpEventHandler(ComponentContext context)

getKeyPreImeEventHandler

public static EventHandler getKeyPreImeEventHandler(ComponentContext context)

getEditorActionEventHandler

public static EventHandler getEditorActionEventHandler(ComponentContext context)

getSetTextEventHandler

public static EventHandler getSetTextEventHandler(ComponentContext context)

getInputConnectionEventHandler

public static EventHandler getInputConnectionEventHandler(ComponentContext context)

requestFocusTrigger

@Deprecated
public static EventTrigger requestFocusTrigger(ComponentContext c,
                                                           String key)

Deprecated.

clearFocusTrigger

@Deprecated
public static EventTrigger clearFocusTrigger(ComponentContext c,
                                                         String key)

Deprecated.

getTextTrigger

@Deprecated
public static EventTrigger getTextTrigger(ComponentContext c,
                                                      String key)

Deprecated.

setTextTrigger

@Deprecated
public static EventTrigger setTextTrigger(ComponentContext c,
                                                      String key)

Deprecated.

dispatchKeyTrigger

@Deprecated
public static EventTrigger dispatchKeyTrigger(ComponentContext c,
                                                          String key)

Deprecated.

setSelectionTrigger

@Deprecated
public static EventTrigger setSelectionTrigger(ComponentContext c,
                                                           String key)

Deprecated.

requestFocus

public static void requestFocus(ComponentContext c,
                                Handle handle)

requestFocus

public static void requestFocus(ComponentContext c,
                                String key)

requestFocus

public static void requestFocus(EventTrigger trigger)

clearFocus

public static void clearFocus(ComponentContext c,
                              Handle handle)

clearFocus

public static void clearFocus(ComponentContext c,
                              String key)

clearFocus

public static void clearFocus(EventTrigger trigger)

getText

public static CharSequence getText(ComponentContext c,
                                   Handle handle)

getText

public static CharSequence getText(ComponentContext c,
                                   String key)

getText

public static CharSequence getText(EventTrigger trigger)

setText

public static void setText(ComponentContext c,
                           Handle handle,
                           CharSequence text)

setText

public static void setText(ComponentContext c,
                           String key,
                           CharSequence text)

setText

public static void setText(EventTrigger trigger,
                           CharSequence text)

dispatchKey

public static void dispatchKey(ComponentContext c,
                               Handle handle,
                               KeyEvent keyEvent)

dispatchKey

public static void dispatchKey(ComponentContext c,
                               String key,
                               KeyEvent keyEvent)

dispatchKey

public static void dispatchKey(EventTrigger trigger,
                               KeyEvent keyEvent)

setSelection

public static void setSelection(ComponentContext c,
                                Handle handle,
                                int start,
                                int end)

setSelection

public static void setSelection(ComponentContext c,
                                String key,
                                int start,
                                int end)

setSelection

public static void setSelection(EventTrigger trigger,
                                int start,
                                int end)

acceptTriggerEvent

public Object acceptTriggerEvent(EventTrigger eventTrigger,
                                 Object eventState,
                                 Object[] params)

Specified by:

acceptTriggerEvent in interface EventTriggerTarget

Overrides:

acceptTriggerEvent in class ComponentLifecycle

recordEventTrigger

public void recordEventTrigger(EventTriggersContainer container)

Specified by:

recordEventTrigger in interface HasEventTrigger

Overrides:

recordEventTrigger in class Component

hasState

protected boolean hasState()

Overrides:

hasState in class ComponentLifecycle

Returns:

true if the Component is using state, false otherwise.

transferState

protected void transferState(StateContainer _prevStateContainer,
                             StateContainer _nextStateContainer)

Description copied from class: ComponentLifecycle

Call this to transfer the State annotated values between two Component with the same global scope.

Overrides:

transferState in class ComponentLifecycle

remeasureForUpdatedText

protected static void remeasureForUpdatedText(ComponentContext c)

remeasureForUpdatedTextAsync

protected static void remeasureForUpdatedTextAsync(ComponentContext c)

remeasureForUpdatedTextSync

protected static void remeasureForUpdatedTextSync(ComponentContext c)

create

public static TextInput.Builder create(ComponentContext context)

create

public static TextInput.Builder create(ComponentContext context,
                                       int defStyleAttr,
                                       int defStyleRes)