public abstract class

Annotation

extends Object
java.lang.Object
   ↳ com.pspdfkit.annotations.Annotation
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

Represents a generic annotation in the PDF document.

Summary

Constants
float DEFAULT_BORDER_WIDTH Default border width when none is set.
float DEFAULT_CLOUDY_BORDER_EFFECT_INTENSITY Default border effect intensity for cloudy borders.
int OBJECT_NUMBER_NOT_SET Return value for when the annotation doesn't have a set object number.
int PAGE_NUMBER_NOT_SET Return value for when the annotation doesn't have a set page number.
Fields
protected static final Size DEFAULT_MINIMUM_SIZE Default minimum size of an annotation in PDF points.
Public Methods
boolean equals(Object o)
void generateAppearanceStream()
Regenerates the annotation's appearance stream if necessary.
Completable generateAppearanceStreamAsync()
Regenerates the annotation's appearance stream if necessary.
float getAlpha()
Returns the annotation's alpha.
AppearanceStreamGenerator getAppearanceStreamGenerator()
Returns custom appearance stream generator that overrides appearance stream generation of this annotation.
BlendMode getBlendMode()
Returns currently set blend mode.
int getBorderColor()
Returns the border color of this annotation or Color#TRANSPARENT if no color is set.
List<Integer> getBorderDashArray()
Returns currently set dash array or null if no pattern is set.
BorderEffect getBorderEffect()
Returns the current border effect on the annotation or NO_EFFECT if none is set.
float getBorderEffectIntensity()
Returns the current border effect intensity.
BorderStyle getBorderStyle()
Returns the current border style on the annotation or NONE if none is set.
float getBorderWidth()
Returns the border line width / thickness.
RectF getBoundingBox(RectF rect)
Position of this annotation on the page.
RectF getBoundingBox()
Position of this annotation on the page.
int getColor()
Returns a color associated with this annotation or Color#TRANSPARENT if no color is set.
String getContents()
Returns text contents of the annotation.
Annotation getCopy(int pageIndex)

Creates a copy of this annotation that isn't attached to the document with the page index set to given index.

