PDFTron PDFNet SDK API Reference

List of all members.


Public Types
enum	Type { e_Text, e_Link, e_FreeText, e_Line, e_Square, e_Circle, e_Polygon, e_Polyline, e_Highlight, e_Underline, e_Squiggly, e_StrikeOut, e_Stamp, e_Caret, e_Ink, e_Popup, e_FileAttachment, e_Sound, e_Movie, e_Widget, e_Screen, e_PrinterMark, e_TrapNet, e_Watermark, e_3D, e_Unknown }
	PDF supports the standard annotation types listed in the following enumeration (plug-in extensions may add new annotation types):. More...
enum	Flag { e_invisible, e_hidden, e_print, e_no_zoom, e_no_rotate, e_no_view, e_read_only, e_locked, e_toggle_no_view }
	Flags specifying various characteristics of the annotation. More...
enum	AnnotationState { e_normal, e_rollover, e_down }
	An annotation can define as many as three separate appearances:. More...
Public Member Functions
	Annot (SDF::Obj d=0)
	Create an annotation and initialize it using given Cos/SDF object.
	Annot (const Annot &d)
	Copy constructor.
Annot &	operator= (const Annot &d)
	Assignment operator.
bool	operator== (const Annot &d)
	Compares two annotations for equality.
bool	IsValid () const
	Returns: true if this is a valid (non-null) annotation, false otherwise.
Type	GetType () const
	Returns: The type of this annotation.
SDF::Obj	GetSDFObj () const
	Returns: The underlying SDF/Cos object.
Rect	GetRect () const
	Returns: annotation’s bounding rectangle, specified in user space coordinates.
void	SetRect (const Rect &pos)
	Sets the size and location of an annotation on its page.
bool	GetFlag (Flag flag) const
	Returns: the value of given AnnotFlag
void	SetFlag (Flag flag, bool value)
	Sets the value of given AnnotFlag.
Date	GetDate () const
	Gets an annotation's date.
void	SetDate (const Date &date)
	Sets an annotation's date.
SDF::Obj	GetUniqueID () const
	Returns: the unique identifier for this annotation, or NULL if the identifier is not available.
void	SetUniqueID (const char *id, int id_buf_sz=0)
	Sets the unique identifier for this annotation.
ColorPt	GetColor () const
	Gets a note or link annotation's color.
void	SetColor (const ColorPt &rgb)
	Sets a note or link annotation's color.
BorderStyle	GetBorderStyle () const
	Gets the border style for the annotation.
void	SetBorderStyle (const BorderStyle &bs)
	Sets the border style for the annotation.
SDF::Obj	GetAppearance (AnnotationState annot_state=e_normal, const char *app_state=0)
	Gets the annotation’s appearance for the given combination of annotation and appearance states.
void	SetAppearance (SDF::Obj app_stream, AnnotationState annot_state=e_normal, const char *app_state=0)
	Sets the annotation’s appearance for the given combination of annotation and appearance states.
class Action	GetLinkAction () const
	Gets a link annotation's action.
void	SetLinkAction (const class Action &action)
	Sets a link annotation's action.
void	RemoveLinkAction ()
	Removes a link annotation's action.
void	SetTextContents (const UString &contents)
	Sets the text of a text annotation.
SDF::Obj	GetTextContents () const
	Gets the text of a text annotation.
const char *	GetTextIcon () const
	Gets the name of an icon to be used in displaying the annotation.
void	SetTextIcon (const char *icon_name)
	Sets the name of an icon to be used in displaying the annotation.
bool	IsTextAnnotOpen () const
	Tests whether a text annotation is open.
void	SetTextAnnotOpen (bool is_open)
	Opens or closes a text annotation.
const char *	GetStampName () const
	Gets the name of the stamp to be used in displaying the annotation.
void	SetStampName (const char *name)
	Sets the name of the stamp to be used in displaying the annotation.
class Field	GetWidgetField () const
	Returns: the Field (if any) associated with this Widget.
FileSpec	GetFileAttachment () const
	Gets the file specification associated with this File Attachment annotation.
void	SetFileAttachment (const FileSpec &file)
	Sets the file specification for this File Attachment annotation.
bool	FileAttachmentExport (const UString &save_as="") const
	The function saves the data referenced by this File Attachment to an external file.
