# Class TextComponent

java.lang.Object
com.codename1.ui.Component
com.codename1.ui.Container
com.codename1.ui.InputComponent
com.codename1.ui.TextComponent

All Implemented Interfaces:
  `Animation, Editable, StyleListener, Iterable<Component>`

Direct Known Subclasses:
  `AutoCompleteTextComponent, TextComponentPassword`

public class TextComponent extends InputComponent

Encapsulates a text field and label into a single component. This allows the UI to adapt for iOS/Android behavior differences and support features like floating hint when necessary. It also includes platform specific error handling logic.

It is highly recommended to use text components in the context of a `com.codename1.ui.layouts.TextModeLayout` This allows the layout to implicitly adapt to the on-top mode and use a box layout Y mode for iOS and other platforms.

This class supports several theme constants:

- `textComponentErrorColor` a hex RGB color which defaults to null in which case this has no effect. When defined this will change the color of the border and label to the given color to match the material design styling.

- `textComponentErrorLineBorderBool` when set to `false`, this will prevent the text component from applying an underline border when there is a validation error. Defaults to `true`.

- `textComponentOnTopBool` toggles the on top mode see `#onTopMode(boolean)`

- `textComponentAnimBool` toggles the animation mode see `#focusAnimation(boolean)`

- `textComponentFieldUIID` sets the UIID of the text field to something other than `TextField` which is useful for platforms such as iOS where the look of the text field is different within the text component

The following code demonstrates a simple set of inputs and validation as it appears in iOS, Android and with validation errors

    TextModeLayout tl = new TextModeLayout(3, 2);
    Form f = new Form("Pixel Perfect", tl);

    TextComponent title = new TextComponent().label("Title");
    TextComponent price = new TextComponent().label("Price");
    TextComponent location = new TextComponent().label("Location");
    PickerComponent date = PickerComponent.createDate(new Date()).label("Date");
    TextComponent description = new TextComponent().label("Description").multiline(true);

    Validator val = new Validator();
    val.addConstraint(title, new LengthConstraint(2));
    val.addConstraint(price, new NumericConstraint(true));

    f.add(tl.createConstraint().widthPercentage(60), title);
    f.add(tl.createConstraint().widthPercentage(40), date);
    f.add(location);
    f.add(price);
    f.add(tl.createConstraint().horizontalSpan(2), description);
    f.setEditOnShow(title.getField());

    f.show();

