Loading...
Searching...
No Matches
pdftron::PDF::Annots::Markup Class Reference

`#include <Markup.h>`

Inheritance diagram for pdftron::PDF::Annots::Markup:

## Public Types
enum | BorderEffect { e_None , e_Cloudy }
Public Types inherited from pdftron::PDF::Annot
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 }
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 }
enum | ActionTriggerEvent { e_action_trigger_activate = 0 , e_action_trigger_annot_enter = 1 , e_action_trigger_annot_exit = 2 , e_action_trigger_annot_down = 3 , e_action_trigger_annot_up = 4 , e_action_trigger_annot_focus = 5 , e_action_trigger_annot_blur = 6 , e_action_trigger_annot_page_open = 7 , e_action_trigger_annot_page_close = 8 , e_action_trigger_annot_page_visible = 9 , e_action_trigger_annot_page_invisible = 10 }
enum | AnnotationState { e_normal , e_rollover , e_down }
typedef pdftron::PDF::BorderStyle | BorderStyle

## Public Member Functions
| Markup (SDF::Obj d=0)
| Markup (const Annot &ann)
UString | GetTitle ()
void | SetTitle (const UString &title)
void | SetTitle (const char *title)
Popup | GetPopup () const
void | SetPopup (const Popup &ppup)
double | GetOpacity () const
void | SetOpacity (double op)
UString | GetSubject () const
void | SetSubject (const UString &contents)
Date | GetCreationDates () const
void | SetCreationDates (const Date &dt)
BorderEffect | GetBorderEffect () const
void | SetBorderEffect (BorderEffect effect=e_None)
double | GetBorderEffectIntensity () const
void | SetBorderEffectIntensity (double intensity=0)
ColorPt | GetInteriorColor () const
int | GetInteriorColorCompNum () const
void | SetInteriorColor (const ColorPt &c, int CompNum)
Rect | GetContentRect () const
void | SetContentRect (const Rect &cr)
Rect | GetPadding () const
void | SetPadding (const Rect &rd)
void | SetPadding (double x)
void | RotateAppearance (double angle)
Public Member Functions inherited from pdftron::PDF::Annot
| Annot (SDF::Obj d=0)
| Annot (const Annot &d)
Annot & | operator= (const Annot &d)
bool | operator== (const Annot &d)
bool | IsValid () const
SDF::Obj | GetSDFObj () const
Type | GetType () const
Rect | GetRect () const
Rect | GetVisibleContentBox () const
bool | IsMarkup () const
void | SetRect (const Rect &pos)
Page | GetPage () const
void | SetPage (const Page &page)
SDF::Obj | GetUniqueID () const
void | SetUniqueID (const char *id, int id_buf_sz=0)
Date | GetDate () const
void | SetDate (const Date &date)
bool | GetFlag (Flag flag) const
void | SetFlag (Flag flag, bool value)
SDF::Obj | GetTriggerAction (Annot::ActionTriggerEvent trigger)
BorderStyle | GetBorderStyle () const
void | SetBorderStyle (const BorderStyle &bs, bool oldStyleOnly=false)
SDF::Obj | GetAppearance (AnnotationState annot_state=e_normal, const char *app_state=0)
void | SetAppearance (SDF::Obj app_stream, AnnotationState annot_state=e_normal, const char *app_state=0)
void | RemoveAppearance (AnnotationState annot_state=e_normal, const char *app_state=0)
void | Flatten (class Page page)
const char * | GetActiveAppearanceState () const
void | SetActiveAppearanceState (const char *astate)
ColorPt | GetColorAsRGB () const
ColorPt | GetColorAsCMYK () const
ColorPt | GetColorAsGray () const
int | GetColorCompNum () const
void | SetColor (const ColorPt &col, int numcomp=3)
int | GetStructParent () const
void | SetStructParent (const int parkeyval)
SDF::Obj | GetOptionalContent () const
void | SetOptionalContent (SDF::Obj content)
void | SetContents (const UString &contents)
UString | GetContents () const
int | GetRotation () const
void | SetRotation (int angle)
void | RefreshAppearance ()
void | RefreshAppearance (const RefreshOptions &options)
UString | GetCustomData (const UString &key) const
void | SetCustomData (const UString &key, const UString &value)
void | DeleteCustomData (const UString &key)
void | Resize (const Rect &newrect)
ptrdiff_t | GetHandleInternal ()

