Class Annot

Annot is a base class for different types of annotations. For annotation specific properties, please refer to derived classes.

An annotation is an interactive object placed on a page, such as a text note, a link, or an embedded file. PDF includes a wide variety of standard annotation types. An annotation associates an object such as a widget, note, or movie with a location on a page of a PDF document, or provides a means of interacting with the user via the mouse and keyboard. For more details on PDF annotations please refer to section 12.5 in the PDF Reference Manual and the

Inheritance

System.Object

Annot

Link

Markup

Movie

Popup

Screen

Watermark

Widget

Implements

System.IDisposable

Inherited Members

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: pdftron.PDF

Assembly: PDFTronDotNet.dll

Syntax

public class Annot : IDisposable

Constructors

Annot(Annot)

create and initialize Annot object from a given one

Declaration

public Annot(Annot b)

Parameters

Type	Name	Description
Annot	b	another Annot object

Annot(Obj)

Create an annotation and initialize it using given Cos/SDF object.

Declaration

public Annot(Obj b)

Parameters

Type	Name	Description
Obj	b	a Obj object

Remarks

The constructor does not copy any data, but is instead the logical equivalent of a type cast.

Methods

Create(SDFDoc, Annot.Type, Rect)

Creates a new annotation of a given type, in the specified document. Because the newly created annotation does not contain any properties specific to a given annotation type, it is faster to create an annotation using type specific Annot.Create method.

Declaration

public static Annot Create(SDFDoc doc, Annot.Type type, Rect pos)

Parameters

Type	Name	Description
SDFDoc	doc	A document to which the annotation is added.
Annot.Type	type	Subtype of annotation to create.
Rect	pos	A rectangle specifying the annotation's bounds, specified in user space coordinates.

Returns

Type	Description
Annot	A newly created blank annotation for the given annotation type.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

CreateInternal(IntPtr, Object)

Create a new annotation object using native impl pointer For internal use only.

Declaration

public static Annot CreateInternal(IntPtr imp, object reference)

Parameters

Type	Name	Description
System.IntPtr	imp	impl pointer from PDFNet core.
System.Object	reference

Returns

Type	Description
Annot

DeleteCustomData(String)

Deletes custom data associated with the given key.

Declaration

public void DeleteCustomData(string key)

Parameters

Type	Name	Description
System.String	key	The key for which to delete the associated data.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Dispose()

Declaration

public void Dispose()

Dispose(Boolean)

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
System.Boolean	disposing

Equals(Object)

Declaration

public override bool Equals(object o)

Parameters

Type	Name	Description
System.Object	o	a given Object

Returns

Type	Description
System.Boolean	true, if equals to the given object

Overrides

System.Object.Equals(System.Object)

Finalize()

Releases all resources used by the Annot

Declaration

protected void Finalize()

Flatten(Page)

Flatten/Merge the existing annotation appearances with the page content and delete this annotation from a given page.

Annotation 'flattening' refers to the operation that changes active annotations (such as markup, widgets, 3D models, etc.) into a static area that is part of the PDF document, just like the other text and images in the document.

Declaration

public void Flatten(Page page)

Parameters

Type	Name	Description
Page	page	the page

Remarks

an alternative approach to set the annotation as read only is using

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetActiveAppearanceState()

Gets the annotation’s active appearance state.

Declaration

public string GetActiveAppearanceState()

Returns

Type	Description
System.String	the name of the active state. The annotation’s appearance state, which selects the applicable appearance stream from an appearance subdictionary.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetAppearance()

Gets the annotation’s appearance for the given combination of annotation and appearance states.

Declaration

public Obj GetAppearance()

Returns

Type	Description
Obj	The appearance stream for this annotation, or NULL if the annotation does not have an appearance for the given combination of annotation and appearance states.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetAppearance(Annot.AnnotationState)

Gets the annotation’s appearance for the given combination of annotation and appearance states.

Declaration

public Obj GetAppearance(Annot.AnnotationState annot_state)

Parameters

Type	Name	Description
Annot.AnnotationState	annot_state	The annotation’s appearance state, which selects the applicable appearance stream from the appearance sub-dictionary. An annotation can define as many as three separate appearances: The normal, rollover, and down appearance.