Static Public Member Functions
static Annot	Create (SDF::SDFDoc &doc, Type type, const Rect &pos)
	Creates a new annotation of a given type, in the specified document.
static Annot	CreateLink (SDF::SDFDoc &doc, const Rect &pos, const class Action &action)
	Creates a new Link annotation.
static Annot	CreateText (SDF::SDFDoc &doc, const Rect &pos, const UString &contents)
	Creates a new Text annotation.
static Annot	CreateStamp (SDF::SDFDoc &doc, const Rect &pos, const char *name="Draft")
	Creates a new rubber stamp annotation.
static Annot	CreateWidget (SDF::SDFDoc &doc, const Rect &pos, class Field field)
	Create a widget annotation given a Field and a rectangle specifying the location where the widget should be positioned.
static Annot	CreateFileAttachment (SDF::SDFDoc &doc, const Rect &pos, const char path, const char icon_name="PushPin")
	Create a file attachment annotation.
Classes
class	BorderStyle
	BorderStyle structure specifies the characteristics of the annotation’s border. More...

Detailed Description

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.

Just like many other classes in PDFNet (e.g. Element, ColorSpace, Font, etc), Annot class follows the composite design pattern. This means that all annotations are accessed through the same interface, but depending on the annotation type (that can be obtained using GetType()), only methods related to that type can be called. For example, if GetType() returns e_Link, it is illegal to call a method specific to another annotation type (i.e. a call to SetTextIcon() may throw an Exception)

For more details on PDF annotations please refer to section 8.4 in the PDF Reference Manual.

Member Enumeration Documentation

enum pdftron::PDF::Annot::Type

PDF supports the standard annotation types listed in the following enumeration (plug-in extensions may add new annotation types):.

Enumerator:

e_Text	Text annotation.
e_Link	Link annotation.
e_FreeText	Free text annotation.
e_Line	Line annotation.
e_Square	Square annotation.
e_Circle	Circle annotation.
e_Polygon	Polygon annotation.
e_Polyline	Polyline annotation.
e_Highlight	Highlight annotation.
e_Underline	Underline annotation.
e_Squiggly	Squiggly-underline annotation.
e_StrikeOut	Strikeout annotation.
e_Stamp	Rubber stamp annotation.
e_Caret	Caret annotation.
e_Ink	Ink annotation.
e_Popup	Pop-up annotation.
e_FileAttachment	File attachment annotation.
e_Sound	Sound annotation.
e_Movie	Movie annotation.
e_Widget	Widget annotation.
e_Screen	Screen annotation.
e_PrinterMark	Printer’s mark annotation.
e_TrapNet	Trap network annotation.
e_Watermark	Watermark annotation.
e_3D	3D annotation
e_Unknown	Unknown annotation type.

enum pdftron::PDF::Annot::Flag

Flags specifying various characteristics of the annotation.

If e_invisible is 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.

If e_hidden is 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.

If e_print is 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.

If e_no_zoom is set, do not scale the annotation’s appearance to match the magnification of the page.

If e_no_rotate is set, do not rotate the annotation’s appearance to match the rotation of the page.

If e_no_view is 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.

If e_read_only is 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.

If e_locked is 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.

If e_toggle_no_view is 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.

Enumerator:

e_invisible
e_hidden
e_print
e_no_zoom
e_no_rotate
e_no_view
e_read_only
e_locked
e_toggle_no_view

enum pdftron::PDF::Annot::AnnotationState

An annotation can define as many as three separate appearances:.

The normal appearance is used when the annotation is not interacting with the user. This appearance is also used for printing the annotation.

The rollover appearance is used when the user moves the cursor into the annotation’s active area without pressing the mouse button.

The down appearance is used when the mouse button is pressed or held down within the annotation’s active area.

Enumerator:

e_normal
e_rollover
e_down

Constructor & Destructor Documentation

pdftron::PDF::Annot::Annot ( SDF::Obj d = 0 )

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

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

pdftron::PDF::Annot::Annot ( const Annot & d )

Copy constructor.

Member Function Documentation

static Annot pdftron::PDF::Annot::Create	(	SDF::SDFDoc &	doc,
		Type	type,
		const Rect &	pos
	)			`[static]`

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.

Parameters:

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

Returns:: A newly created blank annotation for the given annotation type.

