signoAPI Android – STSignoViewer class

The STSignoViewer class is the core of the libSignoPDFSigner. This class is used for displaying and editing PDF documents. The STSignoViewer can load and display PDF documents. Gestures can be used to zoom and scroll, to fill in form fields and to add signatures to signature fields. All methods of the STSignoSigner class also belong to the STSignoViewer class. Only the additionally contained methods are listed below.

Usage:

STSignoViewer signoViewer = STSignoViewerCreator.createSignoViewer(context, true);

Some methods return an integer, which can be used to identify errors. The possible error codes are listed in the table below:

setSignoViewerNotifier method

This method can be used to set the instance of a class that implements the STSignoViewerNotifier interface and is therefore to be informed of events in the STSignoViewer.

void setSignoViewerNotifier(STSignoViewerNotifier signoViewerNotifier);

Usage:

STSignoViewerNotifier signoViewerNotifier = new STSignoViewerNotifierImpl();
signoViewer.setSignoViewerNotifier(signoViewerNotifier);

loadDocumentFromFile method

This method transfers a PDF document as a byte array to the API or starts the asynchronous loading and display of a PDF document. If the STSignoViewer fragment that is used to display the PDF document has not yet been started, the document is only transferred to the API. To display the document in this case, the STSignoViewer fragment must be started after calling this method. However, if the STSignoViewer fragment has already been started, the document is not only transferred to the API. Asynchronous loading is started at the same time and the document is displayed in the STSignoViewer fragment that is already open.

Then the STSignoViewerNotifier.documentLoaded() method is called and the result of this method can be obtained. Once the document has been successfully loaded, the methods that make changes to the document can be executed within the STSignoViewerNotifier.documentLoaded() method. For further information, see also the STSignoViewerNotifier.documentLoaded() method.

If the STSignoViewer instance is generated as a Fragment instance, this method is only responsible for loading the PDF document. To display the PDF document, the FragmentTransaction.add(), FragmentTransaction.replace() and FragmentTransaction.attach() methods must be used. For further information, see also the STSignoViewerCreator.createSignoViewer() and STSignoViewerCreator.newInstance() methods.

void loadDocumentFromFile(byte[] documentData);

Usage:

// Wenn der Viewer noch nicht gestartet ist
signoViewer.loadDocumentFromFile(documentData);
FragmentTransaction ft = fragmentManager.beginTransaction();
ft.add(R.id.docLayout, signoViewer).show(signoViewer).commit();

//oder wenn der Viewer schon gestartet ist
signoViewer.loadDocumentFromFile(documentData);

showToolbar method

This method can be used to define whether or not the toolbar is to be displayed. It must be set before the loadDocumentFromFile() method is called.

The toolbar currently contains the following four buttons:

· ‘Back‘: Calls the STSignoViewerNotifier.backButtonPressed() method.

· ‘Sign‘: Jumps to the signature fields, in sequence.

· ‘Signature fields‘: Calls the STSignoViewerNotifier signatureInfoPressed() method and displays a dialog with the document’s signature fields, if there are any.

· ‘Save‘: Calls the STSignoViewerNotifier.documentSaved() method.

void showToolbar(boolean show);

Usage:

signoViewer.showToolbar(true);

startSignature method

This method begins the process of capturing signatures. This functionality can also be triggered via the ‘Sign’ button in the toolbar or by tapping a signature field in the document.

int startSignature();

int startSignature(String signatureFieldName);

Usage:

int ret = signoViewer.startSignature("customer_signature");
if (ret < 0) {
  // error handling
}

getFormFieldsInfo method

getFormFields method

This method can be used to retrieve information about the form fields contained within the document.

void getFormFields(EnumSet<STFormFieldType> formFieldTypes, STGetFormFieldsCallback getFormFieldsCallback);

Usage:

signoViewer.getFormFields(EnumSet.allOf(STFormFieldType.class), new STSignoViewer.STGetFormFieldsCallback() {
    @Override
    public <T extends STFormFieldInfoDTO> void onResponse(List<T> formFields) {
         //get all form fields
    }
});

STGetFormFieldsCallback interface

The STGetFormFieldsCallback interface is a callback interface whose method is called after the getFormFields() method has been completed.

interface STGetFormFieldsCallback {
    <T extends STFormFieldInfoDTO> void onResponse(List<T> formFields);
}

onResponse method

The method is called when the getFormFields() method has been executed.

<T extends STFormFieldInfoDTO> void onResponse(List<T> formFields);

setFormFieldsInfo method

This method can be used to change the content and ‘read only’ property of form fields.

void setFormFieldsInfo(List<STFormFieldInfoDTO> fields);

