Class Annotation

  • All Implemented Interfaces:

    
    public abstract class Annotation
    
                        

    Represents a generic annotation in the PDF document.

    • Constructor Detail

    • Method Detail

      • setAppearanceStreamGenerator

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

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

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

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

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

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

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

      • 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 alpha.

      • setAlpha

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

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

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

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

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

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

      • isResizable

         boolean isResizable()

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

      • isLocked

         boolean isLocked()

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

      • hasLockedContents

         boolean hasLockedContents()

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

      • isSignature

         boolean isSignature()

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

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

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

      • isAttached

         boolean isAttached()

        Tells whether this annotation is attached to a document.

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

      • isReply

         boolean isReply()

        Whether the annotations is a reply to another annotation.

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

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

      • hasBinaryInstantJsonAttachment

         boolean hasBinaryInstantJsonAttachment()

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

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

      • isUiRotationSupported

         boolean isUiRotationSupported()

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