static Annot pdftron::PDF::Annot::CreateLink	(	SDF::SDFDoc &	doc,
		const Rect &	pos,
		const class Action &	action
	)			`[static]`

Creates a new Link annotation.

Parameters:

	doc	A document to which the annotation is added.
	pos	A rectangle specifying the annotation's bounds, specified in user space coordinates.
	action	Action for the link annotation.

Returns:: A new Link annotation.

static Annot pdftron::PDF::Annot::CreateText	(	SDF::SDFDoc &	doc,
		const Rect &	pos,
		const UString &	contents
	)			`[static]`

Creates a new Text annotation.

A text annotation represents a 'sticky note' attached to a point in the PDF document. When closed, the annotation appears as an icon; when open, it displays a pop-up window containing the text of the note in a font and size chosen by the viewer application. Text annotations do not scale and rotate with the page.

Parameters:

	doc	A document to which the annotation is added.
	pos	A rectangle specifying the annotation's bounds, specified in user space coordinates.
	contents	- a buffer containing new text contents represented in PDFDocEncoding or Unicode.
	contents_sz	- the size of 'contents_sz' buffer, or 0 if the string is NULL terminated.

Returns:: A new Text annotation.

static Annot pdftron::PDF::Annot::CreateStamp	(	SDF::SDFDoc &	doc,
		const Rect &	pos,
		const char *	name = `"Draft"`
	)			`[static]`

Creates a new rubber stamp annotation.

A rubber stamp annotation displays text or graphics intended to look as if they were stamped on the page with a rubber stamp. When opened, it displays a pop-up window containing the text of the associated note.

Parameters:

	doc	A document to which the annotation is added.
	pos	A rectangle specifying the annotation's bounds, specified in user space coordinates.
	name	The name of an icon to be used in displaying the annotation. PDF Viewer applications should provide predefined icon appearances for at least the following standard names: Approved, AsIs, Confidential, Departmental, Draft, Experimental, Expired, Final, ForComment, ForPublicRelease, NotApproved, NotForPublicRelease, Sold, TopSecret. Additional names may be supported as well. Default value: Draft.

Returns:: A new Stamp annotation.

static Annot pdftron::PDF::Annot::CreateWidget	(	SDF::SDFDoc &	doc,
		const Rect &	pos,
		class Field	field
	)			`[static]`

Create a widget annotation given a Field and a rectangle specifying the location where the widget should be positioned.

Interactive forms (see Section 8.6, 'Interactive Forms' in PDF Reference Manual) use widget annotations to represent the appearance of fields and to manage user interactions.

Parameters:

	doc	A document to which the annotation is added.
	pos	A rectangle specifying the annotation's bounds, specified in user space coordinates.
	field	A form Filed used to construct the Widget annotation.

Returns:: A new Widget annotation. You can further modify this annotation in order to set other annotation properties such as appearances, border styles, etc.

static Annot pdftron::PDF::Annot::CreateFileAttachment	(	SDF::SDFDoc &	doc,
		const Rect &	pos,
		const char *	path,
		const char *	icon_name = `"PushPin"`
	)			`[static]`

Create a file attachment annotation.

A file attachment annotation contains a reference to a file, which typically is embedded in the PDF file.

Parameters:

	doc	A document to which the annotation is added.
	pos	A rectangle specifying the annotation's bounds, specified in user space coordinates.
	icon_name	The name of an icon to be used in displaying the annotation. PDF Viewer applications should provide predefined icon appearances for at least the following standard names: Graph PushPin Paperclip Tag. Additional names may be supported as well. Default value: PushPin.

Returns:: A new file attachment annotation. You can further modify this annotation in order to set other annotation properties such as appearances, border styles, etc.

Annot& pdftron::PDF::Annot::operator= ( const Annot & d )

Assignment operator.

bool pdftron::PDF::Annot::operator== ( const Annot & d )

Compares two annotations for equality.

The comparison will return true only if both annotations share the same underlying SDF/Cos object.

bool pdftron::PDF::Annot::IsValid ( ) const

Returns:: 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.

Type pdftron::PDF::Annot::GetType ( ) const

Returns:: The type of this annotation.

SDF::Obj pdftron::PDF::Annot::GetSDFObj ( ) const

Returns:: The underlying SDF/Cos object.

Rect pdftron::PDF::Annot::GetRect ( ) const

Returns:: annotation’s bounding rectangle, specified in user space coordinates.