Usage:

List<STFormFieldInfoDTO> formFields = signoViewer.getFormFieldsInfo();
for (STFormFieldInfo formField : formFields) {
  if (formField.name.equals("MyField")) {
      formFields.value = "My value";
      formField.readOnly = true;
  }
}
signoViewer.setFormFieldsInfo.(formFields);

closeViewer method

unloadDocument method

This method can be used to unload the document last loaded using the loadDocumentFromFile() method, remove the view and switch back to the user’s own app interface.

If the STSignoViewer instance was created as a fragment instance, the view should not only be removed using the FragmentTransaction.remove() method. In any case, this method should also be used. For further information, see also the STSignoViewerCreator.createSignoViewer() and STSignoViewerCreator.newInstance() methods.

void unloadDocument();

Usage:

signoViewer.unloadDocument();

setCustomTheme method

This method can be used to replace the standard design of the toolbar with a user-defined design. The Activity class in the API is based on the Android Compatibility Library v7, which means that the user-defined design must be inherited from Theme.AppCombat. In the user-defined design, the primary colours can be defined with the colorPrimary, colorAccent and colorPrimaryDark attributes, and the standard action bar of the window decor can be manually disabled by setting windowActionBar to false and windowNoTitle to true.

void setCustomTheme(int customTheme);

Usage:

<style name="SignoApiTheme" parent="Theme.AppCompat.Light">
    <item name="colorPrimary">@color/colorPrimary</item>
    <item name="colorPrimaryDark">@color/colorPrimaryDark</item>
    <item name="colorAccent">@color/colorAccent</item>
    <item name="windowActionBar">false</item>
    <item name="windowNoTitle">true</item>
</style>
signoViewer.setCustomTheme(R.style.SignoApiTheme);

createNewSignatureField method

This method generates a new, empty signature field.

void createNewSignatureField(STSignatureFieldInfoDTO signatureField, STCreateNewSignatureFieldCallback createNewSignatureFieldCallback);

Usage:

signoViewer.createNewSignatureField(signatureField, new STCreateNewSignatureFieldCallback() {
    @Override
    public void onFailure(int errorCode) {
       // error handling
    }
 
    @Override
    public void onSuccess() {
       //do anything
    }
});

STCreateNewSignatureFieldCallback interface

The STCreateNewSignatureFieldCallback interface is a callback interface whose methods are called after the createNewSignatureField() method has been completed.

interface STCreateNewSignatureFieldCallback {
    void onFailure(int errorCode);
    void onSuccess();
}

onFailure method

The method is called if an error occurs when executing the createNewSignatureField() method.

void onFailure(int errorCode);

onSuccess method

The method is called when the createNewSignatureField() method has been successfully executed.

void onSuccess();

signDocument method

This method can be used to add a digital signature to the document without the need for a signature capture process.

int signDocument(String signatureFieldName);

void signDocument(String signatureFieldName, STSignDocumentCallback signDocumentCallback);

Usage (synchronous execution):

int ret = signoViewer.signDocument("final_doc_signature");
if (ret < 0) {
  // error handling
}

Usage (asynchronous execution):

signoViewer.signDocument("final_doc_signature ", new STSignoViewer.STSignDocumentCallback() {
    @Override
    public void onFailure(int errorCode) {
       // error handling
    }

    @Override
    public void onSuccess() {
        //do anything
    }
});

STSignDocumentCallback interface

The STSignDocumentCallback interface is a callback interface whose methods are called after the signDocument() method has been completed.

interface STSignDocumentCallback {
    void onFailure(int errorCode);
    void onSuccess();
}

onFailure method

The method is called if an error has occurred during the execution of the signDocument() method.

void onFailure(int errorCode);

onSuccess method

The method is called when the signDocument() method has been successfully executed.

void onSuccess();

createViewerRect method

This method can be used to display a rectangle on the PDF viewer whose size and position can be modified by the user. Two buttons for cancelling and confirming are also generated in addition to the rectangle. Tapping the ‘Cancel’ button calls the STSignoViewerNotifier.viewerRectCancelled() method. Tapping the ‘Confirm’ button calls the STSignoViewerNotifier.viewerRectConfirmed() method. Further rectangle properties can be configured using the STViewerRectDTO class. For further information, see also the STViewerRectDTO class.

int createViewerRect(STViewerRectDTO viewerRectDTO);

Usage:

STViewerRectDTO rectViewerDTO = new STViewerRectDTO();
int rectViewId = signoViewer.createViewerRect(rectViewerDTO);

enableAutoRotation method

This method allows the rotation of the screen to be enabled and disabled.

void enableAutoRotation(boolean enabled);

