#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)

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 ()

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 Annot *	CreateInternal (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

enum pdftron::PDF::Annots::Widget::HighlightingMode

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.

enum pdftron::PDF::Annots::Widget::IconCaptionRelation

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.

enum pdftron::PDF::Annots::Widget::ScaleCondition

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.

enum pdftron::PDF::Annots::Widget::ScaleType

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

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.

pdftron::PDF::Annots::Widget::Widget ( const Annot & ann )

inline

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

Parameters

ann	Annot 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

doc	A document to which the annotation is added.
pos	A rectangle specifying the annotation's bounds in default user space units.
field	A 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

action An 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

col	A color point that denotes the color of the screen background.
compnum	An 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

col	A color object that denotes the color of the screen border.
compnum	An 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

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

void pdftron::PDF::Annots::Widget::SetFont ( const Font & font )

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

Parameters

font	the font to use.

void pdftron::PDF::Annots::Widget::SetFontSize ( double font_size )

Sets the font size of the Widget Annotation.

Parameters

font_size the 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

hl	A 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

icr	A 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

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

void pdftron::PDF::Annots::Widget::SetMouseDownIcon ( SDF::Obj icon )

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

Parameters

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

void pdftron::PDF::Annots::Widget::SetRolloverCaptionText ( const UString & contents )

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

Parameters

contents A 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

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

void pdftron::PDF::Annots::Widget::SetScaleCondition ( ScaleCondition sd )

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

Parameters

sd	A 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

st	An 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

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

void pdftron::PDF::Annots::Widget::SetStaticIcon ( SDF::Obj icon )

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

Parameters

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

void pdftron::PDF::Annots::Widget::SetTextColor	(	const ColorPt &	color,
		int	col_comp
	)

Sets the text color of the Widget Annotation.

Parameters

color	ColorPt object representing the color.
col_comp	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".

void pdftron::PDF::Annots::Widget::SetVIconLeftOver ( double vl )

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

Parameters

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

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

PDF/Annots/Widget.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation