![]() |
#include <Annot.h>
Classes | |
class | BorderStyle |
BorderStyle structure specifies the characteristics of the annotation's border. More... | |
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_Redact, e_Projection, e_RichMedia, 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, e_locked_contents } |
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 |
SDF::Obj | GetSDFObj () const |
Type | GetType () const |
Rect | GetRect () const |
bool | IsMarkup () const |
Return true if this annotation is classified as a markup annotation. | |
void | SetRect (const Rect &p) |
Sets the size and location of an annotation on its page. | |
Page | GetPage () const |
Gets the page the annotation is associated with. | |
void | SetPage (const Page &page) |
Sets the reference to a page the annotation is associated with. | |
SDF::Obj | GetUniqueID () const |
void | SetUniqueID (const char *id, int id_buf_sz=0) |
Sets the unique identifier for this annotation. | |
Date | GetDate () const |
Gets an annotation's date. | |
void | SetDate (const Date &date) |
Sets an annotation's date. | |
bool | GetFlag (Flag flag) const |
void | SetFlag (Flag flag, bool value) |
Sets the value of given Flag. | |
BorderStyle | GetBorderStyle () const |
Gets the border style for the annotation. | |
void | SetBorderStyle (const BorderStyle &bs, bool oldStyleOnly=false) |
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. | |
void | RemoveAppearance (AnnotationState annot_state=e_normal, const char *app_state=0) |
Removes the annotation's appearance for the given combination of annotation and appearance states. | |
void | Flatten (class Page page) |
Flatten/Merge the existing annotation appearances with the page content and delete this annotation from a given page. | |
const char * | GetActiveAppearanceState () const |
Gets the annotation's active appearance state. | |
void | SetActiveAppearanceState (const char *astate) |
Sets the annotation's active appearance state. | |
ColorPt | GetColorAsRGB () const |
Gets an annotation's color in RGB color space. | |
ColorPt | GetColorAsCMYK () const |
Returns the annotation's color in CMYK color space. | |
ColorPt | GetColorAsGray () const |
Returns the annotation's color in Gray color space. | |
int | GetColorCompNum () const |
Returns the color space the annotation's color is represented in. | |
void | SetColor (const ColorPt &c, int comp_num=3) |
Sets an annotation's color. | |
int | GetStructParent () const |
Returns the struct parent of an annotation. | |
void | SetStructParent (const int keyval) |
Sets the struct parent of an annotation. | |
SDF::Obj | GetOptionalContent () const |
Returns optional content associated with this annotation. | |
void | SetOptionalContent (SDF::Obj oc) |
Associates optional content with this annotation. | |
void | SetContents (const UString &contents) |
Sets the content of this annotation. | |
UString | GetContents () const |
Extract the content of this annotation. | |
void | RefreshAppearance () |
Regenerates the appearance stream for the annotation. | |
void | Resize (const Rect &newrect) |
Scales the geometry of the annotation so that its appearance would now fit a new rectangle on the page, in user units. | |
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. |
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 documentation in derived classes.
PDF supports the standard annotation types listed in the following enumeration (plug-in extensions may add new annotation types):.
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_Redact | Redact annotation. |
e_Projection | Projection annotation, Adobe supplement to ISO 32000. |
e_RichMedia | Rich Media annotation, Adobe supplement to ISO 32000. |
e_Unknown | Any other annotation type, not listed in PDF spec and unrecognized by PDFTron software. |
Flags specifying various characteristics of the annotation.
An annotation can define as many as three separate appearances:.
pdftron::PDF::Annot::Annot | ( | SDF::Obj | d = 0 |
) |
Create an annotation and initialize it using given Cos/SDF object.
pdftron::PDF::Annot::Annot | ( | const Annot & | d | ) |
Copy constructor.
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.
The newly created annotation does not contain any properties specific to a given annotation type, which means an invalid annotation object could be created. It is therefore recommended to always create an annotation using type specific methods, such as Annots::Line::Create() or Annots::FileAttachment::Create(). Users should only call Annot::Create() to create annotations of non-standard types that are not recognized by PDFTron software (by using Annot::e_Unknown as a type).
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. |
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 |
SDF::Obj pdftron::PDF::Annot::GetSDFObj | ( | ) | const |
Type pdftron::PDF::Annot::GetType | ( | ) | const |
Rect pdftron::PDF::Annot::GetRect | ( | ) | const |
bool pdftron::PDF::Annot::IsMarkup | ( | ) | const |
Return true if this annotation is classified as a markup annotation.
void pdftron::PDF::Annot::SetRect | ( | const Rect & | p | ) |
Sets the size and location of an annotation on its page.
p | Annotation's bounding rectangle, specified in user space coordinates. |
Page pdftron::PDF::Annot::GetPage | ( | ) | const |
Gets the page the annotation is associated with.
void pdftron::PDF::Annot::SetPage | ( | const Page & | page | ) |
Sets the reference to a page the annotation is associated with.
(Optional PDF 1.3; not used in FDF files)
Page | The page object user wants the annotation to be associated with. |
SDF::Obj pdftron::PDF::Annot::GetUniqueID | ( | ) | const |
void pdftron::PDF::Annot::SetUniqueID | ( | const char * | id, | |
int | id_buf_sz = 0 | |||
) |
Sets the unique identifier for this annotation.
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. |
Date pdftron::PDF::Annot::GetDate | ( | ) | const |
Gets an annotation's date.
void pdftron::PDF::Annot::SetDate | ( | const Date & | date | ) |
Sets an annotation's date.
The | annotation's time and date. |
bool pdftron::PDF::Annot::GetFlag | ( | Flag | flag | ) | const |
flag | The Flag property to query. |
void pdftron::PDF::Annot::SetFlag | ( | Flag | flag, | |
bool | value | |||
) |
Sets the value of given Flag.
flag | The Flag property to modify. | |
value | The new value for the property. |
BorderStyle pdftron::PDF::Annot::GetBorderStyle | ( | ) | const |
Gets the border style for the annotation.
Typically used for Link annotations.
void pdftron::PDF::Annot::SetBorderStyle | ( | const BorderStyle & | bs, | |
bool | oldStyleOnly = false | |||
) |
Sets the border style for the annotation.
bs | New border style for this annotation. | |
oldStyleOnly | PDF manual specifies two ways to add border information to an annotation object, either through an array named 'Border' (PDF 1.0), or a dictionary called 'BS' (PDF 1.2) the latter taking precedence over the former. However, if you want to create a border with rounded corners, you can only do that using PDF 1.0 Border specification, in which case if you call SetBorderStyle() set the parameter oldStyleOnly to true. This parameter has a default value of false in the API and does not need to be used otherwise. |
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.
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. |
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.
(Optional; PDF 1.2)
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 annotation state. |
void pdftron::PDF::Annot::RemoveAppearance | ( | AnnotationState | annot_state = e_normal , |
|
const char * | app_state = 0 | |||
) |
Removes the annotation's appearance for the given combination of annotation and appearance states.
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 annotation state. |
void pdftron::PDF::Annot::Flatten | ( | class Page | 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.
const char* pdftron::PDF::Annot::GetActiveAppearanceState | ( | ) | const |
Gets the annotation's active appearance state.
void pdftron::PDF::Annot::SetActiveAppearanceState | ( | const char * | astate | ) |
Sets the annotation's active appearance state.
(Required if the appearance dictionary AP contains one or more subdictionaries; PDF 1.2)
astate Character 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. |
ColorPt pdftron::PDF::Annot::GetColorAsRGB | ( | ) | const |
Gets an annotation's color in RGB color space.
ColorPt pdftron::PDF::Annot::GetColorAsCMYK | ( | ) | const |
Returns the annotation's color in CMYK color space.
ColorPt pdftron::PDF::Annot::GetColorAsGray | ( | ) | const |
Returns the annotation's color in Gray color space.
int pdftron::PDF::Annot::GetColorCompNum | ( | ) | const |
Returns the color space the annotation's color is represented in.
void pdftron::PDF::Annot::SetColor | ( | const ColorPt & | c, | |
int | comp_num = 3 | |||
) |
Sets an annotation's color.
(Optional; PDF 1.1)
c | A ColorPt object in RGB or Gray or CMYK color space representing the annotation's color. The ColorPt contains an array of numbers in the range 0.0 to 1.0, representing a color 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 |
comp_num | - The number of color components used to represent the color (i.e. 1, 3, 4). |
int pdftron::PDF::Annot::GetStructParent | ( | ) | const |
Returns the struct parent of an annotation.
(Required if the annotation is a structural content item; PDF 1.3)
void pdftron::PDF::Annot::SetStructParent | ( | const int | keyval | ) |
Sets the struct parent of an annotation.
(Required if the annotation is a structural content item; PDF 1.3)
keyval | An integer which is the integer key of the annotation's entry in the structural parent tree. |
SDF::Obj pdftron::PDF::Annot::GetOptionalContent | ( | ) | const |
Returns optional content associated with this annotation.
void pdftron::PDF::Annot::SetOptionalContent | ( | SDF::Obj | oc | ) |
Associates optional content with this annotation.
(Optional, PDF1.5).
oc | A pointer to 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. |
void pdftron::PDF::Annot::SetContents | ( | const UString & | contents | ) |
Sets the content of this annotation.
(Optional).
contents | A reference to unicode string object with the text that will be associated with this annotation. This is the text that annotation displays on user interaction, if the annotation type supports it. |
UString pdftron::PDF::Annot::GetContents | ( | ) | const |
Extract the content of this annotation.
(Optional).
void pdftron::PDF::Annot::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.
void pdftron::PDF::Annot::Resize | ( | const Rect & | newrect | ) |
Scales the geometry of the annotation so that its appearance would now fit a new rectangle on the page, in user units.
Users still have to call RefreshAppearance() later if they want a corresponding appearance stream to be generated for the new rectangle. The main reason for not combining the two operations together is to be able to resize annotations that do not have an appearance stream.
newrect | A reference to the new rectangle to which this annotation has to be resized. |