org.icepdf.core.pobjects.annotations
Class Annotation

java.lang.Object
  org.icepdf.core.pobjects.Dictionary
      org.icepdf.core.pobjects.annotations.Annotation

Direct Known Subclasses:

LinkAnnotation

public class Annotation
extends Dictionary

An Annotation class associates an object such as a note, sound, or movie with a location on a page of a PDF document, or provides a way to interact with the user by means of the mouse and keyboard.

This class allows direct access to the a Annotations dictionary. Developers can take advantage of this information as they see fit. It is important to note that an annotations' rectangle coordinates are defined in the PDF document space. In order to map the rectangle coordinates to a view, they must be converted from the Cartesian plain to the the Java2D plain. The PageView method getPageBounds() can be used to locate the position of a page within its parent component.

Base class of all the specific Annotation types

Taken from the PDF 1.6 spec, here is some relevant documentation, along with some additional commentary

8.4.1 Annotation Dictionaries

Key	Type	Value
Type	name	(Optional) The type of PDF object that this dictionary describes; if present, must be Annot for an annotation dictionary.
Subtype	name	(Required) The type of annotation that this dictionary describes.
Rect	rectangle	(Required) The annotation rectangle, defining the location of the annotation on the page in default user space units.	getUserspaceLocation()
Contents	text string	(Optional) Text to 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.'s contents in support of accessibility to users with disabilities or for other purposes (see Section 10.8.2, "Alternate Descriptions"). See Section 8.4.5, "Annotation Types" for more details on the meaning of this entry for each annotation type.
P	dictionary	(Optional; PDF 1.3; not used in FDF files) An indirect reference to the page object with which this annotation is associated.
NM	text string	(Optional; PDF 1.4) The annotation name, a text string uniquely identifying it among all the annotations on its page.
M	date or string	(Optional; PDF 1.1) The date and time when the annotation was most recently modified. The preferred format is a date string as described in Section 3.8.3, "Dates," but viewer applications should be prepared to accept and display a string in any format. (See implementation note 78 in Appendix H.)
F	integer	(Optional; PDF 1.1) A set of flags specifying various characteristics of the annotation (see Section 8.4.2, "Annotation Flags"). Default value: 0.
BS	dictionary	(Optional; PDF 1.2) A border style dictionary specifying the characteristics of the annotation's border (see Section 8.4.3, "Border Styles"; see also implementation notes 79 and 86 in Appendix H). Note: This entry also specifies the width and dash pattern for the lines drawn by line, square, circle, and ink annotations. See the note under Border (below) for additional information. Table 8.13 summarizes the contents of the border style dictionary. If neither the Border nor the BS entry is present, the border is drawn as a solid line with a width of 1 point.
AP	dictionary	(Optional; PDF 1.2) An appearance dictionary specifying how the annotation is presented visually on the page (see Section 8.4.4, "Appearance Streams" and also implementation notes 79 and 80 in Appendix H). Individual annotation handlers may ignore this entry and provide their own appearances. For convenience in managing appearance streams that are used repeatedly, the AP entry in a PDF document's name dictionary (see Section 3.6.3, "Name Dictionary") can contain a name tree mapping name strings to appearance streams. The name strings have no standard meanings; no PDF objects refer to appearance streams by name.
AS	name	(Required if the appearance dictionary AP contains one or more subdictionaries; PDF 1.2) The annotation's appearance state, which selects the applicable appearance stream from an appearance subdictionary (see Section 8.4.4, "Appearance Streams" and also implementation note 79 in Appendix H).
Border	array	(Optional) An array specifying the characteristics of the annotation's border. The border is specified as a rounded rectangle. In PDF 1.0, 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. (See implementation note 81 in Appendix H.) In PDF 1.1, the array may have a fourth element, an optional dash array defining a pattern of dashes and gaps to be used in drawing the border. The dash array is specified in the same format as in the line dash pattern parameter of the graphics state (see "Line Dash Pattern" on page 187). For example, a Border value of [0 0 1 [3 2]] specifies a border 1 unit wide, with square corners, drawn with 3-unit dashes alternating with 2-unit gaps. Note that no dash phase is specified; the phase is assumed to be 0. (See implementation note 82 in Appendix H.) Note: In PDF 1.2 or later, this entry may be ignored in favor of the BS entry (see above); see implementation note 86 in Appendix H. Default value: [0 0 1].
BE	dictionary	(Optional; PDF 1.5) Some annotations (square, circle, and polygon) may have a BE entry, which is a border effect dictionary that specifies an effect to be applied to the border of the annotations. Its entries are listed in Table 8.14.
C	array	(Optional; PDF 1.1) An array of three numbers in the range 0.0 to 1.0, representing the components of a color in the DeviceRGB color space. This color is 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
A	dictionary	(Optional; PDF 1.1) An action to be performed when the annotation is activated (see Section 8.5, "Actions"). Note: This entry is not permitted in link annotations if a Dest entry is present (see "Link Annotations" on page 587). Also note that the A entry in movie annotations has a different meaning (see "Movie Annotations" on page 601).
AA	dictionary	(Optional; PDF 1.2) An additional-actions dictionary defining the annotation's behavior in response to various trigger events (see Section 8.5.2, "Trigger Events"). At the time of publication, this entry is used only by widget annotations.
StructParent	integer	((Required if the annotation is a structural content item; PDF 1.3) The integer key of the annotation's entry in the structural parent tree (see "Finding Structure Elements from Content Items" on page 797).
OC	dictionary	(Optional; PDF 1.5) An optional content group or optional content membership dictionary (see Section 4.10, "Optional Content") specifying the optional content properties for the annotation. Before the annotation is drawn, its visibility is determined based on this entry as well as the annotation flags specified in the F entry (see Section 8.4.2, "Annotation Flags"). If it is determined to be invisible, the annotation is skipped, as if it were not in the document.

8.4.2 Annotation Flags

The value of the annotation dictionary's F entry is an unsigned 32-bit integer containing flags specifying various characteristics of the annotation. Bit positions within the flag word are numbered from 1 (low-order) to 32 (high-order). Table 8.12 shows the meanings of the flags; all undefined flag bits are reserved and must be set to 0.

Bit position	Name	Meaning
1	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 an unknown annotation using an appearance stream specified by its appearance dictionary, if any (see Section 8.4.4, "Appearance Streams").
2	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. In cases where screen space is limited, the ability to hide and show annotations selectively can be used in combination with appearance streams (see Section 8.4.4, "Appearance Streams") to display auxiliary pop-up information similar in function to online help systems. (See implementation note 83 in Appendix H.)
3	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. This can be useful, for example, for annotations representing interactive pushbuttons, which would serve no meaningful purpose on the printed page. (See implementation note 83 in Appendix H.)
4	NoZoom	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) remains fixed, regardless of the page magnification. See below for further discussion.
5	NoRotate	If set, do not rotate the annotation's appearance to match the rotation of the page. The upper-left corner of the annotation rectangle remains in a fixed location on the page, regardless of the page rotation. See below for further discussion.
6	NoView	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.
7	ReadOnly	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. Note: This flag is ignored for widget annotations; its function is subsumed by the ReadOnly flag of the associated form field (see Table 8.66 on page 638).
8	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. (See implementation note 84 in Appendix H.)
9	ToggleNoView	If set, invert the interpretation of the NoView flag for certain events. A typical use is to have an annotation that appears only when a mouse cursor is held over it; see implementation note 85 in Appendix H.

