PSPDFBookmarkManager

Objective-C


@interface PSPDFBookmarkManager : NSObject

Swift

class BookmarkManager : NSObject

The BookmarkManager manages bookmarks for a given Document.

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 BookmarkManager. Instead attach a custom bookmark provider to achieve your desired behavior.

Thread Safety

BookmarkManager 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.

  • Unavailable

    Not the designated initializer

    Undocumented

    Declaration

    Objective-C

    PSPDF_EMPTY_INIT_UNAVAILABLE

  • Unavailable

    Not the designated initializer

    Undocumented

    Declaration

    Objective-C

    PSPDF_EMPTY_INIT_UNAVAILABLE

  • Creates a new instance of the bookmark manager.

    This is the designated initializer.

    Note

    You should not create an instance of this class yourself. Instead access a document’s bookmark manager through -[PSPDFDocument bookmarkManager].

    Declaration

    Objective-C

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

    Swift

    init?(document: PSPDFDocument)

    Parameters

    document

    The document this bookmark manager should be attached to.

    Return Value

    A newly initialized instance of the receiver.

  • The document associated with this bookmark manager.

    Declaration

    Objective-C

    @property (nonatomic, weak, readonly) PSPDFDocument *_Nullable document;

    Swift

    weak var document: PSPDFDocument? { get }

Accessing Bookmarks

  • Contains the list of bookmarks that are currently owned by the receiver.

    Note

    The sort order of these bookmarks is undefined. If you want to retrieve bookmarks in a sorted order, use bookmarksWithSortOrder:.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly) NSArray<PSPDFBookmark *> *_Nonnull bookmarks;

    Swift

    var bookmarks: [PSPDFBookmark] { get }

  • Returns the list of bookmarks sorted in the specified sort order.

    See

    bookmarks

    Declaration

    Objective-C

    - (nonnull NSArray<PSPDFBookmark *> *)bookmarksWithSortOrder:
    (PSPDFBookmarkManagerSortOrder)sortOrder;

    Swift

    func bookmarks(with sortOrder: BookmarkManager.SortOrder) -> [PSPDFBookmark]

    Parameters

    sortOrder

    The sort order to use for the returned array.

    Return Value

    An array containing the bookmarks in the order of sortOrder.

Modifying Bookmarks

  • Adds a bookmark to the bookmark manager or updates an existing.

    Note

    To persist an update to the bookmarks you need to save the associated document.

    Declaration

    Objective-C

    - (void)addBookmark:(nonnull PSPDFBookmark *)bookmark;

    Swift

    func addBookmark(_ bookmark: PSPDFBookmark)

    Parameters

    bookmark

    The bookmark you want to add.

  • Removes a bookmark from the bookmark manager.

    Note

    To persist an update to the bookmarks you need to save the associated document.

    Declaration

    Objective-C

    - (void)removeBookmark:(nonnull PSPDFBookmark *)bookmark;

    Swift

    func removeBookmark(_ bookmark: PSPDFBookmark)

    Parameters

    bookmark

    The bookmark you want to remove.

  • Moves the bookmark at a given source index to the given destination index and adjusts the index of the bookmarks in between.

    Note

    This method only has an effect on the order of bookmarks that you retrieve by calling bookmarksWithSortOrder: using the PSPDFBookmarkManagerSortOrderCustom sort order. This method does not change the bookmarks array or the sorting of any other sort order.

    Declaration

    Objective-C

    - (void)moveBookmarkAtIndex:(NSUInteger)sourceIndex
                    toIndex:(NSUInteger)destinationIndex;

    Swift

    func moveBookmark(at sourceIndex: UInt, to destinationIndex: UInt)

    Parameters

    sourceIndex

    The current index of the bookmark.
    destinationIndex

    The index the bookmark should have after this operation.

Combining Multiple Operations

  • Schedules a block for asynchronous execution as a single serial operation on the bookmark manager and immediately returns.

    You can use this method if you need to make multiple operations on the same data set as a single operation. If, for example, you want to iterate over the bookmarks array, look for a specific bookmark and then remove it from the list, wrap your code in this method to ensure the underlying data does not change while you perform your operations.

    Note

    Chaining calls to this method is not allowed and will throw an exception.

    Warning

    This still does not guarantee an atomic operation! If one operation does fail for some reason, this method does not perform a roll back to the state at the beginning of this block!

    See

    performBlockAndWait:

    Declaration

    Objective-C

    - (void)performBlock:(nonnull void (^)(void))block;

    Swift

    func perform(_ block: @escaping () -> Void)

    Parameters

    block

    The block you want to perform.

  • Schedules a block for synchronous execution as a single serial operation on the bookmark manager and waits until the block returns.

    You can use this method if you need to make multiple operations on the same data set as a single operation. If, for example, you want to iterate over the bookmarks array, look for a specific bookmark and then remove it from the list, wrap your code in this method to ensure the underlying data does not change while you perform your operations.

    Note

    Chaining calls to this method is not allowed and will throw an exception.

    Warning

    This still does not guarantee an atomic operation! If one operation does fail for some reason, this method does not perform a roll back to the state at the beginning of this block!

    See

    performBlockAndWait:

    Declaration

    Objective-C

    - (void)performBlockAndWait:(nonnull void (^)(void))block;

    Swift

    func performBlockAndWait(_ block: @escaping () -> Void)

    Parameters

    block

    The block you want to perform.

Customizing Bookmark Providers

  • Contains the list of bookmark providers that is used to set and get bookmark data.

    Calls to the bookmark providers are made in the order of this array, first to last.

    Declaration

    Objective-C

    @property (nonatomic, copy) NSArray<id<PSPDFBookmarkProvider>> *_Nonnull provider;

GoToAction