Class Annotation

  • All Implemented Interfaces:

    
    public abstract class Annotation
    
                        

    Represents a generic annotation in the PDF document.

    • Constructor Detail

    • Method Detail

      • getAppearanceStreamGenerator

        @Nullable() 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.

      • setAppearanceStreamGenerator

         void setAppearanceStreamGenerator(@Nullable() AppearanceStreamGenerator appearanceStreamGenerator)

        Sets custom appearance stream generator that overrides appearance stream generation of this annotation. This method will also trigger a call to generateAppearanceStream to generate the annotation's appearance stream (if necessary).

        Note: Make sure to call this only after adding the annotation to the document. Additionally, this does not automatically remove existing appearance streams.

        Parameters:
        appearanceStreamGenerator - Appearance stream generator for this annotation or null to remove custom appearance stream generator from this annotation.
      • getInReplyTo

        @Nullable() 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.

      • setInReplyTo

         void setInReplyTo(@Nullable() Annotation annotation)

        Sets the annotation that this annotation replies to.

        Parameters:
        annotation - Annotation to which this annotation is a reply.
      • getCopy

        @Nullable() Annotation getCopy(@IntRange(from = 0) 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.

      • getType

        @NonNull() abstract AnnotationType getType()

        Gets the annotation type of the annotation.

        Returns:

        The type of the annotation. Makes down casting easier.

      • getBoundingBox

        @NonNull() 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 providing the altered rect to update the annotation.

        Returns:

        Rect with page position in PDF coordinates.

      • setBoundingBox

         void setBoundingBox(@NonNull() RectF newBoundingBox)

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

        Parameters:
        newBoundingBox - Annotation's position on the page in PDF coordinates.
      • getBoundingBox

        @NonNull() RectF getBoundingBox(@Nullable() RectF rect)

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

        Parameters:
        rect - Reuse rectangle.
        Returns:

        Rectangle with page position in PDF coordinates.

      • getFlags

        @NonNull() EnumSet<AnnotationFlags> getFlags()

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

        Returns:

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

      • hasFlag

         boolean hasFlag(@NonNull() AnnotationFlags flag)

        Test annotation flag.

        Returns:

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

      • getName

        @Nullable() 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.

      • setName

         void setName(@Nullable() String name)

        Sets Title / Name field for this annotation

        Parameters:
        name - Name of this annotation or null to clear the field.
      • getContents

        @Nullable() 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.

      • setContents

         void setContents(@Nullable() 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.
      • getRichText

        @Nullable() 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.

      • setRichText

         void setRichText(@Nullable() 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.
      • getSubject

        @Nullable() String getSubject()

        Returns the subject of this annotation.

        Returns:

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

      • setSubject

         void setSubject(@Nullable() 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 and setTitle instead.

        Parameters:
        subject - The subject of this annotation or null to clear the field.
      • getCreatedDate

        @Nullable() Date getCreatedDate()

        Returns the creation date of the annotation.

        Returns:

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

      • setCreatedDate

         void setCreatedDate(@Nullable() Date createdDate)

        Sets created date for this annotation.

        Parameters:
        createdDate - Created date in UTC time or null to clear the field.
      • getModifiedDate

        @Nullable() 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.

      • setModifiedDate

         void setModifiedDate(@Nullable() Date modifiedDate)

        Sets last modified date for this annotation.

        Parameters:
        modifiedDate - Last modified date in UTC time or null to clear the field.
      • getCreator

        @Nullable() String getCreator()

        Returns the name of the creator of this annotation.

        Returns:

        Annotation creator name or null if not set.

      • setCreator

         void setCreator(@Nullable() String creator)

        Sets the creator of this annotation.

        Parameters:
        creator - Creator or null to clear the field.
      • getColor

        @ColorInt() 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. This is the stroke color for shapes.

        Returns:

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

      • setColor

         void setColor(@ColorInt() 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 property.

        Parameters:
        color - The annotation color or Color#TRANSPARENT to clear the field.
      • getFillColor

        @ColorInt() 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.

      • setFillColor

         void setFillColor(@ColorInt() int color)

        Sets the fill color for this annotation. Only used for certain annotation types. s, for example, aren't affected by this property.

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

        Parameters:
        color - The annotation color or Color#TRANSPARENT to clear the field.
      • getAlpha

        @FloatRange(from = 0.0, to = 1.0) float getAlpha()

        Returns the annotation's main alpha (or stroke alpha). For annotations that also have a fill colour, such as shapes, this is the border/line alpha.

        Returns:

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

      • getFillAlpha

        @FloatRange(from = 0.0, to = 1.0) float getFillAlpha()

        Returns the fill alpha.

        Returns:

        Fill alpha for the annotation. It's the value in range <0.0f...1.0f>. Default value is 1.0f.

      • setAlpha

         void setAlpha(@FloatRange(from = 0.0, to = 1.0) float alpha)

        Sets the annotation's alpha (or stroke alpha) value. It's the value in range <0.0f...1.0f>.

      • setFillAlpha

         void setFillAlpha(@FloatRange(from = 0.0, to = 1.0) float alpha)

        Sets the annotation's fill alpha value if supported. It's the value in range <0.0f...1.0f>. NOTE: Added in v2024.6. Currently this API is the only way to change this value. If you need a UI for it, please contact support.

      • getBorderColor

        @ColorInt() 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.

      • setBorderColor

         void setBorderColor(@ColorInt() 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 property.

        Parameters:
        color - The border color or Color#TRANSPARENT to clear the field.
      • setBorderEffectIntensity

         void setBorderEffectIntensity(@FloatRange(from = 0.0) 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.
      • getBorderWidth

         float getBorderWidth()

        Returns the border line width / thickness.

        Returns:

        line width in PDF points.

      • setBorderWidth

         void setBorderWidth(@FloatRange(from = 0.0) float borderWidth)

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

        Parameters:
        borderWidth - border width in PDF points
      • setBorderDashArray

         void setBorderDashArray(@Nullable() 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 should be set to DASHED and color of the border should be set with setBorderColor.

        Parameters:
        dashes - List of integer numbers representing lengths of a pattern.
      • setBlendMode

         void setBlendMode(@NonNull() BlendMode blendMode)

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

        Parameters:
        blendMode - blend mode to use when generating annotations appearance stream.
      • getBlendMode

        @NonNull() BlendMode getBlendMode()

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

        Returns:

        Currently set blend mode.

      • getPageIndex

         int getPageIndex()

        The page number to which this annotation belongs. If the annotation is not attached to any document, this method will return PAGE_NUMBER_NOT_SET.

        Returns:

        Page number tied to the annotation or PAGE_NUMBER_NOT_SET if not set.

      • getObjectNumber

         int getObjectNumber()

        The object number of this annotation inside the PDF document file. This method will only return a valid object number if this annotation is attached to a document (i.e. when isAttached returns true). If the annotation is not attached to any document, this method will return OBJECT_NUMBER_NOT_SET.

        Note that there is no guarantee that object numbers stay the same when saving and reopening a document. If a persistent identifier is required, use the getName property instead, which by default is initialized to hold a type 4 (pseudo randomly generated) UUID.

        Returns:

        Object number of this annotation or OBJECT_NUMBER_NOT_SET if the annotation is not attached to a document.

      • setGroup

         void setGroup(@Nullable() String group)

        Sets the group of the annotation. May be used to have multiple annotations that behave as single one, if their group string is equal. Only works within one page. This is a proprietary extension

        Parameters:
        group - arbitrary group string of the annotation or null to clear the group.
      • getGroup

        @Nullable() String getGroup()

        Returns the group string of the annotation.

        Returns:

        The annotations group sting or null if no group is set.

      • isResizable

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

      • isLocked

         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.

      • hasLockedContents

         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.

      • isSignature

         boolean isSignature()

        Returns true when the annotation is a signature annotation. Annotations that can be signatures are InkAnnotation and StampAnnotation.

        Returns:

        true when the annotation is a signature annotation.

      • getMinimumSize

        @NonNull() Size getMinimumSize()

        Returns the minimum size of the annotation.

        Returns:

        The minimum annotation size in PDF points.

      • renderToBitmap

         void renderToBitmap(@NonNull() Bitmap bitmap)

        Renders the appearance of this annotation into the passed bitmap.

        Parameters:
        bitmap - Target bitmap to render the annotation into.
      • renderToBitmap

         void renderToBitmap(@NonNull() Bitmap bitmap, @NonNull() 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.
      • renderToBitmapAsync

         Single<Bitmap> renderToBitmapAsync(@NonNull() Bitmap bitmap)

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

        Parameters:
        bitmap - Target bitmap to render the annotation into.
      • isModified

         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.

      • toInstantJson

        @NonNull() 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.

      • isAttached

         boolean isAttached()

        Tells whether this annotation is attached to a document.

        Returns:

        true if this annotation is attached to a document, or false if it is not attached.

      • updateTransformationProperties

         abstract void updateTransformationProperties(@NonNull() RectF newBoundingBox, @NonNull() 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).
      • generateAppearanceStream

        @WorkerThread() 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.

      • generateAppearanceStreamAsync

        @NonNull() Completable generateAppearanceStreamAsync()

        Regenerates the annotation's appearance stream if necessary.

        Returns:

        A Completable that can be subscribed to.

      • isReply

         boolean isReply()

        Whether the annotations is a reply to another annotation.

        Returns:

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

      • getInReplyToAsync

        @NonNull() 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 if there's no such annotation.

      • setCustomData

         void setCustomData(@Nullable() 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.
      • getCustomData

        @Nullable() 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.

      • hasBinaryInstantJsonAttachment

         boolean hasBinaryInstantJsonAttachment()

        Checks if this annotation has a binary instant JSON attachment. For example, a stamp annotation with an image has one.

        Returns:

        true if this annotation has a binary instant JSON attachment, false otherwise.

      • getUuid

        @NonNull() String getUuid()

        A unique in-memory identifier for each annotation. Generated at runtime, therefore not persisted (in the PDF).

        Unlike getName, this method is guaranteed to always return a non-null value, even for existing annotations in a document.

        Returns:

        The UUID of this annotation.

      • getInstantRecordGroup

        @Nullable() String getInstantRecordGroup()

        Gets instant record group of the annotation, or null if this annotation is detached.

        Returns:

        Instant record group of this annotation.

      • isUiRotationSupported

         boolean isUiRotationSupported()

        Returns true if this Annotation can be rotated in the UI.

      • setContentSize

         void setContentSize(@Nullable() RectF contentSize, boolean adjustedForPageRotation)

        Sets the inner bounds that are used when rotating the annotation. In order to keep the size consistent when rotating we need to remember the size when rotated 0° degrees.

        Core adds the page rotation to the annotation rotation when handling stamps/free text rotation. So when creating them we can't use the bounding box to initialize the content size when the page they are on is 90° or 270°. We need to flip the width and height so it is correct. The adjustedForPageRotation parameter indicates whether this was already done by the calling code or if it should be done automatically when the annotation is attached to the document.

        Parameters:
        contentSize - The content size to set in PDF coordinates.
        adjustedForPageRotation - true if the content size was already adjusted for the page rotation, false if it should be adjusted as soon as the annotation is attached to the document.
      • makeNewGroupId

        @NonNull() static String makeNewGroupId()

        Creates random string to be used as a group name.

        Returns:

        the created group name.