Since:

2.5

Author:

Mark Collette

Field Summary

static Name	ACTION_KEY The action to be performed whenteh annotation is activated.
static Name	APPEARANCE_STATE_KEY Appearance state selecting default from multiple AP's.
static Name	APPEARANCE_STREAM_DOWN_KEY Appearance dictionary specifying how the annotation is presented visually on the page for down display.
static Name	APPEARANCE_STREAM_KEY Appearance dictionary specifying how the annotation is presented visually on the page.
static Name	APPEARANCE_STREAM_NORMAL_KEY Appearance dictionary specifying how the annotation is presented visually on the page for normal display.
static Name	APPEARANCE_STREAM_ROLLOVER_KEY Appearance dictionary specifying how the annotation is presented visually on the page for rollover display.
protected java.util.Vector<java.lang.Number>	border
static int	BORDER_DASH
static int	BORDER_HORIZONTAL_CORNER_RADIUS Border property indexes for the border vector, only applicable if the border style has not been set.
static Name	BORDER_KEY Annotation border characteristics.
static Name	BORDER_STYLE_KEY Border style
static int	BORDER_VERTICAL_CORNER_RADIUS
static int	BORDER_WIDTH
protected BorderStyle	borderStyle
protected boolean	canDrawBorder
protected java.awt.Color	color
static Name	COLOR_KEY RGB colour value for background, titlebars and link annotation borders
static Name	FLAG_KEY Annotation border characteristics.
static int	INVISIBLE_RECTANGLE
static Name	PARENT_PAGE_KEY Page that this annotation is associated with.
static Name	RECTANGLE_KEY The annotation location on the page in user space units.
protected Name	subtype
static Name	SUBTYPE_CIRCLE
static Name	SUBTYPE_HIGHLIGHT
static Name	SUBTYPE_LINE
static Name	SUBTYPE_LINK Annotation subtype and types.
static Name	SUBTYPE_POLYGON
static Name	SUBTYPE_POLYLINE
static Name	SUBTYPE_SQUARE
static Name	TYPE_VALUE Dictionary constants for Annotations.
protected java.awt.geom.Rectangle2D.Float	userSpaceRectangle
static int	VISIBLE_RECTANGLE Annotion may or may not have a visible rectangle border

