PSPDFDocumentFeatures

Objective-C


@interface PSPDFDocumentFeatures : NSObject <PSPDFDocumentFeaturesSource>

Swift

class PDFDocumentFeatures : NSObject, PDFDocumentFeaturesSource

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 Document‘s features property. So if you, for example, want to check if a document can be modified, you can check document.features.canModify.

See

-[PSPDFDocument features]

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.

  • 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

  • Initializes a document feature for a given document.

    Usually you do not initialize this yourself but instead use the features provided to you by the document, but you can create your own instance of this if you like.

    Declaration

    Objective-C

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

    Swift

    init(document: PSPDFDocument)

    Parameters

    document

    The document this features set is created for.

    Return Value

    A newly initialized document features object, ready to be queried for features.

  • The document this class was initialized with.

    Declaration

    Objective-C

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

    Swift

    weak var document: PSPDFDocument? { get }

Managing Custom Sources

  • Adds custom sources to the document features. These sources will be taken into account for all features they implement.

    Declaration

    Objective-C

    - (void)addSources:(nonnull NSArray<id<PSPDFDocumentFeaturesSource>> *)sources;

    Swift

    func add(_ sources: [PDFDocumentFeaturesSource])

    Parameters

    sources

    The sources to add to the list of sources.

  • Removes custom sources from the document features.

    Declaration

    Objective-C

    - (void)removeSources:
    (nonnull NSArray<id<PSPDFDocumentFeaturesSource>> *)sources;

    Swift

    func remove(_ sources: [PDFDocumentFeaturesSource])

    Parameters

    sources

    Sources to remove from the list of sources.

  • Updates the cache of the states of features.

    If you add a custom source and the state of a feature changes in this source, you must call updateFeatures on the features object assigned to the source to tell it that a feature changed. Otherwise this change might not be reflected in the value returned when checking the state of a feature.

    Declaration

    Objective-C

    - (void)updateFeatures;

    Swift

    func update()

Observing Features

  • Add an observer for the given feature. Each time the feature’s value changes the update handler is invoked.

    You should retain the returned observer to be able to remove the observer again later. Alternatively you can bind the observer to the lifetime of an object by calling bindToObjectLifetime on it. Doing neither of these will result in an observer that is not removable and that will continue calling your update handler until the receiver itself gets deallocated.

    Note

    You can only add observers for features that don’t require any arguments.

    Warning

    Modifying observers inside an update handler will result in a deadlock.

    Declaration

    Objective-C

    - (nonnull id<PSPDFDocumentFeaturesObserver>)
    addObserverForFeature:(nonnull PSPDFDocumentFeature)feature
            updateHandler:(nonnull void (^)(BOOL))handler;

    Swift

    func addObserver(forFeature feature: PSPDFDocumentFeature, updateHandler handler: @escaping (Bool) -> Void) -> PDFDocumentFeaturesObserver

    Parameters

    feature

    The feature to observe.
    handler

    The handler to be called when the feature’s state changes.

    Return Value

    An observer object you can use to unregister the observer again.

  • Removes an observer previously added through addObserverForFeature:updateHandler:.

    Declaration

    Objective-C

    - (void)removeObserver:(nonnull id<PSPDFDocumentFeaturesObserver>)observer;

    Swift

    func remove(_ observer: PDFDocumentFeaturesObserver)

    Parameters

    observer

    The observer to remove.

Debugging

  • Outputs in the console which sources allow or disallow the feature passed in.

    Note

    This only works for features that do not require any arguments.

    Declaration

    Objective-C

    - (void)traceFeature:(nonnull SEL)selector;

    Swift

    func traceFeature(_ selector: Selector)

    Parameters

    selector

    The selector you would call to access this feature.