- ## Field Summary

  ### Fields inherited from class Component

  `BASELINE, BOTTOM, BRB_CENTER_OFFSET, BRB_CONSTANT_ASCENT, BRB_CONSTANT_DESCENT, BRB_OTHER, CENTER, CROSSHAIR_CURSOR, DEFAULT_CURSOR, DRAG_REGION_IMMEDIATELY_DRAG_X, DRAG_REGION_IMMEDIATELY_DRAG_XY, DRAG_REGION_IMMEDIATELY_DRAG_Y, DRAG_REGION_LIKELY_DRAG_X, DRAG_REGION_LIKELY_DRAG_XY, DRAG_REGION_LIKELY_DRAG_Y, DRAG_REGION_NOT_DRAGGABLE, DRAG_REGION_POSSIBLE_DRAG_X, DRAG_REGION_POSSIBLE_DRAG_XY, DRAG_REGION_POSSIBLE_DRAG_Y, E_RESIZE_CURSOR, HAND_CURSOR, LEFT, MOVE_CURSOR, N_RESIZE_CURSOR, NE_RESIZE_CURSOR, NW_RESIZE_CURSOR, RIGHT, S_RESIZE_CURSOR, SE_RESIZE_CURSOR, SW_RESIZE_CURSOR, TEXT_CURSOR, TOP, W_RESIZE_CURSOR, WAIT_CURSOR`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TextComponent()`
  Default constructor allows us to create an arbitrary text component

- ## Method Summary

  Modifier and Type
  Method
  Description
  `TextComponent`
  `action(char icon)`
  Overridden for covariant return type Sets the icon for the action button
  `TextComponent`
  `actionAsButton(boolean asButton)`
  Overridden for covariant return type Indicates the action should behave as a button next to the component and not layered on top of the text component.
  `TextComponent`
  `actionClick(ActionListener c)`
  Overridden for covariant return type Binds an event for the action button
  `TextComponent`
  `actionText(String text)`
  Overridden for covariant return type Provides the text of the action button
  `TextComponent`
  `actionUIID(String uiid)`
  Overridden for covariant return type Sets the UIID for the action button
  `TextComponent`
  `columns(int columns)`
  Sets the columns in the text field
  `TextComponent`
  `constraint(int constraint)`
  Sets the constraint for text input matching the constraints from the text area class
  `TextComponent`
  `descriptionMessage(String descriptionMessage)`
  Overridden for covariant return type Sets the text of the description label which currently only applies in the onTop mode.
  `TextComponent`
  `errorMessage(String errorMessage)`
  Overridden for covariant return type Sets the text of the error label
  `TextComponent`
  `focusAnimation(boolean focusAnimation)`
  The focus animation mode forces the hint and text to be identical and animates the hint to the label when focus is in the text field as is common on Android.
  `Component`
  `getEditor()`
  Returns the editor component e.g.
  `TextField`
  `getField()`
  Allows us to invoke setters/getters and bind listeners to the text field
  `String[]`
  `getPropertyNames()`
  A component may expose mutable property names for a UI designer to manipulate, this API is designed for usage internally by the GUI builder code
  `String[]`
  `getPropertyTypeNames()`
  This method is here to workaround an XMLVM array type bug where property types aren't identified properly, it returns the names of the types using the following type names: String,int,double,long,byte,short,char,String[],String[][],byte[],Image,Image[],Object[],ListModel,ListCellRenderer
  `Class[]`
  `getPropertyTypes()`
  Matches the property names method (see that method for further details).
  `Object`
  `getPropertyValue(String name)`
  Returns the current value of the property name, this method is used by the GUI builder
  `String`
  `getText()`
  Returns the text in the field `com.codename1.ui.TextArea#getText()`
  `TextComponent`
  `hint(Image hint)`
  Sets the hint of the field
  `TextComponent`
  `hint(String hint)`
  Sets the hint of the field
  `boolean`
  `isFocusAnimation()`
  The focus animation mode forces the hint and text to be identical and animates the hint to the label when focus is in the text field as is common on Android.
  `TextComponent`
  `label(String text)`
  Overridden for covariant return type Sets the text of the label
  `TextComponent`
  `labelAndHint(String text)`
  Convenience method for setting the label and hint together
  `TextComponent`
  `multiline(boolean multiline)`
  Sets the text field to multiline or single line
  `TextComponent`
  `onTopMode(boolean onTopMode)`
  Overridden for covariant return type Sets the on top mode which places the label above the text when true.
  `TextComponent`
  `rows(int rows)`
  Sets the rows in the text field
  `String`
  `setPropertyValue(String name, Object value)`
  Sets a new value to the given property, returns an error message if failed and null if successful.
  `TextComponent`
  `text(String text)`
  Sets the text of the field

  ### Methods inherited from class InputComponent

  `calcPreferredSize, createErrorLabel, getAction, getActionText, getActionUIID, group, initInput, isActionAsButton, isMultiLineErrorMessage, isOnTopMode, setMultiLineErrorMessage`

  ### Methods inherited from class Container

  `add, add, add, add, add, add, addAll, addComponent, addComponent, addComponent, addComponent, animateHierarchy, animateHierarchyAndWait, animateHierarchyFade, animateHierarchyFadeAndWait, animateLayout, animateLayoutAndWait, animateLayoutFade, animateLayoutFadeAndWait, animateUnlayout, animateUnlayoutAndWait, applyRTL, cancelRepaints, clearClientProperties, constrainHeightWhenScrollable, constrainWidthWhenScrollable, contains, createAnimateHierarchy, createAnimateHierarchyFade, createAnimateLayout, createAnimateLayoutFade, createAnimateLayoutFadeAndWait, createAnimateMotion, createAnimateUnlayout, createReplaceTransition, dragInitiated, drop, encloseIn, encloseIn, findDropTargetAt, findFirstFocusable, fireClicked, flushReplace, forceRevalidate, getBottomGap, getChildrenAsList, getClosestComponentTo, getComponentAt, getComponentAt, getComponentCount, getComponentIndex, getGridPosX, getGridPosY, getLayout, getLayoutHeight, getLayoutWidth, getLeadComponent, getLeadParent, getResponderAt, getSafeAreaRoot, getScrollIncrement, getSideGap, getUIManager, initLaf, invalidate, isEnabled, isSafeArea, isSafeAreaRoot, isScrollableX, isScrollableY, isSelectableInteraction, isSurface, iterator, iterator, keyPressed, keyReleased, layoutContainer, morph, morphAndWait, paint, paintComponentBackground, paintGlass, paramString, pointerPressed, refreshTheme, removeAll, removeComponent, replace, replace, replaceAndWait, replaceAndWait, replaceAndWait, revalidate, revalidateLater, revalidateWithAnimationSafety, scrollComponentToVisible, setCellRenderer, setEnabled, setLayout, setLeadComponent, setSafeArea, setSafeAreaRoot, setScrollable, setScrollableX, setScrollableY, setScrollIncrement, setShouldCalcPreferredSize, setShouldLayout, setUIManager, updateTabIndices`

  ### Methods inherited from class Component

  `addDragFinishedListener, addDragOverListener, addDropListener, addFocusListener, addLongPressListener, addPointerDraggedListener, addPointerPressedListener, addPointerReleasedListener, addPullToRefresh, addScrollListener, addStateChangeListener, animate, announceForAccessibility, bindProperty, blocksSideSwipe, calcScrollSize, contains, containsOrOwns, createStyleAnimation, deinitialize, deinitializeCustomStyle, dragEnter, dragExit, dragFinished, draggingOver, drawDraggedImage, focusGained, focusLost, getAbsoluteX, getAbsoluteY, getAccessibilityText, getAllStyles, getAnimationManager, getBaseline, getBaselineResizeBehavior, getBindablePropertyNames, getBindablePropertyTypes, getBorder, getBoundPropertyValue, getBounds, getBounds, getClientProperty, getCloudBoundProperty, getCloudDestinationProperty, getComponentForm, getComponentState, getCursor, getDefaultDragTransparency, getDirtyRegion, getDisabledStyle, getDraggedx, getDraggedy, getDragImage, getDragRegionStatus, getDragSpeed, getDragTransparency, getEditingDelegate, getHeight, getInlineAllStyles, getInlineDisabledStyles, getInlinePressedStyles, getInlineSelectedStyles, getInlineStylesTheme, getInlineUnselectedStyles, getInnerHeight, getInnerPreferredH, getInnerPreferredW, getInnerWidth, getInnerX, getInnerY, getLabelForComponent, getName, getNativeOverlay, getNextFocusDown, getNextFocusLeft, getNextFocusRight, getNextFocusUp, getOuterHeight, getOuterPreferredH, getOuterPreferredW, getOuterWidth, getOuterX, getOuterY, getOwner, getParent, getPreferredH, getPreferredSize, getPreferredSizeStr, getPreferredTabIndex, getPreferredW, getPressedStyle, getSameHeight, getSameWidth, getScrollable, getScrollAnimationSpeed, getScrollDimension, getScrollOpacity, getScrollOpacityChangeSpeed, getScrollX, getScrollY, getSelectCommandText, getSelectedRect, getSelectedStyle, getStyle, getTabIndex, getTensileLength, getTextSelectionSupport, getTooltip, getUIID, getUnselectedStyle, getVisibleBounds, getVisibleBounds, getWidth, getX, getY, growShrink, handlesInput, hasFixedPreferredSize, hasFocus, hideNativeOverlay, initComponent, initCustomStyle, initDisabledStyle, initPressedStyle, initSelectedStyle, initUnselectedStyle, installDefaultPainter, isAlwaysTensile, isBlockLead, isCellRenderer, isChildOf, isDragActivated, isDragAndDropOperation, isDraggable, isDragRegion, isDropTarget, isEditable, isEditing, isFlatten, isFocusable, isGrabsPointerEvents, isHidden, isHidden, isHideInLandscape, isHideInPortrait, isIgnorePointerEvents, isInClippingRegion, isInitialized, isOpaque, isOwnedBy, isPinchBlocksDragAndDrop, isRippleEffect, isRTL, isScrollable, isScrollVisible, isSetCursorSupported, isSmoothScrolling, isSnapToGrid, isStickyDrag, isTactileTouch, isTactileTouch, isTensileDragEnabled, isTraversable, isVisible, keyRepeated, laidOut, longKeyPress, longPointerPress, onScrollX, onScrollY, onSetFocusable, paintBackground, paintBackgrounds, paintBorder, paintBorderBackground, paintComponent, paintComponent, paintIntersectingComponentsAbove, paintLock, paintLockRelease, paintRippleOverlay, paintScrollbars, paintScrollbarX, paintScrollbarY, paintShadows, parsePreferredSize, pinch, pinch, pinchReleased, pointerDragged, pointerDragged, pointerHover, pointerHoverPressed, pointerHoverReleased, pointerPressed, pointerReleased, pointerReleased, putClientProperty, refreshTheme, refreshTheme, remove, removeDragFinishedListener, removeDragOverListener, removeDropListener, removeFocusListener, removeLongPressListener, removePointerDraggedListener, removePointerPressedListener, removePointerReleasedListener, removeScrollListener, removeStateChangeListener, repaint, repaint, requestFocus, resetFocusable, respondsToPointerEvents, scrollRectToVisible, scrollRectToVisible, setAccessibilityText, setAlwaysTensile, setBlockLead, setBoundPropertyValue, setCloudBoundProperty, setCloudDestinationProperty, setComponentState, setCursor, setDefaultDragTransparency, setDirtyRegion, setDisabledStyle, setDraggable, setDragTransparency, setDropTarget, setEditingDelegate, setFlatten, setFocus, setFocusable, setGrabsPointerEvents, setHandlesInput, setHeight, setHidden, setHidden, setHideInLandscape, setHideInPortrait, setIgnorePointerEvents, setInitialized, setInlineAllStyles, setInlineDisabledStyles, setInlinePressedStyles, setInlineSelectedStyles, setInlineStylesTheme, setInlineUnselectedStyles, setIsScrollVisible, setLabelForComponent, setName, setNextFocusDown, setNextFocusLeft, setNextFocusRight, setNextFocusUp, setOpaque, setOwner, setPinchBlocksDragAndDrop, setPreferredH, setPreferredSize, setPreferredSizeStr, setPreferredTabIndex, setPreferredW, setPressedStyle, setRippleEffect, setRTL, setSameHeight, setSameSize, setSameWidth, setScrollAnimationSpeed, setScrollOpacityChangeSpeed, setScrollSize, setScrollVisible, setScrollX, setScrollY, setSelectCommandText, setSelectedStyle, setSize, setSmoothScrolling, setSnapToGrid, setTabIndex, setTactileTouch, setTensileDragEnabled, setTensileLength, setTooltip, setTraversable, setUIID, setUIID, setUIIDFinal, setUnselectedStyle, setVisible, setWidth, setX, setY, shouldBlockSideSwipe, shouldBlockSideSwipeLeft, shouldBlockSideSwipeRight, shouldRenderComponentSelection, showNativeOverlay, startEditingAsync, stopEditing, stripMarginAndPadding, styleChanged, toImage, toString, unbindProperty, updateNativeOverlay, visibleBoundsContains`

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### TextComponent

    public TextComponent()
    Default constructor allows us to create an arbitrary text component