## Additional Inherited Members
Static Public Member Functions inherited from pdftron::PDF::Annot
static Annot | Create (SDF::SDFDoc &doc, Type type, const Rect &pos)
static Annot * | CreateInternal (ptrdiff_t impl)

## Detailed Description

Markup is a base class for a number of annotations types that are used to mark up PDF documents. These annotations have text that appears as part of the annotation and may be displayed in other ways by a conforming reader, such as in a Comments pane. Markup annotations may be divided into the following groups:

- Free text annotations display text directly on the page. The annotation's Contents entry specifies the displayed text.
- Most other markup annotations have an associated pop-up window that may contain text. The annotation's Contents entry specifies the text that shall be displayed when the pop-up window is opened. These include text, line, square, circle, polygon, polyline, highlight,underline, squiggly-underline, strikeout, rubber stamp, caret, ink, and file attachment annotations.
- Sound annotations do not have a pop-up window but may also have associated text specified by the Contents entry.
- A subset of markup annotations are intended to markup text of a document (e.g. highlight, strikeout, jagged, underline) and they are derived from TextMarkup base class.

Note
  The pop-up annotation type must not appear by itself; it must be associated with a markup annotation that uses it to display text.

The meaning of an annotation's Contents entry varies by annotation type. Typically, it is the text that shall be displayed for the annotation or, if the annotation does not display text, an alternate description of the annotation's contents in human-readable form. When separating text into paragraphs, a CARRIAGE RETURN (0Dh) must be used.

Definition at line 43 of file Markup.h.

## Member Enumeration Documentation

## ◆ BorderEffect

enum pdftron::PDF::Annots::Markup::BorderEffect

Border Effect Style

Enumerator
e_None | No effect.
e_Cloudy | Use "cloudy" border.

Definition at line 189 of file Markup.h.

## Constructor & Destructor Documentation

## ◆ Markup() [1/2]

pdftron::PDF::Annots::Markup::Markup | ( | SDF::Obj | d = 0 | ) |

Creates a markup annotation and initializes it using given Cos/SDF object.

Parameters

  d | The Cos/SDF object to initialze the annotation with.

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

## ◆ Markup() [2/2]

pdftron::PDF::Annots::Markup::Markup | ( | const Annot & | ann | ) |
| inline

Creates a markup annotation and initializes it using given annotation object.

Parameters

  ann | Annot object used to initialize the Markup annotation.

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

Definition at line 61 of file Markup.h.

## Member Function Documentation

## ◆ GetBorderEffect()

BorderEffect pdftron::PDF::Annots::Markup::GetBorderEffect | ( |  | ) | const

Returns
  the border effect of the markup annotation. Default value: e_None.

Beginning with PDF 1.5, some annotations (square, circle, and polygon) may have a 'BE' entry, which is a border effect dictionary that specifies an effect that shall be applied to the border of the annotations. Beginning with PDF 1.6, the free text annotation may also have a BE entry.

Note
  When "e_Cloudy" is chosen,the width and dash array specified by the annotation's BorderStyle entry needs to be taken into consideration.

## ◆ GetBorderEffectIntensity()

double pdftron::PDF::Annots::Markup::GetBorderEffectIntensity | ( |  | ) | const

Returns
  A number describing the intensity of the border effect, in the range 0 to 2.

Beginning with PDF 1.5, some annotations (square, circle, and polygon) may have a 'BE' entry, which is a border effect dictionary that specifies an effect that shall be applied to the border of the annotations. Beginning with PDF 1.6, the free text annotation may also have a BE entry.

## ◆ GetContentRect()

Rect pdftron::PDF::Annots::Markup::GetContentRect | ( |  | ) | const

Returns the inner bounding rectangle of the Markup annotation.

