# Class InputComponent

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

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

Direct Known Subclasses:
  `PickerComponent, TextComponent`

public abstract class InputComponent extends Container

A base class for `com.codename1.ui.TextComponent`, `com.codename1.ui.PickerComponent` and potentially other components that wish to accept input in a dynamic way that matches iOS and Android native input guidelines.

It is highly recommended to use input 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)`

- `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

- `inputComponentErrorMultilineBool` sets the error label to multiline when activated

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
  Modifier
  Constructor
  Description
  `protected`
  `InputComponent()`
  Protected constructor for subclasses to override

- ## Method Summary

  Modifier and Type
  Method
  Description
  `InputComponent`
  `action(char icon)`
  Sets the icon for the action button
  `InputComponent`
  `actionAsButton(boolean asButton)`
  Indicates the action should behave as a button next to the component and not layered on top of the text component.
  `InputComponent`
  `actionClick(ActionListener c)`
  Binds an event for the action button
  `InputComponent`
  `actionText(String text)`
  Provides the text of the action button
  `InputComponent`
  `actionUIID(String uiid)`
  Sets the UIID for the action button
  `protected Dimension`
  `calcPreferredSize()`
  Calculates the preferred size based on component content.
  `protected TextHolder`
  `createErrorLabel()`
  Can be overriden by subclasses to support custom error label components
  `InputComponent`
  `descriptionMessage(String descriptionMessage)`
  Sets the text of the description label which currently only applies in the onTop mode.
  `InputComponent`
  `errorMessage(String errorMessage)`
  Sets the text of the error label
  `Button`
  `getAction()`
  Returns the button underlying the action button that is placed on the right of the field on top of it
  `String`
  `getActionText()`
  Provides the text of the action button
  `String`
  `getActionUIID()`
  UIID for the action button
  `abstract Component`
  `getEditor()`
  Returns the editor component e.g.
  `Object`
  `getPropertyValue(String name)`
  Returns the current value of the property name, this method is used by the GUI builder
  `static void`
  `group(Component... cmps)`
  Groups together multiple text components and labels so they align properly, this is implicitly invoked by `com.codename1.ui.layouts.TextModeLayout` so this method is unnecessary when using that layout
  `protected final void`
  `initInput()`
  This method must be invoked by the constructor of the subclasses to initialize the UI
  `boolean`
  `isActionAsButton()`
  Indicates the action should behave as a button next to the component and not layered on top of the text component.
  `static boolean`
  `isMultiLineErrorMessage()`
  True if error messages should be multiline by default.
  `boolean`
  `isOnTopMode()`
  Indicates the on top mode which places the label above the text when true.
  `InputComponent`
  `label(String text)`
  Sets the text of the label
  `InputComponent`
  `onTopMode(boolean onTopMode)`
  Sets the on top mode which places the label above the text when true.
  `static void`
  `setMultiLineErrorMessage(boolean aMultiLineErrorMessage)`
  True if error messages should be multiline by default.
  `String`
  `setPropertyValue(String name, Object value)`
  Sets a new value to the given property, returns an error message if failed and null if successful.

  ### 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, getPropertyNames, getPropertyTypeNames, getPropertyTypes, 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, setPullToRefresh, 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`

  ### Methods inherited from interface Iterable

  `forEach`

- ## Constructor Details

  - ### InputComponent

    protected InputComponent()
    Protected constructor for subclasses to override

- ## Method Details

  - ### group

    public static void group(Component... cmps)

    Groups together multiple text components and labels so they align properly, this is implicitly invoked by `com.codename1.ui.layouts.TextModeLayout` so this method is unnecessary when using that layout

    ###### Parameters

    - `cmps`: @param cmps a list of components if it's a text component that is not in the on top mode the width of the labels will be aligned

  - ### isMultiLineErrorMessage

    public static boolean isMultiLineErrorMessage()

    True if error messages should be multiline by default. This can be set via the theme constant `inputComponentErrorMultilineBool`

    ###### Returns

    the multiLineErrorMessage

  - ### setMultiLineErrorMessage

    public static void setMultiLineErrorMessage(boolean aMultiLineErrorMessage)

    True if error messages should be multiline by default. This can be set via the theme constant `inputComponentErrorMultilineBool`

    ###### Parameters

    - `aMultiLineErrorMessage`: the multiLineErrorMessage to set

  - ### initInput

    protected final void initInput()
    This method must be invoked by the constructor of the subclasses to initialize the UI

  - ### createErrorLabel

    protected TextHolder createErrorLabel()

    Can be overriden by subclasses to support custom error label components

    ###### Returns

    Returns:
      Component instance such as JLabel, TextArea etc. usually with the `ErrorLabel` UIID

  - ### calcPreferredSize

    protected Dimension calcPreferredSize()
    Description copied from class: `Container`

    Calculates the preferred size based on component content. This method is invoked lazily by getPreferred size.

    ###### Returns

    the calculated preferred size based on component content

    Overrides:
      `calcPreferredSize` in class `Container`

  - ### getEditor

    public abstract Component getEditor()

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

    ###### Returns

    the editor component

  - ### onTopMode

    public InputComponent onTopMode(boolean onTopMode)

    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");`

  - ### isOnTopMode

    public boolean isOnTopMode()

    Indicates 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

    ###### Returns

    true if the text should be on top

  - ### errorMessage

    public InputComponent errorMessage(String errorMessage)

    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");`

  - ### descriptionMessage

    public InputComponent descriptionMessage(String descriptionMessage)

    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");`

  - ### label

    public InputComponent label(String text)

    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");`

  - ### actionUIID

    public InputComponent actionUIID(String uiid)

    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");`

  - ### getActionUIID

    public String getActionUIID()

    UIID for the action button

    ###### Returns

    the UIID

  - ### actionAsButton

    public InputComponent actionAsButton(boolean asButton)

    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");`

  - ### isActionAsButton

    public boolean isActionAsButton()

    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.

    ###### Returns

    true if the action acts as a button

  - ### actionText

    public InputComponent actionText(String text)

    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");`

  - ### getActionText

    public String getActionText()

    Provides the text of the action button

    ###### Returns

    the text of the action

  - ### action

    public InputComponent action(char icon)

    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");`

  - ### actionClick

    public InputComponent actionClick(ActionListener c)

    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");`

  - ### getAction

    public Button getAction()

    Returns the button underlying the action button that is placed on the right of the field on top of it

    ###### Returns

    a button for manual customization

  - ### 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 `Component`

  - ### 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 `Component`