Returns

Type	Description
Obj	the appearance

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetAppearance(Annot.AnnotationState, String)

Gets the annotation’s appearance for the given combination of annotation and appearance states.

Declaration

public Obj GetAppearance(Annot.AnnotationState annot_state, string app_state)

Parameters

Type	Name	Description
Annot.AnnotationState	annot_state	The annotation’s appearance state, which selects the applicable appearance stream from the appearance sub-dictionary. An annotation can define as many as three separate appearances: The normal, rollover, and down appearance.
System.String	app_state	Is an optional parameter specifying the appearance state to look for (e.g. "Off", "On", etc). If appearance_state is NULL, the choice between different appearance states is determined by the AS (Appearance State) entry in the annotation dictionary.

Returns

Type	Description
Obj	The appearance stream for this annotation, or NULL if the annotation does not have an appearance for the given combination of annotation and appearance states.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetBorderStyle()

Gets the border style for the annotation. Typically used for Link annotations.

Declaration

public Annot.BorderStyle GetBorderStyle()

Returns

Type	Description
Annot.BorderStyle	Annotation's border style.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetColorAsCMYK()

Gets an annotation's color.

Declaration

public ColorPt GetColorAsCMYK()

Returns

Type

Description

ColorPt

A ColorPt object containing an array of four numbers in the range 0.0 to 1.0, representing a CMYK 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 If the annotation does not specify an explicit color, a default color is returned. Text annotations return 'default yellow;' all others return black.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetColorAsGray()

Gets an annotation's color.

Declaration

public ColorPt GetColorAsGray()

Returns

Type

Description

ColorPt

A ColorPt object containing a number in the range 0.0 to 1.0, representing a Gray Scale 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 If the annotation does not specify an explicit color, a default color is returned. Text annotations return 'default yellow;' all others return black.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetColorAsRGB()

Gets an annotation's color.

Declaration

public ColorPt GetColorAsRGB()

Returns

Type

Description

ColorPt

A ColorPt object containing an array of three numbers in the range 0.0 to 1.0, representing an RGB 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 If the annotation does not specify an explicit color, a default color is returned. Text annotations return 'default yellow;' all others return black.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetColorCompNum()

Gets the color space the annotation's color is represented in.

Declaration

public int GetColorCompNum()

Returns

Type	Description
System.Int32	An integer that is either 1(for DeviceGray), 3(DeviceRGB), or 4(DeviceCMYK). If the annotation has no color, i.e. is transparent, 0 will be returned.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetContents()

Gets the contents.

Declaration

public string GetContents()

Returns

Type	Description
System.String	the contents

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetCustomData(String)

Returns custom data associated with the given key.

Declaration

public string GetCustomData(string key)

Parameters

Type	Name	Description
System.String	key	The key for which to retrieve the associated data.

Returns

Type	Description
System.String	the custom data string. If no data is available an empty string is returned.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetDate()

Gets an annotation's last modified date.

Declaration

public Date GetDate()

Returns

Type	Description
Date	The annotation's time and date. If the annotation has no associated date structure, the returned date is not valid (date.IsValid() returns false). Corresponds to the "M" entry of the annotation dictionary.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetFlag(Annot.Flag)

Gets the flag.

Declaration

public bool GetFlag(Annot.Flag flag)

Parameters

Type	Name	Description
Annot.Flag	flag	The Flag property to query.

Returns

Type	Description
System.Boolean	The value of given Flag

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetHandleInternal()

Declaration

public IntPtr GetHandleInternal()

Returns

Type	Description
System.IntPtr

GetOptionalContent()

Gets optional content of an annotation.

Declaration

public Obj GetOptionalContent()

Returns

Type	Description
Obj	An SDF object corresponding to the grup of optional properties.

Remarks

The return value is an (optional content) group or (optional content) membership dictionary (PDF.OCG.OCMD)specifying the optional content properties for the annotation. Before the annotation is drawn, its visibility shall be determined based on this entry as well as the annotation flags specified in the Flag entry . If it is determined to be invisible, the annotation shall be skipped, as if it were not in the document.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetPage()

