public interface

AnnotationProvider

com.pspdfkit.annotations.AnnotationProvider
Known Indirect Subclasses

Class Overview

Handles all annotation related operations on the owning document. Retrieve it with getAnnotationProvider().

Summary

Nested Classes
interface AnnotationProvider.OnAnnotationUpdatedListener Listener for annotation update events inside AnnotationProvider. 
Fields
public static final EnumSet<AnnotationType> ALL_ANNOTATION_TYPES All annotation types that can displayed in the annotation list.
Public Methods
abstract void addAnnotationToPage(Annotation annotation)
Adds annotation to the owner PDF document.
abstract void addAnnotationToPage(Annotation annotation, int zIndex)
Adds annotation to the owner PDF document at the specified z-index.
abstract Completable addAnnotationToPageAsync(Annotation annotation, int zIndex)
Adds annotation to the owner PDF document asynchronously, at the specified z-index.
abstract Completable addAnnotationToPageAsync(Annotation annotation)
Adds annotation to the owner PDF document asynchronously.
abstract void addAppearanceStreamGenerator(AppearanceStreamGenerator appearanceStreamGenerator)
Adds appearance stream generator to the list of global appearance stream generators.
abstract void addAppearanceStreamGenerator(AppearanceStreamGenerator appearanceStreamGenerator, boolean addFirst)
Adds appearance stream generator to the list of global appearance stream generators.
abstract void addOnAnnotationUpdatedListener(AnnotationProvider.OnAnnotationUpdatedListener updatedListener)
Adds an AnnotationProvider.OnAnnotationUpdatedListener for being notified of updates to annotations.
abstract void appendAnnotationState(Annotation annotation, AnnotationStateChange annotationStateChange)
Appends a new annotation state for the given annotation (adds it to the review history).
abstract Completable appendAnnotationStateAsync(Annotation annotation, AnnotationStateChange annotationStateChange)
Appends a new annotation state for the given annotation asynchronously (adds it to the review history).
abstract Annotation createAnnotationFromInstantJson(String annotationJson)
Creates an annotation from the Instant JSON annotation format.
abstract Single<Annotation> createAnnotationFromInstantJsonAsync(String annotationJson)
Creates an annotation from the Instant JSON annotation format asynchronously.
abstract List<Annotation> getAllAnnotationsOfType(EnumSet<AnnotationType> types, int startIndex, int pageCount)
Returns all annotations of passed types in the specified page index range.
abstract List<Annotation> getAllAnnotationsOfType(EnumSet<AnnotationType> types)
Returns all annotations of passed types in this document.
abstract Observable<Annotation> getAllAnnotationsOfTypeAsync(EnumSet<AnnotationType> types, int startIndex, int pageCount)
Returns all annotations of passed types in the specified page index range.
abstract Observable<Annotation> getAllAnnotationsOfTypeAsync(EnumSet<AnnotationType> types)
Returns all annotations of passed types in this document.
abstract Annotation getAnnotation(int pageIndex, int objectNumber)
Returns annotation with certain object ID on the page if it exists.
abstract Maybe<Annotation> getAnnotationAsync(int pageIndex, int objectNumber)
Returns annotation with certain object ID on the page if it exists, asynchronously.
abstract List<Annotation> getAnnotationReplies(Annotation annotation)
Gets all first-level replies to a particular annotation.
abstract Single<List<Annotation>> getAnnotationRepliesAsync(Annotation annotation)
Gets all first-level replies to a particular annotation asynchronously.
abstract List<Annotation> getAnnotations(Collection<Integer> objectNumbers)
Returns annotations with given object numbers.
abstract List<Annotation> getAnnotations(int pageIndex)
Returns a list of annotations on the page.
abstract Observable<List<Annotation>> getAnnotationsAsync(int pageIndex)
Returns list of annotations on the page.
abstract Observable<List<Annotation>> getAnnotationsAsync(Collection<Integer> objectNumbers)
Returns annotations with given object numbers, asynchronously.
abstract List<Annotation> getFlattenedAnnotationReplies(Annotation annotation)
Gets all flattened replies (all replies included but no nesting) to a particular annotation.
abstract Single<List<Annotation>> getFlattenedAnnotationRepliesAsync(Annotation annotation)
Gets all flattened replies (all replies included but no nesting) to a particular annotation asynchronously.
abstract List<AnnotationStateChange> getReviewHistory(Annotation annotation)
Gets the review history of an annotation.
abstract Single<List<AnnotationStateChange>> getReviewHistoryAsync(Annotation annotation)
Gets the review history of an annotation asynchronously.
abstract AnnotationReviewSummary getReviewSummary(Annotation annotation, String currentUser)
Gets a summary information about the given annotation's review state.
abstract Maybe<AnnotationReviewSummary> getReviewSummaryAsync(Annotation annotation, String currentUser)
Gets a summary information about the given annotation's review state asynchronously.
abstract int getZIndex(Annotation annotation)
Gets the z-index of the provided annotation.
abstract Single<Integer> getZIndexAsync(Annotation annotation)
Gets the z-index of the provided annotation.
abstract boolean hasUnsavedChanges()
Returns whether there are unsaved changes to annotations in this document.
abstract void moveAnnotation(Annotation annotation, int zIndex)
Moves the annotation to the specified z-index.
abstract void moveAnnotation(int pageIndex, int fromZIndex, int toZIndex)
Moves the annotation to the specified z-index.
abstract void moveAnnotation(Annotation annotation, AnnotationZIndexMove zIndexMove)
Moves the annotation with the specified z-index move action.
abstract Completable moveAnnotationAsync(Annotation annotation, AnnotationZIndexMove zIndexMove)
Moves the annotation with the specified z-index move action asynchronously.
abstract Completable moveAnnotationAsync(Annotation annotation, int zIndex)
Moves the annotation to the specified z-index asynchronously.
abstract Completable moveAnnotationAsync(int pageIndex, int fromZIndex, int toZIndex)
Moves the annotation to the specified z-index asynchronously.
abstract void removeAnnotationFromPage(Annotation annotation)
Removes annotation from the document.
abstract Completable removeAnnotationFromPageAsync(Annotation annotation)
Removes annotation from this document asynchronously.
abstract void removeAppearanceStreamGenerator(AppearanceStreamGenerator appearanceStreamGenerator)
Remove appearance stream generator that was previously added in addAppearanceStreamGenerator(AppearanceStreamGenerator).
abstract void removeOnAnnotationUpdatedListener(AnnotationProvider.OnAnnotationUpdatedListener updatedListener)
Removes a previously added AnnotationProvider.OnAnnotationUpdatedListener.