Usage:

signoViewer.enableAutoRotation(true);

enableTouchEvents method

This method allows all touch events in the PDF viewer to be enabled and disabled.

void enableTouchEvents(boolean enabled);

Usage:

signoViewer.enableTouchEvents(true);

addImages method

This method can be used to insert images into the loaded document.

void addImages(List<STImageDTO> images, STAddImagesCallback addImagesCallback);

Usage:

STRectDTO size = new STRectDTO();
size.setUnit(STRectDTO.Unit.UnitMillimetres);
size.setRectangle(new RectF(0.0f, 0.0f, 210.0f, 297.0f));

STImageDTO imageDTO = new STImageDTO();
Bitmap myimage = BitmapFactory.decodeResource(this.getResources(), R.drawable.myimage);
imageDTO.setImage(myimage);
imageDTO.setRectDTO(size);
imageDTO.setPage(1);

List<STImageDTO> images = new ArrayList<>();
images.add(imageDTO);
signoViewer.addImages(images, new STSignoViewer.STAddImagesCallback(){
    @Override
    public void onFailure(int errorCode) {
        //error handling
    }

    @Override
    public void onSuccess() {
        //do anything
    }
});

STAddImagesCallback interface

The STAddImagesCallback interface is a callback interface whose methods are called after the addImages() method has been completed.

interface STAddImagesCallback {
    void onFailure(int errorCode);
    void onSuccess();
}

onFailure method

The method is called if an error occurs when executing the addImages() method.

void onFailure(int errorCode);

onSuccess method

The method is called when the addImages() method has been successfully executed.

void onSuccess();

startTextSearch method

This method searches for text in the loaded PDF, visually highlights all places where the text was found, optionally scrolls to the first search result and returns the positions of all places.

List<Rect> startTextSearch(String text, int page, int highlightColor, boolean onlyWholeWord, boolean caseSensitive);

void startTextSearch(String text, int page, int highlightColor, boolean onlyWholeWord, boolean caseSensitive, STStartTextSearchCallback textSearchCallback);

Usage (synchronous execution):

List<Rect> foundTextPositions = signoViewer.startTextSearch("Signature", 1, null, true, true);
for (Rect rect : foundTextPositions) {
  SignatureFieldInfoDTO field = new SignatureFieldInfoDTO();
  field.setName("New_Signature");
  field.setPage(1);
  field.setRectangle(rect);
  int result = signoViewer.createNewSignatureField(field);
}

Usage (asynchronous execution):

signoViewer.startTextSearch("Signature", 1, null, true, true, new STSignoViewer.STStartTextSearchCallback() {
    @Override
    public void onResponse(List<Rect> foundTextPositions) {
        for (Rect rect : foundedTextPositions) {
            SignatureFieldInfoDTO field = new SignatureFieldInfoDTO();
            field.setName("New_Signature");
            field.setPage(1);
            field.setRectangle(rect);
            int result = signoViewer.createNewSignatureField(field);
        }
    }
});

STStartTextSearchCallback interface

The STStartTextSearchCallback interface is a callback interface whose method is called after the startTextSearch() method has been completed.

interface STStartTextSearchCallback {
    void onResponse(List<Rect> foundTextPositions);
}

onResponse method

The method is called when the startTextSearch() method has been executed.

void onResponse(List<Rect> foundTextPositions);

finishTextSearch method

This method can be used to remove the visual highlights which are displayed at all places where the search text was found after calling the startTextSearch() method from the PDF viewer.

void finishTextSearch();

Usage:

signoViewer.finishTextSearch();

showPageNumber method

This method can be used to configure whether the page number is displayed in the PDF viewer. It only has an effect if it is called before the loadDocumentFromFile() method.

void showPageNumber(boolean show);

Usage:

signoViewer.showPageNumber(true);

scrollToPage method

This method can be used to scroll the document to the height of a particular page.

void scrollToPage(int pageNr, boolean smoothScrollingEnabled);

Usage:

signoViewer.scrollToPage(3, true);

setSignatureCaptureConfig method

This method sets an instance of the STSignatureCaptureConfig class in which the signature dialogue is configured. This must be set at least once before the loadDocumentFromFile() method. However, the instance of the STSignatureCaptureConfig class can be updated at any time using this method.

void setSignatureCaptureConfig(STSignatureCaptureConfig captureConfig);

Usage:

STSignatureCaptureConfig captureConfig = new STSignatureCaptureConfig();
captureConfig.setSignatureColor(Color.BLUE);
captureConfig.setLineWidth(4);
captureConfig.setEnableFullScreenCapture(false);
captureConfig.setEnableBiometricDataCapturing(true);
captureConfig.setEnablePressureDependentCapturing(false);
captureConfig.setMarginBottom(30);
captureConfig.setEnableTouchSignature(true);
captureConfig.setEnablePencilSignature(true);
captureConfig.setCaptureTextConfig(new STCaptureTextConfig.Builder()
        .displayText("Your signature")
        .font(Typeface.create("Arial", Typeface.BOLD))
        .textColor(Color.BLACK)
        .fontSize(20)
        .backgroundColor(Color.YELLOW)
        .gravity(STCaptureTextConfig.CaptureGravity.TOP_START)
        .marginTop(20)
        .marginStart(20)
        .paddingStart(10)
        .paddingEnd(10)
        .paddingTop(10)
        .paddingBottom(10)
        .build());
signoViewer.setSignatureCaptureConfig(captureConfig);

startNotesMode method

This method makes it possible to activate notes mode, which allows hand-written notes to be added to a PDF document. When notes mode is active, all actions are deactivated that could result in changes being made to the PDF viewer. The notes mode does not work with PDF/A-1b documents.

void startNotesMode(STNotesConfig notesConfig, STNotesStartCallback notesStartCallback);

Usage:

STNotesConfig notesConfig =
    new STNotesConfig().withStrokeColor(Color.RED).
    withStrokeWidth(2);

signoViewer.startMode(notesConfig, new STSignoViewer. STNotesStartCallback(){
    @Override
    public void onNotesModeStarted() {
        //success
    }

    @Override
    public void onNotesModeFailedToStart(int errorCode) {
        //error handling
    }
});

STNotesStartCallback interface

The STNotesStartCallback interface is a callback interface that makes it possible to monitor whether notes mode was started successfully or if it failed as the result of certain conditions.

interface STNotesStartCallback {
    void onNotesModeStarted();
    void onNotesModeFailedToStart(int errorCode);
}

onNotesModeStarted method

The method is called when the startNotesMode() method has been successfully executed.

void onNotesModeStarted();

onNotesModeFailedToStart method

The method is called if an error occurs when executing the startNotesMode() method.

void onNotesModeFailedToStart(int errorCode);

cancelNotesMode method

This method ends the currently active notes mode and restores the original display mode of the PDF viewer. Any notes that have not been saved are lost. This method has no effect if notes mode is not active.

void cancelNotesMode();

Usage:

signoViewer.cancelNotesMode();

saveAndFinishNotesMode method

This method saves all changes made during the current notes session and then exits notes mode. Once the notes have been saved, the viewer changes back to standard mode. The callback interface provided enables the results of the saving procedure to be processed.

void saveAndFinishNotesMode(STNotesFinishCallback notesFinishCallback);

Usage:

signoViewer.saveAndFinishNotesMode(new STNotesFinishCallback() { @Override
    public void onFinish(boolean isSaved) {
       if (isSaved) {
          System.out.println("Notes saved successfully!");
       } else {
          System.out.println("No notes have been saved.");
       }
    }
    
    @Override
    public void onFailure(int errorCode) {
        System.err.println("Error " + errorCode + " occurred while saving
    the notes.");
    }
});

STNotesFinishCallback interface

The STNotesFinishCallback interface is a callback interface that deals with the result of the saving procedure.

interface STNotesFinishCallback {
    void onFinish(isSaved);
    void onFailure(int errorCode);
}

onFinish method

This method is called when the saveAndFinishNotesMode() method is ended – regardless of whether notes were saved successfully or no notes were present.

void onFinish(boolean isSaved);

onFailure method

This method is called when an error occurs during execution of saveAndFinishNotesMode().

void onFailure(int errorCode);

changeNotesConfig method

This method makes it possible to update the notes configuration while notes mode is active. Changes are applied immediately and apply to all following notes within the current session. This method can only be called when notes mode is active. Notes that had already been created remain unchanged. The changes only affect future notes.

void changeNotesConfig(STNotesConfig notesConfig);

Usage:

STNotesConfig notesConfig = new STNotesCofig().withStrokeColor(Color.BLUE).withStrokeWidth(3);
signoViewer.changeNotesConfig(notesConfig);

undoNote method

This method removes the most recently created note during the current notes session. It enables users to undo their last action so they can correct errors or make adjustments. This method is only available when notes mode is active and has no effect if no notes have been created in the current session.

void undoNote();

Usage:

signoViewer.undoNote();

redoNote method

This method restores the most recently undone note in notes mode. It allows users to restore a note they have removed, undoing the action performed by undoNote(). This method is only available when notes mode is active and has no effect if no note has been undone.

void redoNote();

Usage:

signoViewer.redoNote();