Date getCreatedDate()
Returns the creation date of the annotation.
String getCreator()
Returns the name of the creator of this annotation.
JSONObject getCustomData()
Retrieves custom data for the annotation.
int getFillColor()
Returns a fill color associated with this object or Color#TRANSPARENT if no color is set.
EnumSet<AnnotationFlags> getFlags()
Annotation flags set.
Annotation getInReplyTo()
Retrieves the annotation this annotation replies to, or null it this annotation is not a reply or the license doesn't support replies feature.
Maybe<Annotation> getInReplyToAsync()
Retrieves the annotation this annotation replies to asynchronously.
Size getMinimumSize()
Returns the minimum size of the annotation.
Date getModifiedDate()
Returns the date when this annotation was last modified.
String getName()
Returns the content of Title/Name field of this annotation.
int getObjectNumber()
The object number of this annotation.
int getPageIndex()
The page number to which this annotation belongs.
String getRichText()
Returns rich text contents of the annotation.
String getSubject()
Returns the subject of this annotation.
abstract AnnotationType getType()
Gets the annotation type of the annotation.
boolean hasFlag(AnnotationFlags flag)
Test annotation flag.
boolean hasLockedContents()
Check if the annotation has locked contents - i.e.
int hashCode()
boolean isAttached()
Whether the annotation is attached to the document and it has a valid object number.
boolean isLocked()
Check if the annotation is locked - i.e.
boolean isModified()
Returns whether the annotation is modified or not.
boolean isReply()
Whether the annotations is a reply to another annotation.
boolean isResizable()
Check if the annotation is resizable, or if this is a non-resizable annotation.
void renderToBitmap(Bitmap bitmap)
Renders the appearance of this annotation into the passed bitmap.
void renderToBitmap(Bitmap bitmap, AnnotationRenderConfiguration configuration)
Renders the appearance of this annotation into the passed bitmap.
Single<Bitmap> renderToBitmapAsync(Bitmap bitmap)
Asynchronously renders the appearance of this annotation into the passed bitmap.
Single<Bitmap> renderToBitmapAsync(Bitmap bitmap, AnnotationRenderConfiguration configuration)
Asynchronously renders the appearance of this annotation into the passed bitmap.
void setAlpha(float alpha)
Sets the annotations' alpha value.
void setAppearanceStreamGenerator(AppearanceStreamGenerator appearanceStreamGenerator)
Sets custom appearance stream generator that overrides appearance stream generation of this annotation.
void setBlendMode(BlendMode blendMode)
Sets the blend mode used when generating annotation's appearance stream.
void setBorderColor(int color)
Sets the border color for this annotation.
void setBorderDashArray(List<Integer> dashes)
Sets a dash style for the border.
void setBorderEffect(BorderEffect borderEffect)
Sets a border effect for current annotation.
void setBorderEffectIntensity(float borderEffectIntensity)
Sets border effect intensity.
void setBorderStyle(BorderStyle borderStyle)
Sets a border style for current annotation.
void setBorderWidth(float borderWidth)
Sets border line width / thickness.
void setBoundingBox(RectF newBoundingBox)
Sets the position and size of this annotation on the page.
void setColor(int color)
Sets the color for this annotation.
void setContents(String contents)
Sets text contents of the annotation.
void setCreatedDate(Date createdDate)
Sets created date for this annotation.
void setCreator(String creator)
Sets the creator of this annotation.
void setCustomData(JSONObject customData)
Sets custom data to the annotation.
void setFillColor(int color)
Sets the fill color for this annotation.
void setFlags(EnumSet<AnnotationFlags> flags)
Sets annotation flags.
void setInReplyTo(Annotation annotation)
Sets the annotation that this annotation replies to.
void setModifiedDate(Date modifiedDate)
Sets last modified date for this annotation.
void setName(String name)
Sets Title / Name field for this annotation
void setRichText(String richText)
Sets rich text contents of the annotation.
void setSubject(String subject)
Sets the subject of this annotation.
String toInstantJson()
Produces Instant JSON representation of this annotation.
String toString()
abstract void updateTransformationProperties(RectF newBoundingBox, RectF oldBoundingBox)
Annotations may override this method to transform their properties (i.e.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final float DEFAULT_BORDER_WIDTH

Default border width when none is set.

Constant Value: 1.0

public static final float DEFAULT_CLOUDY_BORDER_EFFECT_INTENSITY

Default border effect intensity for cloudy borders.

Constant Value: 5.0

public static final int OBJECT_NUMBER_NOT_SET

Return value for when the annotation doesn't have a set object number.

Constant Value: -2147483648 (0x80000000)

public static final int PAGE_NUMBER_NOT_SET

Return value for when the annotation doesn't have a set page number.

Constant Value: -2147483648 (0x80000000)

Fields

protected static final Size DEFAULT_MINIMUM_SIZE

Default minimum size of an annotation in PDF points.

Public Methods

public boolean equals (Object o)

public void generateAppearanceStream ()

Regenerates the annotation's appearance stream if necessary.

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

public Completable generateAppearanceStreamAsync ()

Regenerates the annotation's appearance stream if necessary.

Returns

public float getAlpha ()

Returns the annotation's alpha.

Returns
  • Alpha for the annotation. It's the value in range <0.0f...1.0f>. Default value is 1.0f.

public AppearanceStreamGenerator getAppearanceStreamGenerator ()

Returns custom appearance stream generator that overrides appearance stream generation of this annotation.

Returns
  • Custom AP stream generator for this annotation or null when no custom appearance stream generator is set.

public BlendMode getBlendMode ()

Returns currently set blend mode. Defaults to NORMAL for all annotations except highlight.

Returns
  • Currently set blend mode.

public int getBorderColor ()

Returns the border color of this annotation or Color#TRANSPARENT if no color is set. Note that alpha channel is not taken into account as per PDF specifications.

Returns
  • Color of annotations border or Color#TRANSPARENT if no color is set.

public List<Integer> getBorderDashArray ()

Returns currently set dash array or null if no pattern is set.

Returns
  • Currently set dash array

public BorderEffect getBorderEffect ()

Returns the current border effect on the annotation or NO_EFFECT if none is set.

Returns

public float getBorderEffectIntensity ()

Returns the current border effect intensity.

Returns
  • Border effect intensity.

public BorderStyle getBorderStyle ()

Returns the current border style on the annotation or NONE if none is set.

Returns
  • Border style or NONE if none is set.

public float getBorderWidth ()

Returns the border line width / thickness.

Returns
  • line width in PDF points.

public RectF getBoundingBox (RectF rect)

Position of this annotation on the page. Changing bounding box does not change annotations bounds. Instead call setBoundingBox(RectF) to change annotation bounds.

Parameters
rect Reuse rectangle.
Returns
  • Rectangle with page position in PDF coordinates.

public RectF getBoundingBox ()

Position of this annotation on the page. The returned RectF is a copy, so changing its values won't update the annotation's bounds. Instead call setBoundingBox(RectF) providing the altered rect to update the annotation.

Returns
  • Rect with page position in PDF coordinates.

public int getColor ()

Returns a color associated with this annotation or Color#TRANSPARENT if no color is set. Note that alpha channel is not taken into account as per PDF specifications. This is the text color for FreeTextAnnotation and WidgetAnnotation.

Returns
  • Color of annotation or Color#TRANSPARENT if none is set.

public String getContents ()

Returns text contents of the annotation. This is usually the displayed text for annotations that display text or accessibility label for annotations that don't.

Returns
  • Annotation contents string or null if it's not set.

public Annotation getCopy (int pageIndex)

Creates a copy of this annotation that isn't attached to the document with the page index set to given index. If this type of annotation can't be copied this method will return null.

Note: This will reset the name of the resulting annotation to an automatically generated UUID if you want to keep the original name you have to manually set it on the returned copy.

Parameters
pageIndex The page index the copied annotation should belong to.
Returns
  • A copy of this annotation or null if no copy could be made.

public Date getCreatedDate ()

Returns the creation date of the annotation.

Returns
  • UTC date when this annotation was created or null if non-existent.

public String getCreator ()

Returns the name of the creator of this annotation.

Returns
  • Annotation creator name or null if not set.

public JSONObject getCustomData ()

Retrieves custom data for the annotation.

Annotations can store additional user-specified data. PSPDFKit will not use or evaluate customData in the UI directly. You have full control over this property. For new annotation, this defaults to null.

Returns
  • Custom data for the annotation or null if annotation has no custom data.

public int getFillColor ()

Returns a fill color associated with this object or Color#TRANSPARENT if no color is set. Note that alpha channel is not taken into account as per PDF specifications.

Returns
  • Color of annotation or Color#TRANSPARENT if no color is set.

public EnumSet<AnnotationFlags> getFlags ()

Annotation flags set. Changing returned EnumSet does not change annotation flags. Instead call setFlags(EnumSet) to change annotation flags.

Returns
  • Set of annotation flags of empty set if no flags were configured.

public Annotation getInReplyTo ()

Retrieves the annotation this annotation replies to, or null it this annotation is not a reply or the license doesn't support replies feature.

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

Returns
  • Annotation this annotation replies to, or null.

public Maybe<Annotation> getInReplyToAsync ()

Retrieves the annotation this annotation replies to asynchronously. The response is emitted inside the RxJava's Maybe. It will contain the requested annotation if it exists, or be empty otherwise.

Returns
  • Maybe emitting the annotation this annotation replies to or an empty Maybe if there's no such annotation.

public Size getMinimumSize ()

Returns the minimum size of the annotation.

Returns
  • The minimum annotation size in PDF points.

public Date getModifiedDate ()

Returns the date when this annotation was last modified.

Returns
  • UTC date of when this annotation was last modified or null if non-existent.

public String getName ()

Returns the content of Title/Name field of this annotation. This can be used to globally identify the annotation. This property will be automatically set to a type 4 (pseudo random) UUID during annotation construction time.

Returns
  • Name of this annotation or null. By default, this is initialized to a random UUID.

public int getObjectNumber ()

The object number of this annotation.

Returns

public int getPageIndex ()

The page number to which this annotation belongs.

Returns

public String getRichText ()

Returns rich text contents of the annotation. This is text to be displayed in a pop-up for text markup annotations.

Returns
  • Rich text contents of the annotation or null if it's not set.

public String getSubject ()

Returns the subject of this annotation.

Returns
  • Subject field of the annotation or null if it's not set.

public abstract AnnotationType getType ()

Gets the annotation type of the annotation.

Returns
  • The type of the annotation. Makes down casting easier.

public boolean hasFlag (AnnotationFlags flag)

Test annotation flag.

Returns
  • true if flag is set on this annotation, false otherwise.

public boolean hasLockedContents ()

Check if the annotation has locked contents - i.e. annotation content can't be modified.

Returns
  • true if the annotation has locked content or false if annotation's content can be modified.

public int hashCode ()

public boolean isAttached ()

Whether the annotation is attached to the document and it has a valid object number.

Returns
  • true if annotation is attached to the document and it has a valid object number, false otherwise.

public boolean isLocked ()

Check if the annotation is locked - i.e. annotation can't be deleted or modified (except contents).

Returns
  • true if the annotation is locked or false if it can be freely modified.

public boolean isModified ()

Returns whether the annotation is modified or not.

Returns
  • Returns true if this annotations has been modified and the document containing it hasn't been saved as part of the document.

public boolean isReply ()

Whether the annotations is a reply to another annotation.

Returns
  • true if this annotations is a reply to another annotation, false otherwise.

public boolean isResizable ()

Check if the annotation is resizable, or if this is a non-resizable annotation.

Returns
  • true if the annotation can be resized (e.g. ink annotation) or false if it is a non-resizable one (e.g. note annotation).

public void renderToBitmap (Bitmap bitmap)

Renders the appearance of this annotation into the passed bitmap.

Parameters
bitmap Target bitmap to render the annotation into.

public void renderToBitmap (Bitmap bitmap, AnnotationRenderConfiguration configuration)

Renders the appearance of this annotation into the passed bitmap.

Parameters
bitmap Target bitmap to render the annotation into.
configuration Advanced annotation rendering configuration.

public Single<Bitmap> renderToBitmapAsync (Bitmap bitmap)

Asynchronously renders the appearance of this annotation into the passed bitmap.

Parameters
bitmap Target bitmap to render the annotation into.

public Single<Bitmap> renderToBitmapAsync (Bitmap bitmap, AnnotationRenderConfiguration configuration)

Asynchronously renders the appearance of this annotation into the passed bitmap.

Parameters
bitmap Target bitmap to render the annotation into.
configuration Advanced annotation rendering configuration.

public void setAlpha (float alpha)

Sets the annotations' alpha value. It's the value in range <0.0f...1.0f>.

public void setAppearanceStreamGenerator (AppearanceStreamGenerator appearanceStreamGenerator)

Sets custom appearance stream generator that overrides appearance stream generation of this annotation. The appearanceStreamGenerator will be called when necessary to generate annotation's appearance stream.

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 for this annotation or null to remove custom appearance stream generator from this annotation.

public void setBlendMode (BlendMode blendMode)

Sets the blend mode used when generating annotation's appearance stream.

Parameters
blendMode blend mode to use when generating annotations appearance stream.

public void setBorderColor (int color)

Sets the border color for this annotation. Border color usually redirects to color, unless overridden to have a real backing store (this is the case for WidgetAnnotation).

Note: The annotation will only store the RGB part and discard the alpha channel set here. Annotation opacity is set via the setAlpha(float) property.

Parameters
color The border color or Color#TRANSPARENT to clear the field.

public void setBorderDashArray (List<Integer> dashes)

Sets a dash style for the border. It's in form of an array where the numbers mean full_length, empty length, full_length... etc.. The pattern is repeated.

To get a dashed border, setBorderStyle(BorderStyle) should be set to DASHED and color of the border should be set with setBorderColor(int).

Parameters
dashes List of integer numbers representing lengths of a pattern. E.g. { 2, 3 } will generate a dash pattern with lines of length 2 and empty spaces of length 3.

public void setBorderEffect (BorderEffect borderEffect)

Sets a border effect for current annotation. Currently supports no effect and cloudy. Note: setBorderEffectIntensity(float) should be set to non-zero (e.g. 1.0) for Cloudy border to be displayed.

Parameters
borderEffect BorderEffect to be set. NO_EFFECT to clear it.

public void setBorderEffectIntensity (float borderEffectIntensity)

Sets border effect intensity. Valid only if the border effect is CLOUDY. The value is suggested to be between 0 and 2 but other values are valid as well. Default value is 0.

Parameters
borderEffectIntensity Intensity of the border effect.

public void setBorderStyle (BorderStyle borderStyle)

Sets a border style for current annotation. It should be accompanied with setBorderColor(int) call to set the border color as well.

Parameters
borderStyle BorderStyle to be set. NONE to clear it.

public void setBorderWidth (float borderWidth)

Sets border line width / thickness. For border to appear, color and style should be set via setBorderColor(int) and setBorderStyle(BorderStyle) as well.

Parameters
borderWidth border width in PDF points

public void setBoundingBox (RectF newBoundingBox)

Sets the position and size of this annotation on the page.

Parameters
newBoundingBox Annotation's position on the page in PDF coordinates.

public void setColor (int color)

Sets the color for this annotation. This is the text color for FreeTextAnnotation, WidgetAnnotation, and RedactionAnnotation.

Note: The annotation will only store the RGB part and discard the alpha channel set here. Annotation opacity is set via the setAlpha(float) property.

Parameters
color The annotation color or Color#TRANSPARENT to clear the field.

public void setContents (String contents)

Sets text contents of the annotation. This is usually the displayed text for annotations that display text or accessibility label for annotations that don't.

Parameters
contents Contents string or null to clear the field.

public void setCreatedDate (Date createdDate)

Sets created date for this annotation.

Parameters
createdDate Created date in UTC time or null to clear the field.

public void setCreator (String creator)

Sets the creator of this annotation.

Parameters
creator Creator or null to clear the field.

public void setCustomData (JSONObject customData)

Sets custom data to the annotation. The contents of this property are saved to the document when saving.

Annotations can store additional user-specified data here. PSPDFKit will not use or evaluate customData in the UI directly. You have full control over this property. For new annotation, this defaults to null.

Parameters
customData JSONObject to set as the custom data. null to clear the custom data property.

public void setFillColor (int color)

Sets the fill color for this annotation.

Note: The annotation will only store the RGB part and discard the alpha channel set here. Annotation opacity is set via the setAlpha(float) property.

Parameters
color The annotation color or Color#TRANSPARENT to clear the field.

public void setFlags (EnumSet<AnnotationFlags> flags)

Sets annotation flags.

Parameters
flags Set of annotation flags to be set.

public void setInReplyTo (Annotation annotation)

Sets the annotation that this annotation replies to.

Parameters
annotation Annotation to which this annotation is a reply.

public void setModifiedDate (Date modifiedDate)

Sets last modified date for this annotation.

Parameters
modifiedDate Last modified date in UTC time or null to clear the field.

public void setName (String name)

Sets Title / Name field for this annotation

Parameters
name Name of this annotation or null to clear the field.

public void setRichText (String richText)

Sets rich text contents of the annotation. This is the text to be displayed in a pop-up for text markup annotations.

Parameters
richText Rich text contents for annotation or null to clear the field.

public void setSubject (String subject)

Sets the subject of this annotation.

Starting with PSPDFKit 5.0 this method will no longer affect the appearance of stamp annotations. Use setStampType(StampType) and setTitle(String) instead.

Parameters
subject The subject of this annotation or null to clear the field.

public String toInstantJson ()

Produces Instant JSON representation of this annotation.

Note: Make sure the annotation is attached to the document before exporting it to Instant JSON.

Returns
  • Instant JSON representation for this annotation.

public String toString ()

public abstract void updateTransformationProperties (RectF newBoundingBox, RectF oldBoundingBox)

Annotations may override this method to transform their properties (i.e. points, rects, sizes) whenever the bounding box of the annotation changed.

Parameters
newBoundingBox New bounding box of the annotation (in PDF points).
oldBoundingBox Old bounding box of the annotation (in PDF points).