Android Platform UI Interface

/**
 *  UI abstract class that has abstract methods called by the FourF library. Allows the library
 *  to control the platform gui from the library. Must not change any method signatures without
 *  also making the same changes in the library.
 */

public interface FourFUIInterface {

    /**
     * The distinct modes in which 4FingerID can capture fingerprint data.
     */
    enum captureMode{
        /** 4 fingers of one hand, presented from the side of the screen */
        Hand(0),
        /** thumb, presented from the bottom of the screen */
        Thumb(1),
        /** single finger, presented from the side of the screen */
        Finger(2),
        /** 4 fingers of one hand, presented from the top of the screen */
        AgentHand(3);

        private int code;
        captureMode(int code) {
            this.code = code;
        }
        public int getCode() {
            return code;
        }

        public static captureMode resolve(int what) {
            captureMode[] states = values();
            for (captureMode state : states) {
                if (state.code == what) {
                    return state;
                }
            }
            return null;
        }
    }

    /**
     * The current target for capture, either an individual finger, a thumb, or 4 fingers of a hand
     */
    enum printToCapture{
        INVALID(0),
        THUMB_RIGHT(1),
        INDEX_RIGHT(2),
        MIDDLE_RIGHT(3),
        RING_RIGHT(4),
        LITTLE_RIGHT(5),
        THUMB_LEFT(6),
        INDEX_LEFT(7),
        MIDDLE_LEFT(8),
        RING_LEFT(9),
        LITTLE_LEFT(10),
        HAND_RIGHT(11),
        HAND_LEFT(12);

        private int code;
        printToCapture(int code) {
            this.code = code;
        }
        public int getCode() {
            return code;
        }

        public static printToCapture resolve(int what) {
            printToCapture[] states = values();
            for (printToCapture state : states) {
                if (state.code == what) {
                    return state;
                }
            }
            return null;
        }

        public boolean isLeftHand(){
            switch (this) {
                case INVALID:
                    return false;
                case THUMB_RIGHT:
                case INDEX_RIGHT:
                case MIDDLE_RIGHT:
                case RING_RIGHT:
                case LITTLE_RIGHT:
                    return false;
                case THUMB_LEFT:
                case INDEX_LEFT:
                case MIDDLE_LEFT:
                case RING_LEFT:
                case LITTLE_LEFT:
                    return true;
                case HAND_RIGHT:
                    return false;
                case HAND_LEFT:
                    return true;
            }
            return false;
        }
    }

    /**
     * Instructions to relay to the user as to the progress of a capture.
     */
    enum uiInstruction{  //FIXME improve instruction names
        /** correct position for capture, the user must be still */
        Wait(0),
        /** an image was out of focus */
        OutOfFocus(1),
        /** correct position, preparing to take an image */
        Yes(2),
        /** hand is too close to the camera */
        RoiTooBig(3),
        /** hand is too far from the camera */
        RoiTooSmall(4),
        /** the user is holding their fingers apart */
        FingersTooFarApart(5),
        /** fingers too high (towards the index finger) */
        FingersHigh(6),
        /** fingers too low (towards the little finger) */
        FingersLow(7),
        /** fingers too far left */
        FingersFarLeft(8),
        /** fingers too far right */
        FingersFarRight(9),
        /** the system is expecting an image to be taken */
        ImageRequestedWaiting(10),
        /** the fingers can not been seen or are unexpected */
        InvalidROIS(11),
        /** the camera feed is too dim */
        ImageTooDim(12),
        /** user showing the wrong hand */
        WrongHand(13);

        private int code;
        uiInstruction(int code) {
            this.code = code;
        }
        public int getCode() {
            return code;
        }

        public static uiInstruction resolve(int what) {
            uiInstruction[] states = values();
            for (uiInstruction state : states) {
                if (state.code == what) {
                    return state;
                }
            }
            return null;
        }

    }

    /**
     * Types of blocking event for indicating specific events to a user
     */
    enum blockingUIInstruction{
        /** NONE */
        NONE(0),
        /** switching to the next capture target */
        SWITCH_CAPTURE_TARGET(1),
        /** Enrolment step 2 of 2 will begin */
        ENROLLMENT_STEP2_OF_2(2),
        /** Enrolment step 2 of 3 will begin */
        ENROLLMENT_STEP2_OF_3(3),
        /** Enrolment step 3 of 3 will begin */
        ENROLLMENT_STEP3_OF_3(4),
        /** User failed in the biometric match */
        INTERNAL_MISMATCH(5),
        /** Display help to the user */
        DISPLAY_HELP(6);

        private int code;
        blockingUIInstruction(int code) {
            this.code = code;
        }
        public int getCode() {
            return code;
        }

        public static blockingUIInstruction resolve(int what) {
            blockingUIInstruction[] states = values();
            for (blockingUIInstruction state : states) {
                if (state.code == what) {
                    return state;
                }
            }
            return null;
        }

    }

    /**
     * Types of user actions.
     */
    enum UserAction{
        /** user wishes to continue */
        NEXT(0),
        /** user wishes to cancel */
        CANCEL(1);

        private int code;
        UserAction(int code) {
            this.code = code;
        }
        public int getCode() {
            return code;
        }

        public static UserAction resolve(int what) {
            UserAction[] states = values();
            for (UserAction state : states) {
                if (state.code == what) {
                    return state;
                }
            }
            return null;
        }

    }

    /**
     * Reasons for ending an operation
     */
    enum FourFFinishReason{
        SUCCESS_ENROLL(0),
        SUCCESS_AUTHENTICATE(1),
        SUCCESS_EXPORT(2),
        FAIL_ENROLL(3),
        FAIL_AUTHENTICATE(4),
        FAIL_LIVENESS(5),
        CANCEL(6),
        TIMEOUT(7),
        ERROR(8);