Gets the page the annotation is associated with.

Declaration

public Page GetPage()

Returns

Type	Description
Page	A Page object or NULL if the page reference is not available. The page object returned is an indirect reference to the page object with which this annotation is associated. This entry shall be present in screen annotations associated with rendition actions. Optional. PDF 1.3 PDF 1.4 PDF 1.5 not used in FDF files.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetRect()

Gets the rect.

Declaration

public Rect GetRect()

Returns

Type	Description
Rect	Annotation’s bounding rectangle, specified in user space coordinates. The meaning of the rectangle depends on the annotation type. For Link and RubberStamp annotations, the rectangle specifies the area containing the hyperlink area or stamp. For Note annotations, the rectangle is describing the popup window when it's opened. When it's closed, the icon is positioned at lower left corner.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetRefHandleInternal()

Declaration

public object GetRefHandleInternal()

Returns

Type	Description
System.Object

GetRotation()

Gets the rotation value of the annotation. The Rotation specifies the number of degrees by which the annotation shall be rotated counterclockwise relative to the page. The value shall be a multiple of 90.

Declaration

public int GetRotation()

Returns

Type	Description
System.Int32	An integer representing the rotation value of the annotation.

Remarks

This property is part of the appearance characteristics dictionary, this dictionary that shall be used in constructing a dynamic appearance stream specifying the annotation’s visual presentation on the page.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetSDFObj()

Gets the SDFObj.

Declaration

public Obj GetSDFObj()

Returns

Type	Description
Obj	The underlying SDF/Cos object.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetStructParent()

Gets the struct parent of an annotation. (Required if the annotation is a structural content item; PDF 1.3)

Declaration

public int GetStructParent()

Returns

Type	Description
System.Int32	An integer which is the integer key of the annotation’s entry in the structural parent tree.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetType()

Gets the type.

Declaration

public Annot.Type GetType()

Returns

Type	Description
Annot.Type	The type of this annotation.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetUniqueID()

Gets the unique ID.

Declaration

public Obj GetUniqueID()

Returns

Type	Description
Obj	The unique identifier for this annotation, or NULL if the identifier is not available. The returned value is a string object and is the value of the "NM" field, which was added as an optional attribute in PDF 1.4.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetVisibleContentBox()

It is possible during viewing that GetRect does not return the most accurate bounding box of what is actually rendered. This method calculates the bounding box, rather than relying on what is specified in the PDF document. The bounding box is defined as the smallest rectangle that includes all the visible content on the annotation.

Declaration

public Rect GetVisibleContentBox()

Returns

Type	Description
Rect	the bounding box for this annotation. The dimensions are specified in user space coordinates.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsMarkup()

Checks if is markup.

Declaration

public bool IsMarkup()

Returns

Type	Description
System.Boolean	true, if is markup

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsValid()

Checks if is valid.

Declaration

public bool IsValid()

Returns

Type	Description
System.Boolean	True if this is a valid (non-null) annotation, false otherwise. If the function returns false the underlying SDF/Cos object is null or is not valid and the annotation object should be treated as a null object.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

op_Assign(Annot)

Assignment operator

Declaration

public Annot op_Assign(Annot r)

Parameters

Type	Name	Description
Annot	r	a Annot object

Returns

Type	Description
Annot	a Annotobject equals to the given one

RefreshAppearance()

Regenerates the appearance stream for the annotation. This method can be used to auto-generate the annotation appearance after creating or modifying the annotation without providing an explicit appearance or setting the "NeedAppearances" flag in the AcroForm dictionary.

Declaration

public void RefreshAppearance()

Remarks

If this annotation contains text, and has been added to a rotated page, the text in the annotation may be rotated. If RefreshAppearance is called after the annotation is added to a rotated page, then any text will be rotated in the opposite direction of the page rotation. If this method is called before the annotation is added to any rotated page, then no counter rotation will be applied. If you wish to call RefreshAppearance on an annotation already added to a rotated page, but you don't want the text to be rotated, you can do one of the following; temporarily un-rotate the page, or, temporarily remove the "Rotate" object from the annotation. To support users adding text annotations while using a PDF viewer, you can also add any viewer rotation to the annotations Rotate object, to have text always rotated correctly, from the users perspective.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