Fields

public static final EnumSet<AnnotationType> ALL_ANNOTATION_TYPES

All annotation types that can displayed in the annotation list.

Public Methods

public abstract void addAnnotationToPage (Annotation annotation)

Adds annotation to the owner PDF document. The annotation will be attached to the page set in its constructor.

Parameters
annotation Annotation to be added to the document.

public abstract void addAnnotationToPage (Annotation annotation, int zIndex)

Adds annotation to the owner PDF document at the specified z-index. The annotation will be attached to the page set in its constructor.

Parameters
annotation Annotation to be added to the document.
zIndex Z-index at which the annotation will be inserted.

public abstract Completable addAnnotationToPageAsync (Annotation annotation, int zIndex)

Adds annotation to the owner PDF document asynchronously, at the specified z-index. The annotation will be attached to the page set in its constructor.

Parameters
annotation Annotation to be added to the document.
zIndex Z-index at which the annotation will be inserted.
Returns
  • Completable which has to be subscribed to for operation to run.

public abstract Completable addAnnotationToPageAsync (Annotation annotation)

Adds annotation to the owner PDF document asynchronously. The annotation will be attached to the page set in its constructor.

Parameters
annotation Annotation to be added to the document.
Returns
  • Completable which has to be subscribed to for operation to run.

public abstract void addAppearanceStreamGenerator (AppearanceStreamGenerator appearanceStreamGenerator)

Adds appearance stream generator to the list of global appearance stream generators.

Appearance stream generators in this list are queried for all annotations in the document until one of them returns true from shouldUseGeneratorForAnnotation(Annotation). This generator is then used to generate custom appearance stream by calling getDataProviderForAnnotation(Annotation, EnumSet). If no such generator is found in the list, annotation's generator (set via setAppearanceStreamGenerator(AppearanceStreamGenerator) is used. Appearance stream generation fallbacks to default rendering if annotation has no appearance stream generator set.

Note: This does not automatically remove existing appearance streams. The appearance stream only gets generated when the annotation has been modified or when calling generateAppearanceStream() explicitly.

Parameters
appearanceStreamGenerator Appearance stream generator.

public abstract void addAppearanceStreamGenerator (AppearanceStreamGenerator appearanceStreamGenerator, boolean addFirst)

Adds appearance stream generator to the list of global appearance stream generators.