        private int code;
        FourFFinishReason(int code) {
            this.code = code;
        }
        public int getCode() {
            return code;
        }

        public static FourFFinishReason resolve(int what) {
            FourFFinishReason[] states = values();
            for (FourFFinishReason state : states) {
                if (state.code == what) {
                    return state;
                }
            }
            return null;
        }
    }

    /*
        Methods to be called by Library
        (To communicate from the UI to the FourF library call the methods available in the
         FourFIntegrationWrapper)
     */

    /**
     * Implement UI updates given an instruction. These events do not halt progress of the capture
     * so you should not expect user input. Newly received instructions should override previous
     * instructions.
     * @param instruction instruction
     */
    void handleUIInstruction(uiInstruction instruction);

    /**
     * Implement UI updates given an instruction. These events halt progress of the capture in order
     * to get user input if desired. Once handled, call
     * FourFUIIntegrationWrapper.handledBlockingUIInstruction() with a UserAction to continue.
     * @param instruction instruction
     */
    void handleBlockingUIInstruction(blockingUIInstruction instruction);

    /**
     * Indicates the biometric is processing for a result following successful acceptance
     * of a capture. No other feedback is given until onPocessingStop() is received. Use this, for
     * example, to show a spinning progress wheel.
     */
    void onProcessingStart();

    /**
     * Indicates the biometric has finished processing for a result following successful acceptance
     * of a capture. This is always paired with an onPocessingStart().
     */
    void onProcessingStop();

    /**
     * The system is about to begin taking a high resolution picture. This is always paired with
     * onTakePictureStop().
     */
    void onTakePictureStart();

    /**
     * The system has finished taking a high resolution picture. This is always paired with
     * onTakePictureStart().
     */
    void onTakePictureStop();

    /**
     * An image has been accepted as being of good quality. Processing will not begin until this
     * has occurred. Once received a user can safely remove their hand from view.
     */
    void onImageAcceptance();

    /**
     * An image has been rejected because of poor quality. Processing will not begin, and another
     * image may be requested.
     */
    void onImageRejection();

    /**
     * Provides information about the *mode* 4 FingerID is currently in, where the hand / digit
     * should be placed within the camera view, and if the user is able to decide to alter which
     * hand they are capturing.
     *
     * configureUI() will be called whenever 4 FingerID indicates it would like to capture a
     * particular print, and this may occur several times. For example, when configured to capture
     * both the left and right hand `configureUI()` will be called twice; once at the start
     * of left hand capture, and again after successful capture of the left hand to begin right hand
     * capture.
     *
     * @param mode The mode that the UI should prepare capture for. You should layout your UI
     *             accordingly.
     * @param print Which fingerprint, or prints, are about to be captured
     * @param regionOfInterest A rectangle indicating the region in the camera preview a user should
     *                         place their fingers within. You should use this region to position your
     *                         hand guide on screen. Values are normalised to the camera preview.
     *                         For example, an x value of 0.5 is the centre of the preview. A width
     *                         value of 0.25 is 25% the width of the preview. Note: this area will
     *                         differ between devices, so do not use a static positioning of UI
     *                         components.
     * @param canSwitchHand TRUE if the user is allowed to choose to switch hands during capture. If
     *                      TRUE you should provide a mechanism for the user to change hands (see
     *                      FourFUIIntegrationWrapper.requestSwitchHand()). If FALSE, disable any
     *                      UI for hand switching.
     */
    void configureUI(captureMode mode, printToCapture print, RectF regionOfInterest, boolean canSwitchHand);

    /**
     * Display realtime feedback. This includes "hand distance" relative to the
     * optimal, and position of each finger.
     *
     * @param rois RectF array indicating the position of fingers; index, middle, ring, and little.
     *             Values are normalised to the camera preview. For example, an x value of 0.5 is the
     *             centre of the preview. A width value of 0.25 is 25% the width of the preview.
     *             You must account for how your UI has cropped and positioned the camera preview in
     *             order to display them correctly.
     * @param distance the normalised distance of the hand from the optimal distance given in the
     *                 range [-2.5, 2.5], where values [-1.0, 1.0] are acceptable for capture.
     */
    void displayRealTimeInformation(RectF[] rois, float distance);

    /**
     * Informs your UI of camera preview width and height, for example, to set aspect ratios.
     *
     * @param width camera preview width (pixels)
     * @param height camera preview height (pixels)
     */
    void setPreviewResolution(int width, int height);

    /**
     * Control display of the instruction screen
     *
     * @param showInstructionScreen When TRUE the instruction screen is displayed
     */
    void setShowInstructionScreen(boolean showInstructionScreen);

    /*
        Methods that will be called by the platform
     */

    /**
     * Provide a frame layout for rendering the camera preview to.
     * @return an AspectRatioSafeFrameLayout frame layout
     */
    AspectRatioSafeFrameLayout getPreviewHolder();

    /**
     * Receive a listener object on which to call FourFFragmentReady() once the UI fragment is
     * inited.
     * @param onFourFFragmentReadyListener listener to allow the UI fragment to declare it is ready
     */
    void onReady(onFourFFragmentReadyListener onFourFFragmentReadyListener);

    /**
     * Called when an operation has completed, including a reason for the completion. Call
     * MyCustomUIFragment.this.getActivity().finish(); to finish.
     *
     * @param reason reason for completion.
     */
    void dismiss(FourFFinishReason reason);
}