Returns
  A rectangle specifying the region where content should be displayed.

Note
  This rectangle can be same as or inside of the annotation's rectangle. If it is smaller, such a difference may occur in situations where a border effect causes the size of the annotation Rect entry to increase beyond that of the rectangle. For FreeText annotation with a callout, content rectangle specifies an inner region for the text to be displayed.
  According to PDF Reference Manual content rectangle is not the property that is expected for Markup annotations in general, but it applies to many derived annotation classes (FreeText,Square,Circle,Caret) and therefore get()/set() methods are provided in the base class Markup. Annotations that do not use this property will ignore the content rectangle ('RD' entry), if present in their annotation dictionary.

## ◆ GetCreationDates()

Date pdftron::PDF::Annots::Markup::GetCreationDates | ( |  | ) | const

Returns
  The creation date for the markup annotation.

Note
  This corresponds to the 'CreationDate' field of the markup annotation's dictionary.

## ◆ GetInteriorColor()

ColorPt pdftron::PDF::Annots::Markup::GetInteriorColor | ( |  | ) | const

Returns the interior color of the annotation.

Returns
  A ColorPt object that denotes the color of the annotation.

Note
  The color can be in different color spaces: Gray, RGB, or CMYK. Call "GetInteriorColorCompNum" to access the color space information.
  According to PDF Reference Manual interior color is not the property that is expected for Markup annotations in general, but it applies to many derived annotations (Line,Square,Circle,Polygon,PolyLine,Redaction) and therefore get()/set() methods are provided in the base class Markup. Annotations that do not use interior color will ignore the interior color ('IC' entry), if present in their annotation dictionary. In case no color is specified, CMYK white is returned.

## ◆ GetInteriorColorCompNum()

int pdftron::PDF::Annots::Markup::GetInteriorColorCompNum | ( |  | ) | const

Returns the number indicating the interior color space of the annotation.

Returns
  An integer indicating the number of channels forming the color space. 3 corresponds to RGB, 4 corresponds to CMYK, and 1 corresponds to Gray. If the interior is transparent, the return value is 0.

## ◆ GetOpacity()

double pdftron::PDF::Annots::Markup::GetOpacity | ( |  | ) | const

Returns
  The opacity value.
  Default value: 1.0.

Note
  This value is applied to all visible elements of the annotation in its closed state (including its background and border) but not to the pop-up window that appears when the annotation is opened. When an appearance stream is presented with the annotation, this entry is ignored.(However, if the compliant viewer regenerates the annotation's appearance stream, it may incorporate this Opacity entry into the stream's content.)
  This corresponds to the 'CA' field of the annotation's dictionary.

## ◆ GetPadding()

Rect pdftron::PDF::Annots::Markup::GetPadding | ( |  | ) | const

Returns the rectangle difference between overall annotation rectangle and content rectangle.

Returns
  A set of four numbers represented as a Rect struct.

Note
  The four numbers of the returning struct specify the difference between two rectangles: the Rect entry of the annotation and the actual bounding box of the underlying rectangle. Such a difference may occur in situations where a border effect causes the size of the annotation Rect entry to increase beyond that of the rectangle. The four numbers of the returning struct correspond to the differences in default user space, between the left, top, right, and bottom of the two above mentioned rectangles.
  GetPadding() and GetContentRectangle() both use 'RD' entry of the annotation dictionary, but represent it to user in different ways.

See also
  GetContentRect()

## ◆ GetPopup()

Popup pdftron::PDF::Annots::Markup::GetPopup | ( |  | ) | const

Returns the Popup object associated with this markup annotation.

Returns
  A Popup object that is associated with this markup annotation.

Note
  The Popup is An indirect reference to a pop-up annotation for entering or editing the text associated with this annotation.

## ◆ GetSubject()

UString pdftron::PDF::Annots::Markup::GetSubject | ( |  | ) | const

Returns the subject of the Markup annotation. (PDF 1.5)

Returns
  A string representing the subject of the Markup annotation.

Note
  The subject is a short piece of text description about the annotation.
  This corresponds to the 'Subj' field of the annotation's dictionary.

