All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
pdftron::PDF::Annots::Widget Class Reference

#include <Widget.h>

+ Inheritance diagram for pdftron::PDF::Annots::Widget:

Public Types

enum  HighlightingMode {
  e_none, e_invert, e_outline, e_push,
  e_toggle
}
 
enum  IconCaptionRelation {
  e_NoIcon, e_NoCaption, e_CBelowI, e_CAboveI,
  e_CRightILeft, e_CLeftIRight, e_COverlayI
}
 
enum  ScaleCondition { e_Always, e_WhenBigger, e_WhenSmaller, e_Never }
 
enum  ScaleType { e_Anamorphic, e_Proportional }
 
- 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

 Widget (SDF::Obj d=0)
 
 Widget (const Annot &ann)
 
Field GetField () const
 
HighlightingMode GetHighlightingMode () const
 
void SetHighlightingMode (HighlightingMode mode=e_invert)
 
Action GetAction () const
 
void SetAction (const Action &action)
 
int GetBorderColorCompNum () const
 
ColorPt GetBorderColor () const
 
void SetBorderColor (const ColorPt &col, int compnum)
 
int GetBackgroundColorCompNum () const
 
ColorPt GetBackgroundColor () const
 
void SetBackgroundColor (const ColorPt &c, int compnum)
 
UString GetStaticCaptionText () const
 
void SetStaticCaptionText (const UString &contents)
 
UString GetRolloverCaptionText () const
 
void SetRolloverCaptionText (const UString &contents)
 
UString GetMouseDownCaptionText () const
 
void SetMouseDownCaptionText (const UString &contents)
 
SDF::Obj GetStaticIcon () const
 
void SetStaticIcon (SDF::Obj icon)
 
SDF::Obj GetRolloverIcon () const
 
void SetRolloverIcon (SDF::Obj icon)
 
SDF::Obj GetMouseDownIcon () const
 
void SetMouseDownIcon (SDF::Obj icon)
 
IconCaptionRelation GetIconCaptionRelation () const
 
void SetIconCaptionRelation (IconCaptionRelation icr)
 
ScaleCondition GetScaleCondition () const
 
void SetScaleCondition (ScaleCondition sd)
 
ScaleType GetScaleType () const
 
void SetScaleType (ScaleType st)
 
double GetHIconLeftOver () const
 
void SetHIconLeftOver (double hl)
 
double GetVIconLeftOver () const
 
void SetVIconLeftOver (double vl)
 
bool GetFitFull () const
 
void SetFitFull (bool ff)
 
ColorPt GetTextColor ()
 
int GetTextColorCompNum ()
 
void SetTextColor (const ColorPt &color, int col_comp)
 
double GetFontSize () const
 
void SetFontSize (double font_size)
 
Font GetFont () const
 
void SetFont (const Font &font)
 
- Public Member Functions inherited from pdftron::PDF::Annot
 Annot (SDF::Obj d=0)
 
 Annot (const Annot &d)
 
