Document API#
Delegates#
When developing your own custom UI, your application’s ViewController should, at a minimum, implement the ARDKBasicDocViewDelegate and ARDKDocumentEventTarget protocols to intercept events.
ARDKBasicDocViewDelegate#
Document Completed#
Called when the document has completely loaded.
/// Inform the UI that both the loading of the document
/// and the initial rendering have completed. An app might
/// display a busy indicator while a document is initially
/// loading, and use this delegate method to dismiss the
/// indicator.
func loadingAndFirstRenderComplete() {
}
/// Inform the UI that both the loading of the document
/// and the initial rendering have completed. An app might
/// display a busy indicator while a document is initially
/// loading, and use this delegate method to dismiss the
/// indicator.
- (void)loadingAndFirstRenderComplete {
}
UI Update#
Called when the document changes selection state and the UI should update appropriately.
/// Tell the UI to update according to changes in the
/// selection state of the document. This allows an app
/// to refresh any currently displayed state information.
/// E.g., a button used to toggle whether the currently
/// selected text is bold, may show a highlight to indicate
/// bold or not. This call would be the appropriate place to
/// ensure that highlight reflects the current state.
func updateUI() {
}
/// Tell the UI to update according to changes in the
/// selection state of the document. This allows an app
/// to refresh any currently displayed state information.
/// E.g., a button used to toggle whether the currently
/// selected text is bold, may show a highlight to indicate
/// bold or not. This call would be the appropriate place to
/// ensure that highlight reflects the current state.
- (void)updateUI {
}
Detecting Page Movement#
The following method is called when the document is moved - i.e. on pan or zoom events.
/// Tell the UI that the view of the document has moved. This
/// may be called very frequently if the document is scrolling,
/// and can be used to keep UI elements positioned next to items
/// within the document, such as the current selection.
func viewDidMove() {
}
/// Tell the UI that the view of the document has moved. This
/// may be called very frequently if the document is scrolling,
/// and can be used to keep UI elements positioned next to items
/// within the document, such as the current selection.
- (void)viewDidMove {
}
Page Change#
Called on a page change event - i.e. when the document has scrolled or jumped to another page.
/// Tell the UI that the document has scrolled to a new page.
/// An app may use this to update a label showing the current
/// displayed page number or to scroll a view of thumbnails
/// to the correct page.
func viewDidScroll(toPage page: Int) {
}
/// Tell the UI that the document has scrolled to a new page.
/// An app may use this to update a label showing the current
/// displayed page number or to scroll a view of thumbnails
/// to the correct page.
- (void)viewDidScrollToPage:(NSInteger)page {
}
Scrolling Completed#
Called when a user scrolling event has concluded it’s animation.
/// Tell the delegate when a scrolling animation concludes.
/// This can be used like viewDidScrollToPage, but for more
/// intensive tasks that one wouldn't want to run repeatedly
/// during scrolling.
func scrollViewDidEndScrollingAnimation() {
}
/// Tell the delegate when a scrolling animation concludes.
/// This can be used like viewDidScrollToPage, but for more
/// intensive tasks that one wouldn't want to run repeatedly
/// during scrolling.
- (void)scrollViewDidEndScrollingAnimation {
}
Swallowing Tap Selections#
An application developer has the ability to intercept tap events on the document to prevent a default selection from occurring. To do this the following delegate methods need to return false. Essentially a document is in a read only state in this mode.
/// Offer the UI the opportunity to swallow a tap that
/// may have otherwise caused selection. Return YES
/// to swallow the event. This is not called for taps
/// over links or form fields. An app might use this to
/// provide a way out of a special mode (full-screen for
/// example). In that case, if the app is using the tap to
/// provoke exit from full-screen mode, then it would return
/// YES from this method to avoid the tap being interpreted
/// also by the main document view.
func swallowSelectionTap() -> Bool {
return false
}
/// Offer the UI the opportunity to swallow a double tap that
/// may have otherwise caused selection. Return YES to swallow
/// the event. This is not called for double taps over links
/// or form fields. An app might use this in a way similar to
/// that appropriate to swallowSelectionTap.
func swallowSelectionDoubleTap() -> Bool {
return false
}
/// Offer the UI the opportunity to swallow a tap that
/// may have otherwise caused selection. Return YES
/// to swallow the event. This is not called for taps
/// over links or form fields. An app might use this to
/// provide a way out of a special mode (full-screen for
/// example). In that case, if the app is using the tap to
/// provoke exit from full-screen mode, then it would return
/// YES from this method to avoid the tap being interpreted
/// also by the main document view.
- (BOOL)swallowSelectionTap {
return NO;
}
/// Offer the UI the opportunity to swallow a double tap that
/// may have otherwise caused selection. Return YES to swallow
/// the event. This is not called for double taps over links
/// or form fields. An app might use this in a way similar to
/// that appropriate to swallowSelectionTap.
- (BOOL)swallowSelectionDoubleTap {
return NO;
}
Note
It is important that these delegate methods return true by default for expected text and annotation selection behaviour to occur.
Inhibiting the Keyboard#
If required an application developer can prevent the keyboard from appearing.
/// Called to allow the delegate to inhibit the keyboard. An app
/// might use this in special modes where there is limited
/// vertical space, so as to avoid the keyboard appearing.
func inhibitKeyBoard() -> Bool {
return false
}
/// Called to allow the delegate to inhibit the keyboard. An app
/// might use this in special modes where there is limited
/// vertical space, so as to avoid the keyboard appearing.
- (BOOL)inhibitKeyBoard {
return NO;
}
Opening a URL#
This method is called when the document interaction invokes a URL to open.
/// The document view calls this when
/// a link to an external document is tapped.
func callOpenUrlHandler(_ url: URL!, fromVC presentingView: UIViewController!) {
}
/// The document view calls this when
/// a link to an external document is tapped.
- (void)callOpenUrlHandler:(NSURL *)url fromVC:(UIViewController *)presentingView {
}
ARDKDocumentEventTarget#
Page Load Events and Loading Complete#
Called as pages are loaded from the document.
/// Called as pages are loaded from the document.
/// There may be further calls, e.g., if pages
/// are added or deleted from the document.
func updatePageCount(_ pageCount: Int, andLoadingComplete complete: Bool) {
}
/// Called as pages are loaded from the document.
/// There may be further calls, e.g., if pages
/// are added or deleted from the document.
- (void)updatePageCount:(NSInteger)pageCount andLoadingComplete:(BOOL)complete {
}
Called when layout has completed.
func layoutHasCompleted() {
}
- (void)layoutHasCompleted {
}
Called when the page size changes.
func pageSizeHasChanged() {
}
- (void)pageSizeHasChanged {
}
Selection Changes#
Called when a selection is made within the document, moved or removed.
func selectionHasChanged() {
}
// there is also a function method which can be
// associated against the instance of `MuPDFDKDoc` as follows
doc.onSelectionChanged = {
}
- (void)selectionHasChanged {
}
// there is also a function method which can be
// associated against the instance of `MuPDFDKDoc` as follows
doc.onSelectionChanged = ^() {
};
Selection Types#
Once a selection has been made on a document it might be necessary to understand what type of selection it is and if there is any further data. For example, is the user’s selection a redaction annotation or is it a note annotation? Does the selected annotation have a date associated with it?
To determine this information, the following type of query against the document instance (MuPDFDKDoc) can be made:
let selectionIsRedaction:Bool = doc.selectionIsRedaction
let selectionIsNote:Bool = doc.selectionIsAnnotationWithText
let selectedAnnotationsDate:Date? = doc.selectedAnnotationsDate
let haveTextSelection:Bool = doc.haveTextSelection
BOOL selectionIsRedaction = doc.selectionIsRedaction;
BOOL selectionIsNote = doc.selectionIsAnnotationWithText;
NSDate* selectedAnnotationsDate = doc.selectedAnnotationsDate;
BOOL haveTextSelection = doc.haveTextSelection;
The following table defines the full set of available selections:
| Variable name | Type | Description | Return type |
|---|---|---|---|
| selectionIsWidget | form widget | Whether a form widget is currently selected | Bool |
| selectedAnnotationsText | text | The text string associated with the selected annotation | String or nil |
| selectedAnnotationsDate | date | The date associated with the selected annotation | Date or nil |
| selectedAnnotationsAuthor | author | The author of the selected annotation | String or nil |
| selectionIsRedaction | redaction | Whether a redaction annotation is selected | Bool |
| selectionIsStamp | stamp | Whether a stamp annotation is selected | Bool |
| selectionIsTextHighlight | highlight | Whether a text highlight annotation is selected | Bool |
| selectionIsAnnotationWithText | note | Whether an annotation that has text is selected | Bool |
| haveTextSelection | text | Whether text is currently selected | Bool |
| haveAnnotationSelection | any | Whether an annotation is currently selected | Bool |
ARDKPageSelectorDelegate#
Select Page#
Called when the document page selector selects a page.
func selectPage(_ page: Int) {
}
-(void) selectPage:(NSInteger)page {
}
Delete Page#
Called when the document page selector deletes a page.
func deletePage(_ page: Int) {
}
-(void) deletePage:(NSInteger)page {
}
Duplicate Page#
Called when the document page selector duplicates a page.
func duplicatePage(_ page: Int) {
}
-(void) duplicatePage:(NSInteger)page {
}
Move Page#
Called when the document page selector moves a page.
func movePage(_ page: Int, to newPos: Int) {
}
- (void)movePage:(NSInteger)pageNumber to:(NSInteger)newNumber {
}
Listeners#
Document Load#
An application developer can listen for basic success or error for a document load.
When a document load is requested, the following function blocks can be defined for the document (i.e. the instance of MuPDFDKDoc).
doc.successBlock = {
}
doc.errorBlock = {(error:ARDKDocErrorType?) in
}
doc.successBlock = ^() {
};
doc.errorBlock = ^(ARDKDocErrorType error) {
};
Request Password#
For documents which may be password protected a developer should set a method against the document session to be triggered on the event of a password protected file attempting to load.
session.passwordRequestBlock = {[weak self] in
}
session.passwordRequestBlock = ^{
};
Typically the passwordRequestBlock implementation should offer a way which allows the user to input a document password. When your implementation is ready the providePassword API call should be made. If the password is correct then the document will display, if incorrect then your application should handle the failure.
doc.providePassword("password")
[doc providePassword:@"password"];
Document actions#
Undo#
To undo a previous action (such as adding an annotation) use the the following method against your document instance.
if doc.canUndo {
doc.undo()
}
if (doc.canUndo) {
[doc undo];
}
Redo#
To redo a previous action (such as adding an annotation) use the the following method against your document instance.
if doc.canRedo {
doc.redo()
}
if (doc.canRedo) {
[doc redo];
}
Get Selected Text#
If the document has selected text (i.e. PDF document text which the user has selected) then this text can be read by your application with the selectedText method.
doc.selectedText({ text in
print("text=\(text)")
})
[doc selectedText:^(NSString *text) {
NSLog(@"text=%@",text);
}];
Note
Typically an application will want to copy the text value to the pasteboard.
This software is provided AS-IS with no warranty, either express or implied. This software is distributed under license and may not be copied, modified or distributed except as expressly authorized under the terms of that license. Refer to licensing information at artifex.com or contact Artifex Software, Inc., 39 Mesa Street, Suite 108A, San Francisco, CA 94129, USA, for further information.