## ◆ GetTitle()

UString pdftron::PDF::Annots::Markup::GetTitle | ( |  | ) |

Returns the title of the markup annotation.

Returns
  A string representing the title of the markup annotation, or null is the title is not specified.

Note
  The title is The text label that is displayed in the title bar of the annotation's pop-up window when open and active Markup annotation. This entry is also used to identify the user who added the annotation. It corresponds to the 'T' field of the annotation's dictionary.

## ◆ RotateAppearance()

void pdftron::PDF::Annots::Markup::RotateAppearance | ( | double | angle | ) |

Rotates the appearance of the Markup annotation.

Parameters

  angle | The new rotation

Note
  Apply a rotation to an existing appearance. This rotation will be reflected in the bounding rect of the annot (which will be updated), but not in any other part of the annotation dictionary. This will effectively create a custom appearance for the annotation, and any subsequent calls to RefreshAppearance will clear this transformation.

## ◆ SetBorderEffect()

void pdftron::PDF::Annots::Markup::SetBorderEffect | ( | BorderEffect | effect = e_None | ) |

Sets the border effect of the markup annotation. (Optional; PDF 1.5 )

Beginning with PDF 1.5, some annotations (square, circle, and polygon) may have a 'BE' entry, which is a border effect dictionary that specifies an effect that shall be applied to the border of the annotations. Beginning with PDF 1.6, the free text annotation may also have a BE entry.

Parameters

  effect | An entry from the enum "BorderEffect" that represents the border effect of the Markup annotation. Default value: e_None.

Note
  When "e_Cloudy" is chosen,the width and dash array specified by the annotation's BorderStyle entry needs to be taken into consideration.

## ◆ SetBorderEffectIntensity()

void pdftron::PDF::Annots::Markup::SetBorderEffectIntensity | ( | double | intensity = 0 | ) |

Sets the border effect intensity of the markup annotation. (Optional; valid only if Border effect is Cloudy)

Beginning with PDF 1.5, some annotations (square, circle, and polygon) may have a 'BE' entry, which is a border effect dictionary that specifies an effect that shall be applied to the border of the annotations. Beginning with PDF 1.6, the free text annotation may also have a BE entry.

Parameters

  intensity | A number describing the intensity of the border effect, in the range 0 (which is default) to 2.

Note
  this parameter applies only if Border effect is e_Cloudy.

## ◆ SetContentRect()

void pdftron::PDF::Annots::Markup::SetContentRect | ( | const Rect & | cr | ) |

Sets the inner bounding rectangle of the Markup annotation. (Optional)

Parameters

  cr | A Rect struct to be assign to the 'RD' entry of the annotation dictionary.

Note
  This rectangle can be same as or inside of the annotation's rectangle. If it is smaller, such a difference may occur in situations where a border effect causes the size of the annotation Rect entry to increase beyond that of the rectangle. For FreeText annotation with a callout, content rectangle specifies an inner region for the text to be displayed.
  According to PDF Reference Manual content rectangle is not the property that is expected for Markup annotations in general, but it applies to many derived annotation classes (FreeText,Square,Circle,Caret) and therefore get()/set() methods are provided in the base class Markup. Annotations that do not use this property will ignore the content rectangle ('RD' entry), if present in their annotation dictionary.

## ◆ SetCreationDates()

void pdftron::PDF::Annots::Markup::SetCreationDates | ( | const Date & | dt | ) |

Sets the creation date for the markup annotation. (Optional; PDF 1.5 )

Parameters

  dt | A Date object indicating the date the markup annotation is created.

Note
  This corresponds to the 'CreationDate' field of the markup annotation's dictionary.

## ◆ SetInteriorColor()

void pdftron::PDF::Annots::Markup::SetInteriorColor | ( | const ColorPt & | c,
|  | int | CompNum )

Sets the interior color of the Markup annotation.

Parameters

  c | A ColorPt object that denotes the color of the Markup annotation.
  CompNum | An integer indicating the number of channels forming the color space used. It also defines the length of the array to be allocated for storing the entries of c.

