signoAPI Android – Klasse STSignoViewer

Die Klasse STSignoViewer ist das Herzstück der libSignoPDFSigner. Diese Klasse wird zur Anzeige und zum Editieren von PDF-Dokumenten verwendet. Der STSignoViewer kann PDF-Dokumente laden und anzeigen. Es kann durch Gesten gezoomt und geblättert werden, Formularfelder können ausgefüllt und Signaturfelder unterschrieben werden. Sämtliche Methoden der Klasse STSignoSigner gehören auch zur Klasse STSignoViewer, nachfolgend sind nur die zusätzlich enthaltenen aufgeführt.

Anwendung:

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

Einige Methoden geben eine Ganzzahl zurück, anhand der ein Fehler erkannt werden kann. Folgende Tabelle enthält die möglichen Fehlercodes:

Methode setSignoViewerNotifier

Mit dieser Methode kann die Instanz einer Klasse festgelegt werden, die das Interface STSignoViewerNotifier implementiert und somit über Ereignisse im STSignoViewer informiert werden soll.

void setSignoViewerNotifier(STSignoViewerNotifier signoViewerNotifier);

Anwendung:

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

Methode loadDocumentFromFile

Diese Methode übergibt ein PDF-Dokument als Byte-Array an das API oder startet das asynchrone Laden und Anzeigen eines PDF-Dokuments. Wenn das STSignoViewer-Fragment, das für die Anzeige des PDF-Dokuments verwendet wird, noch nicht gestartet wurde, erfolgt lediglich die Übergabe des Dokuments an das API. Um das Dokument in diesem Fall anzuzeigen, muss nach dem Aufruf dieser Methode das STSignoViewer-Fragment gestartet werden. Ist das STSignoViewer-Fragment jedoch bereits gestartet, wird das Dokument nicht nur an das API übergeben, sondern es wird gleichzeitig das asynchrone Laden gestartet und das Dokument im bereits geöffneten STSignoViewer-Fragment angezeigt.

Anschließend wird die Methode STSignoViewerNotifier.documentLoaded() aufgerufen und das Ergebnis dieser Methode kann erhalten werden. Beim erfolgreichen Laden des Dokuments können die Methoden, die Änderungen im Dokument vornehmen, innerhalb der Methode STSignoViewerNotifier.documentLoaded() ausgeführt werden. Für weitere Informationen siehe auch die Methode STSignoViewerNotifier.documentLoaded().

Wenn die STSignoViewer-Instanz als Fragment-Instanz erzeugt wird, ist diese Methode nur zuständig, das PDF-Dokument zu laden. Um das PDF-Dokument anzuzeigen, müssen die Methoden FragmentTransaction.add(), FragmentTransaction.replace() und FragmentTransaction.attach() verwendet werden. Für weitere Informationen siehe auch die Methoden STSignoViewerCreator.createSignoViewer() und STSignoViewerCreator.newInstance().

void loadDocumentFromFile(byte[] documentData);

Anwendung:

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

Methode showToolbar

Mit dieser Methode kann definiert werden, ob die Werkzeugleiste angezeigt werden soll. Sie muss gesetzt werden, bevor die Methode loadDocumentFromFile() aufgerufen wird.

Die Werkzeugleiste enthält derzeit die folgenden vier Schaltflächen:

·        „Zurück“: Ruft die Methode STSignoViewerNotifier.backButtonPressed() auf.

·        „Unterschreiben“: Springt die Signaturfelder der Reihe nach ab.

·        „Signaturfelder“: Ruft die Methode STSignoViewerNotifier.signatureInfoPressed() auf und zeigt ggf. einen Dialog mit den Signaturfeldern des Dokuments an.

·        „Speichern“: Ruft die Methode STSignoViewerNotifier.documentSaved() auf.

void showToolbar(boolean show);

Anwendung:

signoViewer.showToolbar(true);

Methode startSignature

Diese Methode startet das Erfassen von Unterschriften. Diese Funktionalität kann auch durch die „Unterschreiben“-Schaltfläche in der Werkzeugleiste oder durch das Antippen eines Signaturfeldes im Dokument ausgelöst werden.

int startSignature();

int startSignature(String signatureFieldName);

