com.codename1.ui

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

1. 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.
2. 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.
3. textComponentOnTopBool toggles the on top mode see onTopMode(boolean)
4. textComponentAnimBool toggles the animation mode see focusAnimation(boolean)
5. 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

Field Summary

Fields inherited from class com.codename1.ui.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 and Description
TextComponent() Default constructor allows us to create an arbitrary text component

Method Summary

Modifier and Type	Method and 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 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 com.codename1.ui.InputComponent

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

Methods inherited from class com.codename1.ui.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, paintBackground, paintBorderBackground, 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 com.codename1.ui.Component

addDragFinishedListener, addDragOverListener, addDropListener, addFocusListener, addLongPressListener, addPointerDraggedListener, addPointerPressedListener, addPointerReleasedListener, addPullToRefresh, addScrollListener, addStateChangeListener, animate, bindProperty, blocksSideSwipe, calcScrollSize, contains, containsOrOwns, createStyleAnimation, deinitialize, deinitializeCustomStyle, dragEnter, dragExit, dragFinished, draggingOver, drawDraggedImage, focusGained, focusLost, getAbsoluteX, getAbsoluteY, 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, paintBackgrounds, paintBorder, 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, 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, setUnselectedStyle, setVisible, setWidth, setX, setY, shouldBlockSideSwipe, shouldBlockSideSwipeLeft, shouldBlockSideSwipeRight, shouldRenderComponentSelection, showNativeOverlay, startEditingAsync, stopEditing, stripMarginAndPadding, styleChanged, toImage, toString, unbindProperty, updateNativeOverlay, visibleBoundsContains

Methods inherited from class java.lang.Object

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

Constructor Detail

TextComponent

public TextComponent()

Default constructor allows us to create an arbitrary text component

Method Detail

getEditor

public Component getEditor()

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

Specified by:

getEditor in class InputComponent

Returns:

the editor component

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

Overrides:

onTopMode in class InputComponent

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

action

public TextComponent action(char icon)

Overridden for covariant return type Sets the icon for the action button

Overrides:

action in class InputComponent

Parameters:

icon - the icon constant from FontImage

Returns:

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

actionClick

public TextComponent actionClick(ActionListener c)

Overridden for covariant return type Binds an event for the action button

Overrides:

actionClick in class InputComponent

Parameters:

c - action listener callback

Returns:

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

errorMessage

public TextComponent errorMessage(String errorMessage)

Overridden for covariant return type Sets the text of the error label

Overrides:

errorMessage in class InputComponent

Parameters:

errorMessage - the text

Returns:

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

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

Overrides:

descriptionMessage in class InputComponent

Parameters:

descriptionMessage - the text

Returns:

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

label

public TextComponent label(String text)

Overridden for covariant return type Sets the text of the label

Overrides:

label in class InputComponent

Parameters:

text - the text

Returns:

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

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.

Overrides:

actionAsButton in class InputComponent

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

actionUIID

public TextComponent actionUIID(String uiid)

Overridden for covariant return type Sets the UIID for the action button

Overrides:

actionUIID in class InputComponent

Parameters:

uiid - a custom UIID for the action

Returns:

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

actionText

public TextComponent actionText(String text)

Overridden for covariant return type Provides the text of the action button

Overrides:

actionText in class InputComponent

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

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 - one of the constants from the TextArea class see 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

Overrides:

getPropertyNames in class Component

Returns:

the property names allowing mutation

getPropertyTypes

public Class[] getPropertyTypes()

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

Overrides:

getPropertyTypes in class Component

Returns:

the types of the properties

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

Overrides:

getPropertyTypeNames in class Component

Returns:

Array of type names

getPropertyValue

public Object getPropertyValue(String name)

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

Overrides:

getPropertyValue in class InputComponent

Parameters:

name - the name of the property

Returns:

the value of said property

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.

Overrides:

setPropertyValue in class InputComponent

Parameters:

name - the name of the property

value - new value for the property

Returns:

error message or null

getText

public String getText()

Returns the text in the field TextArea.getText()

Returns:

the text