This class allows a transparent decryption of AES256 encrypted files using the RNCryptor file format https://github.com/RNCryptor/RNCryptor-Spec/blob/master/RNCryptor-Spec-v3.md

Legacy PSPDFKit old file format is also supported. Use the provided encryption tool to prepare your documents.

Ensure your passphrase/salt are also protected within the binary, or at least obfuscated. Encryption marginally slows down rendering, since everything is decrypted on the fly.

If saving annotations to a file managed by a PSPDFAESCryptoDataProvider, the whole file will be re-written.

The data sink that works with PSPDFAESCryptoDataProvider

AES encryption, RNCryptor data format (see https://github.com/RNCryptor/RNCryptor-Spec/blob/master/RNCryptor-Spec-v3.md )

AES decryption, RNCryptor data format (see https://github.com/RNCryptor/RNCryptor-Spec/blob/master/RNCryptor-Spec-v3.md )

Undocumented

Base class for Line, Polygon and PolyLine annotations.

Undocumented

Defines an action that is defined in the PDF spec, either from an outline or an annotation object. See the Adobe PDF Specification for more about actions and action types.

Initialize with PSPDFDocument object as activityItems or directly with title/URL/NSData.

This is a PSPDFKit provided PSPDFAnalyticsClient implementation that dispatches events to all registered clients. Events are dispatched on a background queue.

PSPDFAnnotation is the base class for all PDF annotations and forms.

Don’t directly make an instance of this class, use subclasses like PSPDFNoteAnnotation or PSPDFLinkAnnotation. This class will return nil if initialized directly, unless with the type PSPDFAnnotationTypeUndefined.

PSPDFAnnotationManager searches the runtime for subclasses of PSPDFAnnotation and builds up a dictionary using supportedTypes.

Annotation properties are specified in normalized PDF coordinates: they take page rotation and CropBox offset into account. Prior to PSPDFKit 8 for iOS and PSPDFKit 3 for macOS properties were specified in PDF coordinates: not taking the page rotation and offset into account. After unarchiving annotations from NSCoder archives created with older versions of PSPDFKit, the properties will be untransformed, and will be modified to apply the page transform when the annotation is added to a document.

Annotations contain internal state once they are attached to a document. Don’t take them and add them to another document. Instead, create a new annotation and set the properties relevant for you, and add this annotation.

A PSPDFAnnotationAppearanceStream manages an image to include as part of an annotation appearance (ie. a handwritten signature). Supported filetypes are .JPG and .PDF. For PDF files, the first page of the document is used.

Displays information about an annotation.

Allows saving/loading of stored annotations. Annotations are stored securely in the keychain.

Used to configure custom annotation groups for the annotation toolbar.

[[PSPDFAnnotationToolbarConfiguration alloc] initWithAnnotationGroups:@[

[PSPDFAnnotationGroup groupWithItems:@[
[PSPDFAnnotationGroupItem itemWithType:PSPDFAnnotationStringInk variant:PSPDFAnnotationVariantStringInkPen
configurationBlock:[PSPDFAnnotationGroupItem inkConfigurationBlock]]]],

[PSPDFAnnotationGroup groupWithItems:@[
[PSPDFAnnotationGroupItem itemWithType:PSPDFAnnotationStringLine],
[PSPDFAnnotationGroupItem itemWithType:PSPDFAnnotationStringPolyLine]]]
]];

An annotation group items defines one annotation type, optionally with a variant.

Collects annotations from the various PSPDFAnnotationProvider implementations.

Usually you want to add your custom PSPDFAnnotationProvider instead of subclassing this class. If you subclass, use overrideClass:withClass: in PSPDFDocument.

This class will set the documentProvider on both annotation adding and retrieving. You don’t have to handle this in your annotationProvider subclass.

A fully KVO observable stand in for actual annotation content that is loaded on demand.

Custom annotation providers may need to resolve certain annotation types using external sources. Instant, for example, only loads image annotations separately from the document and other annotations on demand, thus giving users the quickest possible time to display and sync, without sacrificing high fidelity for high bandwidth media.

This, however, requires a mechanism to display placeholder content for annotations whose media is not readily available. PSPDFAnnotationPlaceholder fulfills that role by offering a state machine that tracks the process towards replacing a suitable placehoöder with the actual content.

States and Allowed Transitions

Each annotation placeholder starts in an idle state. Any PSPDFAnnotationPresenting view that implements the annotationPlaceholder property can use that object’s content to display a suitable placeholder until the actual content has become available.

In order to provide feedback as to when the actual content will be available, it can observe the placeholder’s placeholderState, which will change to “progressing” or “failed” when the process of providing the actual content starts or has failed.

While the actual content for the placeholder instance is loaded, the object remains in state “progressing” until the process completes — which results in a transition to state “completed” — or fails — which results in a transition to state “failed”. Both of these states are final, meaning there will not be any further state transitions.

Upon transition to state “completed”, any PSPDFAnnotationPresenting view tracking a placeholder should dispose of the object, and use its new content property instead.

Upon transition to state “failed”, any such view should update based on the placeholder object’s error, which (in many cases) will provide a localizedRecoverySuggestion, alongside a recoveryAttempter.

An annotation set may be used to add and position multiple annotations.

Annotation Set cell, displays an annotation set.

Shows multiple annotation sets within a table cell.

PSPDFAnnotationStateManager holds the current annotation state and configures the associated PSPDFViewController to accept input related to the currently selected annotation state. The class also provides several convenience methods and user interface components required for annotation creation and configuration.

Interested parties can use KVO to observe the manager’s properties.

You should never use more than one PSPDFAnnotationStateManager for any given PSPDFViewController. It’s recommended to use -[PSPDFViewController annotationStateManager] instead of creating your own one in order to make sure this requirement is always met.

PSPDFAnnotationStateManager is internally used by PSPDFAnnotationToolbar and can be re-used for any custom annotation related user interfaces.

Defines an annotation style.

The default implementation for the style manager.

An inspector that allows users to view and change the properties of annotations.

Produces a summary of the annotations in a document.

Shows an overview of all annotations in the current document.

The annotation toolbar allows the creation of most annotation types supported by PSPDFKit.

To customize which annotation icons should be displayed, edit editableAnnotationTypes in PSPDFDocument. Further appearance customization options are documented in the superclass header (PSPDFFlexibleToolbar.h).

PSPDFAnnotationToolbar needs to be used together with a PSPDFFlexibleToolbarContainerView just like its superclass PSPDFFlexibleToolbar.

Specifies a list the toolbar annotation items and their grouping. The PSPDFAnnotationToolbar accepts multiple configurations and will use the most matching one.

Helper for showing/hiding the toolbar on a view controller. Internally manages a PSPDFFlexibleToolbarContainer.

Generic annotation view that listens on annotation changes.

Advanced appearance characteristics for a widget annotation. It contains additional information for constructing the annotation’s appearance stream

Coordinates appearance mode changes.

On iOS versions prior to iOS 13, this class will update the PDF page rendering style, as well as the UI appearance of certain UI widgets when transitioning in and out of the dark interface style.

On iOS 13 and later the this class will only change the PDF page rendering style. Any UI appearance changes should be instead handled by the host application via the delegate methods this class offers.

Allows the user to enable and disable the Apple Pencil.

Tracks the state of use of the Apple Pencil.

This class should not be instantiated manually but fetched from the PSPDFKitGlobal shared object.

Default implementation that forwards calls to the app delegate.

Default extension implementation that interacts and requires an NSExtensionContext to work.

The default security auditor simply returns YES for every request.

Abstract subclass that contains an asset from a link

Scroll view subclass that listens to keyboard and half modal events and moves itself up accordingly.

Keeps track of executed Action instances, allowing us to navigate through the action history.

Back and forward buttons, used for the action stack navigation.

Used for various configuration options.

Base class for building a configuration object.

Abstract class for a controller that manages a table view. Adds support for hardware keyboard navigation, and automatically sizing popovers to fit the table view contents.

Undocumented

A PSPDFSignatureContents instance that returns zeroed data.

A bookmark encapsulates a PDF action and a name. It is managed by a document’s bookmark manager.

Undocumented

Custom cell used for bookmarks.

Custom UIButton that sets the appropriate bookmark image based on imageType, and applies a shadow as well. The image will always have a tint applied to it, based on the normalTintColor and selectedTintColor properties These colors can be customised using regular UIAppearance APIs. To customise the appearance even further, your can use the custom image loading API to change the images.

The PSPDFBookmarkManager manages bookmarks for a given PSPDFDocument.

You should not initialize a bookmark manager yourself but instead access it through the document’s bookmarkManager property.

Bookmarks and PDF files

The concept of bookmarks does not exist in a PDF document. Therefore all the bookmarks you add will be stored inside the PDF but are only read by PSPDFKit and Apple Preview. If you want to support other formats, you need to create your own bookmark provider and store them yourself.

Subclassing

You should not subclass PSPDFBookmarkManager. Instead attach a custom bookmark provider to achieve your desired behavior.

Thread Safety

PSPDFBookmarkManager is thread safe and can be accessed from any thread. To ensure multiple operations are executed as one serial block without other threads interfering, wrap you operations in performBlock: or performBlockAndWait: whenever you need to do complex operations.

However, if you need to do something that can be achieved by calling a single method on this class (e.g. adding a bookmark or removing a known bookmark), call the appropriate method directly as it is more performant than wrapping calls in the above mentioned block calls.

Show list of bookmarks for the current document and allows editing/reordering of the bookmarks.

PSPDFBrightnessManager can be used to manage the screen idle timer.

Controller to change the brightness and some related appearance options. In addition to mimicking the system brightness options it also supports additional software dimming and social appearance modes.

A collection of useful extensions to UIButton.

Button Form Element (check boxes, radio buttons, regular form push buttons)

Buttons / choice form views.

Represents one button form field in a PDF form. They come in three variants:

• A push button that can have a action attached to it.
• A check box that can be independently checked or unchecked.
• A radio button that are mutually exclusive.

A PSPDFButtonFormField can be the parent of multiple buttons, like a RadioButton group.

The PSPDFCache is responsible for managing the memory and disk cache of rendered images.

Usually you do not access any methods of PSPDFCache directly but instead schedule a PSPDFRenderTask in a PSPDFRenderQueue which will then reach out to the cache and check if there are images available before rendering a new one.

A caret annotation (PDF 1.5) is a visual symbol that indicates the presence of text edits, and share much similarity with note (text) annotations.

Displays a view controller to offer selecting a signer for digitally signing a document.

Choice Form Element.

Undocumented

Represents a choice form field in a PDF form. This allows the user to select one of the given options or, if isEdit is YES, enter their own option value.

The PDF Circle annotations (PDF 1.3) shall display an ellipse on the page.

A view that is suitable to display a (sticky) filtering interface for a collection view.

Button that shows a selected color. Highlightable.

A color patch represents a single patch of colors in the UI. It contains of one or multiple colors that should be grouped together.

A color palette is a set of color patches that are grouped together based on a specific look or theme.

The factory used to create color pickers. Subclass this to customize your color pickers.

Model class used to define custom color presets.

The configuration builder object offers all properties of PSPDFConfiguration in a writable version, in order to build an immutable PSPDFConfiguration object.

A PSPDFConfiguration defines the behavior of a PSPDFViewController. It uses the builder pattern via PSPDFConfigurationBuilder to create an immutable copy via a block.

Handles conflict resolution UI presentation in response to a PSPDFDocumentUnderlyingFileChangedNotification. Invokes the delegate to perform the selected conflict resolution option when done.

Default container for annotations. It’s crucial that you use this class as your base class if you implement a custom annotation provider, because this class offers efficient undo/redo which otherwise is almost impossible to replicate unless you understand the PSPDFKit internals extremely well.

This class conforms to the deprecated protocol PSPDFAnnotationProviderRefreshing. In a future release, this protocol will be removed. The reason is that this class handles refreshing internally. This class will continue to conform to PSPDFAnnotationProvider.

A container view cannot draw content in itself.

It uses a CATransformLayer as backing. This allows blend mode pass-through, and is more lightweight than a regular view.

Similar to UITabBarController but using a segmented control at the top to switch between child view controllers.

Undocumented

PSPDFConversionOperation is the base class for all PDF conversion operations.

Operation that converts a website or local URL to PDF. Needs to be executed from background thread.

Operation that converts a HTML string to PDF. Needs to be executed from background thread.

Operation that converts an attributed string to PDF. Needs to be executed from background thread.

Operation that converts a local Office document to PDF by sending it to a server.

An implementation of PSPDFDataProviding that acts upon a file. All file access is coordinated with file coordination (NSFileCoordinator). This class implements the optional conflict resolution methods of PSPDFCoordinatedFileDataProviding.

Undocumented

Undocumented

Simple class that encrypts/decrypts files in a format compatible to PSPDFAESCryptoDataProvider.

An implementation of PSPDFDataProviding that operates on a single NSData.

This may be used to initialize PSPDFDocument with data.

If you use NSData because of encryption, look into PSPDFAESCryptoDataProvider or a custom implementation of PSPDFDataProviding instead for a way to dynamically decrypt the needed portions of the PDF.

A PSPDFDataSink that works with PSPDFDataContainerProvider.

The digital signature coordinator handles signing and presenting a digitally signed document. Signing a document with a certificate creates a readonly copy, as the file has to be completely re-written.

Register your subclass via overrideClass:withClass: on the configuration object. Don’t instantiate an object of this class yourself.

Represents a possible destination directory.

The disk cache persists its metadata on disk together with the images and provides cached images even after the app restarts.

The disk cache is designed to store and fetch images, including metadata, in a fast way. No actual images will be held in memory (besides during the time they are scheduled for writing to disk).

The PSPDFDocument class represents a set of PDF sources that are displayed as one document.

The PDF sources are internally represented as data providers (implementations of the PSPDFDataProviding protocol). The typical use case is to initialize the document with a single fileURL, which creates an implicit PSPDFCoordinatedFileDataProvider by default. You can also opt to use NSData or custom implementations of PSPDFDataProviding as sources during initialization.

This object can be created on any thread. Accessing properties is thread safe but might take some time, as the underlying PDF documents need to be processed to fetch data like pageCount or title. The document builds an internal cache, so subsequent access is faster. For this reason, ensure that document objects are not created/destroyed randomly for maximum efficiency.

PSPDFDocument supports NSFastEnumeration by enumerating over its documentProviders. The document providers are internal wrappers around the data providers created during initialization.

A checkpointer handles autosaving of annotations for recovery in case of a crash that occurs without saving. A checkpoint is a small file that contains all the changes made to the document that haven’t been saved. The checkpoint is created according to the strategy. On a save of the document, it is automatically deleted.

Manages document editing. Supports operations such as remove, move, rotate and add page.

The thumbnail cell class used for the document editor.

Undocumented

Configuration options for various document editor controllers.

Represents a page size option for new pages.

Define a compression used for image compression.

A flexible toolbar with various document editing functions.

Manages the document editor toolbar state and presents various document editing controllers.

The main view controller for document editing. Shows a collection view with page thumbnails that reflect the document editor changes. Selection is performed on this object and the selection state is then forwarded to toolbarController.

PSPDFDocumentFeatures provides the main interface for querying features and registering observers.

It conforms to PSPDFDocumentFeaturesSource itself, but additionally to the document features source protocol it also guarantees that it implements all methods of this protocol. Therefore it is save to query every feature on an instance of this class without checking its availability for.

Usually you access this class through PSPDFDocument‘s features property. So if you, for example, want to check if a document can be modified, you can check document.features.canModify.

Threading

PSPDFDocumentFeatures is thread safe and can be used from any thread. This also means that your custom sources will be called from various threads and queues. Do not rely on being called on a particular thread in your custom sources.

Coordinates a common view controller for document metadata, such as outline, bookmarks or annotations.

Document Info View Controller.

Present and allows to edit the most common PDF Document properties (metadata). Changes are applied to the document automatically.

This class allows you to modify a PDF document’s metadata. Metadata is defined in two ways in the PDF spec (§ 14.3):

• The Info PDF dictionary. This class is handling this.
• A metadata stream containing XMP data. See PSPDFDocumentXMPMetadata for that. (https://en.wikipedia.org/wiki/Extensible_Metadata_Platform)

Info dictionary support

All values specified in the Info dictionary are represented by the following types:

• NSString
• NSNumber
• NSDate
• NSArray<id>: can include any of the types mentioned.
• NSDictionary<NSString*, id>: value can be any of the types mentioned.

These types can be combined in any way you see fit and it will be converted into the proper PDF types.

UITableViewCell subclass representing a document. Used in PSPDFDocumentPickerController.

Shows all documents available in the specified directory or the the documents set directly. By default this will enqueue all documents into the default PSPDFLibrary for FTS.

Uses a UISearchController internally.

Shows status of indexing while we’re indexing or searching.

A PSPDFDocument consists of one or multiple PSPDFDocumentProvider‘s. Each document provider has exactly one data source (file/data/dataProvider)

This class describes the security options you want to use when saving a PDF file. Using a security options object overrides the default options of a file.

A PDF file can have multiple security-related options set. The owner password generally controls the editing of a document and is required as soon as you want to encrypt a document of any kind. The user password prevents users from viewing the PDF. It is optional but if you specify it you also need to specify an owner password.

You can also specify the key length of the encryption. This controls how large the key is that is used for actually encrypting the document. The key is derived from the passwords you specify. As soon as you specify at least an owner password you also need to decide on a key length to be used. You can also specify PSPDFDocumentSecurityOptionsKeyLengthAutomatic in all cases and let PSPDFKit decide on if and what key length to use.

To specify what operations are allowed when opening the document with user privileges you can also set PSPDFDocumentPermissions. With user privileges you can always view the file in question and by specifying PSPDFDocumentPermissions you can grant further rights that otherwise would only be available when the user has owner privileges.

PSPDFKit supports two encryption algorithms: RC4 and AES. RC4 is a proprietary encryption algorithm of RSA Security Inc. It is a symmetric stream cipher, ie. the same algorithm is used for both encryption and decryption, and the algorithm does not change the length of the data. AES support was introduced with PDF 1.6. It is a symmetric block cipher, ie. the same algorithm is used for both encryption and decryption, and the length of the data when encrypted is rounded up to a multiple of the block size, which is fixed in this implementation to always be 16 bytes.

Document Security and Permissions View Controller.

Present and allows to edit the PDF Document permissions and passwords.

Undocumented

A PSPDFDocumentSharingConfiguration instance configures how the sharing view controller behaves, and what options it lets the user customize.

Displays an interface that allows the user to pick a set of options that determine how a set of PDF files should be processed before being shared to a destination. By default, the user can choose the file type, the page range, and how annotations should be handled.

Documents can be shared to different Destinations specified by the PSPDFDocumentSharingDestination enumeration. By default, the PSPDFDocumentSharingViewController will share toPSPDFDocumentSharingDestinationActivity, which will let the user pick the ultimate action for the generated documents via a UIActivityViewController instance (which can be customized via the -activityViewControllerForSharingItems:sender: method.).

A single PSPDFDocumentSharingViewController instance can offer multiple destinations to share the documents to to the user — they will be represented on a segmented control on the navigation bar of the sharing view controller. However, a Share can only be performed to a single destination at a time. To add Destinations to the list the user can choose from, create a PSPDFDocumentSharingConfiguration object and set the appropriate value on its builder’s destination property, then add that configuration to the sharingConfigurations property on the sharing view controller.

Please note that Destinations are exclusive per sharing view controller instance, so you can’t have 2 or more configurations with the same destination set.

Once the instance has been configured appropriately, call -presentFromViewController:sender: on it to present the UI.

The document view controller is the starting point for visualizing a document on screen. It groups all the UI that deals with showing documents on screen and controls the view hierarchy and the layout.

The Layout

The main way of controlling how a layout looks is through PSPDFDocumentViewLayout. While PSPDFKit provides you with a set of default layouts such as a continuous scrolling layout, a paginated scroll per spread layout and a curl based layout, layouts are meant to be fully customizable so you can adopt PSPDFKit to your design perfectly.

To customize a design you can start by changing properties on a design provided by PSPDFKit. If this is not enough, PSPDFDocumentViewLayout and its subclasses provide various levels of entry points to best fit what your desired outcome is.

You can either subclass PSPDFContinuousScrollingLayout or PSPDFScrollPerSpreadLayout if you want a layout similar to these two but only need a couple of tweaks. If you want to have more control but your layout still follows the general idea of a layout that scrolls in a single direction, either vertically or horizontally, PSPDFStackViewLayout, gives you a lot of control while covering the basics and a couple of convenience methods that make your life easier. This should be enough control for almost all designs. However if your design is very specific, we also give you the same base class all of our own layouts use: PSPDFDocumentViewLayout. With this layout you need to do everything on your own but there should be pretty much no limitations on what to do with it.

To get you started with implementing your own layout, check out the documentation for PSPDFDocumentViewLayout.

The Hierarchy

The document view hierarchy can be seen in the following diagram.

╔═══════════════════════════╗         ┌───────────────────────────┐
║  DocumentViewController   ║         │  PSPDFDocumentViewLayout  │
║                           ║────────▶│                           │
╚═══════════════════════════╝         └───────────────────────────┘
┌───────────────────────────┐
│       UIScrollView        │
│   (scrolling & zooming)   │◀───┐            Depending on
└───────────────────────────┘    │     spreadBasedZooming either
┌───────────────────────────┐    ├──── one of these scroll views
│       UIScrollView        │    │     is responsible for zooming
│         (zooming)         │◀───┘            the content.
└───────────────────────────┘
╔═══════════════════════════╗
║        SpreadView         ║
║                           ║
╚═══════════════════════════╝
╔═══════════════════════════╗
║         PageView          ║
║                           ║
╚═══════════════════════════╝

┌─────────────────────────────────────────────────────────────────┐
│               ─── Public, ═══ Public & Subclassable             │
└─────────────────────────────────────────────────────────────────┘

Continuous Spread Index

Usually you should prefer the integer based spreadIndex APIs. The spreadIndex is less complex and does the necessary conversion to the continuous spread index for you. However there are usecases where you need floating point precision for the current scrolling position.

The continuousSpreadIndex maps the spreads of the document on to the viewport in a size independent way. That means that no matter what size a spread is displayed on and also no matter what other spread sizes are already known of a document, the continuous spread index remains stable. E.g. a continuous spread index of 2.5 will always refer to the center of spread 2.

In the places where a continuous spread index is related to a certain position in the view hierarchy, it is related to the center of the current viewport. So if you call continuousSpreadIndex you will receive the continuous spread index that is currently shown at the center of the document view controller’s view.

If you implement your own custom layout and this layout does not build on top of PSPDFStackViewLayout, you may need to deal with the continuous spread index though and do calculations between the continuous spread index and the content offset yourself. For that it is important how the function of the continuous spread index looks. It is a monotonically increasing function over all spreads of a document. Its valid range is [0, spreadCount). Note that it is monotonically, but not strictly monotonically increasing. The spaces between spread are not considered to be a part of a spread, therefore in this area, the continuous spread index does not change. E.g. spread 2 has a range of [2, 3), then there is the interitem spacing between spread 2 and 3 where the continuous spread index is 3 and only when you start scrolling into spread 3, the continuous spread index starts increasing again in the range of [3, 4) for this spread.

3.0 ─│               ╱
     │              ╱
     │             ╱      This diagram shows how the continuous spread index
     │            ╱       is calculated over the spreads. In the gap between
2.0 ─│         ╱─╱        two spreads, the continuous spread index is not
     │        ╱           changing.
     │       ╱
     │      ╱             Inside each spread, the continuous spread index is
1.0 ─│   ╱─╱              linear in the range [i, i+1).
     │  ╱
     │ ╱
     │╱
     ╳────────────────
     ┌───┐ ┌───┐ ┌───┐
     │   │ │   │ │   │
     │ 0 │ │ 1 │ │ 2 │
     │   │ │   │ │   │
     └───┘ └───┘ └───┘

Undocumented

A document view layout controls how a document is visualized on screen. It controls where a spread (a set of pages) is placed on the screen and how scrolling and zooming behaves.

Subclassing

PSPDFDocumentViewLayout is an abstract base class meant for subclassing. You can either subclass PSPDFContinuousScrollingLayout or PSPDFScrollPerSpreadLayout if you want a layout similar to these two but only need a couple of tweaks. If you want to have more control but your layout still follows the general idea of a layout that scrolls in a single direction, either vertically or horizontally, PSPDFStackViewLayout, the superclass of the two aforementioned layouts, gives you a lot of control while covering the basics and a couple of convenience methods that make your life easier. This should be enough control for almost all designs. However if your design is very specific, we also give you the same base class all of our own layouts use: PSPDFDocumentViewLayout. With this layout you need to do everything on your own but there are almost no limitations on what to do with it.

Spreads

The main thing that a document view layout cares about is a spread; this is what it calculates the position of. A spread is a collection of pages that are always viewed together. If you have the most basic layout, a layout with its spread mode set to single, every spread corresponds to a single page in the document, which means the amount of spreads is equal to the amount of pages. However you can also have a double paged layout or a book layout. To convert between pages and spreads, PSPDFDocumentViewLayout provides you with helper methods. To make your layout work with all spread modes, it is important that you use these methods for conversion and, in case you want to implement your own spreading algorithms, override these methods and make them do the proper conversion, otherwise your layout may not work correctly in all cases.

UICollectionViewLayout

It is very important to keep in mind that a document view layout is based on UICollectionViewLayout and that this is what is used to calculate the position of a spread on the screen in the end. PSPDFDocumentViewLayout and especially its subclass PSPDFStackViewLayout offer you convenience methods that hide a lot of the complexity of collection views but depending on how the layout you are building should look, keep in mind that all the collection view layout methods can be used as well.

While the collection view layout works with index paths as its item identifying object, the document view layout does not need multiple levels of indexes. Each layout only needs to deal with one section. The important identifier for a document view layout is the spread index an item is representing. Therefore all the methods a PSPDFDocumentViewLayout and its subclasses offer refer to the spread index instead of an index path. For most layouts you will not come into contact with any of the index path based methods, but in case you do need them, PSPDFKit offers you two new methods on NSIndexPath to easily convert between index paths and spread indexes: +[NSIndexPath pspdf_indexPathForSpreadAtIndex:] and -[NSIndexPath pspdf_spreadIndex]. You should always use these methods to convert back and forth between spread indexes and index paths and not make any assumptions about how an index path maps to a spread index.

Additional APIs

Aside from the collection view layout, a document view layout also offers a few additional things that the document view controller and its views use to determine other behaviours, such as how zooming behaves (spreadBasedZooming), how spreads map to pages, and how the actual view hierarchy is positioned in relation to the view controller’s view (scrollViewFrameInsets).

Make sure to use the methods PSPDFDocumentViewLayout and its subclasses offer instead of just implementing everything by overriding the collection view layout methods. If you override one of the collection view layout methods, it is up to you to make sure that other methods such as spreadIndexForPageAtIndex:, pageRangeForSpreadAtIndex:, continuousSpreadIndexForContentOffset:, or contentOffsetForContinuousSpreadIndex: don’t return conflicting values or otherwise you might get unexpected results.

This class allows you to modify a PDF document’s metadata. Metadata is defined in two ways in the PDF spec (§ 14.3):

• A metadata stream containing XMP data. This class is handling this. (https://en.wikipedia.org/wiki/Extensible_Metadata_Platform)
• The Info PDF dictionary. See PSPDFDocumentPDFMetadata.

XMP support

This class implements limited XMP support. You can only set and retrieve simple strings.

Namespaces

Each key in the XMP metadata stream has to have a namespace set. You can define your own namespace or use one of the already existing ones. PSPDFKit exposes two constants for common namespaces:

• PSPDFXMPPDFNamespace/PSPDFXMPPDFNamespacePrefix: The XMP PDF namespace created by Adobe: https://www.adobe.com/content/dam/Adobe/en/devnet/xmp/pdfs/XMPSpecificationPart2.pdf §3.1
• PSPDFXMPDCNamespace/PSPDFXMPDCNamespacePrefix: The Dublin Core namespace: https://en.wikipedia.org/wiki/Dublin_Core

When setting a value, you also have to pass along a suggested namespace prefix, as this can’t be automatically generated.

Undocumented

This configuration builder offers all properties of PSPDFDragAndDropConfiguration in a writable version.

Used to configure various drag and drop options, on how and where it should work. Set the object you create here on PSPDFConfiguration.dragAndDropConfiguration.

PSPDFDrawView allows drawing or erasing on top of a PSPDFPageView and handles new annotation creation.

Unless otherwise noted, boxed points need to be of type PSPDFDrawingPoint.

The default appearance stream generator.

Calls -[PSPDFAnnotation drawInContext:options:] and transforms it into an appearance stream.

Represents a change that was performed by PSPDFDocumentEditor.

Represents an embedded file.

Undocumented

Shows a list of all embedded files.

An embedded go-to action (PDF 1.6) is similar to a remote go-to action but allows jumping to or from a PDF file that is embedded in another PDF file.

Draws a circle shape representing the user touch during erasing.

Undocumented

PDF File Attachment Annotation (see 12.5.6.15, “File attachment annotations”). A file attachment annotation (PDF 1.3) contains a reference to a file, which typically shall be embedded in the PDF file (see 7.11.4, “Embedded file streams”).

An implementation of the PSPDFAnnotationProvider protocol that uses the PDF document as source/target to load/save annotations. You almost always want to use the PSPDFFileAnnotationProvider in your PSPDFAnnotationManager. You can also use this class inside a custom annotation provider, to parse PDF annotations once and then manage them in your custom database.

An appearance stream generator that takes an NSURL to any PDF file and returns it as the appearance stream.

Custom appearance streams are only intended to be used with stamp annotations to create a vector stamp. Using this class with other annotation types is not supported.

An implementation of PSPDFDataProviding that acts upon a file.

A data sink backed by a file on disk

This class encapsulates the metadata associated with a document used in the PSPDFLibraryFileSystemDataSource

The default file manager implementation is a thin wrapper around NSFileManager.

Coordinates file presenters and notifications. Observed presenters are automatically unregistered in response to UIApplicationDidEnterBackgroundNotification notification.

A custom toolbar, that can dragged around the screen and anchored to different positions.

This class holds an array of UIButton objects. For best results use PSPDFToolbarButton or one of its subclasses. PSPDFFlexibleToolbar should be used in combination with a PSPDFFlexibleToolbarContainer instance. The bar’s visual appearance can be customized using UIAppearance compliant properties.

The flexible toolbar container holds and manages a PSPDFFlexibleToolbar instance. Its main responsibilities include toolbar anchoring and drag & drop handling. Add this view to your view hierarchy (a good candidate might be the UINavigationController’s view).

Undocumented

Toolbar drag & drop indicator view.

Font picker that allows the user to select a font and customize the style.

Represents a PDF form element.

Generic view for form elements. Adds the form accessory view and additional keyboard support. Form views are not synced with the page to allow snappier editing.

A form field represents one logical field in the PDF form. Use a PSPDFFormParser to retrieve them. You can access the form parser from a PSPDFDocument or PSPDFDocumentProvider.

Toolbar for Next|Previous controls for Form Elements.

Undocumented

Parses PDF Forms (“AcroForms”). This will not create objects based on the (soon deprecated) XFA standard.

Models a request to submit a form in a PDF document to a remove server.

Undocumented

Free Text accessory toolbar for faster styling.

PDF FreeText Annotation.

A free text annotation (PDF 1.3) displays text directly on the page. Unlike an ordinary text annotation (see 12.5.6.4, “Text Annotations”), a free text annotation has no open or closed state; instead of being displayed in a pop-up window, the text shall be always visible.

Free Text View. Allows inline text editing.

The gallery configuration builder object offers all properties of PSPDFGalleryConfiguration in a writable version, in order to build an immutable PSPDFGalleryConfiguration object.

A PSPDFGalleryConfiguration defines the behavior of a PSPDFGalleryViewController.

Undocumented

Undocumented

Used to group the error, loading and gallery view and to properly lay them out.

The caption view used in PSPDFGalleryContentCaptionView.

The (reusable) content view of a PSPDFGalleryView.

Undocumented

An image item in a gallery.

The abstract class for an item in a gallery. Most items will have content that needs to be loaded, hence this class allows for asynchronous state changes. It is the responsibility of the subclass to implement loading, for example by implementing the PSPDFRemoteContentObject protocol.

PSPDFGalleryManifest models the manifest file that is the data source of every gallery. It abstracts the task of loading an array of PSPDFGalleryItems from potentially multiple sources.

An item of unknown type in a gallery.

PSPDFGalleryVideoContentView displays a video item.

A video item in a gallery. This class uses the class cluster design pattern.

A gallery view works a lot like a UITableView. It has content views, which need to be provided by a data source and can be reused. It is built on top of a UIScrollView.

Handles a gallery of one or multiple images, videos, audio or even web content.

PSPDFGalleryWebContentView displays a web item.

A web item in a gallery.

Represents a single character (glyph, quad) on the PDF page.

Defines the action of going to a specific location within the PDF document.