Fields inherited from class org.icepdf.core.pobjects.Dictionary

entries, inited, isDeleted, isNew, library, SUBTYPE_KEY, TYPE_KEY

Constructor Summary

Annotation(Library l, java.util.Hashtable h)
Creates a new instance of an Annotation.

Method Summary

Action	addAction(Action action) Adds the specified action to this annotation isnstance.
boolean	allowAlterProperties()
boolean	allowPrintNormalMode()
boolean	allowScreenDownMode()
boolean	allowScreenNormalMode()
protected boolean	allowScreenOrPrintRenderingOrInteraction()
boolean	allowScreenRolloverMode()
static Annotation	buildAnnotation(Library library, java.util.Hashtable hashTable) Should only be called from Parser, Use AnnotationFactory if you creating a new annotation.
boolean	deleteAction(Action action) Deletes the annotation action specified as a paramater.
Action	getAction() Gets the action to be performed when the annotation is activated.
java.util.Vector<java.lang.Number>	getBorder()
BorderStyle	getBorderStyle()
java.awt.Color	getColor() Gest the RGB colour of the annotation used for the following purposes: the background of the annotaiton's icon when closed the title bar of the anntoation's pop-up window the border of a link annotation
boolean	getFlagHidden()
boolean	getFlagInvisible()
boolean	getFlagLocked() A locked annotation can not be deleted or its properties such as position and size to be modified by the user.
boolean	getFlagNoRotate()
boolean	getFlagNoView()
boolean	getFlagNoZoom()
boolean	getFlagPrint()
boolean	getFlagReadOnly()
boolean	getFlagToggleNoView()
java.lang.String	getLineStyle() Gets the Annotation border style for the given annotation.
float	getLineThickness() Gets the line thickness assoicated with this annotation.
int	getLinkType() Gets the Link type, can be either VISIBLE_RECTANGLE or INVISIBLE_RECTANGLE, it all depends on the if the border or BS has border width > 0.
Page	getPage()
Annotation	getParentAnnotation()
java.lang.String	getSubType() Gets the type of annotation that this dictionary describes.
java.awt.geom.Rectangle2D.Float	getUserSpaceRectangle() Gets the annotation rectangle, and defines the location of the annotation on the page in default user space units.
boolean	isBorder() Checks to see if the annotation has defined a drawable border width.
protected boolean	isSupportedAnnotationType() The PDF spec defines rules for displaying annotation subtypes that the viewer does not recognise.
void	render(java.awt.Graphics2D origG, int renderHintType, float totalRotation, float userZoom, boolean tabSelected)
protected void	renderAppearanceStream(java.awt.Graphics2D g)
protected void	renderBorder(java.awt.Graphics2D g)
protected void	renderBorderTabSelected(java.awt.Graphics2D g)
void	setBorderStyle(BorderStyle borderStyle)
void	setColor(java.awt.Color color) Sets the Annotation colour and underlying
void	setUserSpaceRectangle(java.awt.geom.Rectangle2D.Float rect) Sets the users page rectangle for this annotation action instance
java.lang.String	toString() Returns a summary of the dictionary entries.
boolean	updateAction(Action action) Update the current annotation action with this entry.

Methods inherited from class org.icepdf.core.pobjects.Dictionary

getEntries, getFloat, getInt, getLibrary, getNumber, getObject, getObject, getPObjectReference, init, isDeleted, isNew, setDeleted, setNew, setPObjectReference

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

TYPE_VALUE

public static final Name TYPE_VALUE

Dictionary constants for Annotations.

SUBTYPE_LINK

public static final Name SUBTYPE_LINK

Annotation subtype and types.

SUBTYPE_LINE

public static final Name SUBTYPE_LINE

SUBTYPE_SQUARE

public static final Name SUBTYPE_SQUARE

SUBTYPE_CIRCLE

public static final Name SUBTYPE_CIRCLE

SUBTYPE_POLYGON

