UI abstract class with methods callable by the 4FingerID library. Allows the library to control the platform GUI from the library. Implement this abstract class to build a completely custom UI.
/**
* 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);
}