PSPDFDocumentEditor

Objective-C


@interface PSPDFDocumentEditor : NSObject <PSPDFOverridable>

Swift

class PDFDocumentEditor : NSObject, Overridable

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

Note

This class requires the Document Editor component to be enabled for your license.

  • Starts an editing session on the document or a new blank editing session.

    Warning

    Document editing is currently only supported for documents that contain no annotations or have all annotations embedded in the PDF file. Other annotation providers are not yet supported.

    Declaration

    Objective-C

    - (nullable instancetype)initWithDocument:(nullable PSPDFDocument *)document;

    Swift

    init?(document: Document?)

    Parameters

    document

    The document used to initialize the document editor or nil. If nil, the document editor is initialized with zero pages. If a document is used, it must be a valid document. The changes won’t be visible on the document until the document editor is saved.

  • Creates a document editor without a document. Use this to create a new document from scratch.

    Note

    You need to add at least one page before saving with saveToPath:withCompletionBlock:. An empty document has 0 pages, which does not constitute a valid PDF document.

    See

    initWithDocument:

    Declaration

    Objective-C

    - (nonnull instancetype)init;

    Swift

    convenience init()

  • Reference to the backing document. Will never be nil if initWithDocument: with a document was used.

    See

    initWithDocument:

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) PSPDFDocument *document;

    Swift

    var document: Document? { get }

  • Allows you to set security options for saving.

    Declaration

    Objective-C

    @property (nonatomic, nullable) PSPDFDocumentSecurityOptions *securityOptions;

    Swift

    var securityOptions: Document.SecurityOptions? { get set }

  • Adds a document editor delegate to the subscriber list.

    Note

    Delegates are weakly retained, but be a good citizen and manually deregister.

    Declaration

    Objective-C

    - (void)addDelegate:(nonnull id<PSPDFDocumentEditorDelegate>)delegate;

    Swift

    func add(_ delegate: PDFDocumentEditorDelegate)

  • Removes a document editor delegate from the subscriber list.

    Declaration

    Objective-C

    - (BOOL)removeDelegate:(nonnull id<PSPDFDocumentEditorDelegate>)delegate;

    Swift

    func remove(_ delegate: PDFDocumentEditorDelegate) -> Bool

Page info

  • Returns the page count of the edited Document. If you remove or add pages, this will reflect that change.

    Declaration

    Objective-C

    @property (nonatomic, readonly) PSPDFPageCount pageCount;

    Swift

    var pageCount: PageCount { get }

  • Returns the page size, already rotated.

    Declaration

    Objective-C

    - (CGSize)pageSizeForPageAtIndex:(PSPDFPageIndex)pageIndex;

    Swift

    func pageSizeForPage(at pageIndex: PageIndex) -> CGSize