Appearance stream generators in this list are queried in order until one of them returns true from shouldUseGeneratorForAnnotation(Annotation). This generator is then used to generate custom appearance stream for the annotation by calling getDataProviderForAnnotation(Annotation, EnumSet). If no such generator is found in the list, annotation's generator (set via setAppearanceStreamGenerator(AppearanceStreamGenerator) is used. Appearance stream generation fallbacks to default rendering if annotation has no appearance stream generator set.

Note: This does not automatically remove existing appearance streams. The appearance stream only gets generated when the annotation has been modified or when calling generateAppearanceStream() explicitly.

Parameters
appearanceStreamGenerator Appearance stream generator.
addFirst Adds appearance stream generator to the beginning of the list. It will be used before any registered generator.

public abstract void addOnAnnotationUpdatedListener (AnnotationProvider.OnAnnotationUpdatedListener updatedListener)

Adds an AnnotationProvider.OnAnnotationUpdatedListener for being notified of updates to annotations. If the listener has already been added previously, this method will be a no-op. Passing null is not allowed and will result in an exception.

Parameters
updatedListener AnnotationProvider.OnAnnotationUpdatedListener that should be notified. Must be non-null.
See Also

public abstract void appendAnnotationState (Annotation annotation, AnnotationStateChange annotationStateChange)

Appends a new annotation state for the given annotation (adds it to the review history).

Parameters
annotation Annotation for which to set the state.
annotationStateChange New annotation state to be set.

public abstract Completable appendAnnotationStateAsync (Annotation annotation, AnnotationStateChange annotationStateChange)

Appends a new annotation state for the given annotation asynchronously (adds it to the review history).

Parameters
annotation Annotation for which to set the state.
annotationStateChange New annotation state to be set.
Returns
  • A Completable that completes once the annotation state has been appended.

public abstract Annotation createAnnotationFromInstantJson (String annotationJson)

Creates an annotation from the Instant JSON annotation format. The JSON must contain the type, the page number and any other required properties for that type. The created annotation will be automatically added to the document, and any registered AnnotationProvider.OnAnnotationUpdatedListener will be notified of the creation.

Parameters
annotationJson Instant JSON representation of the annotation to be created.
Returns
  • Annotation created from the provided Instant JSON. If creation of the annotation from JSON failed, this method throws an exception.
See Also

public abstract Single<Annotation> createAnnotationFromInstantJsonAsync (String annotationJson)

Creates an annotation from the Instant JSON annotation format asynchronously. The JSON must contain the type, the page number and any other required properties for that type. The created annotation will be automatically added to the document, and any registered AnnotationProvider.OnAnnotationUpdatedListener will be notified of the creation.

Parameters
annotationJson Instant JSON representation of the annotation to be created.
Returns
  • Single emitting annotation imported from provided Instant JSON or an error if creation of the annotation from JSON failed.
See Also

public abstract List<Annotation> getAllAnnotationsOfType (EnumSet<AnnotationType> types, int startIndex, int pageCount)

Returns all annotations of passed types in the specified page index range.

Note: this call may block for a while and should not be invoked on the main thread. You can use getAllAnnotationsOfTypeAsync(EnumSet, int, int) instead.

Parameters
types Annotation types to return. ALL_ANNOTATION_TYPES can be used as a shorthand parameter for all annotations.
startIndex Index of the page to start the search.
pageCount Number of pages to be included, starting the count with the startIndex page.
Returns
  • List of all annotations of passed types in a document.
See Also

public abstract List<Annotation> getAllAnnotationsOfType (EnumSet<AnnotationType> types)

Returns all annotations of passed types in this document.

Note: this call may block for a while and should not be invoked on the main thread. You can use getAllAnnotationsOfTypeAsync(EnumSet) instead.

Parameters
types Annotation types to return. ALL_ANNOTATION_TYPES can be used as a shorthand parameter for all annotations.
Returns
  • List of all annotations of passed types in a document.
See Also

public abstract Observable<Annotation> getAllAnnotationsOfTypeAsync (EnumSet<AnnotationType> types, int startIndex, int pageCount)

Returns all annotations of passed types in the specified page index range.

WARNING: Parsing all annotations in a document can take some time. If you have to use it as a synchronous call, use getAllAnnotationsOfType(EnumSet, int, int).

Parameters
types Annotation types to return. ALL_ANNOTATION_TYPES can be used as a shorthand parameter for all annotations.
startIndex Index of the page to start the search.
pageCount Number of pages to be included, starting the count with the startIndex page.
Returns
  • Observable emitting all annotations of passed types in a document.
See Also