- ## Method Details

  - ### getEditor

    public Component getEditor()

    Returns the editor component e.g. text field picker etc.

    ###### Returns

    the editor component

    Specified by:
      `getEditor` in class `InputComponent`

  - ### isFocusAnimation

    public boolean isFocusAnimation()

    The focus animation mode forces the hint and text to be identical and animates the hint to the label when focus is in the text field as is common on Android. This can be customized using the theme constant `textComponentAnimBool` which is true by default on Android. Notice that this is designed for the `onTopMode` and might not work if that is set to false...

    ###### Returns

    true if the text should be on top

  - ### focusAnimation

    public TextComponent focusAnimation(boolean focusAnimation)

    The focus animation mode forces the hint and text to be identical and animates the hint to the label when focus is in the text field as is common on Android. This can be customized using the theme constant `textComponentAnimBool` which is true by default on Android. Notice that this is designed for the `onTopMode` and might not work if that is set to false...

    ###### Parameters

    - `focusAnimation`: true for the label to animate into place on focus, false otherwise

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

  - ### text

    public TextComponent text(String text)

    Sets the text of the field

    ###### Parameters

    - `text`: the text

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

  - ### onTopMode

    public TextComponent onTopMode(boolean onTopMode)

    Overridden for covariant return type

    Sets the on top mode which places the label above the text when true. It's to the left of the text otherwise (right in bidi languages). This is determined by the platform theme using the `textComponentOnTopBool` theme constant which defaults to false

    ###### Parameters

    - `onTopMode`: true for the label to be above the text

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

    Overrides:
      `onTopMode` in class `InputComponent`

  - ### action

    public TextComponent action(char icon)

    Overridden for covariant return type

    Sets the icon for the action button

    ###### Parameters

    - `icon`: the icon constant from `com.codename1.ui.FontImage`

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

    Overrides:
      `action` in class `InputComponent`

  - ### actionClick

    public TextComponent actionClick(ActionListener c)

    Overridden for covariant return type

    Binds an event for the action button

    ###### Parameters

    - `c`: action listener callback

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

    Overrides:
      `actionClick` in class `InputComponent`

  - ### errorMessage

    public TextComponent errorMessage(String errorMessage)

    Overridden for covariant return type

    Sets the text of the error label

    ###### Parameters

    - `errorMessage`: the text

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

    Overrides:
      `errorMessage` in class `InputComponent`

  - ### descriptionMessage

    public TextComponent descriptionMessage(String descriptionMessage)

    Overridden for covariant return type

    Sets the text of the description label which currently only applies in the onTop mode. This text occupies the same space as the error message and thus hides when there's an error

    ###### Parameters

    - `descriptionMessage`: the text

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

    Overrides:
      `descriptionMessage` in class `InputComponent`

  - ### label

    public TextComponent label(String text)

    Overridden for covariant return type

    Sets the text of the label

    ###### Parameters

    - `text`: the text

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

    Overrides:
      `label` in class `InputComponent`

  - ### actionAsButton

    public TextComponent actionAsButton(boolean asButton)

    Overridden for covariant return type

    Indicates the action should behave as a button next to the component and not layered on top of the text component. This is useful for UI in the style of a browse button next to a text field.

    ###### Parameters

    - `asButton`: true so the action will act like a button

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

    Overrides:
      `actionAsButton` in class `InputComponent`

  - ### actionUIID

    public TextComponent actionUIID(String uiid)

    Overridden for covariant return type

    Sets the UIID for the action button

    ###### Parameters

    - `uiid`: a custom UIID for the action

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

    Overrides:
      `actionUIID` in class `InputComponent`

  - ### actionText

    public TextComponent actionText(String text)

    Overridden for covariant return type

    Provides the text of the action button

    ###### Parameters

    - `text`: the text that should appear on the action button

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

    Overrides:
      `actionText` in class `InputComponent`

  - ### labelAndHint

    public TextComponent labelAndHint(String text)

    Convenience method for setting the label and hint together

    ###### Parameters

    - `text`: the text and hint

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

  - ### hint

    public TextComponent hint(String hint)

    Sets the hint of the field

    ###### Parameters

    - `hint`: the text of the hint

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

  - ### hint

    public TextComponent hint(Image hint)

    Sets the hint of the field

    ###### Parameters

    - `hint`: the icon for the hint

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

  - ### multiline

    public TextComponent multiline(boolean multiline)

    Sets the text field to multiline or single line

    ###### Parameters

    - `multiline`: true for multiline, false otherwise

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

  - ### columns

    public TextComponent columns(int columns)

    Sets the columns in the text field

    ###### Parameters

    - `columns`: the number of columns which is used for preferred size calculations

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

  - ### rows

    public TextComponent rows(int rows)

    Sets the rows in the text field

    ###### Parameters

    - `rows`: the number of rows which is used for preferred size calculations

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

  - ### constraint

    public TextComponent constraint(int constraint)

    Sets the constraint for text input matching the constraints from the text area class

    ###### Parameters

    - `constraint`: @param constraint one of the constants from the `com.codename1.ui.TextArea` class see `com.codename1.ui.TextArea#setConstraint(int)`

    ###### Returns

    this for chaining calls E.g. `TextComponent tc = new TextComponent().text("Text").label("Label");`

  - ### getField

    public TextField getField()

    Allows us to invoke setters/getters and bind listeners to the text field

    ###### Returns

    the text field instance

  - ### getPropertyNames

    public String[] getPropertyNames()

    A component may expose mutable property names for a UI designer to manipulate, this API is designed for usage internally by the GUI builder code

    ###### Returns

    the property names allowing mutation

    Overrides:
      `getPropertyNames` in class `Component`

  - ### getPropertyTypes

    public Class[] getPropertyTypes()

    Matches the property names method (see that method for further details).

    ###### Returns

    the types of the properties

    Overrides:
      `getPropertyTypes` in class `Component`

  - ### getPropertyTypeNames

    public String[] getPropertyTypeNames()

    This method is here to workaround an XMLVM array type bug where property types aren't identified properly, it returns the names of the types using the following type names: String,int,double,long,byte,short,char,String[],String[][],byte[],Image,Image[],Object[],ListModel,ListCellRenderer

    ###### Returns

    Array of type names

    Overrides:
      `getPropertyTypeNames` in class `Component`

  - ### getPropertyValue

    public Object getPropertyValue(String name)

    Returns the current value of the property name, this method is used by the GUI builder

    ###### Parameters

    - `name`: the name of the property

    ###### Returns

    the value of said property

    Overrides:
      `getPropertyValue` in class `InputComponent`

  - ### setPropertyValue

    public String setPropertyValue(String name, Object value)

    Sets a new value to the given property, returns an error message if failed and null if successful. Notice that some builtin properties such as "$designMode" might be sent to components to indicate application state.

    ###### Parameters

    - `name`: the name of the property

    - `value`: new value for the property

    ###### Returns

    error message or null

    Overrides:
      `setPropertyValue` in class `InputComponent`

  - ### getText

    public String getText()

    Returns the text in the field `com.codename1.ui.TextArea#getText()`

    ###### Returns

    the text