Operations

  • Uses the given configuration to insert multiple pages in the specified range at once.

    As this is an insertion, any pages in the document at or after the range.location are moved back by range.length to make room for the new pages. As a side effect, this behavior disqualifies use of this method for the purpose of duplicating and modifying a page of the receiver’s document. If this is your goal, please use duplicatePages: and the appropriate modification calls instead, or (if you absolutely must) make a copy of the document in order to create a suitable PSPDFNewPageConfiguration.

    Note

    If called inside an edition group (see -[PSPDFDocumentEditor groupUpdates:completion:]), the delegates are not going to be called and the return value will be an empty array.

    Note

    If the document editor is used to drive a UI (e.g, a UICollectionView), you should call this method on the main thread and apply the resulting changes (or perform a refresh) to your UI immediately after the method returns. This will ensure that the UI state and the document editor model representation are always in sync.

    Declaration

    Objective-C

    - (nonnull NSArray<PSPDFEditingChange *> *)
      addPagesInRange:(NSRange)range
    withConfiguration:(nonnull PSPDFNewPageConfiguration *)configuration;

    Swift

    func addPages(in range: NSRange, with configuration: PDFNewPageConfiguration) -> [PDFEditingChange]

    Parameters

    range

    The range in which the new pages should be added. The provided range’s location must be within bounds of the document’s page count.
    configuration

    The configuration used to create each one of the new pages.

    Return Value

    Array of PSPDFEditingChange objects describing the changes performed by this method.

  • Aggregates all the changes made by the actions inside the block, applies them as a single action, and notifies the delegates.

    Call updatesCompletedBlock when you’re done describing the updates to be performed.

    Declaration

    Objective-C

    - (void)groupUpdates:(nonnull void (^)(void (^_Nonnull)(BOOL)))updateBlock;

    Swift

    func groupUpdates(_ updateBlock: @escaping (@escaping (Bool) -> Void) -> Void)

    Parameters

    updateBlock

    Block that groups all the actions to be performed by the editor.

  • Combines all editing actions inside updateBlock into one.

    Call updatesCompletedBlock when you’re done describing the updates to be performed.

    Note

    If a completionBlock is provided the editor’s delegates are not going to be called, and the aggregated updates will be delivered on the completion block.

    Note

    If this method is called from within a group, the completion block is not going to be called.

    Declaration

    Objective-C

    - (void)groupUpdates:(nonnull void (^)(void (^_Nonnull)(BOOL)))updateBlock
          completion:
              (nullable void (^)(NSArray<PSPDFEditingChange *> *_Nonnull))
                  completionBlock;

    Swift

    func groupUpdates(_ updateBlock: @escaping (@escaping (Bool) -> Void) -> Void, completion completionBlock: (([PDFEditingChange]) -> Void)? = nil)

    Parameters

    updateBlock

    Block that groups all the actions to be performed by the editor.
    completionBlock

    Block to be executed when the editor finishes the changes. Parameter is a list of PSPDFEditingChange.

  • Moves pages at the given page indexes to a new page index.

    Note

    If called inside an edition group (see -[PSPDFDocumentEditor groupUpdates:completion:]), returns an empty array and the delegates are not called.

    Note

    If the document editor is used to drive a UI (e.g, a UICollectionView), you should call this method on the main thread and apply the resulting changes (or perform a refresh) to your UI immediately after the method returns. This will ensure that the UI state and the document editor model representation are always in sync.

    Declaration

    Objective-C

    - (nonnull NSArray<PSPDFEditingChange *> *)
    movePages:(nonnull NSIndexSet *)pageIndexes
           to:(PSPDFPageIndex)destination;

    Swift

    func movePages(_ pageIndexes: IndexSet, to destination: PageIndex) -> [PDFEditingChange]

  • Removes pages at the given page indexes.

    Note

    If called inside an edition group (see -[PSPDFDocumentEditor groupUpdates:completion:]), returns an empty array and the delegates are not called.

    Note

    If the document editor is used to drive a UI (e.g, a UICollectionView), you should call this method on the main thread and apply the resulting changes (or perform a refresh) to your UI immediately after the method returns. This will ensure that the UI state and the document editor model representation are always in sync.

    Declaration

    Objective-C

    - (nonnull NSArray<PSPDFEditingChange *> *)removePages:
    (nonnull NSIndexSet *)pageIndexes;

    Swift

    func removePages(_ pageIndexes: IndexSet) -> [PDFEditingChange]

  • Duplicates pages at the given page indexes. The duplicated pages will be inserted exactly after the original page.

    Note

    If called inside an edition group (see -[PSPDFDocumentEditor groupUpdates:completion:]), returns an empty array and the delegates are not called.

    Note

    If the document editor is used to drive a UI (e.g, a UICollectionView), you should call this method on the main thread and apply the resulting changes (or perform a refresh) to your UI immediately after the method returns. This will ensure that the UI state and the document editor model representation are always in sync.

    Declaration

    Objective-C

    - (nonnull NSArray<PSPDFEditingChange *> *)duplicatePages:
    (nonnull NSIndexSet *)pageIndexes;

    Swift

    func duplicatePages(_ pageIndexes: IndexSet) -> [PDFEditingChange]

  • Rotates the pages with the given page indexes. Rotation can be 0, 90, 180 and 270. Clockwise and counter-clockwise (depending on the sign). The rotation is added to the current page rotation value.

    Note

    If called inside an edition group (see -[PSPDFDocumentEditor groupUpdates:completion:]), returns an empty array and the delegates are not called.

    Note

    If the document editor is used to drive a UI (e.g, a UICollectionView), you should call this method on the main thread and apply the resulting changes (or perform a refresh) to your UI immediately after the method returns. This will ensure that the UI state and the document editor model representation are always in sync.

    Declaration

    Objective-C

    - (nonnull NSArray<PSPDFEditingChange *> *)rotatePages:
                                               (nonnull NSIndexSet *)pageIndexes
                                              rotation:(NSInteger)rotation;

    Swift

    func rotatePages(_ pageIndexes: IndexSet, rotation: Int) -> [PDFEditingChange]

  • Returns the rotation value for the page at the given index.

    Rotation can be 0, 90, 180 and 270. Clockwise (positive sign) and counter-clockwise (negative sign).

    Declaration

    Objective-C

    - (NSInteger)rotationForPageAtIndex:(PSPDFPageIndex)pageIndex;

    Swift

    func rotationForPage(at pageIndex: PageIndex) -> Int

