# Class PhoneVerification

java.lang.Object
com.codename1.ui.Component
com.codename1.ui.Container
com.codename1.components.PhoneVerification

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

public class PhoneVerification extends Container

The two stages of verifying that a user holds a phone number: enter the number, then enter the code that arrives by SMS.

The application supplies both server calls. This component owns everything around them: the number entry, the code entry, the wait before a resend is offered, the way back to a mistyped number, and the errors either call reports.

##### Example

    PhoneVerification verify = new PhoneVerification();
    verify.setCodeSender((number, response) -> myServer.sendSms(number, response));
    verify.setCodeVerifier((number, code, response) -> myServer.check(number, code, response));
    verify.addVerifiedListener(e -> showMainScreen());
    form.add(verify);

A sender is handed the number and a `Response`, and calls exactly one of `Response#succeeded()` or `Response#failed(String)` when its server answers -- from any thread. Until then the button it came from stays disabled, so a second tap cannot send a second message.

##### The code is offered by the platform

The code field is an `OtpField`, so it carries the one-time-code hint and the platform offers the arriving code on the keyboard or through autofill. Nothing here reads messages, and no messaging permission is involved.

##### Styling

The component uses the UIID "PhoneVerification", its explanatory lines "PhoneVerificationText", its error line "PhoneVerificationError" and its buttons "PhoneVerificationButton" -- except the resend and change-number buttons, which use "PhoneVerificationLink".

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `PhoneVerification.CodeSender`
  Asks the application's server to send a code to a number.
  `static interface`
  `PhoneVerification.CodeVerifier`
  Asks the application's server whether a code matches a number.
  `static final class`
  `PhoneVerification.Response`
  The application's answer to one request.

