Package com.itextpdf.kernel.pdf.annot

Class PdfAnnotation

    • Constructor Detail

      • PdfAnnotation

        protected PdfAnnotation​(Rectangle rect)

      • PdfAnnotation

        protected PdfAnnotation​(PdfDictionary pdfObject)

    • Method Detail

      • makeAnnotation

        public static PdfAnnotation makeAnnotation​(PdfObject pdfObject)
        Factory method that creates the type specific PdfAnnotation from the given PdfObject that represents annotation object. This method is useful for property reading in reading mode or modifying in stamping mode. See derived classes of this class to see possible specific annotation types created.
        Parameters:
        pdfObject - a PdfObject that represents annotation in the document.
        Returns:
        created PdfAnnotation.

      • getSubtype

        public abstract PdfName getSubtype()
        Gets a PdfName which value is a subtype of this annotation. See ISO-320001 12.5.6, "Annotation Types" for the reference to the possible types.
        Returns:
        subtype of this annotation.

      • setLayer

        public void setLayer​(IPdfOCG layer)
        Sets the layer this annotation belongs to.
        Parameters:
        layer - the layer this annotation belongs to

      • getContents

        public PdfString getContents()
        Gets the text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternate description of the annotation’s contents in human-readable form.
        Returns:
        annotation text content.

      • setContents

        public PdfAnnotation setContents​(PdfString contents)
        Sets the text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternate description of the annotation’s contents in human-readable form.
        Parameters:
        contents - a PdfString containing text content to be set to the annotation.
        Returns:
        this PdfAnnotation instance.

      • setContents

        public PdfAnnotation setContents​(java.lang.String contents)
        Sets the text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternate description of the annotation’s contents in human-readable form.
        Parameters:
        contents - a java String containing text content to be set to the annotation.
        Returns:
        this PdfAnnotation instance.

      • getPageObject

        public PdfDictionary getPageObject()
        Gets a PdfDictionary that represents a page of the document on which annotation is placed, i.e. which has this annotation in it's /Annots array.
        Returns:
        PdfDictionary that is a page pdf object or null if annotation is not added to the page yet.

      • getPage

        public PdfPage getPage()
        Gets a PdfPage on which annotation is placed.
        Returns:
        PdfPage on which annotation is placed or null if annotation is not placed yet.

      • setPage

        public PdfAnnotation setPage​(PdfPage page)
        Method that modifies annotation page property, which defines to which page annotation belongs. Keep in mind that this doesn't actually add an annotation to the page, it should be done via PdfPage.addAnnotation(PdfAnnotation). Also you don't need to set this property manually, this is done automatically on addition to the page.
        Parameters:
        page - the PdfPage to which annotation will be added.
        Returns:
        this PdfAnnotation instance.

      • getName

        public PdfString getName()
        Gets the annotation name, a text string uniquely identifying it among all the annotations on its page.
        Returns:
        a PdfString with annotation name as it's value or null if name is not specified.

      • setName

        public PdfAnnotation setName​(PdfString name)
        Sets the annotation name, a text string uniquely identifying it among all the annotations on its page.
        Parameters:
        name - a PdfString to be set as annotation name.
        Returns:
        this PdfAnnotation instance.

      • getDate

        public PdfString getDate()
        The date and time when the annotation was most recently modified. This is an optional property of the annotation.
        Returns:
        a PdfString with the modification date as it's value or null if date is not specified.

      • setDate

        public PdfAnnotation setDate​(PdfString date)
        The date and time when the annotation was most recently modified.
        Parameters:
        date - a PdfString with date. The format should be a date string as described in ISO-320001 7.9.4, "Dates".
        Returns:
        this PdfAnnotation instance.

      • getFlags

        public int getFlags()
        A set of flags specifying various characteristics of the annotation (see ISO-320001 12.5.3, "Annotation Flags"). For specific annotation flag constants see setFlag(int). Default value: 0.
        Returns:
        an integer interpreted as one-bit flags specifying various characteristics of the annotation.

      • setFlags

        public PdfAnnotation setFlags​(int flags)
        Sets a set of flags specifying various characteristics of the annotation (see ISO-320001 12.5.3, "Annotation Flags"). On the contrary from setFlag(int), this method sets a complete set of enabled and disabled flags at once. If not set specifically the default value is 0.
        Parameters:
        flags - an integer interpreted as set of one-bit flags specifying various characteristics of the annotation.
        Returns:
        this PdfAnnotation instance.

      • setFlag

        public PdfAnnotation setFlag​(int flag)
        Sets a flag that specifies a characteristic of the annotation to enabled state (see ISO-320001 12.5.3, "Annotation Flags"). On the contrary from setFlags(int), this method sets only specified flags to enabled state, but doesn't disable other flags. Possible flags:
        • INVISIBLE - If set, do not display the annotation if it does not belong to one of the standard annotation types and no annotation handler is available. If clear, display such unknown annotation using an appearance stream specified by its appearance dictionary, if any.
        • HIDDEN - If set, do not display or print the annotation or allow it to interact with the user, regardless of its annotation type or whether an annotation handler is available.
        • PRINT - If set, print the annotation when the page is printed. If clear, never print the annotation, regardless of whether it is displayed on the screen.
        • NO_ZOOM - If set, do not scale the annotation’s appearance to match the magnification of the page. The location of the annotation on the page (defined by the upper-left corner of its annotation rectangle) shall remain fixed, regardless of the page magnification.}
        • NO_ROTATE - If set, do not rotate the annotation’s appearance to match the rotation of the page. The upper-left corner of the annotation rectangle shall remain in a fixed location on the page, regardless of the page rotation.
        • NO_VIEW - If set, do not display the annotation on the screen or allow it to interact with the user. The annotation may be printed (depending on the setting of the Print flag) but should be considered hidden for purposes of on-screen display and user interaction.
        • READ_ONLY - If set, do not allow the annotation to interact with the user. The annotation may be displayed or printed (depending on the settings of the NoView and Print flags) but should not respond to mouse clicks or change its appearance in response to mouse motions.
        • LOCKED - If set, do not allow the annotation to be deleted or its properties (including position and size) to be modified by the user. However, this flag does not restrict changes to the annotation’s contents, such as the value of a form field.
        • TOGGLE_NO_VIEW - If set, invert the interpretation of the NoView flag for certain events.
        • LOCKED_CONTENTS - If set, do not allow the contents of the annotation to be modified by the user. This flag does not restrict deletion of the annotation or changes to other annotation properties, such as position and size.
        Parameters:
        flag - - an integer interpreted as set of one-bit flags which will be enabled for this annotation.
        Returns:
        this PdfAnnotation instance.

      • resetFlag

        public PdfAnnotation resetFlag​(int flag)
        Resets a flag that specifies a characteristic of the annotation to disabled state (see ISO-320001 12.5.3, "Annotation Flags").
        Parameters:
        flag - an integer interpreted as set of one-bit flags which will be reset to disabled state.
        Returns:
        this PdfAnnotation instance.

      • hasFlag

        public boolean hasFlag​(int flag)
        Checks if the certain flag that specifies a characteristic of the annotation is in enabled state (see ISO-320001 12.5.3, "Annotation Flags"). This method allows only one flag to be checked at once, use constants listed in setFlag(int).
        Parameters:
        flag - an integer interpreted as set of one-bit flags. Only one bit must be set in this integer, otherwise exception is thrown.
        Returns:
        true if the given flag is in enabled state.

      • getAppearanceDictionary

        public PdfDictionary getAppearanceDictionary()
        An appearance dictionary specifying how the annotation shall be presented visually on the page during its interactions with the user (see ISO-320001 12.5.5, "Appearance Streams"). An appearance dictionary is a dictionary containing one or several appearance streams or subdictionaries.
        Returns:
        an appearance PdfDictionary or null if it is not specified.

      • getAppearanceObject

        public PdfDictionary getAppearanceObject​(PdfName appearanceType)
        Specific appearance object corresponding to the specific appearance type. This object might be either an appearance stream or an appearance subdictionary. In the latter case, the subdictionary defines multiple appearance streams corresponding to different appearance states of the annotation. See ISO-320001 12.5.5, "Appearance Streams".
        Parameters:
        appearanceType - a PdfName specifying appearance type. Possible types are Normal, Rollover and Down.
        Returns:
        null if their is no such appearance type or an appearance object which might be either an appearance stream or an appearance subdictionary.

      • getNormalAppearanceObject

        public PdfDictionary getNormalAppearanceObject()
        The normal appearance is used when the annotation is not interacting with the user. This appearance is also used for printing the annotation. See also getAppearanceObject(PdfName).
        Returns:
        an appearance object which might be either an appearance stream or an appearance subdictionary.

      • getRolloverAppearanceObject

        public PdfDictionary getRolloverAppearanceObject()
        The rollover appearance is used when the user moves the cursor into the annotation’s active area without pressing the mouse button. If not specified normal appearance is used. See also getAppearanceObject(PdfName).
        Returns:
        null if rollover appearance is not specified or an appearance object which might be either an appearance stream or an appearance subdictionary.

      • getDownAppearanceObject

        public PdfDictionary getDownAppearanceObject()
        The down appearance is used when the mouse button is pressed or held down within the annotation’s active area. If not specified normal appearance is used. See also getAppearanceObject(PdfName).
        Returns:
        null if down appearance is not specified or an appearance object which might be either an appearance stream or an appearance subdictionary.

      • getAppearanceState

        public PdfName getAppearanceState()
        The annotation’s appearance state, which selects the applicable appearance stream from an appearance subdictionary if there is such. See getAppearanceObject(PdfName) for more info.
        Returns:
        a PdfName which defines selected appearance state.

      • setAppearanceState

        public PdfAnnotation setAppearanceState​(PdfName as)
        Sets the annotation’s appearance state, which selects the applicable appearance stream from an appearance subdictionary. See getAppearanceObject(PdfName) for more info.
        Parameters:
        as - a PdfName which defines appearance state to be selected.
        Returns:
        this PdfAnnotation instance.

      • getBorder

        public PdfArray getBorder()
        An array specifying the characteristics of the annotation’s border. The array consists of three numbers defining the horizontal corner radius, vertical corner radius, and border width, all in default user space units. If the corner radii are 0, the border has square (not rounded) corners; if the border width is 0, no border is drawn.

        The array may have a fourth element, an optional dash array (see ISO-320001 8.4.3.6, "Line Dash Pattern").

        Returns:
        an PdfArray specifying the characteristics of the annotation’s border.

      • setBorder

        public PdfAnnotation setBorder​(PdfArray border)
        Sets the characteristics of the annotation’s border.
        Parameters:
        border - an PdfArray specifying the characteristics of the annotation’s border. See getBorder() for more detailes.
        Returns:
        this PdfAnnotation instance.

      • getColorObject

        public PdfArray getColorObject()
        An array of numbers in the range 0.0 to 1.0, representing a colour used for the following purposes:
        • The background of the annotation’s icon when closed
        • The title bar of the annotation’s pop-up window
        • The border of a link annotation
        The number of array elements determines the colour space in which the colour shall be defined:
        • 0 - No colour; transparent
        • 1 - DeviceGray
        • 3 - DeviceRGB
        • 4 - DeviceCMYK
        Returns:
        An array of numbers in the range 0.0 to 1.0, representing an annotation colour.

      • setColor

        public PdfAnnotation setColor​(PdfArray color)
        Sets an annotation color. For more details on annotation color purposes and the format of the passing PdfArray see getColorObject().
        Parameters:
        color - an array of numbers in the range 0.0 to 1.0, specifying color.
        Returns:
        this PdfAnnotation instance.

      • setColor

        public PdfAnnotation setColor​(float[] color)
        Sets an annotation color. For more details on annotation color purposes and the format of the passing array see getColorObject().
        Parameters:
        color - an array of numbers in the range 0.0 to 1.0, specifying color.
        Returns:
        this PdfAnnotation instance.

      • getStructParentIndex

        public int getStructParentIndex()
        The integer key of the annotation’s entry in the structural parent tree (see ISO-320001 14.7.4.4, "Finding Structure Elements from Content Items").
        Returns:
        integer key in structural parent tree or -1 if annotation is not tagged.

      • setStructParentIndex

        public PdfAnnotation setStructParentIndex​(int structParentIndex)
        Sets he integer key of the annotation’s entry in the structural parent tree (see ISO-320001 14.7.4.4, "Finding Structure Elements from Content Items"). Note: Normally, there is no need to take care of this manually, struct parent index is set automatically if annotation is added to the tagged document's page.
        Parameters:
        structParentIndex - integer which is to be the key of the annotation's entry in structural parent tree.
        Returns:
        this PdfAnnotation instance.

      • setTitle

        public PdfAnnotation setTitle​(PdfString title)
        Sets annotation title. This property affects not all annotation types.
        Parameters:
        title - a PdfString which value is to be annotation title.
        Returns:
        this PdfAnnotation instance.

      • getTitle

        public PdfString getTitle()
        Annotation title. For example for markup annotations, the title is the text label that shall be displayed in the title bar of the annotation’s pop-up window when open and active. For movie annotation Movie actions (ISO-320001 12.6.4.9, "Movie Actions") may use this title to reference the movie annotation.
        Returns:
        PdfString which value is an annotation title or null if it isn't specified.

      • setRectangle

        public PdfAnnotation setRectangle​(PdfArray array)
        The annotation rectangle, defining the location of the annotation on the page in default user space units.
        Parameters:
        array - a PdfArray which specifies a rectangle by two diagonally opposite corners. Typically, the array is of form [llx lly urx ury].
        Returns:
        this PdfAnnotation instance.

      • getRectangle

        public PdfArray getRectangle()
        The annotation rectangle, defining the location of the annotation on the page in default user space units.
        Returns:
        a PdfArray which specifies a rectangle by two diagonally opposite corners. Typically, the array is of form [llx lly urx ury].

      • getLang

        public java.lang.String getLang()
        PDF 2.0. A language identifier overriding the document’s language identifier to specify the natural language for all text in the annotation except where overridden by other explicit language specifications
        Returns:
        the lang entry

      • setLang

        public PdfAnnotation setLang​(java.lang.String lang)
        PDF 2.0. A language identifier overriding the document’s language identifier to specify the natural language for all text in the annotation except where overridden by other explicit language specifications
        Parameters:
        lang - language identifier
        Returns:
        this PdfAnnotation instance

      • getBlendMode

        public PdfName getBlendMode()
        PDF 2.0. The blend mode that shall be used when painting the annotation onto the page
        Returns:
        the blend mode

      • setBlendMode

        public PdfAnnotation setBlendMode​(PdfName blendMode)
        PDF 2.0. The blend mode that shall be used when painting the annotation onto the page
        Parameters:
        blendMode - blend mode
        Returns:
        this PdfAnnotation instance

      • getNonStrokingOpacity

        public float getNonStrokingOpacity()
        PDF 2.0. When regenerating the annotation's appearance stream, this is the opacity value that shall be used for all nonstroking operations on all visible elements of the annotation in its closed state (including its background and border) but not the popup window that appears when the annotation is opened.
        Returns:
        opacity value for nonstroking operations. Returns 1.0 (default value) if entry is not present

      • setNonStrokingOpacity

        public PdfAnnotation setNonStrokingOpacity​(float nonStrokingOpacity)
        PDF 2.0. When regenerating the annotation's appearance stream, this is the opacity value that shall be used for all nonstroking operations on all visible elements of the annotation in its closed state (including its background and border) but not the popup window that appears when the annotation is opened.
        Parameters:
        nonStrokingOpacity - opacity for nonstroking operations
        Returns:
        this PdfAnnotation instance

      • getStrokingOpacity

        public float getStrokingOpacity()
        PDF 2.0. When regenerating the annotation's appearance stream, this is the opacity value that shall be used for stroking all visible elements of the annotation in its closed state, including its background and border, but not the popup window that appears when the annotation is opened.
        Returns:
        opacity for stroking operations, including background and border

      • setStrokingOpacity

        public PdfAnnotation setStrokingOpacity​(float strokingOpacity)
        PDF 2.0. When regenerating the annotation's appearance stream, this is the opacity value that shall be used for stroking all visible elements of the annotation in its closed state, including its background and border, but not the popup window that appears when the annotation is opened.
        Parameters:
        strokingOpacity - opacity for stroking operations, including background and border
        Returns:
        this PdfAnnotation object

      • put

        public PdfAnnotation put​(PdfName key,
                         PdfObject value)
        Inserts the value into into the underlying PdfDictionary of this PdfAnnotation and associates it with the specified key. If the key is already present in this PdfAnnotation, this method will override the old value with the specified one.
        Parameters:
        key - key to insert or to override
        value - the value to associate with the specified key
        Returns:
        this PdfAnnotation instance.

      • addAssociatedFile

        public void addAssociatedFile​(PdfFileSpec fs)

        Adds file associated with PDF annotation and identifies the relationship between them.

        Associated files may be used in Pdf/A-3 and Pdf 2.0 documents. The method adds file to array value of the AF key in the annotation dictionary.

        For associated files their associated file specification dictionaries shall include the AFRelationship key

        Parameters:
        fs - file specification dictionary of associated file

      • getAssociatedFiles

        public PdfArray getAssociatedFiles​(boolean create)
        Returns files associated with PDF annotation.
        Parameters:
        create - defines whether AF arrays will be created if it doesn't exist
        Returns:
        associated files array

      • flush

        public void flush()
        To manually flush a PdfObject behind this wrapper, you have to ensure that this object is added to the document, i.e. it has an indirect reference. Basically this means that before flushing you need to explicitly call PdfObjectWrapper.makeIndirect(PdfDocument). For example: wrapperInstance.makeIndirect(document).flush(); Note that not every wrapper require this, only those that have such warning in documentation.
        Overrides:
        flush in class PdfObjectWrapper<PdfDictionary>

      • isWrappedObjectMustBeIndirect

        protected boolean isWrappedObjectMustBeIndirect()
        Description copied from class: PdfObjectWrapper
        Defines if the object behind this wrapper must be an indirect object in the resultant document.

        If this method returns true it doesn't necessarily mean that object must be in the indirect state at any moment, but rather defines that when the object will be written to the document it will be transformed into indirect object if it's not indirect yet.

        Return value of this method shouldn't depend on any logic, it should return always true or false.
        Specified by:
        isWrappedObjectMustBeIndirect in class PdfObjectWrapper<PdfDictionary>
        Returns:
        true if in the resultant document the object behind the wrapper must be indirect, otherwise false.