RemoveAppearance()

Removes the annotation's appearance

Declaration

public void RemoveAppearance()

RemoveAppearance(Annot.AnnotationState)

Removes the annotation's appearance for the given combination of annotation and appearance states.

Declaration

public void RemoveAppearance(Annot.AnnotationState annot_state)

Parameters

Type	Name	Description
Annot.AnnotationState	annot_state	the annotation's appearance state, which selects the applicable appearance stream from the appearance sub-dictionary. An annotation can define as many as three separate appearances: The normal, rollover, and down appearance.

Exceptions

Type	Condition
PDFNetException	PDFNetException the pDF net exception

RemoveAppearance(Annot.AnnotationState, String)

Removes the annotation's appearance for the given combination of annotation and appearance states.

Declaration

public void RemoveAppearance(Annot.AnnotationState annot_state, string app_state)

Parameters

Type	Name	Description
Annot.AnnotationState	annot_state	the annotation's appearance state, which selects the applicable appearance stream from the appearance sub-dictionary. An annotation can define as many as three separate appearances: The normal, rollover, and down appearance.
System.String	app_state	is an optional parameter specifying the appearance state (e.g. "Off", "On", etc) under which the new appearance should be stored. If appearance_state is NULL, the annotation will have only one annotaion state.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Resize(Rect)

Resize.

Declaration

public void Resize(Rect newrect)

Parameters

Type	Name	Description
Rect	newrect	the pos

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetActiveAppearanceState(String)

Sets the annotation’s active appearance state. (Required if the appearance dictionary AP contains one or more subdictionaries; PDF 1.2)

Declaration

public void SetActiveAppearanceState(string astate)

Parameters

Type	Name	Description
System.String	astate	astate Charactor string representing the name of the active appearance state. The string used to select the annotation’s appearance state, which selects the applicable appearance stream from an appearance subdictionary.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetAppearance(Obj)

Sets the annotation’s appearance for the given combination of annotation and appearance states. (Optional; PDF 1.2)

Declaration

public void SetAppearance(Obj app_stream)

Parameters

Type	Name	Description
Obj	app_stream	a content stream defining the new appearance.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetAppearance(Obj, Annot.AnnotationState)

Removes the annotation's appearance for the given combination of annotation and appearance states.

Declaration

public void SetAppearance(Obj app_stream, Annot.AnnotationState annot_state)

Parameters

Type	Name	Description
Obj	app_stream	a content stream defining the new appearance.
Annot.AnnotationState	annot_state	is an optional parameter specifying the appearance state (e.g. "Off", "On", etc) under which the new appearance should be stored. If appearance_state is NULL, the annotation will have only one annotaion state.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetAppearance(Obj, Annot.AnnotationState, String)

Sets the annotation’s appearance for the given combination of annotation and appearance states. (Optional; PDF 1.2)

Declaration

public void SetAppearance(Obj app_stream, Annot.AnnotationState annot_state, string app_state)

Parameters

Type	Name	Description
Obj	app_stream	a content stream defining the new appearance.
Annot.AnnotationState	annot_state	the annotation’s appearance state, which selects the applicable appearance stream from the appearance sub-dictionary. An annotation can define as many as three separate appearances: The normal, rollover, and down appearance.
System.String	app_state	is an optional parameter specifying the appearance state (e.g. "Off", "On", etc) under which the new appearance should be stored. If appearance_state is NULL, the annotation will have only one annotaion state.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetBorderStyle(Annot.BorderStyle)

Sets the border style for the annotation. Typically used for Link annotations.

Declaration

public void SetBorderStyle(Annot.BorderStyle bs)

Parameters

Type	Name	Description
Annot.BorderStyle	bs	New border style for this annotation.

Exceptions

Type	Condition
PDFNetException	PDFNetException the pDF net exception

SetColor(ColorPt)

Sets an annotation's color. (Optional; PDF 1.1)

Declaration

public void SetColor(ColorPt cpt)

Parameters

Type	Name	Description
ColorPt	cpt	the color point

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetColor(ColorPt, Int32)