Anwendung:

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

Methode getFormFieldsInfo

Methode getFormFields

Mit dieser Methode können Informationen über die im Dokument enthaltenen Formularfelder abgerufen werden.

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

Anwendung:

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

Interface STGetFormFieldsCallback

Die Interface STGetFormFieldsCallback ist eine Callback-Schnittstelle, deren Methode nach Abschluss der Methode getFormFields() aufgerufen wird.

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

Methode onResponse

Die Methode wird aufgerufen, wenn die Methode getFormFields() ausgeführt wurde.

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

Methode setFormFieldsInfo

Mit dieser Methode können der Inhalt und die „read only“-Eigenschaft von Formularfeldern geändert werden.

void setFormFieldsInfo(List<STFormFieldInfoDTO> fields);

Anwendung:

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

Methode closeViewer

Methode unloadDocument

Mit dieser Methode kann das zuletzt mit der Methode loadDocumentFromFile() geladene Dokument entladen, die View entfernt und zurück zur eigenen App-Oberfläche gewechselt werden.

Wenn die STSignoViewer-Instanz als Fragment-Instanz erzeugt wurde, soll die View nicht nur mit der Methode FragmentTransaction.remove() entfernt werden. In jedem Fall soll diese  Methode auch ausgeführt werden. Für weitere Informationen siehe auch die Methode STSignoViewerCreator.createSignoViewer() und STSignoViewerCreator.newInstance().

void unloadDocument();

Anwendung:

signoViewer.unloadDocument();

Methode setCustomTheme

Mit dieser Methode kann das Standard-Design der Werkzeugleiste durch ein benutzerdefiniertes Design ersetzt werden. Die Activity-Klasse im API basiert auf der Android Compability Library v7, was bedeutet, dass das benutzerdefiniertes Design von Theme.AppCombat geerbt werden muss. Im benutzerdefinierten Design können die Primärfarben mit den Attributen colorPrimary, colorAccent und colorPrimaryDark definiert und die Standard-Aktionsleiste des Fensterdekors manuell deaktiviert werden, indem windowActionBar auf false und windowNoTitle auf true gesetzt wird.

void setCustomTheme(int customTheme);

Anwendung:

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

Methode createNewSignatureField

Diese Methode erzeugt ein neues leeres Signaturfeld.

void createNewSignatureField(STSignatureFieldInfoDTO signatureField, STCreateNewSignatureFieldCallback createNewSignatureFieldCallback);

Anwendung:

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

Interface STCreateNewSignatureFieldCallback

Die Interface STCreateNewSignatureFieldCallback ist eine Callback-Schnittstelle, deren Methoden nach Abschluss der Methode createNewSignatureField() aufgerufen werden.

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

Methode onFailure

Die Methode wird aufgerufen, wenn bei der Ausführung der Methode createNewSignatureField() ein Fehler aufgetreten ist.

void onFailure(int errorCode);

Methode onSuccess

Die Methode wird aufgerufen, wenn die Methode createNewSignatureField() erfolgreich ausgeführt wurde.

void onSuccess();

Methode signDocument

Diese Methode fügt dem Dokument eine digitale Signatur hinzu, ohne dass eine Unterschrifterfassung durchgeführt wird.

int signDocument(String signatureFieldName);

void signDocument(String signatureFieldName, STSignDocumentCallback signDocumentCallback);

Anwendung (synchrone Ausführung):

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

Anwendung (asynchrone Ausführung):

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

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

Interface STSignDocumentCallback

Die Interface STSignDocumentCallback ist eine Callback-Schnittstelle, deren Methoden nach Abschluss der Methode signDocument() aufgerufen werden.

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

Methode onFailure

Die Methode wird aufgerufen, wenn bei der Ausführung der Methode signDocument() ein Fehler aufgetreten ist.

void onFailure(int errorCode);

Methode onSuccess

Die Methode wird aufgerufen, wenn die Methode signDocument() erfolgreich ausgeführt wurde.

void onSuccess();

Methode createViewerRect

