signoAPI iOS – STSignoViewController class

The STSignoViewController class is the core of the libSignoPDFSigner. This class is used for displaying and editing PDF documents. The STSignoViewController 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. The STSignoViewController class currently supports only the value UIModalPresentationFullScreen for the modalPresentationStyle property. All properties and methods of the STSignoSigner class also belong to the STSignoViewController class. Only the additionally contained properties and methods are listed below.

@interface STSignoViewController : UIViewController

Usage:

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

Or

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

signatureCaptureVC property

This property contains the instance of the STSignatureCaptureViewController used to capture the signature. The instance itself cannot be set or changed, but its properties and methods can be used.

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

Usage:

signoVC.signatureCaptureVC.signCaptureDelegate = self;

toolbarHeight property

This property contains the height of the toolbar and thus also defines the upper border of the document viewer. The elements within the toolbar are always displayed at the bottom edge of the toolbar. This property can therefore prevent an overlap between these elements and the elements of the iOS status bar. This property needs to be set before the loadDocumentFromFile method is called.

@property (nonatomic, assign) NSInteger toolbarHeight

Usage:

signoVC.toolbarHeight = 50;

showToolbar property

This property defines whether or not the toolbar is to be displayed. This property needs to be set before the loadDocumentFromFile method is called.

The toolbar currently contains the following four buttons:

• ‘Back’: Calls -[STSignoInfoDelegate backButtonPressed].

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

• ‘Signature fields’: Calls -[STSignoInfoDelegate signatureInfoPressed] and displays a dialog with the document’s signature fields, if there are any.

• ‘Save’: Calls -[STSignoInfoDelegate documentSaved].

@property (nonatomic, assign) BOOL showToolbar

Usage:

signoVC.showToolbar = NO;

enableAutoRotation property

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

@property (nonatomic, assign) BOOL enableAutoRotation

Usage:

signoVC.enableAutoRotation = YES;

showPageNumber property

This property can be used to configure whether the page number is displayed in the PDF viewer.

@property (nonatomic, assign) BOOL showPageNumber

Usage:

signoVC.showPageNumber = YES;

signatureCaptureConfig property

This property contains the instance of the STSignatureCaptureConfig, whose properties can be used to configure the signature dialog.

@property (nonatomic, strong) STSignatureCaptureConfig* signatureCaptureConfig

Usage:

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;

setPhotoFieldNames:maxWidth:maxHeight: method

This method can be used to define the names of the form fields that are intended to be used for taking photos. The form fields that are defined in this way will no longer behave as normal form fields. Instead, when touched, they activate the device’s camera so that the user can take a photo. The photo that is taken will then be inserted and displayed at the position of the form field. By touching the field again, the user can replace the photo – unless the field has been set to ‘read only’.

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

Usage:

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

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 touching a signature field in the document.

-(void)startSignature

-(void)startSignature:(NSString*)signatureFieldName

Usage:

[signoVC startSignature:@"customer_signature"];

scrollToFormField:withFocus: method

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

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

Usage:

[signoVC scrollToFormField:formField withFocus:focus];

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 [STSignoInfoDelegate viewerRectCancelled:] method. Tapping the confirmation button calls the [STSignoInfoDelegate viewerRectConfirmed:inPage:viewerRectId] 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 = [STViewerRectDTO alloc] init];
int rectViewId = [signoVC createViewerRect: rectViewerDTO];

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 -[STSignoViewController startTextSearch:inPage:highlightColor:onlyWholeWord:caseSensitive] method, from the PDF viewer.

-(void)finishTextSearch

Usage:

[signoVC finishTextSearch];

enableTouchEvents: method

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

-(void)enableTouchEvents:(BOOL)enable

Usage:

[signoVC enableTouchEvents:YES];

releaseSignoViewController method

This method can be used to release the generated instance of the STSignoViewController class. It should always be called when an instance is no longer needed.

-(void)releaseSignoViewController

Usage:

[signoSigner releaseSignoViewController];

scrollToPage:animationDuration method

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

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

Usage:

[signoVC scrollToPage:3 animationDuration:0.3];

scrollToSearchResult:withHighlightColor: method

This method allows you to navigate between the search results previously highlighted by the -[STSignoSigner startTextSearch:inPage:highlightColor:primaryColor:onlyWholeWord:caseSensitive] method.

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

Usage:

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

startNotesModeWithConfig: 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. Note mode does not work with PDF/A-1b documents because they do not support transparency. The -[STSignoInfoDelegate notesModeDidStartSuccessfully] and -[STSignoInfoDelegate notesModeDidFailToStart:] methods can be used to check whether the notes mode was started successfully or failed due to certain conditions.

-(void)startNotesModeWithConfig:(STNotesConfig*)notesConfig

Usage:

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

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:

[signoVC 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. The -[STSignoInfoDelegate notesModeDidFinishWithSavedStatus:] and -[STSignoInfoDelegate notesModeDidFinishWithFailure:] methods can be used to check whether the notes were saved successfully or whether the saving process failed.

-(void)saveAndFinishNotesMode

Usage:

[signoVC saveAndFinishNotesMode];

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

[signoVC 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 -[STSignoViewController undoNote]. This method is only available when notes mode is active and has no effect if no note has been undone.

-(void)redoNote

Usage:

[signoVC redoNote];

currentLockedOrientationMask method

Returns the currently valid orientation mask.

Signature

- (UIInterfaceOrientationMask)currentLockedOrientationMask;

Return value

Description

When the lock is active, only the orientation that was active at the time the lock was set is returned, so that the app retains it. Without a lock, the default mask (AllButUpsideDown) is used.

Example (Swift)

let mask = signoViewController.currentLockedOrientationMask()

syncOrientationLockToApp method

Synchronises the current orientation state with the app.

Signature

- (void)syncOrientationLockToApp;

Return value

No return value.

Description

Sets the global orientation mask and forces an immediate update in the system (including the UIWindowScene Geometry Update from iOS 16). As a result, when the lock is active, the app is kept in its current orientation; when the lock is deactivated, it is released again.

Example (Swift)

signoViewController.syncOrientationLockToApp()

Required adjustments in the app

For the orientation control to take effect, the following additions are required in the integrating app.

1. UIView extension (synchronisation with the app)

Synchronises the orientation state of the signature controller with the entire app. Sets the global orientation mask and forces an immediate update in the system (including the Geometry Update from iOS 16). When the lock is active, the app remains in its current orientation; when the lock is deactivated, normal rotation behaviour is restored.

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. Global state class

Global state for the app’s orientation control. This class serves as the central source for the current orientation lock:

• isLocked indicates whether the orientation is frozen.

• lockedMask defines the permitted orientation.

It is queried by the AppDelegate to dynamically control the supported orientations of the entire app.

import UIKit

final class STSignoVCOrientationLock {
    static let shared = STSignoVCOrientationLock()

    private init() {}

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

3. AppDelegate extension

Returns the app’s currently permitted orientations. When the orientation lock is active, only the stored orientation mask is returned, so that the app remains in that orientation. Without a lock, the default orientations (allButUpsideDown) are used.

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

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