Annotoperator= (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 ()
 

Static Public Member Functions

static Widget Create (SDF::SDFDoc &doc, const Rect &pos, Field field)
 
- Static Public Member Functions inherited from pdftron::PDF::Annot
static Annot Create (SDF::SDFDoc &doc, Type type, const Rect &pos)
 
static AnnotCreateInternal (ptrdiff_t impl)
 

Detailed Description

Interactive forms use widget annotations (PDF 1.2) to represent the appearance of fields and to manage user interactions. As a convenience, when a field has only a single associated widget annotation, the contents of the field dictionary and the annotation dictionary may be merged into a single dictionary containing entries that pertain to both a field and an annotation. NOTE This presents no ambiguity, since the contents of the two kinds of dictionaries do not conflict.

Definition at line 26 of file Widget.h.

Member Enumeration Documentation

This enum specifies the Highlighting mode of the widget annotation

Enumerator
e_none 

No highlighting.

e_invert 

Invert the contents of the annotation rectangle.

e_outline 

Invert the annotation's border.

e_push 

Display the annotation's down appearance, if any. If no down appearance is defined, the contents of the annotation rectangle shall be offset to appear as if it were being pushed below the surface of the page.

e_toggle 

Same as e_push (which is preferred).

Definition at line 66 of file Widget.h.

An enumeration indicating where to position the text of the annotation's caption relative to its icon.

e_NoIcon - No icon; caption only e_NoCaption - No caption; icon only e_CBelowI - Caption below the icon e_CAboveI - Caption above the icon e_CRightILeft - Caption to the right of the icon e_CLeftIRight - Caption to the left of the icon e_COverlayI - Caption overlaid directly on the icon Default value: e_NoIcon.

Enumerator
e_NoIcon 
e_NoCaption 
e_CBelowI 
e_CAboveI 
e_CRightILeft 
e_CLeftIRight 
e_COverlayI 

Definition at line 323 of file Widget.h.

Note
The functionality documented below is part of the Icon Fit dictionary. This dictionary specifies how to display the button's icon within the annotation rectangle. If present, the icon fit dictionary shall apply to all of the annotation's icons (normal, rollover, and alternate). This enum represents the circumstances under which the icon shall be scaled inside the annotation rectangle .
Enumerator
e_Always 

Always scale.

e_WhenBigger 

Scale only when the icon is bigger than the annotation rectangle.

e_WhenSmaller 

Scale only when the icon is smaller than the annotation rectangle.

e_Never 

Never scale.

Definition at line 366 of file Widget.h.

This enum represents the scale type of the annotation.

e_Anamorphic - Scale the icon to fill the annotation rectangle exactly, without regard to its original aspect ratio (ratio of width to height). e_Proportional - Scale the icon to fit the width or height of the annotation rectangle while maintaining the icon's original aspect ratio. If the required horizontal and vertical scaling factors are different, use the smaller of the two, centering the icon within the annotation rectangle in the other dimension. Default value: e_Proportional.

Enumerator
e_Anamorphic 
e_Proportional 

Definition at line 407 of file Widget.h.

Constructor & Destructor Documentation

pdftron::PDF::Annots::Widget::Widget ( SDF::Obj  d = 0)

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

Parameters
dThe 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.
pdftron::PDF::Annots::Widget::Widget ( const Annot ann)
inline

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

Parameters
annAnnot object used to initialize the Widget annotation.
Note
The constructor does not copy any data, but is instead the logical equivalent of a type cast.

Definition at line 44 of file Widget.h.

Member Function Documentation

static Widget pdftron::PDF::Annots::Widget::Create ( SDF::SDFDoc doc,
const Rect pos,
Field  field 
)
static

Creates a new widget annotation in the specified document.

Parameters
docA document to which the annotation is added.
posA rectangle specifying the annotation's bounds in default user space units.
fieldA form field associated with this widget.
Returns
A newly created blank widget annotation.
Action pdftron::PDF::Annots::Widget::GetAction ( ) const

Returns the action of the widget annotation

Returns
An action object representing the action of the widget annotation that should be performed when the annotation is activated.
ColorPt pdftron::PDF::Annots::Widget::GetBackgroundColor ( ) const

Returns the background color of the annotation.

Returns
A color object that denotes the color of the Screen background.
Note
The color can be in different color spaces: Gray, RGB, or CMYK. Call "GetBackgroundColorCompNum" to access the color space information corresponding to the border color.
int pdftron::PDF::Annots::Widget::GetBackgroundColorCompNum ( ) const

Returns the number indicating background color space of the annotation.

Returns
An integer indicating a color space value from the ColorSpace::Type enum. That is, 1 corresponding to "e_device_gray", 3 corresponding to "e_device_rgb", and 4 corresponding to "e_device_cmyk" if color space is applicable, 0 means no background color was assigned.
ColorPt pdftron::PDF::Annots::Widget::GetBorderColor ( ) const

Returns the border color of the annotation.

Returns
A color object that denotes the color of the Screen border.
Note
The color can be in different color spaces: Gray, RGB, or CMYK. Call "GetBorderColorCompNum" to access the color space information corresponding to the border color.
int pdftron::PDF::Annots::Widget::GetBorderColorCompNum ( ) const

Returns the number indicating border color space of the annotation.

Returns
An integer indicating a color space value from the ColorSpace::Type enum. That is, 1 corresponding to "e_device_gray", 3 corresponding to "e_device_rgb", and 4 corresponding to "e_device_cmyk". 0 means this annotation had no color assigned.
Field pdftron::PDF::Annots::Widget::GetField ( ) const

Returns the field associated with the Widget.

Returns
A Field object.
bool pdftron::PDF::Annots::Widget::GetFitFull ( ) const

Returns the "fit full" flag.

Returns
A boolean value indicating the "fit full" flag value.
Note
the fit full flag, if true, indicates that the button appearance shall be scaled to fit fully within the bounds of the annotation without taking into consideration the line width of the border. Default value: false.
Font pdftron::PDF::Annots::Widget::GetFont ( ) const

Retrieves the font used for displaying text in this Widget.

Returns
the font used by this Widget.
double pdftron::PDF::Annots::Widget::GetFontSize ( ) const

Returns the font size used in this Widget Annotation.

Returns
the font size
Note
A font size of 0 specifies that the text should be autosized to fit in the Widget.
double pdftron::PDF::Annots::Widget::GetHIconLeftOver ( ) const

Returns the horizontal leftover space of the icon within the annotation.

Returns
A number indicating the horizontal leftover space of the icon within the annotation.
Note
the horizontal leftover is a number that shall be between 0.0 and 1.0 indicating the fraction of leftover space to allocate at the left. A value of 0.0 shall position the icon at the left of the annotation rectangle. A value of 0.5 shall center it in the horizontal direction within the rectangle. This entry shall be used only if the icon is scaled proportionally. Default value: 0.5.
HighlightingMode pdftron::PDF::Annots::Widget::GetHighlightingMode ( ) const
Returns
the HighlightingMode of the widget annotation.
Note
The annotation's highlighting mode is the visual effect that shall be used when the mouse button is pressed or held down inside its active area
A highlighting mode other than e_push will override any down appearance defined for the annotation. e_invert.
IconCaptionRelation pdftron::PDF::Annots::Widget::GetIconCaptionRelation ( ) const

Returns the Icon and caption relationship of the annotation.

Returns
A value of the "IconCaptionRelation" enum type. Default value: e_NoIcon.
See also
IconCaptionRelation
UString pdftron::PDF::Annots::Widget::GetMouseDownCaptionText ( ) const

Returns the button down caption text of the annotation.

Returns
A string containing the button down text of the annotation.
Note
The button down caption shall be displayed when the mouse button is pressed within its active area.
SDF::Obj pdftron::PDF::Annots::Widget::GetMouseDownIcon ( ) const

Returns the Mouse Down icon associated with the annotation.

Returns
An SDF object that represents the Mouse Down icon associated with the annotation.
Note
The Mouse Down icon object is a form XObject defining the annotation's alternate (down) icon, which shall be displayed when the mouse button is pressed within its active area.
UString pdftron::PDF::Annots::Widget::GetRolloverCaptionText ( ) const

Returns the rollover caption text of the annotation.

Returns
A string containing the rollover caption text of the annotation.
Note
The rollover caption shall be displayed when the user rolls the cursor into its active area without pressing the mouse button.
SDF::Obj pdftron::PDF::Annots::Widget::GetRolloverIcon ( ) const

Returns the rollover icon associated with the annotation.

Returns
An SDF object that represents the rollover icon associated with the annotation.
Note
The rollover icon object is a form XObject defining the annotation's rollover icon, which shall be displayed when the user rolls the cursor into its active area without pressing the mouse button.
ScaleCondition pdftron::PDF::Annots::Widget::GetScaleCondition ( ) const

Returns the condition under which the icon should be scaled.

Returns
A value of the "ScaleCondition" enum type. Default value: e_Always.
See also
ScaleCondition
ScaleType pdftron::PDF::Annots::Widget::GetScaleType ( ) const

Returns the Scale Type of the annotation.

Returns
A value of the "ScaleType" enum which represents the Scale Type of the annotation. Default value: P.
See also
ScaleType
UString pdftron::PDF::Annots::Widget::GetStaticCaptionText ( ) const

Returns static caption text of the annotation.

Returns
A string containing the static caption text of the annotation.
Note
The static caption is the annotation's normal caption, which shall be displayed when it is not interacting with the user. Unlike the remaining entries with the captions, which apply only to widget annotations associated with pushbutton fields, the Static Caption(CA) entry may be used with any type of button field, including check boxes.
This property is part of the Widget appearance characteristics dictionary, this dictionary that shall be used in constructing a dynamic appearance stream specifying the annotation's visual presentation on the page.
SDF::Obj pdftron::PDF::Annots::Widget::GetStaticIcon ( ) const

Returns the static icon associated with the annotation.

Returns
An SDF object that represents the static icon associated with the annotation.
Note
The static icon object is a form XObject defining the annotation's normal icon, which shall be displayed when it is not interacting with the user.
ColorPt pdftron::PDF::Annots::Widget::GetTextColor ( )

Returns the text color of the Widget Annotation.

Returns
the text color.
Note
the color can be in different color spaces: Gray, RGB, or CMYK. Call "GetTextColorCompNum" to access the color space information corresponding to the border color.
int pdftron::PDF::Annots::Widget::GetTextColorCompNum ( )

Returns the number of color components in the text color of the Widget Annotation.

Returns
An integer indicating a color space value from the ColorSpace::Type enum. That is, 1 corresponding to "e_device_gray", 3 corresponding to "e_device_rgb", and 4 corresponding to "e_device_cmyk" if color space is applicable.
double pdftron::PDF::Annots::Widget::GetVIconLeftOver ( ) const

Returns the vertical leftover space of the icon within the annotation.

Returns
a number indicating the vertical leftover space of the icon within the annotation.
Note
the vertical leftover space is a number that shall be between 0.0 and 1.0 indicating the fraction of leftover space to allocate at the bottom of the icon. A value of 0.0 shall position the icon at the bottom of the annotation rectangle. A value of 0.5 shall center it in the vertical direction within the rectangle. This entry shall be used only if the icon is scaled proportionally. Default value: 0.5.
void pdftron::PDF::Annots::Widget::SetAction ( const Action action)

Sets the action of the widget annotation (Optional; PDF 1.2 )

Parameters
actionAn action object representing the action of the widget annotation that should be performed when the annotation is activated.
void pdftron::PDF::Annots::Widget::SetBackgroundColor ( const ColorPt c,
int  compnum 
)

Sets the background color of the annotation. (Optional)

Parameters
colA color point that denotes the color of the screen background.
compnumAn integer which value indicates the color space used for the parameter c.
void pdftron::PDF::Annots::Widget::SetBorderColor ( const ColorPt col,
int  compnum 
)

Sets the border color of the annotation. (Optional)

Parameters
colA color object that denotes the color of the screen border.
compnumAn integer which value indicates the color space used for the parameter c.
void pdftron::PDF::Annots::Widget::SetFitFull ( bool  ff)

Sets the "fit full" flag. (Optional)

Parameters
ffA boolean value indicating the "fit full" flag value.
Note
the fit full flag, if true, indicates that the button appearance shall be scaled to fit fully within the bounds of the annotation without taking into consideration the line width of the border. Default value: false.
void pdftron::PDF::Annots::Widget::SetFont ( const Font font)

Specifies a font to be used for text in this Widget.

Parameters
fontthe font to use.
void pdftron::PDF::Annots::Widget::SetFontSize ( double  font_size)

Sets the font size of the Widget Annotation.

Parameters
font_sizethe new font size
Note
A font size of 0 specifies that the text should be autosized to fit in the Widget.
void pdftron::PDF::Annots::Widget::SetHIconLeftOver ( double  hl)

Sets the horizontal leftover space of the icon within the annotation. (Optional)

Parameters
hlA number indicating the horizontal leftover space of the icon within the annotation.
Note
the horizontal leftover space is a number that shall be between 0.0 and 1.0 indicating the fraction of leftover space to allocate at the left. A value of 0.0 shall position the icon at the left of the annotation rectangle. A value of 0.5 shall center it in the horizontal direction within the rectangle. This entry shall be used only if the icon is scaled proportionally. Default value: 0.5.
void pdftron::PDF::Annots::Widget::SetHighlightingMode ( HighlightingMode  mode = e_invert)

Sets the HighlightingMode for the widget annotation.

Note
The annotation's highlighting mode is the visual effect that shall be used when the mouse button is pressed or held down inside its active area
Parameters
mode- New highlighting mode for the widget.
Note
A highlighting mode other than e_push shall override any down appearance defined for the annotation. Default value: e_invert.
void pdftron::PDF::Annots::Widget::SetIconCaptionRelation ( IconCaptionRelation  icr)

Sets the Icon and caption relationship of the annotation. (Optional; pushbutton fields only)

Parameters
icrA value of the "IconCaptionRelation" enum type. Default value: e_NoIcon.
See also
IconCaptionRelation
void pdftron::PDF::Annots::Widget::SetMouseDownCaptionText ( const UString contents)

Sets the button down caption text of the annotation. (Optional; button fields only)

Parameters
contentsA string containing the button down text of the annotation.
Note
The button down caption shall be displayed when the mouse button is pressed within its active area.
void pdftron::PDF::Annots::Widget::SetMouseDownIcon ( SDF::Obj  icon)

Sets the Mouse Down icon associated with the annotation. (Optional; button fields only)

Parameters
iconAn SDF object that represents the Mouse Down icon associated with the annotation.
Note
The Mouse Down icon object is a form XObject defining the annotation's alternate (down) icon, which shall be displayed when the mouse button is pressed within its active area.
void pdftron::PDF::Annots::Widget::SetRolloverCaptionText ( const UString contents)

Sets the roll over caption text of the annotation. (Optional; button fields only)

Parameters
contentsA string containing the roll over caption text of the annotation.
Note
The rollover caption shall be displayed when the user rolls the cursor into its active area without pressing the mouse button.
void pdftron::PDF::Annots::Widget::SetRolloverIcon ( SDF::Obj  icon)

Sets the rollover icon associated with the annotation. (Optional; button fields only)

Parameters
iconAn SDF object that represents the rollover icon associated with the annotation.
Note
The rollover icon object is a form XObject defining the annotation's rollover icon, which shall be displayed when the user rolls the cursor into its active area without pressing the mouse button.
void pdftron::PDF::Annots::Widget::SetScaleCondition ( ScaleCondition  sd)

Sets the condition under which the icon should be scaled. (Optional)

Parameters
sdA value of the "ScaleCondition" enum type. Default value: e_Always.
void pdftron::PDF::Annots::Widget::SetScaleType ( ScaleType  st)

Sets the Scale Type of the annotation. (Optional)

Parameters
stAn entry of the "ScaleType" enum which represents the Scale Type of the annotation. Default value: P.
See also
ScaleType
void pdftron::PDF::Annots::Widget::SetStaticCaptionText ( const UString contents)

Sets static caption text of the annotation. (Optional; button fields only)

Parameters
contentsA string containing the static caption text of the annotation.
Note
The static caption is the annotation's normal caption, which shall be displayed when it is not interacting with the user. Unlike the remaining entries with the captions, which apply only to widget annotations associated with pushbutton fields, the Static Caption(CA) entry may be used with any type of button field, including check boxes.
This property is part of the Widget appearance characteristics dictionary, this dictionary that shall be used in constructing a dynamic appearance stream specifying the annotation's visual presentation on the page.
void pdftron::PDF::Annots::Widget::SetStaticIcon ( SDF::Obj  icon)

Sets the static icon associated with the annotation. (Optional; button fields only)

Parameters
iconAn SDF object that represents the static icon associated with the annotation.
Note
The static icon object is a form XObject defining the annotation's normal icon, which shall be displayed when it is not interacting with the user.
void pdftron::PDF::Annots::Widget::SetTextColor ( const ColorPt color,
int  col_comp 
)

Sets the text color of the Widget Annotation.

Parameters
colorColorPt object representing the color.
col_compAn integer indicating a color space value from the ColorSpace::Type enum. That is, 1 corresponding to "e_device_gray", 3 corresponding to "e_device_rgb", and 4 corresponding to "e_device_cmyk".
void pdftron::PDF::Annots::Widget::SetVIconLeftOver ( double  vl)

Sets the vertical leftover space of the icon within the annotation. (Optional)

Parameters
vlA number indicating the vertical leftover space of the icon within the annotation.
Note
the vertical leftover space is a number that shall be between 0.0 and 1.0 indicating the fraction of leftover space to allocate at the bottom of the icon. A value of 0.0 shall position the icon at the bottom of the annotation rectangle. A value of 0.5 shall center it in the vertical direction within the rectangle. This entry shall be used only if the icon is scaled proportionally. Default value: 0.5.

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