Note
  It is necessary to make sure the consistency between the type of parameter c and the value of parameter CompNum. RGB ColorPt corresponds to 3, CMYK ColorPt corresponds to 4, Gray ColorPt corresponds to 1, and transparent corresponds to 0.
  According to PDF Reference Manual interior color is not the property that is expected for Markup annotations in general, but it applies to many derived annotation classes and therefore get()/set() methods are provided in the base class Markup. Annotations that do not use interior color will ignore the interior color ('IC' entry), if present in their annotation dictionary.

Entries out of the specified color space array length will be discarded. Missing entries for a specified color space will lead to potential exceptions.

## ◆ SetOpacity()

void pdftron::PDF::Annots::Markup::SetOpacity | ( | double | op | ) |

Sets the opacity value for the annotation. (Optional; PDF 1.4 )

Parameters

  op | A number indicating the Markup annotation's opacity value. Default value: 1.0.

Note
  This value is applied to all visible elements of the annotation in its closed state (including its background and border) but not to the pop-up window that appears when the annotation is opened. When an appearance stream is presented with the annotation, this entry is ignored.(However, if the compliant viewer regenerates the annotation's appearance stream, it may incorporate this Opacity entry into the stream's content.)
  This corresponds to the 'CA' field of the annotation's dictionary.

## ◆ SetPadding() [1/2]

void pdftron::PDF::Annots::Markup::SetPadding | ( | const Rect & | rd | ) |

Sets the rectangle difference between overall annotation rectangle and content rectangle. (Optional)

Parameters

  rd | A set of four numbers represented as a Rect struct

Note
  The four numbers of rd specify the difference between two rectangles: the Rect entry of the annotation and the actual bounding box of the underlying rectangle. Such a difference may occur in situations where a border effect causes the size of the annotation Rect entry to increase beyond that of the rectangle. The four numbers of the rd correspond to the differences in default user space, between the left, top, right, and bottom of the two above mentioned rectangles.
  SetPadding() and SetContentRectangle() both use 'RD' entry of the annotation dictionary. Two methods are provided to give users additional flexibility and ease of use in setting the values of the 'RD' field.

See also
  GetContentRect()

## ◆ SetPadding() [2/2]

void pdftron::PDF::Annots::Markup::SetPadding | ( | double | x | ) |

## ◆ SetPopup()

void pdftron::PDF::Annots::Markup::SetPopup | ( | const Popup & | ppup | ) |

Sets the Popup object associated with this markup annotation. (Optional; PDF 1.3 )

Parameters

  ppup | A Popup object that is associated with this markup annotation.

Note
  the Popup is An indirect reference to a pop-up annotation for entering or editing the text associated with this annotation.

## ◆ SetSubject()

void pdftron::PDF::Annots::Markup::SetSubject | ( | const UString & | contents | ) |

Sets subject of the Markup annotation. (Optional; PDF 1.5 )

Parameters

  contents | A string representing the subject of the Markup annotation.

Note
  The subject is a short piece of text description about the annotation.
  This corresponds to the 'Subj' field of the annotation's dictionary.

## ◆ SetTitle() [1/2]

void pdftron::PDF::Annots::Markup::SetTitle | ( | const char * | title | ) |

Sets the title of the markup annotation. (Optional; PDF 1.1)

Parameters

  title | A string.

Note
  The title is The text label that is displayed in the title bar of the annotation's pop-up window when open and active Markup annotation. This entry is also used to identify the user who added the annotation. It corresponds to the 'T' field of the annotation's dictionary.

## ◆ SetTitle() [2/2]

void pdftron::PDF::Annots::Markup::SetTitle | ( | const UString & | title | ) |

Sets the title of the markup annotation. (Optional; PDF 1.1)

Parameters

  title | A string.

Note
  The title is The text label that is displayed in the title bar of the annotation's pop-up window when open and active Markup annotation. This entry is also used to identify the user who added the annotation. It corresponds to the 'T' field of the annotation's dictionary.

The documentation for this class was generated from the following file:

- PDF/Annots/Markup.h