Mit dieser Methode kann ein Rechteck auf dem PDF-Viewer angezeigt werden, welches vom Anwender in der Größe und Position verändert werden kann. Zusätzlich zum Rechteck werden zwei Schaltflächen zum Abbrechen und Bestätigen erzeugt. Beim Antippen der „Abbrechen“-Schaltfläche wird die Methode STSignoViewerNotifier.viewerRectCancelled() aufgerufen. Beim Antippen der „Bestätigen“-Schaltfläche wird die Methode STSignoViewerNotifier.viewerRectConfirmed() aufgerufen. Mit Hilfe der Klasse STViewerRectDTO können weitere Eigenschaften des Rechtecks konfiguriert werden. Für weitere Informationen siehe auch die Klasse STViewerRectDTO.

int createViewerRect(STViewerRectDTO viewerRectDTO);

Anwendung:

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

Methode enableAutoRotation

Mit dieser Methode kann das Drehen des Bildschirms gesperrt und entsperrt werden.

void enableAutoRotation(boolean enabled);

Anwendung:

signoViewer.enableAutoRotation(true);

Methode enableTouchEvents

Mit dieser Methode können alle Touch-Events im PDF-Viewer gesperrt und entsperrt werden.

void enableTouchEvents(boolean enabled);

Anwendung:

signoViewer.enableTouchEvents(true);

Methode addImages

Mit dieser Methode können Bilder in das geladene Dokument eingefügt werden.

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

Anwendung:

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

Interface STAddImagesCallback

Die Interface STAddImagesCallback ist eine Callback-Schnittstelle, deren Methoden nach Abschluss der Methode addImages() aufgerufen werden.

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

Methode onFailure

Die Methode wird aufgerufen, wenn bei der Ausführung der Methode addImages() ein Fehler aufgetreten ist.

void onFailure(int errorCode);

Methode onSuccess

Die Methode wird aufgerufen, wenn die Methode addImages() erfolgreich ausgeführt wurde.

void onSuccess();

Methode startTextSearch

Diese Methode sucht nach einem Text auf einer PDF-Seite, hebt ggf. alle Fundstellen visuell hervor und liefert die Positionen aller Fundstellen zurück.

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

Anwendung (synchrone Ausführung):

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

Anwendung (asynchrone Ausführung):

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

Interface STStartTextSearchCallback

Die Interface STStartTextSearchCallback ist eine Callback-Schnittstelle, deren Methode nach Abschluss der Methode startTextSearch() aufgerufen wird.

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

Methode onResponse

Die Methode wird aufgerufen, wenn die Methode startTextSearch() ausgeführt wurde.

void onResponse(List<Rect> foundTextPositions);

Methode finishTextSearch

Mit dieser Methode können die visuellen Hervorhebungen, die nach der Ausführung der Methode startTextSearch() an allen Fundstellen des Suchtextes angezeigt werden, aus dem PDF-Viewer entfernt werden.

void finishTextSearch();

Anwendung:

signoViewer.finishTextSearch();

Methode showPageNumber

Mit dieser Methode kann konfiguriert werden, ob die Seitennummer im PDF-Viewer angezeigt wird. Sie wirkt sich nur aus, wenn sie vor der Methode loadDocumentFromFile() aufgerufen wird.

void showPageNumber(boolean show);

Anwendung:

signoViewer.showPageNumber(true);

Methode scrollToPage

Mit dieser Methode kann das Dokument auf die Höhe einer bestimmten Seite gescrollt werden.

void scrollToPage(int pageNr, boolean smoothScrollingEnabled);

Anwendung:

signoViewer.scrollToPage(3, true);

Methode setSignatureCaptureConfig

Diese Methode setzt eine Instanz der Klasse STSignatureCaptureConfig, in der der Signaturdialog konfiguriert wird. Diese muss mindestens einmal vor der Methode loadDocumentFromFile() gesetzt werden. Allerdings kann die Instanz der Klasse STSignatureCaptureConfig zu jedem Zeitpunkt mit dieser Methode aktualisiert werden.

void setSignatureCaptureConfig(STSignatureCaptureConfig captureConfig);

Anwendung:

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

Methode startNotesMode

