signoAPI iOS – Klasse STSignoViewController

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

@interface STSignoViewController : UIViewController

Anwendung:

STSignoViewController *signoVC = [[STSignoViewController alloc] init];
signoVC.modalPresentationStyle = UIModalPresentationFullScreen;
[self presentViewController:signoVC animated:YES completion:nil];

Oder

STSignoViewController *signoVC = [[STSignoViewController alloc] init];
signoVC.modalPresentationStyle = UIModalPresentationFullScreen;
[self addChildViewController:signoVC];
[self.view addSubview:signoVC.view];
[signoVC didMoveToParentViewController:self];

Eigenschaft signatureCaptureVC

Diese Eigenschaft enthält die Instanz des , der zur Erfassung der Unterschrift verwendet wird. Die Instanz selbst kann nicht gesetzt bzw. geändert werden, es können aber Ihre Eigenschaften und Methoden verwendet werden.

@property (readonly, nonatomic, retain) STSignatureCaptureViewController* signatureCaptureVC

Anwendung:

signoVC.signatureCaptureVC.signCaptureDelegate = self;

Eigenschaft toolbarHeight

Diese Eigenschaft enthält die Höhe der Werkzeugleiste und definiert somit auch den oberen Rand der Dokumentanzeige. Die Elemente der Werkzeugleiste werden in jedem Fall immer am unteren Rand der Werkzeugleiste angezeigt, so dass durch diese Eigenschaft verhindert werden kann, dass sich die Elemente mit den Elementen der iOS Statusbar überschneiden. Sie muss gesetzt werden, bevor die loadDocumentFromFile Methode aufgerufen wird.

@property (nonatomic, assign) NSInteger toolbarHeight

Anwendung:

signoVC.toolbarHeight = 50;

Eigenschaft showToolbar

Diese Eigenschaft definiert, ob die Werkzeugleiste angezeigt werden soll. Sie muss gesetzt werden, bevor die loadDocumentFromFile Methoden aufgerufen wird.

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

• „Zurück“: Ruft auf.

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

• „Signaturfelder“: Ruft auf und zeigt ggf. einen Dialog mit den Signaturfeldern des Dokuments an.

• „Speichern“: Ruft auf.

@property (nonatomic, assign) BOOL showToolbar

Anwendung:

signoVC.showToolbar = NO;

Eigenschaft enableAutoRotation

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

@property (nonatomic, assign) BOOL enableAutoRotation

Anwendung:

signoVC.enableAutoRotation = YES;

Eigenschaft showPageNumber

Mit dieser Eigenschaft kann konfiguriert werden, ob die Seitennummer im PDF-Viewer angezeigt wird.

@property (nonatomic, assign) BOOL showPageNumber

Anwendung:

signoVC.showPageNumber = YES;

Eigenschaft signatureCaptureConfig

Diese Eigenschaft enthält die Instanz des , über deren Eigenschaften der Signaturdialog konfiguriert werden kann.

@property (nonatomic, strong) STSignatureCaptureConfig* signatureCaptureConfig

Anwendung:

STSignatureCaptureConfig *sigCapConfig = 
[[STSignatureCaptureConfig alloc] init];
sigCapConfig.displayText = signatureFieldName;
sigCapConfig.font = [UIFont fontWithName:@"Helvetica" size:24];
sigCapConfig.textColor = [UIColor blackColor];
sigCapConfig.position = CGRectMake(30.0f, 30.0f, 200.0f, 40.0f);
sigCapConfig.signatureColor = [UIColor blueColor];

signoVC.signatureCaptureConfig = sigCapConfig;

Methode setPhotoFieldNames:maxWidth:maxHeight:

Mit dieser Methode können die Namen von Formularfeldern definiert werden, die für die Aufnahme von Fotos verwendet werden sollen. Die so definierten Formularfelder verhalten sich dann nicht wie übliche Formularfelder, sondern sprechen beim Antippen die Kamera des Geräts an, damit der Anwender ein Foto erfassen kann. Das erfasste Foto wird dann an der Position des Formularfeldes sichtbar eingebracht. Der Anwender kann durch ein erneutes Antippen des Feldes das Foto austauschen, solange das Feld nicht auf „read only“ gesetzt worden ist.