Sets an annotation's color. (Optional; PDF 1.1)

Declaration

public void SetColor(ColorPt cpt, int comp_num)

Parameters

Type	Name	Description
ColorPt	cpt	the color point
System.Int32	comp_num	The color component number that indirectly implies the color space the color is from.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetContents(String)

Sets the contents.

Declaration

public void SetContents(string contents)

Parameters

Type	Name	Description
System.String	contents	the new contents

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetCustomData(String, String)

Sets the custom data associated with the specified key.

Declaration

public void SetCustomData(string key, string value)

Parameters

Type	Name	Description
System.String	key	The key under which to store this custom data.
System.String	value	The custom data string to store.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetDate(Date)

Sets an annotation's last modified date.

Declaration

public void SetDate(Date date)

Parameters

Type	Name	Description
Date	date	The annotation's last modified time and date. Corresponds to the "M" entry of the annotation dictionary.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetFlag(Annot.Flag, Boolean)

Sets the value of given Flag.

Declaration

public void SetFlag(Annot.Flag flag, bool value)

Parameters

Type	Name	Description
Annot.Flag	flag	The Flag property to modify.
System.Boolean	value	The new value for the property.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetOptionalContent(Obj)

Sets optional content of an annotation. (Optional, PDF1.5).

Declaration

public void SetOptionalContent(Obj oc)

Parameters

Type	Name	Description
Obj	oc	An SDF object corresponding to the optional content, a PDF.OCG.Group or membership dictionary specifying the PDF.OCG.Group properties for the annotation. Before the annotation is drawn, its visibility shall be determined based on this entry as well as the annotation flags specified in the Flag entry . If it is determined to be invisible, the annotation shall be skipped, as if it were not in the document.

SetPage(Page)

Sets the reference to a page the annotation is associated with. (Optional PDF 1.3; not used in FDF files)

Declaration

public void SetPage(Page page)

Parameters

Type	Name	Description
Page	page	the new page

Remarks

The parameter should be an indirect reference to the page object with which this annotation is associated. This entry shall be present in screen annotations associated with rendition actions

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetRect(Rect)

Sets the size and location of an annotation on its page.

Declaration

public void SetRect(Rect pos)

Parameters

Type	Name	Description
Rect	pos	the new rect

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetRotation(Int32)

Sets the rotation value of the annotation. The Rotation specifies the number of degrees by which the annotation shall be rotated counterclockwise relative to the page. The value shall be a multiple of 90. (Optional)

Declaration

public void SetRotation(int rot)

Parameters

Type	Name	Description
System.Int32	rot	An integer representing the rotation value of the annotation.

Remarks

This property is part of the appearance characteristics dictionary, this dictionary that shall be used in constructing a dynamic appearance stream specifying the annotation’s visual presentation on the page.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetStructParent(Int32)

Sets the struct parent of an annotation. (Required if the annotation is a structural content item; PDF 1.3)

Declaration

public void SetStructParent(int keyval)

Parameters

Type	Name	Description
System.Int32	keyval	An integer which is the integer key of the annotation’s entry in the structural parent tree.

Remarks

The StructParent is the integer key of the annotation’s entry in the structural parent tree.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetUniqueID(String)

Sets the unique identifier for this annotation.

Declaration

public void SetUniqueID(string data)

Parameters

Type	Name	Description
System.String	data	the new unique id

Remarks

It is necessary to ensure that the unique ID generated is actually unique.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Operators

Equality(Annot, Annot)

Equality operator checks whether two Annot objects are the same

Declaration

public static bool operator ==(Annot l, Annot r)

Parameters

Type	Name	Description
Annot	l	the Annot object on the left of operator
Annot	r	the Annot object on the right of operator

Returns

Type	Description
System.Boolean	true if both objects are equal, false otherwise

Inequality(Annot, Annot)

Inequality operator checks whether two Annot objects are different

Declaration

public static bool operator !=(Annot l, Annot r)

Parameters

Type	Name	Description
Annot	l	the Annot object on the left of operator
Annot	r	the Annot object on the right of operator

Returns

Type	Description
System.Boolean	true if both objects are not equal, false otherwise

Implements

System.IDisposable