PDF Annotations#

Annotations#

Annotations includes functionality for drawing, text markup and placing objects on a PDF document.

App Kit provides the following sets:

Note

You should not set annotation modes on a document until the document has loaded, therefore ensure to add any API calls for annotation methods after listening for the document loaded event.

Document Drawing Annotations#

Document text annotations depend on a “Drawing Annotation Mode” being activated. The following API allows for control over setting this mode.

Setting the Drawing Annotation Mode#

This is as simple as setting the annotating mode to a given “Drawing Annotation Mode” type on your MuPDFDKBasicDocumentViewController instance. To turn off the mode set the annotating mode to MuPDFDKAnnotatingMode_None.

Drawing mode enumeration#

Mode

Description

MuPDFDKAnnotatingMode_Ink

Freehand ink

MuPDFDKAnnotatingMode_Line

Line

MuPDFDKAnnotatingMode_Square

Squares & Rectangles

MuPDFDKAnnotatingMode_Circle

Circles & Ovals

MuPDFDKAnnotatingMode_Polygon

Polygon

MuPDFDKAnnotatingMode_PolyLine

Polyline

The following code toggles the freehand ink drawing mode on and off and might serve as the handler for one of the buttons in your UI.

if basicDocVc.annotatingMode == MuPDFDKAnnotatingMode_Ink {
    basicDocVc.annotatingMode = MuPDFDKAnnotatingMode_None
} else {
    basicDocVc.annotatingMode = MuPDFDKAnnotatingMode_Ink
}

When a “Drawing Annotation Mode” is disabled, the annotation is saved to the document.

Styling Drawing Annotations#

Drawing annotations can be styled as follows:

Opacity#

To set & get annotation opacity, access the annotationOpacity value as a Float.

basicDocVc.annotationOpacity = 1.0

Line Thickness#

To set & get line thickness, access the annotationStrokeThickness value as a CGFloat.

basicDocVc.annotationStrokeThickness = 10

Line Color#

To set & get line color, access the annotationStrokeColor value as a UIColor.

basicDocVc.annotationStrokeColor = .green

Line Endings#

Line endings are only supported for the MuPDFDKAnnotatingMode_Line annotation. They can be set & get by accessing the annotationLineHeadStyle & annotationLineTailStyle properties.

basicDocVc.annotationLineHeadStyle = ARDKLineEndStyle_Circle
basicDocVc.annotationLineTailStyle = ARDKLineEndStyle_ClosedArrow

Line ending enumeration#

Style

Description

ARDKLineEndStyle_None

None

ARDKLineEndStyle_Butt

Butt

ARDKLineEndStyle_Slash

Slash

ARDKLineEndStyle_Circle

Cirle

ARDKLineEndStyle_Diamond

Diamond

ARDKLineEndStyle_OpenArrow

Open arrow

ARDKLineEndStyle_ROpenArrow

Right pointing open arrow

ARDKLineEndStyle_Square

Square

ARDKLineEndStyle_ClosedArrow

Closed arrow

ARDKLineEndStyle_RClosedArrow

Right pointing closed arrow

Document Text Annotations#

Document text annotations depend on a “Text Annotation Mode” being activated. The following API allows for control over setting this mode.

Setting the Text Annotation Mode#

This is as simple as setting the annotating mode to a given “Text Annotation Mode” type on your MuPDFDKBasicDocumentViewController instance. To turn off the mode set the annotating mode to MuPDFDKAnnotatingMode_None.

Text mode enumeration#

mode

Description

MuPDFDKAnnotatingMode_HighlightTextSelect

Highlight text

MuPDFDKAnnotatingMode_UnderlineTextSelect

Underline text

MuPDFDKAnnotatingMode_SquiggleTextSelect

Squiggle text

MuPDFDKAnnotatingMode_StrikethroughTextSelect

Strikethrough text

When a “Text Annotation Mode” is active, the user can select text and apply the text annotations accordingly.

Document Placement Annotations#

Document text annotations depend on a “Placement Annotation Mode” being activated. The following API allows for control over setting this mode.

Setting the Placement Annotation Mode#

This is as simple as setting the annotating mode to a given “Placement Annotation Mode” type on your MuPDFDKBasicDocumentViewController instance. To turn off the mode set the annotating mode to MuPDFDKAnnotatingMode_None.

Placement mode enumeration#

mode

Description

MuPDFDKAnnotatingMode_Note

Note

MuPDFDKAnnotatingMode_FreeText

Free text

MuPDFDKAnnotatingMode_Stamp

Stamp

MuPDFDKAnnotatingMode_FileAttachment

File attachment

MuPDFDKAnnotatingMode_Link

Link

When a “Placement Annotation Mode” is active, the user can tap on the document to create the placement annotation. In-built UI will then handle the anootation creation and manipulation.

Getting the Annotation Mode#

Access the annotatingMode variable on your MuPDFDKBasicDocumentViewController instance to find out the current mode.

let mode:MuPDFDKAnnotatingMode = documentViewController.annotatingMode

De-selecting Annotations#

Essentially all annotations are treated the same as simply selections once they have been selected by a user. This selection can then be cleared (de-selected) by calling the clearSelection() method against the MuPDFDKDoc instance within MuPDFDKBasicDocumentViewController.

let myDoc:MuPDFDKDoc? = basicDocVc?.session.doc as! MuPDFDKDoc
myDoc?.clearSelection()

Without an annotation being currently selected, calling clearSelection() will have no effect.

Deleting Annotations#

Selections can be removed (deleted) by calling the deleteSelectedAnnotation() method against the MuPDFDKDoc instance within MuPDFDKBasicDocumentViewController.

func deleteDocumentSelection() {
    let myDoc:MuPDFDKDoc? = basicDocVc?.session.doc as! MuPDFDKDoc
    myDoc?.deleteSelectedAnnotation()
}

Without an annotation being currently selected, calling deleteSelectedAnnotation() will have no effect.

Author#

To set the author name for subsequent annotation creations, an application developer should set the documentAuthor property to the required string value within the MuPDFDKDoc instance.

func setAuthor(name:String) {
    let myDoc:MuPDFDKDoc? = basicDocVc?.session.doc as! MuPDFDKDoc
    myDoc?.documentAuthor = name
}

Targetting Document Areas#

Sometimes in order to focus an annotation, or to suggest an area to annotate, a developer may wish to highlight areas in a document and/or jump to a specific area of interest in a document. There are two API calls available to assist with this.

Outlining an Area#

To draw outlines on a document page use outlineArea.

basicDocVc.session.doc.outlineArea(<rect>, onPage: <page>)

Showing an Area#

To show an area on a document page use showArea.

basicDocVc.showArea(<rect>, onPage: <page>)
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.Discord logo