Undo / redo

  • Undoes the last action and returns the changes’ descriptions.

    Note

    If the document editor is used to drive a UI (e.g, a UICollectionView), you should call this method on the main thread and apply the resulting changes (or perform a refresh) to your UI immediately after the method returns. This will ensure that the UI state and the document editor model representation are always in sync.

    Declaration

    Objective-C

    - (nullable NSArray<PSPDFEditingChange *> *)undo;

    Swift

    func undo() -> [PDFEditingChange]?

  • Redo the last undo and returns information about what changed.

    Note

    If the document editor is used to drive a UI (e.g, a UICollectionView), you should call this method on the main thread and apply the resulting changes (or perform a refresh) to your UI immediately after the method returns. This will ensure that the UI state and the document editor model representation are always in sync.

    Declaration

    Objective-C

    - (nullable NSArray<PSPDFEditingChange *> *)redo;

    Swift

    func redo() -> [PDFEditingChange]?

  • Checks if you can redo.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL canRedo;

    Swift

    var canRedo: Bool { get }

  • Checks if you can undo.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL canUndo;

    Swift

    var canUndo: Bool { get }

  • Discards all changes and clears the undo and redo stack. Calls documentEditor:didPerformChanges: with a nil `changes array.

    Note

    Any cached state on the caller side should be reset after calling this.

    Declaration

    Objective-C

    - (void)reset;

    Swift

    func reset()

Save

  • Specifies if it is possible to overwrite the PDF file represented by document by invokingsave().

    Returns true if the document is backed by a single document provider with a valid and writable file path or a data sink.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL canSave;

    Swift

    var canSave: Bool { get }

  • Overwrites the document PDF file and clears the document caches.

    Note

    If the Document referenced by document is currently displayed on a PDFViewController, you should call -[PDFViewController reloadData] after saving.

    Warning

    Don’t make any assumptions about the execution context of block. Can be called on a background queue.

    See

    canSave

    Declaration

    Objective-C

    - (void)saveWithCompletionBlock:(nullable PSPDFDocumentEditorSaveBlock)block;

    Swift

    func save(completionBlock block: PSPDFDocumentEditorSaveBlock? = nil)

    Parameters

    block

    If successful, returns a reference to the current document with cleared caches. Otherwise an error will be available.

  • Saves the modified document to a new PDF file at path.

    Note

    This does not affect the Document referenced by document.

    Warning

    Don’t make any assumptions about the execution context of block. Can be called on a background queue.

    Declaration

    Objective-C

    - (void)saveToPath:(nonnull NSString *)path
    withCompletionBlock:(nullable PSPDFDocumentEditorSaveBlock)block;

    Swift

    func save(toPath path: String, withCompletionBlock block: PSPDFDocumentEditorSaveBlock? = nil)

    Parameters

    path

    The destination path for the new document. Should be a directory to which the application can write to.
    block

    If successful, returns a new document that is configured for the given path. Otherwise an error will be available.

  • Saves the modified document to a data sink.

    Note

    This does not affect the Document referenced by document.

    Warning

    Don’t make any assumptions about the execution context of block. Can be called on a background queue.

    Declaration

    Objective-C

    - (void)saveToDataSink:(nonnull id<PSPDFDataSink>)dataSink
    withCompletionBlock:(nullable PSPDFDocumentEditorSuccessBlock)block;

    Swift

    func save(to dataSink: DataSink, withCompletionBlock block: PSPDFDocumentEditorSuccessBlock? = nil)

    Parameters

    dataSink

    The destination data sink for the new document.
    block

    If successful, returns success of the write operation as boolean. Otherwise an error will be available.

Import and Export

  • Saves the pages listed in pageIndexes to a new PDF at path.

    Note

    This does not affect the Document referenced by document.

    Warning

    Don’t make any assumptions about the execution context of block. Can be called on a background queue.

    Declaration

    Objective-C

    - (void)exportPages:(nonnull NSIndexSet *)pageIndexes
                 toPath:(nonnull NSString *)path
    withCompletionBlock:(nullable PSPDFDocumentEditorSaveBlock)block;

    Swift

    func exportPages(_ pageIndexes: IndexSet, toPath path: String, withCompletionBlock block: PSPDFDocumentEditorSaveBlock? = nil)

    Parameters

    pageIndexes

    A set of indexes corresponding to pages that should copied to the new document. All indexes need to be bounded by pageCount.
    path

    The destination path for the new document. Should be a directory to which the application can write to.
    block

    If successful, returns a new document that is configured for the given path. Otherwise an error will be available.

  • Saves the pages listed in pageIndexes to a data sink.

    Note

    This does not affect the Document referenced by document.

    Warning

    Don’t make any assumptions about the execution context of block. Can be called on a background queue.

    Declaration

    Objective-C

    - (void)exportPages:(nonnull NSIndexSet *)pageIndexes
             toDataSink:(nonnull id<PSPDFDataSink>)dataSink
    withCompletionBlock:(nullable PSPDFDocumentEditorSuccessBlock)block;

    Swift

    func exportPages(_ pageIndexes: IndexSet, to dataSink: DataSink, withCompletionBlock block: PSPDFDocumentEditorSuccessBlock? = nil)

    Parameters

    pageIndexes

    A set of indexes corresponding to pages that should copied to the new document. All indexes need to be bounded by pageCount.
    dataSink

    The destination data sink for the new document.
    block

    If successful, returns success of the write operation as boolean. Otherwise an error will be available.

  • Imports pages from a given document into the currently edited document and returns a progress.

    As with any other document editor changes, the added pages are not preserved until a document editor save is invoked. The provided documents will be copied internally and preserved until a save is invoked or the document editor gets deallocated.

    Note

    If called inside an edition group (see -[PSPDFDocumentEditor groupUpdates:completion:]), the delegates are not going to be called and the first parameter on the completion block will be an empty array.

    Note

    If the document editor is used to drive a UI (e.g, a UICollectionView), you should use the main queue as the queue parameter of this method (or pass in nil). Use the completion block or delegate calls to apply the resulting changes (or perform a refresh). This will ensure that the UI state and the document editor model representation are always in sync.

    Declaration

    Objective-C

    - (nonnull NSProgress *)importPagesTo:(PSPDFPageIndex)index
                         fromDocument:(nonnull PSPDFDocument *)sourceDocument
                  withCompletionBlock:
                      (nullable PSPDFDocumentEditorImportBlock)block
                                queue:(nullable dispatch_queue_t)queue;

    Swift

    func importPages(to index: PageIndex, from sourceDocument: Document, withCompletionBlock block: PSPDFDocumentEditorImportBlock?, queue: DispatchQueue?) -> Progress

    Parameters

    index

    The insertion index for the new sourceDocument pages amongst the current pages.
    sourceDocument

    The source document. Needs to be a fileURL backed Document.
    block

    A optional block, called when the import completes. Invoked on the provided queue.
    queue

    The queue that should be used to invoke the block and delegate calls on. If nil, the main queue will be used.

Rendering

  • Returns the rendered page as an UIImage with custom scale.

    Declaration

    Objective-C

    - (nullable NSImage *)imageForPageAtIndex:(PSPDFPageIndex)pageIndex
                                     size:(CGSize)size
                                    scale:(CGFloat)scale;

    Swift

    func imageForPage(at pageIndex: PageIndex, size: CGSize, scale: CGFloat) -> NSImage?