public static final Name SUBTYPE_POLYGON

SUBTYPE_POLYLINE

public static final Name SUBTYPE_POLYLINE

SUBTYPE_HIGHLIGHT

public static final Name SUBTYPE_HIGHLIGHT

BORDER_STYLE_KEY

public static final Name BORDER_STYLE_KEY

Border style

RECTANGLE_KEY

public static final Name RECTANGLE_KEY

The annotation location on the page in user space units.

ACTION_KEY

public static final Name ACTION_KEY

The action to be performed whenteh annotation is activated.

PARENT_PAGE_KEY

public static final Name PARENT_PAGE_KEY

Page that this annotation is associated with.

BORDER_KEY

public static final Name BORDER_KEY

Annotation border characteristics.

FLAG_KEY

public static final Name FLAG_KEY

Annotation border characteristics.

COLOR_KEY

public static final Name COLOR_KEY

RGB colour value for background, titlebars and link annotation borders

APPEARANCE_STREAM_KEY

public static final Name APPEARANCE_STREAM_KEY

Appearance dictionary specifying how the annotation is presented visually on the page.

APPEARANCE_STATE_KEY

public static final Name APPEARANCE_STATE_KEY

Appearance state selecting default from multiple AP's.

APPEARANCE_STREAM_NORMAL_KEY

public static final Name APPEARANCE_STREAM_NORMAL_KEY

Appearance dictionary specifying how the annotation is presented visually on the page for normal display.

APPEARANCE_STREAM_ROLLOVER_KEY

public static final Name APPEARANCE_STREAM_ROLLOVER_KEY

Appearance dictionary specifying how the annotation is presented visually on the page for rollover display.

APPEARANCE_STREAM_DOWN_KEY

public static final Name APPEARANCE_STREAM_DOWN_KEY

Appearance dictionary specifying how the annotation is presented visually on the page for down display.

BORDER_HORIZONTAL_CORNER_RADIUS

public static final int BORDER_HORIZONTAL_CORNER_RADIUS

Border property indexes for the border vector, only applicable if the border style has not been set.

See Also:

Constant Field Values

BORDER_VERTICAL_CORNER_RADIUS

public static final int BORDER_VERTICAL_CORNER_RADIUS

See Also:

Constant Field Values

BORDER_WIDTH

public static final int BORDER_WIDTH

See Also:

Constant Field Values

BORDER_DASH

public static final int BORDER_DASH

See Also:

Constant Field Values

VISIBLE_RECTANGLE

public static final int VISIBLE_RECTANGLE

Annotion may or may not have a visible rectangle border

See Also:

Constant Field Values

INVISIBLE_RECTANGLE

public static final int INVISIBLE_RECTANGLE

See Also:

Constant Field Values

subtype

protected Name subtype

borderStyle

protected BorderStyle borderStyle

border

protected java.util.Vector<java.lang.Number> border

color

protected java.awt.Color color

userSpaceRectangle

protected java.awt.geom.Rectangle2D.Float userSpaceRectangle

canDrawBorder

protected boolean canDrawBorder

Constructor Detail

Annotation

public Annotation(Library l,
                  java.util.Hashtable h)

Creates a new instance of an Annotation.

Parameters:

l - document library.

h - dictionary entries.

Method Detail

buildAnnotation

public static Annotation buildAnnotation(Library library,
                                         java.util.Hashtable hashTable)

Should only be called from Parser, Use AnnotationFactory if you creating a new annotation.

Parameters:

library - document library

hashTable - annotation properties.

Returns:

annotation instance.

getSubType

public java.lang.String getSubType()

Gets the type of annotation that this dictionary describes. For compatibility with the old org.icepdf.core.pobjects.Annotation.getSubType()

Returns:

subtype of annotation

getUserSpaceRectangle

public java.awt.geom.Rectangle2D.Float getUserSpaceRectangle()

Gets the annotation rectangle, and defines the location of the annotation on the page in default user space units. For compatibility with the old org.icepdf.core.pobjects.Annotation.getRectangle()

Returns:

rectangle of annotation

setUserSpaceRectangle

public void setUserSpaceRectangle(java.awt.geom.Rectangle2D.Float rect)

Sets the users page rectangle for this annotation action instance

getAction

public Action getAction()

Gets the action to be performed when the annotation is activated. For compatibility with the old org.icepdf.core.pobjects.Annotation.getAction()

Returns:

action to be activated, if no action, null is returned.

addAction

public Action addAction(Action action)

Adds the specified action to this annotation isnstance. If the annotation instance already has an action then this action replaces it.