-(int)setPhotoFieldsNames:(NSMutableArray*)fieldNames maxWidth:(int)width maxHeight:(int)height

Anwendung:

int ret = [signoVC setPhotoFieldsNames:fieldNames maxWidth:1000 maxHeight:600];
if (ret < 0)
{
    // error handling
}

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.

-(void)startSignature

-(void)startSignature:(NSString*)signatureFieldName

Anwendung:

[signoVC startSignature:@"customer_signature"];

Methode scrollToFormField:withFocus:

Mit dieser Methode kann das Dokument auf die Höhe eines bestimmten Formularfeldes gescrollt werden.

-(void)scrollToFormField:(STFormFieldInfoDTO*)formField withFocus:(BOOL)focus

Anwendung:

[signoVC scrollToFormField:formField withFocus:focus];

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 aufgerufen. Beim Antippen der Bestätigungs-Schaltfläche wird die Methode aufgerufen. Mit Hilfe der Klasse können weitere Eigenschaften des Rechtecks konfiguriert werden. Für weitere Informationen siehe auch die Klasse .

-(int)createViewerRect:(STViewerRectDTO*)viewerRectDTO

Anwendung:

STViewerRectDTO* rectViewerDTO = [STViewerRectDTO alloc] init];
int rectViewId = [signoVC createViewerRect: rectViewerDTO];

Methode finishTextSearch

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

-(void)finishTextSearch

Anwendung:

[signoVC finishTextSearch];

Methode enableTouchEvents:

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

-(void)enableTouchEvents:(BOOL)enable

Anwendung:

[signoVC enableTouchEvents:YES];

Methode releaseSignoViewController

Mit dieser Methode kann die erzeugte Instanz der -Klasse freigegeben werden. Sie sollte immer aufgerufen werden, wenn eine Instanz nicht mehr benötigt wird.

-(void)releaseSignoViewController

Anwendung:

[signoSigner releaseSignoViewController];

Methode scrollToPage:animationDuration

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

-(void)scrollToPage:(int)pageNr animationDuration:(double)animationDuration

Anwendung:

[signoVC scrollToPage:3 animationDuration:0.3];

Methode scrollToSearchResult:withHighlightColor:

Diese Methode ermöglicht zwischen den zuvor durch die Methode hervorgehobenen Suchergebnissen zu navigieren.

-(void)scrollToSearchResult()direction withHighlightColor:(UIColor*)highlightColor

Anwendung:

[signoVC scrollToSearchResult:SearchDirectionNext withHighlightColor:[UIColor redColor]];

Methode startNotesModeWithConfig:

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, weil diese keine Transparenz unterstützen. Mithilfe der Methoden und lässt sich überprüfen, ob der Notizen-Modus erfolgreich gestartet wurde oder aufgrund bestimmter Bedingungen fehlgeschlagen ist.

-(void)startNotesModeWithConfig:(STNotesConfig*)notesConfig

Anwendung:

STNotesConfig* notesConfig = [[STNotesConfig alloc] init];
notesConfig.strokeWidth = 3.0;
notesConfig.strokeColor = [UIColor redColor];
[signoVC startModeWithConfig: notesConfig];

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:

[signoVC 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. Mithilfe der Methoden und lässt sich überprüfen, ob die Notizen erfolgreich gespeichert wurden oder ob der Speichervorgang fehlgeschlagen ist.

-(void)saveAndFinishNotesMode

Anwendung:

[signoVC saveAndFinishNotesMode];

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 = [[STNotesConfig alloc] init];
notesConfig.strokeWidth = 3.0;
notesConfig.strokeColor = [UIColor greenColor];
[signoVC 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:

[signoVC 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 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:

[signoVC redoNote];

Methoden currentLockedOrientationMask

Liefert die aktuell gültige Orientierungsmaske.

Signatur

- (UIInterfaceOrientationMask)currentLockedOrientationMask;

Rückgabewert

Beschreibung

Bei aktivem Lock wird ausschließlich die zum Lock-Zeitpunkt aktive Orientierung zurückgegeben, sodass die App diese beibehält. Ohne Lock wird die Standardmaske (AllButUpsideDown) verwendet.

Beispiel (Swift)

let mask = signoViewController.currentLockedOrientationMask()

syncOrientationLockToApp

Synchronisiert den aktuellen Orientierungszustand mit der App.

Signatur

- (void)syncOrientationLockToApp;

Rückgabewert

Kein Rückgabewert.

Beschreibung

Setzt die globale Orientierungsmaske und erzwingt eine sofortige Aktualisierung im System (inklusive UIWindowScene Geometry Update ab iOS 16). Dadurch wird die App bei aktivem Lock in der aktuellen Orientierung gehalten bzw. bei deaktiviertem Lock wieder freigegeben.

Beispiel (Swift)

signoViewController.syncOrientationLockToApp()

Erforderliche Anpassungen in der App

Damit die Orientierungssteuerung wirksam wird, sind in der einbindenden App die folgenden Ergänzungen erforderlich.

1. UIView-Extension (Synchronisation mit der App)

Synchronisiert den Orientierungszustand des Signatur-Controllers mit der gesamten App. Setzt die globale Orientierungsmaske und erzwingt eine sofortige Aktualisierung im System (inklusive Geometry Update ab iOS 16). Bei aktivem Lock bleibt die App in der aktuellen Orientierung, bei deaktiviertem Lock wird das normale Rotationsverhalten wiederhergestellt.

import UIKit

@objc extension STSignoViewController {

    @objc func syncOrientationLockToApp() {
        let mask = currentLockedOrientationMask()

        STSignoVCOrientationLock.shared.lockedMask = mask
        STSignoVCOrientationLock.shared.isLocked = (mask != .allButUpsideDown)

        if #available(iOS 16.0, *) {
            if let windowScene = view.window?.windowScene {
                let preferences = UIWindowScene.GeometryPreferences.iOS(
                    interfaceOrientations: mask
                )
                try? windowScene.requestGeometryUpdate(preferences)
            }

            setNeedsUpdateOfSupportedInterfaceOrientations()
            navigationController?.setNeedsUpdateOfSupportedInterfaceOrientations()
        } else {
            UIViewController.attemptRotationToDeviceOrientation()
        }
    }
}

2. Globale Zustandsklasse

Globaler Zustand für die Orientierungssteuerung der App. Diese Klasse dient als zentrale Quelle für den aktuellen Orientation-Lock:

• isLocked gibt an, ob die Orientierung eingefroren ist.

• lockedMask definiert die erlaubte Orientierung.

Sie wird vom AppDelegate abgefragt, um die unterstützten Orientierungen der gesamten App dynamisch zu steuern.

import UIKit

final class STSignoVCOrientationLock {
    static let shared = STSignoVCOrientationLock()

    private init() {}

    var isLocked: Bool = false
    var lockedMask: UIInterfaceOrientationMask = .allButUpsideDown
}

3. AppDelegate-Erweiterung

Liefert die aktuell erlaubten Orientierungen der App. Bei aktivem Orientation-Lock wird ausschließlich die gespeicherte Orientierungsmaske zurückgegeben, sodass die App in dieser Orientierung bleibt. Ohne Lock werden die Standard-Orientierungen (allButUpsideDown) verwendet.

func application(
    _ application: UIApplication,
    supportedInterfaceOrientationsFor window: UIWindow?
) -> UIInterfaceOrientationMask {
    if STSignoVCOrientationLock.shared.isLocked {
        return STSignoVCOrientationLock.shared.lockedMask
    }
    return .allButUpsideDown
}

<key>UIRequiresFullScreen</key>
<true/>