public abstract Observable<Annotation> getAllAnnotationsOfTypeAsync (EnumSet<AnnotationType> types)

Returns all annotations of passed types in this document.

WARNING: Parsing all annotations in a document can take some time. If you have to use it as a synchronous call, use getAllAnnotationsOfType(EnumSet).

Parameters
types Annotation types to return. ALL_ANNOTATION_TYPES can be used as a shorthand parameter for all annotations.
Returns
  • Observable emitting all annotations of passed types in a document.
See Also

public abstract Annotation getAnnotation (int pageIndex, int objectNumber)

Returns annotation with certain object ID on the page if it exists.

Note: this call may block for a while and should not be invoked on the main thread.

Parameters
pageIndex Page index of the page where the annotation is.
objectNumber Object number of the annotation to retrieve.
Returns
  • The requested annotation or null if not found.

public abstract Maybe<Annotation> getAnnotationAsync (int pageIndex, int objectNumber)

Returns annotation with certain object ID on the page if it exists, asynchronously.

Parameters
pageIndex Page index of the page where the annotation is.
objectNumber Object number of the annotation to retrieve.
Returns
  • An instance of Maybe that either emits the requested annotation in `onSuccess()` or terminates with `onCompleted()` or `onError()`.

public abstract List<Annotation> getAnnotationReplies (Annotation annotation)

Gets all first-level replies to a particular annotation. First-level replies are annotations that return the given annotation via getInReplyTo(). The sort order is determined by the creation date.

Parameters
annotation Annotation whose replies we're fetching.
Returns
  • List of top-level replies to the given annotation, or an empty list if none are available.

public abstract Single<List<Annotation>> getAnnotationRepliesAsync (Annotation annotation)

Gets all first-level replies to a particular annotation asynchronously. First-level replies are annotations that return the given annotation via getInReplyTo(). The sort order is determined by the creation date.

Parameters
annotation Annotation whose replies we're fetching.
Returns
  • Single that emits a list of first-level replies to the given annotation.

public abstract List<Annotation> getAnnotations (Collection<Integer> objectNumbers)

Returns annotations with given object numbers.

Parameters
objectNumbers Collection of object numbers to search for.
Returns
  • List of resolved annotations.

public abstract List<Annotation> getAnnotations (int pageIndex)

Returns a list of annotations on the page. For annotations not currently recognised and handled by PSPDFKit this returns UnknownAnnotation.

Note: this call may block for a while and should not be invoked on the main thread.

Parameters
pageIndex 0-indexed page number.
Returns
  • List of annotations on the page with the given page number.

public abstract Observable<List<Annotation>> getAnnotationsAsync (int pageIndex)

Returns list of annotations on the page. For annotations not currently recognised and handled by PSPDFKit this returns UnknownAnnotation.

Parameters
pageIndex 0-indexed page number.
Returns
  • Observable stream of annotations on page.

public abstract Observable<List<Annotation>> getAnnotationsAsync (Collection<Integer> objectNumbers)

Returns annotations with given object numbers, asynchronously.

Parameters
objectNumbers Collection of object numbers to search for.
Returns
  • Observable emitting list of found annotations.

public abstract List<Annotation> getFlattenedAnnotationReplies (Annotation annotation)

Gets all flattened replies (all replies included but no nesting) to a particular annotation. The sort order is determined by the creation date.

Parameters
annotation Annotation whose replies we're fetching.
Returns
  • List all replies (flattened) to the given annotation, or an empty list if none are available.

public abstract Single<List<Annotation>> getFlattenedAnnotationRepliesAsync (Annotation annotation)

Gets all flattened replies (all replies included but no nesting) to a particular annotation asynchronously. The sort order is determined by the creation date.

Parameters
annotation Annotation whose replies we're fetching.
Returns
  • Single that emits a list of all replies (flattened) to the given annotation.

public abstract List<AnnotationStateChange> getReviewHistory (Annotation annotation)

Gets the review history of an annotation. The review history of an annotation is the list of states it has passed, for example, "Accepted", "Cancelled", and so on. This list is ordered chronologically, where the last element is the most current one according to the creation date of the annotation change.

Parameters
annotation Annotation for which to retrieve the review history.
Returns
  • List of annotation state changes ordered chronologically.

public abstract Single<List<AnnotationStateChange>> getReviewHistoryAsync (Annotation annotation)

Gets the review history of an annotation asynchronously. The review history of an annotation is the list of states it has passed, for example, "Accepted", "Cancelled", and so on. This list is ordered chronologically, where the last element is the most current one according to the creation date of the annotation change.