todo: future enhancment add support of next/muliple action chains.

Parameters:

action - action to add to this annotation. This action must be created using the the ActionFactory in order to correctly setup the Pobject reference.

Returns:

action that was added to Annotation, null if it was not success fully added.

deleteAction

public boolean deleteAction(Action action)

Deletes the annotation action specified as a paramater. If an instance of the specified action can not be found, no delete is make.

Parameters:

action - action to remove

Returns:

true if the delete was successful, false otherwise.

updateAction

public boolean updateAction(Action action)

Update the current annotation action with this entry. This is very similar to add but this method will return false if there was no previous annotation. In such a case a call to addAction should be made.

Parameters:

action - action to update

Returns:

true if the update was successful, othere; false.

allowScreenNormalMode

public boolean allowScreenNormalMode()

allowScreenRolloverMode

public boolean allowScreenRolloverMode()

allowScreenDownMode

public boolean allowScreenDownMode()

allowPrintNormalMode

public boolean allowPrintNormalMode()

allowAlterProperties

public boolean allowAlterProperties()

setBorderStyle

public void setBorderStyle(BorderStyle borderStyle)

getBorderStyle

public BorderStyle getBorderStyle()

getBorder

public java.util.Vector<java.lang.Number> getBorder()

getParentAnnotation

public Annotation getParentAnnotation()

getPage

public Page getPage()

getLinkType

public int getLinkType()

Gets the Link type, can be either VISIBLE_RECTANGLE or INVISIBLE_RECTANGLE, it all depends on the if the border or BS has border width > 0.

Returns:

VISIBLE_RECTANGLE if the annotation has a visible borde, otherwise INVISIBLE_RECTANGLE

getLineStyle

public java.lang.String getLineStyle()

Gets the Annotation border style for the given annotation. If no annotation line style can be found the default value of BORDER_STYLE_SOLID is returned. Otherwise the bordStyle and border dictionaries are used to deduse a line style.

Returns:

BorderSTyle line constants.

getLineThickness

public float getLineThickness()

Gets the line thickness assoicated with this annotation.

Returns:

point value used when drawing line thickness.

isBorder

public boolean isBorder()

Checks to see if the annotation has defined a drawable border width.

Returns:

true if a border will be drawn; otherwise, false.

render

public void render(java.awt.Graphics2D origG,
                   int renderHintType,
                   float totalRotation,
                   float userZoom,
                   boolean tabSelected)

renderAppearanceStream

protected void renderAppearanceStream(java.awt.Graphics2D g)

renderBorder

protected void renderBorder(java.awt.Graphics2D g)

renderBorderTabSelected

protected void renderBorderTabSelected(java.awt.Graphics2D g)

getColor

public java.awt.Color getColor()

Gest the RGB colour of the annotation used for the following purposes:

• the background of the annotaiton's icon when closed
• the title bar of the anntoation's pop-up window
• the border of a link annotation

Returns:

A Color for the border, or null if none is to be used

setColor

public void setColor(java.awt.Color color)

Sets the Annotation colour and underlying

Parameters:

color -

allowScreenOrPrintRenderingOrInteraction

protected boolean allowScreenOrPrintRenderingOrInteraction()

Returns:

Whether this annotation may be shown in any way to the user

isSupportedAnnotationType

protected boolean isSupportedAnnotationType()

The PDF spec defines rules for displaying annotation subtypes that the viewer does not recognise. But, from a product point of view, we may or may not wish to make a best attempt at showing an unsupported annotation subtype, as that may make users think we're quality deficient, instead of feature deficient. Subclasses should override this, and return true, indicating that that particular annotation is supported.

Returns:

true, if this annotation is supported; else, false.

getFlagInvisible

public boolean getFlagInvisible()

getFlagHidden

public boolean getFlagHidden()

getFlagPrint

public boolean getFlagPrint()

getFlagNoZoom

public boolean getFlagNoZoom()

getFlagNoRotate

public boolean getFlagNoRotate()

getFlagNoView

public boolean getFlagNoView()

getFlagReadOnly

public boolean getFlagReadOnly()

getFlagLocked

public boolean getFlagLocked()

A locked annotation can not be deleted or its properties such as position and size to be modified by the user. This property does not restrict annotation contents such as the value of a form field.

Returns:

true if locked, false otherwise.

getFlagToggleNoView

public boolean getFlagToggleNoView()

toString

public java.lang.String toString()

Description copied from class: Dictionary

Returns a summary of the dictionary entries.

Overrides:

toString in class Dictionary

Returns:

dictionary values.