Diese Methode ermöglicht die Aktivierung des Notizen-Modus, in dem handschriftliche Notizen zu einem PDF-Dokument hinzugefügt werden können. Während der Notizen-Modus aktiv ist, werden alle Aktionen deaktiviert, die Änderungen am PDF-Viewer bewirken könnten. Der Notizen-Modus funktioniert nicht mit PDF/A-1b-Dokumenten.

void startNotesMode(STNotesConfig notesConfig, STNotesStartCallback notesStartCallback);

Anwendung:

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

Interface STNotesStartCallback

Die Interface STNotesStartCallback ist eine Callback-Schnittstelle, die es ermöglicht zu überwachen, ob der Notizen-Modus erfolgreich gestartet wurde oder aufgrund bestimmter Bedingungen fehlgeschlagen ist.

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

Methode onNotesModeStarted

Die Methode wird aufgerufen, wenn die Methode startNotesMode() erfolgreich ausgeführt wurde.

void onNotesModeStarted();

Methode onNotesModeFailedToStart

Die Methode wird aufgerufen, wenn bei der Ausführung der Methode startNotesMode() ein Fehler aufgetreten ist.

void onNotesModeFailedToStart(int errorCode);

Methode cancelNotesMode

Diese Methode beendet den aktuell aktiven Notizen-Modus und stellt den ursprünglichen Anzeigemodus des PDF-Viewers wieder her. Alle nicht gespeicherten Notizen gehen verloren. Diese Methode hat keine Auswirkungen, wenn der Notizen-Modus nicht aktiv ist.

void cancelNotesMode();

Anwendung:

signoViewer.cancelNotesMode();

Methode saveAndFinishNotesMode

Diese Methode speichert alle während der aktuellen Notizen-Sitzung vorgenommenen Änderungen und beendet anschließend den Notizen-Modus. Nach dem erfolgreichen Speichern wechselt der Viewer zurück in den Standardmodus. Über die mitgegebene Callback-Schnittstelle kann das Ergebnis des Speichervorgangs verarbeitet werden.

void saveAndFinishNotesMode(STNotesFinishCallback notesFinishCallback);

Anwendung:

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

Interface STNotesFinishCallback

Die Interface STNotesFinishCallback ist eine Callback-Schnittstelle, die das Ergebnis des Speichervorgangs behandelt.

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

Methode onFinish

Diese Methode wird aufgerufen, wenn die Methode saveAndFinishNotesMode() beendet wurde – unabhängig davon, ob Notizen erfolgreich gespeichert wurden oder keine Notizen vorhanden sind.

void onFinish(boolean isSaved);

Methode onFailure

Diese Methode wird aufgerufen, wenn während der Ausführung von saveAndFinishNotesMode() ein Fehler auftritt.

void onFailure(int errorCode);

Methode changeNotesConfig

Diese Methode ermöglicht die Aktualisierung der Notizen-Konfiguration während des aktiven Notizen-Modus. Änderungen werden sofort übernommen und gelten für alle nachfolgenden Notizen innerhalb der aktuellen Sitzung. Diese Methode kann nur aufgerufen werden, wenn der Notizen-Modus aktiv ist. Bereits erstellte Notizen bleiben unverändert, die Änderungen wirken sich nur auf zukünftige Notizen aus.

void changeNotesConfig(STNotesConfig notesConfig);

Anwendung:

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

Methode undoNote

Diese Methode entfernt die zuletzt erstellte Notiz während der aktuellen Notizen-Sitzung. Sie ermöglicht es dem Benutzer, die letzte Aktion rückgängig zu machen, um Fehler zu korrigieren oder Anpassungen vorzunehmen. Diese Methode ist nur im aktiven Notizen-Modus verfügbar und hat keine Auswirkung, wenn in der aktuellen Sitzung keine Notizen erstellt worden sind.

void undoNote();

Anwendung:

signoViewer.undoNote();

Methode redoNote

Diese Methode stellt die zuletzt rückgängig gemachte Notiz im Notizen-Modus wieder her. Sie dient dazu, eine zuvor entfernte Notiz erneut anzuwenden und macht die Aktion von undoNote() rückgängig. Diese Methode ist nur im aktiven Notizen-Modus verfügbar und hat keine Auswirkung, wenn keine Notiz rückgängig gemacht worden ist.

void redoNote();

Anwendung:

signoViewer.redoNote();