PSPDFAnnotationPlaceholder
Objective-C
@interface PSPDFAnnotationPlaceholder : NSObject
Swift
class AnnotationPlaceholder : NSObject
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 placeholder 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.
Note
Important: In the context ofPSPDFAnnotationPlaceholder
, cancellation is considered an
error. It will be signaled by an NSUserCancelled
error in combination with state “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
.
-
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
-
The current state of the receiver — KVO observable.
Declaration
Objective-C
@property (readonly) PSPDFAnnotationPlaceholderState placeholderState;
Swift
var placeholderState: PSPDFAnnotationPlaceholderState { get }
-
The progress towards replacing the receiver with actual content —
nil
unless it is progressing.See
placeholderStateDeclaration
Objective-C
@property (readonly, nullable) NSProgress *progress;
Swift
var progress: Progress? { get }
-
The error that caused replacing the receiver with actual content to fail —
nil
unless it failed.See
placeholderStateDeclaration
Objective-C
@property (readonly, nullable) NSError *error;
Swift
var error: Error? { get }
-
The localized name of the appropriate action to take when interacting with the receiver.
This KVO observable property is updated whenever the
placeholderState
changes. Will be nil if no action has been configured for the current state.Declaration
Objective-C
@property (readonly, nullable) NSString *localizedAction;
Swift
var localizedAction: String? { get }
-
Tells an idle placeholder that the actual content should be retrieved.
This method has no effect if the placeholder is in any other state than
PSPDFAnnotationPlaceholderStateIdle
. If the placeholder is idle, it will transition to state progressing or failed.Note
The caller should not make any assumption on when the transition away from the idle state is completed! -
Asks a progressing placeholder to cancel the ongoing resolution, and provide a suitable replacement for a new resolution attempt at a later time.
Will return
nil
if the receiver is not in statePSPDFAnnotationPlaceholderStateProgressing
, or no suitable replacement could be provided. Otherwise, it will return a suitable replacement inPSPDFAnnotationPlaceholderStateIdle
.Declaration
Objective-C
- (nullable PSPDFAnnotationPlaceholder *)cancelResolution: (NSError *_Nullable *_Nullable)error;
Swift
func cancelResolution() throws -> AnnotationPlaceholder
-
Asks a failed placeholder to provide a suitable replacement for a new resolution attempt at a later time.
Will return
nil
if the receiver is not in statePSPDFAnnotationPlaceholderStateFailed
, or no suitable replacement could be provided. Otherwise, it will return a suitable replacement object that has already begun to resolve the actual content.Declaration
Objective-C
- (nullable PSPDFAnnotationPlaceholder *)replacementForReattemptingResolution: (NSError *_Nullable *_Nullable)error;
Swift
func replacementForReattemptingResolution() throws -> AnnotationPlaceholder