- ## 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
  `PhoneVerification()`
  Builds the flow with a six digit code.
  `PhoneVerification(int codeLength)`
  Builds the flow with a code of the given length.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addFailedListener(ActionListener l)`
  Adds a listener fired when either server call reports a failure.
  `void`
  `addVerifiedListener(ActionListener l)`
  Adds a listener fired when a code is accepted.
  `protected void`
  `deinitialize()`
  Invoked to indicate that the component initialization is being reversed since the component was detached from the container hierarchy.
  `Button`
  `getChangeNumberButton()`
  The button that returns to the number stage, exposed for theming.
  `OtpField`
  `getOtpField()`
  The code entry field, exposed for theming.
  `String`
  `getPhoneNumber()`
  The number the code was sent to, in E.164 form, or null before a code has been requested.
  `PhoneNumberField`
  `getPhoneNumberField()`
  The number entry field, exposed for theming and for narrowing the country list.
  `Button`
  `getResendButton()`
  The button that asks for another code, exposed for theming.
  `int`
  `getResendDelay()`
  The seconds the user waits before a resend is offered; 60 by default.
  `Button`
  `getSendButton()`
  The button that sends the first code, exposed for theming and for relabelling.
  `Button`
  `getVerifyButton()`
  The button that submits a typed code, exposed for theming.
  `protected void`
  `initComponent()`
  Allows subclasses to bind functionality that relies on fully initialized and "ready for action" component state
  `boolean`
  `isCodeStage()`
  True when the code stage is showing.
  `static boolean`
  `isPlausibleE164(String e164Number)`
  The shape a number must have before a request is worth making: a "+", then between five and fifteen digits, which is what E.164 allows.
  `void`
  `removeFailedListener(ActionListener l)`
  Removes a previously-registered listener.
  `void`
  `removeVerifiedListener(ActionListener l)`
  Removes a previously-registered listener.
  `void`
  `requestCode(String e164Number)`
  Sends a code to a number, moving to the code stage when the server accepts it.
  `void`
  `setCodeSender(PhoneVerification.CodeSender codeSender)`
  Sets the server call that sends a code to a number.
  `void`
  `setCodeVerifier(PhoneVerification.CodeVerifier codeVerifier)`
  Sets the server call that checks a code.
  `void`
  `setResendDelay(int seconds)`
  Sets the seconds before a resend is offered.
  `void`
  `showCodeStage(String e164Number)`
  Moves to the code stage for a number, as though the code had just been sent.
  `void`
  `showNumberStage()`
  Returns to the first stage, with the number as it was left, and clears any code that was typed.
  `void`
  `submitCode()`
  Verifies the code currently entered.

  ### 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, calcPreferredSize, 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

  `accessibilityChanged, accessibilityChanged, addContextMenuListener, addDragFinishedListener, addDragOverListener, addDropListener, addFocusListener, addLongPressListener, addMouseWheelListener, addPointerDraggedListener, addPointerPressedListener, addPointerReleasedListener, addPullToRefresh, addScrollListener, addStateChangeListener, addStylusListener, animate, announceForAccessibility, bindProperty, blocksSideSwipe, calcScrollSize, consumesRawTextInput, contains, containsOrOwns, createStyleAnimation, deinitializeCustomStyle, deregisterFromAnimation, dragEnter, dragExit, dragFinished, draggingOver, drawDraggedImage, focusGained, focusLost, getAbsoluteX, getAbsoluteY, getAccessibilityNode, 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, getPropertyValue, getSameHeight, getSameWidth, getScrollable, getScrollAnimationSpeed, getScrollDimension, getScrollOpacity, getScrollOpacityChangeSpeed, getScrollX, getScrollY, getSelectCommandText, getSelectedRect, getSelectedStyle, getSemantics, getStyle, getTabIndex, getTensileLength, getTextSelectionSupport, getTooltip, getTopLevelContainer, getUIID, getUnselectedStyle, getVisibleBounds, getVisibleBounds, getWidth, getX, getY, growShrink, handlesInput, hasFixedPreferredSize, hasFocus, hideNativeOverlay, initCustomStyle, initDisabledStyle, initPressedStyle, initSelectedStyle, initUnselectedStyle, installDefaultPainter, isAlwaysTensile, isBlockLead, isCellRenderer, isChildOf, isDragActivated, isDragAndDropOperation, isDraggable, isDragRegion, isDropTarget, isEditable, isEditing, isFlatten, isFocusable, isGrabsPointerEvents, isHidden, isHidden, isHideInLandscape, isHideInPortrait, isHScrollThumbGrabbed, isHScrollThumbHover, isIgnorePointerEvents, isInClippingRegion, isInitialized, isOpaque, isOwnedBy, isPinchBlocksDragAndDrop, isRippleEffect, isRTL, isScrollable, isScrollVisible, isSetCursorSupported, isSmoothScrolling, isSnapToGrid, isStickyDrag, isTactileTouch, isTactileTouch, isTensileDragEnabled, isTraversable, isVisible, isVScrollThumbGrabbed, isVScrollThumbHover, keyRepeated, laidOut, longKeyPress, longPointerPress, mouseWheel, 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, registerForAnimation, remove, removeContextMenuListener, removeDragFinishedListener, removeDragOverListener, removeDropListener, removeFocusListener, removeLongPressListener, removeMouseWheelListener, removePointerDraggedListener, removePointerPressedListener, removePointerReleasedListener, removeScrollListener, removeStateChangeListener, removeStylusListener, repaint, repaint, requestFocus, resetFocusable, respondsToPointerEvents, rotation, 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, setHorizontalScrollBounds, setIgnorePointerEvents, setInitialized, setInlineAllStyles, setInlineDisabledStyles, setInlinePressedStyles, setInlineSelectedStyles, setInlineStylesTheme, setInlineUnselectedStyles, setIsScrollVisible, setLabelForComponent, setName, setNextFocusDown, setNextFocusLeft, setNextFocusRight, setNextFocusUp, setOpaque, setOwner, setPinchBlocksDragAndDrop, setPreferredH, setPreferredSize, setPreferredSizeStr, setPreferredTabIndex, setPreferredW, setPressedStyle, setPropertyValue, 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, setVerticalScrollBounds, 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

  - ### PhoneVerification

    public PhoneVerification()
    Builds the flow with a six digit code.

  - ### PhoneVerification

    public PhoneVerification(int codeLength)

    Builds the flow with a code of the given length.

    ###### Parameters

    - `codeLength`: the number of digits in the code