Parameters
annotation Annotation for which to retrieve the review history.
Returns
  • Single emitting a list of annotation state changes ordered chronologically.

public abstract AnnotationReviewSummary getReviewSummary (Annotation annotation, String currentUser)

Gets a summary information about the given annotation's review state.

Parameters
annotation Annotation for which to get the review summary.
currentUser The name of the current user, null to avoid including the current user into the review summary.
Returns
  • Annotation review summary, or null if it could not be retrieved.

public abstract Maybe<AnnotationReviewSummary> getReviewSummaryAsync (Annotation annotation, String currentUser)

Gets a summary information about the given annotation's review state asynchronously.

Parameters
annotation Annotation for which to get the review summary.
currentUser The name of the current user, null to avoid including the current user into the review summary.
Returns
  • Maybe returning the given annotation review summary, or none if it could not be retrieved.

public abstract int getZIndex (Annotation annotation)

Gets the z-index of the provided annotation.

Parameters
annotation Annotation for which to retrieve the z-index.
Returns
  • Z-index of the targeted annotation on the page that it's on.

public abstract Single<Integer> getZIndexAsync (Annotation annotation)

Gets the z-index of the provided annotation.

Parameters
annotation Annotation for which to retrieve the z-index.
Returns
  • A Single object that will contain the z-index as the value.

public abstract boolean hasUnsavedChanges ()

Returns whether there are unsaved changes to annotations in this document.

Returns
  • true if annotations were modified in this document and the document should be saved.

public abstract void moveAnnotation (Annotation annotation, int zIndex)

Moves the annotation to the specified z-index.

Parameters
annotation Annotation to move.
zIndex Target z-index to move the annotation to.

public abstract void moveAnnotation (int pageIndex, int fromZIndex, int toZIndex)

Moves the annotation to the specified z-index.

Parameters
pageIndex Index of the page on which to reorder the annotations.
fromZIndex The original z-index of the annotation that needs to be moved (from the specified page)
toZIndex Target z-index for the annotation to be moved to.

public abstract void moveAnnotation (Annotation annotation, AnnotationZIndexMove zIndexMove)

Moves the annotation with the specified z-index move action.

Parameters
annotation Annotation to move.
zIndexMove Z-index move action to be applied on the given annotation.

public abstract Completable moveAnnotationAsync (Annotation annotation, AnnotationZIndexMove zIndexMove)

Moves the annotation with the specified z-index move action asynchronously.

Parameters
annotation Annotation to move.
zIndexMove Z-index move action to be applied on the given annotation.
Returns
  • Completable object completing after the move has been done.

public abstract Completable moveAnnotationAsync (Annotation annotation, int zIndex)

Moves the annotation to the specified z-index asynchronously.

Parameters
annotation Annotation to move.
zIndex Target z-index to move the annotation to.
Returns
  • Completable object completing after the move has been done.

public abstract Completable moveAnnotationAsync (int pageIndex, int fromZIndex, int toZIndex)

Moves the annotation to the specified z-index asynchronously.

Parameters
pageIndex Index of the page on which to reorder the annotations.
fromZIndex The original z-index of the annotation that needs to be moved (from the specified page)
toZIndex Target z-index for the annotation to be moved to.
Returns
  • Completable object completing after the move has been done.

public abstract void removeAnnotationFromPage (Annotation annotation)

Removes annotation from the document. If the annotation is not attached to the document of this annotation provider, this will be a no-op. Note that when using the Replies component of PSPDFKit (requires extra license flag), any replies to the removed annotation will be automatically removed as well from the document.

Parameters
annotation Annotation to be removed from the document. May not be null.

public abstract Completable removeAnnotationFromPageAsync (Annotation annotation)

Removes annotation from this document asynchronously.

Parameters
annotation Annotation to be removed from the document.
Returns
  • Completable which has to be subscribed to for operation to run.

public abstract void removeAppearanceStreamGenerator (AppearanceStreamGenerator appearanceStreamGenerator)

Remove appearance stream generator that was previously added in addAppearanceStreamGenerator(AppearanceStreamGenerator).

public abstract void removeOnAnnotationUpdatedListener (AnnotationProvider.OnAnnotationUpdatedListener updatedListener)

Removes a previously added AnnotationProvider.OnAnnotationUpdatedListener. Upon calling this method the listener will no longer be notified of any changes. If the listener has not been added previously, this method will be a no-op. Passing null is not allowed, and will result in an exception.

Parameters
updatedListener AnnotationProvider.OnAnnotationUpdatedListener that should be removed. Must be non-null.
See Also