The meaning of the rectangle depends on the annotation type. For Link and Stamp 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.

void pdftron::PDF::Annot::SetRect ( const Rect & pos )

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

Parameters:

pos

Annotation’s bounding rectangle, specified in user space coordinates.

bool pdftron::PDF::Annot::GetFlag ( Flag flag ) const

Returns:: the value of given AnnotFlag

Parameters:

flag

the Flag property to query.

void pdftron::PDF::Annot::SetFlag	(	Flag	flag,
		bool	value
	)

Sets the value of given AnnotFlag.

Parameters:

	flag	the Flag property to modifiy.
	value	The new value for the property.

Date pdftron::PDF::Annot::GetDate ( ) const

Gets an annotation's date.

Returns:: The annotation's time and date. If the annotation has no associated date structure, the returned date is not valid (date.IsValid() returns false).

void pdftron::PDF::Annot::SetDate ( const Date & date )

Sets an annotation's date.

SDF::Obj pdftron::PDF::Annot::GetUniqueID ( ) const

Returns:: 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.

void pdftron::PDF::Annot::SetUniqueID	(	const char *	id,
		int	id_buf_sz = `0`
	)

Sets the unique identifier for this annotation.

Parameters:

	id	- a buffer containing a unique identifier for this annotation.
	id_buf_sz	- the size of 'id' buffer, or 0 if the string is NULL terminated.

Note:: it is user responsibility to ensure that the unique ID generated is actually unique.

ColorPt pdftron::PDF::Annot::GetColor ( ) const

Gets a note or link annotation's color.

Returns:

A color point in RGB color space representing the border or background icon color for this annotation. RGB components are three numbers in the range 0.0 to 1.0. Depending on the annotation's type this color is used for the following purposes:

The border of a link annotation
The background of the annotation’s icon when closed
The title bar of the annotation’s pop-up window

If the annotation does not specify an explicit color, a default color is returned. Text annotations return 'default yellow;' all others return black.

void pdftron::PDF::Annot::SetColor ( const ColorPt & rgb )

Sets a note or link annotation's color.

Parameters:

rgb

- A color point in RGB color space representing the color for this annotation. RGB components are three numbers in the range 0.0 to 1.0. Depending on the annotation's type this color is used for the following purposes:

The border of a link annotation
The background of the annotation’s icon when closed
The title bar of the annotation’s pop-up window

BorderStyle pdftron::PDF::Annot::GetBorderStyle ( ) const

Gets the border style for the annotation.

Typically used for Link annotations.

Returns:: annotation's border style.

void pdftron::PDF::Annot::SetBorderStyle ( const BorderStyle & bs )

Sets the border style for the annotation.

Typically used for Link annotations.

Parameters:

new

border style for this annotation.

SDF::Obj pdftron::PDF::Annot::GetAppearance	(	AnnotationState	annot_state = `e_normal`,
		const char *	app_state = `0`
	)

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

Parameters:

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

void pdftron::PDF::Annot::SetAppearance	(	SDF::Obj	app_stream,
		AnnotationState	annot_state = `e_normal`,
		const char *	app_state = `0`
	)

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

Parameters:

	app_stream	a content stream defining the new appearance.
	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.
	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.

class Action pdftron::PDF::Annot::GetLinkAction ( ) const

Gets a link annotation's action.

Returns:: The link annotation's action.

Note:: This method is applicable only if this is e_Link annotation.

void pdftron::PDF::Annot::SetLinkAction ( const class Action & action )

Sets a link annotation's action.

Parameters:

action

- New action for the link annotation.

Note:: This method is applicable only if this is e_Link annotation.

void pdftron::PDF::Annot::RemoveLinkAction ( )

Removes a link annotation's action.

Note:: This method is applicable only if this is e_Link annotation.

void pdftron::PDF::Annot::SetTextContents ( const UString & contents )

Sets the text of a text annotation.

Parameters:

contents

- new text contents string.

Note:: This method is applicable only if this is e_Text annotation.

SDF::Obj pdftron::PDF::Annot::GetTextContents ( ) const

Gets the text of a text annotation.

Returns:: SDF string object with text contents or NULL if there is no associated text contents. The string buffer can be accessed using Obj.GetAsPDFText() method.

Note:: This method is applicable only if this is e_Text annotation.