- ## Method Details

  - ### showNumberStage

    public void showNumberStage()
    Returns to the first stage, with the number as it was left, and clears any code that was typed.

  - ### showCodeStage

    public void showCodeStage(String e164Number)

    Moves to the code stage for a number, as though the code had just been sent. Useful when the application sent the message itself rather than through `#setCodeSender(CodeSender)`.

    ###### Parameters

    - `e164Number`: the number the code went to

  - ### isCodeStage

    public boolean isCodeStage()
    True when the code stage is showing.

  - ### requestCode

    public void requestCode(String e164Number)

    Sends a code to a number, moving to the code stage when the server accepts it. Called by the send and resend buttons; an application driving the flow from its own button calls it directly.

    ###### Parameters

    - `e164Number`: the number to send to

  - ### isPlausibleE164

    public static boolean isPlausibleE164(String e164Number)

    The shape a number must have before a request is worth making: a "+", then between five and fifteen digits, which is what E.164 allows. It is not a check that the number exists -- that is the sending service's answer, and its refusal is shown to the user like any other failure.

    ###### Parameters

    - `e164Number`: the number to check

    ###### Returns

    true when the number is worth sending to

  - ### submitCode

    public void submitCode()
    Verifies the code currently entered. Called when the last box is filled and by the verify button.

  - ### deinitialize

    protected void deinitialize()
    Description copied from class: `Component`
    Invoked to indicate that the component initialization is being reversed since the component was detached from the container hierarchy. This allows the component to deregister animators and cleanup after itself. This method is the opposite of the initComponent() method.
    Overrides:
      `deinitialize` in class `Component`

  - ### initComponent

    protected void initComponent()
    Description copied from class: `Component`
    Allows subclasses to bind functionality that relies on fully initialized and "ready for action" component state
    Overrides:
      `initComponent` in class `Component`

  - ### setCodeSender

    public void setCodeSender(PhoneVerification.CodeSender codeSender)

    Sets the server call that sends a code to a number.

    ###### Parameters

    - `codeSender`: the sender

  - ### setCodeVerifier

    public void setCodeVerifier(PhoneVerification.CodeVerifier codeVerifier)

    Sets the server call that checks a code.

    ###### Parameters

    - `codeVerifier`: the verifier

  - ### getResendDelay

    public int getResendDelay()
    The seconds the user waits before a resend is offered; 60 by default.

  - ### setResendDelay

    public void setResendDelay(int seconds)

    Sets the seconds before a resend is offered. Zero offers it at once.

    ###### Parameters

    - `seconds`: the delay

  - ### getPhoneNumber

    public String getPhoneNumber()
    The number the code was sent to, in E.164 form, or null before a code has been requested.

  - ### getPhoneNumberField

    public PhoneNumberField getPhoneNumberField()
    The number entry field, exposed for theming and for narrowing the country list.

  - ### getOtpField

    public OtpField getOtpField()
    The code entry field, exposed for theming.

  - ### getSendButton

    public Button getSendButton()
    The button that sends the first code, exposed for theming and for relabelling.

  - ### getVerifyButton

    public Button getVerifyButton()
    The button that submits a typed code, exposed for theming. The code is also submitted as soon as the last box is filled.

  - ### getResendButton

    public Button getResendButton()
    The button that asks for another code, exposed for theming.

  - ### getChangeNumberButton

    public Button getChangeNumberButton()
    The button that returns to the number stage, exposed for theming.

  - ### addVerifiedListener

    public void addVerifiedListener(ActionListener l)

    Adds a listener fired when a code is accepted.

    ###### Parameters

    - `l`: the listener

  - ### removeVerifiedListener

    public void removeVerifiedListener(ActionListener l)

    Removes a previously-registered listener.

    ###### Parameters

    - `l`: the listener

  - ### addFailedListener

    public void addFailedListener(ActionListener l)

    Adds a listener fired when either server call reports a failure. The failure is already shown to the user; this is for an application that wants to count attempts or log them.

    ###### Parameters

    - `l`: the listener

  - ### removeFailedListener

    public void removeFailedListener(ActionListener l)

    Removes a previously-registered listener.

    ###### Parameters

    - `l`: the listener