const char* pdftron::PDF::Annot::GetTextIcon ( ) const

Gets the name of an icon to be used in displaying the annotation.

Returns:: The string representing the name of an icon to be used in displaying the annotation.

Viewer applications should provide predefined icon appearances for at least the following standard names: Comment, Key, Note, Help, NewParagraph, Paragraph, Insert Additional names may be supported as well. Default value: Note.

Note:: This method is applicable only if this is e_Text annotation.

void pdftron::PDF::Annot::SetTextIcon ( const char * icon_name )

Sets the name of an icon to be used in displaying the annotation.

Parameters:

icon_name

The string representing the name of an icon to be used in displaying the annotation or NULL if the default should be used.

Viewer applications should provide predefined icon appearances for at least the following standard names: Comment, Key, Note, Help, NewParagraph, Paragraph, Insert, Additional names may be supported as well.

Note:: This method is applicable only if this is e_Text annotation.

bool pdftron::PDF::Annot::IsTextAnnotOpen ( ) const

Tests whether a text annotation is open.

Returns:: true if the annotation is open, false otherwise.

Note:: In versions later than Acrobat 4.0, this method cannot always correctly determine a text annotation's open state. Beginning with Acrobat 4 (PDF 1.3), text annotations (and other annotations) have an associated Popup annotation which maintains the open state of the popup window; the method works correctly when you pass it the popup annotation itself. You can use SDF/Cos-level routines to find the Popup entry in the annotation dictionary, which is itself a dictionary containing an Open entry.
This method is applicable only if this is e_Text annotation.

void pdftron::PDF::Annot::SetTextAnnotOpen ( bool is_open )

Opens or closes a text annotation.

Parameters:

is_open

true if the annotation is opened, false if the annotation is closed.

Note:: This method is applicable only if this is e_Text annotation.
See IsTextAnnotOpen() for details.

const char* pdftron::PDF::Annot::GetStampName ( ) const

Gets the name of the stamp to be used in displaying the annotation.

Returns:: The string representing the stamp name or NULL if the default text (i.e. "Draft") should be used.

Note:: This method is applicable only if this is e_Stamp annotation.
See SetStampName() for details.

void pdftron::PDF::Annot::SetStampName ( const char * name )

Sets the name of the stamp to be used in displaying the annotation.

Parameters:

name

The string representing the stamp name of an icon to be used in displaying the annotation. PDF Viewer applications should provide predefined icon appearances for at least the following standard names: Approved, AsIs, Confidential, Departmental, Draft, Experimental, Expired, Final, ForComment, ForPublicRelease, NotApproved, NotForPublicRelease, Sold, TopSecret. Additional names may be supported as well.

Note:: This method is applicable only if this is e_Stamp annotation.

class Field pdftron::PDF::Annot::GetWidgetField ( ) const

Returns:: the Field (if any) associated with this Widget.

Because in some documents a Widget may not be attached to a field make sure that the returned field is valid (i.e. Field.IsValid()).

Note:: This method is applicable only if this is e_Widget annotation.

FileSpec pdftron::PDF::Annot::GetFileAttachment ( ) const

Gets the file specification associated with this File Attachment annotation.

Returns:: the FileSpec (if any) associated with this File Attachment annotation. To guard against broken PDF documents, make sure that the returned FileSpec is valid (i.e. FileSpec.IsValid()).

Note:: This method is applicable only if this is e_FileAttachment annotation.

void pdftron::PDF::Annot::SetFileAttachment ( const FileSpec & file )

Sets the file specification for this File Attachment annotation.

Parameters:

file

The new file specification for the annotation.

Note:: This method is applicable only if this is e_FileAttachment annotation.

bool pdftron::PDF::Annot::FileAttachmentExport ( const UString & save_as = "" ) const

The function saves the data referenced by this File Attachment to an external file.

If the file is embedded, the function saves the embedded file. If the file is not embedded, the function will copy the external file. If the file is not embedded and the external file can't be found, the function returns false.

Parameters:

save_as

An optional parameter indicating the filepath and filename where the data should be saved. If this parameter is not specified the function will attempt to save the file using FileSpec.GetFilePath().

Returns:: true is the file was saved successfully, false otherwise.

Note:: This method is applicable only if this is e_FileAttachment annotation.

pdftron::PDF::Annot Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Classes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation