pdftron::PDF::Annots::Widget Class Reference

A Widget annotation (PDF 1.2) are used to represent the appearance of interactive form field and to manage user interactions with forms. More...

#include <Widget.h>

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

Inheritance graph
[legend]
Collaboration diagram for pdftron::PDF::Annots::Widget:

Collaboration graph
[legend]

List of all members.

Public Types

enum  HighlightingMode {
  e_none, e_invert, e_outline, e_push,
  e_toggle
}
 This enum specifies the Highlighting mode of the widget annotation. More...
enum  IconCaptionRelation {
  e_NoIcon, e_NoCaption, e_CBelowI, e_CAboveI,
  e_CRightILeft, e_CLeftIRight, e_COverlayI
}
 An enumeration indicating where to position the text of the annotation’s caption relative to its icon. More...
enum  ScaleCondition { e_Always, e_WhenBigger, e_WhenSmaller, e_Never }
 This enum represents the circumstances under which the icon shall be scaled inside the annotation rectangle . More...
enum  ScaleType { e_Anamorphic, e_Proportional }
 This enum represents the scale type of the annotation. More...

Public Member Functions

 Widget (SDF::Obj d=0)
 Creates a widget annotation and initializes it using given Cos/SDF object.
 Widget (const Annot &ann)
 Creates a widget annotation and initializes it using given annotation object.
Field GetField () const
 Returns the field associated with the Widget.
HighlightingMode GetHighlightingMode () const
void SetHighlightingMode (HighlightingMode mode=e_invert)
 Sets the HighlightingMode for the widget annotation.
Action GetAction () const
 Returns the action of the widget annotation.
void SetAction (const Action &action)
 Sets the action of the widget annotation (Optional; PDF 1.2 ).
SDF::Obj GetTriggerAction () const
 Returns the additional actions of the annotation.
void SetTriggerAction (SDF::Obj action)
 Assigns additional actions to the annotation (Optional; PDF 1.1 ).
int GetRotation () const
 Returns the rotation value of the annotation.
void SetRotation (int rot)
 Sets the rotation value of the annotation.
int GetBorderColorCompNum () const
 Returns the number indicating border color space of the annotation.
ColorPt GetBorderColor () const
 Returns the border color of the annotation.
void SetBorderColor (const ColorPt &c, int CompNum)
 Sets the border color of the annotation.
int GetBackgroundColorCompNum () const
 Returns the number indicating background color space of the annotation.
ColorPt GetBackgroundColor () const
 Returns the background color of the annotation.
void SetBackgroundColor (const ColorPt &c, int CompNum)
 Sets the background color of the annotation.
UString GetStaticCaptionText () const
 Returns static caption text of the annotation.
void SetStaticCaptionText (const UString &ct)
 Sets static caption text of the annotation.
UString GetRolloverCaptionText () const
 Returns the rollover caption text of the annotation.
void SetRolloverCaptionText (const UString &ct)
 Sets the roll over caption text of the annotation.
UString GetMouseDownCaptionText () const
 Returns the button down caption text of the annotation.
void SetMouseDownCaptionText (const UString &ct)
 Sets the button down caption text of the annotation.
SDF::Obj GetStaticIcon () const
 Returns the static icon associated with the annotation.
void SetStaticIcon (SDF::Obj ic)
 Sets the static icon associated with the annotation.
SDF::Obj GetRolloverIcon () const
 Returns the rollover icon associated with the annotation.
void SetRolloverIcon (SDF::Obj ic)
 Sets the rollover icon associated with the annotation.
SDF::Obj GetMouseDownIcon () const
 Returns the Mouse Down icon associated with the annotation.
void SetMouseDownIcon (SDF::Obj ic)
 Sets the Mouse Down icon associated with the annotation.
IconCaptionRelation GetIconCaptionRelation () const
 Returns the Icon and caption relationship of the annotation.
void SetIconCaptionRelation (IconCaptionRelation icr)
 Sets the Icon and caption relationship of the annotation.
ScaleCondition GetScaleCondition () const
 Returns the condition under which the icon should be scaled.
void SetScaleCondition (ScaleCondition sd)
 Sets the condition under which the icon should be scaled.
ScaleType GetScaleType () const
 Returns the Scale Type of the annotation.
void SetScaleType (ScaleType st)
 Sets the Scale Type of the annotation.
double GetHIconLeftOver () const
 Returns the horizontal leftover space of the icon within the annotation.
void SetHIconLeftOver (double hl)
 Sets the horizontal leftover space of the icon within the annotation.
double GetVIconLeftOver () const
 Returns the vertical leftover space of the icon within the annotation.
void SetVIconLeftOver (double vl)
 Sets the vertical leftover space of the icon within the annotation.
bool GetFitFull () const
 Returns the "fit full" flag.
void SetFitFull (bool ff)
 Sets the "fit full" flag.

Static Public Member Functions

static Widget Create (SDF::SDFDoc &doc, const Rect &pos, Field field)
 Creates a new widget annotation in the specified document.


Detailed Description

A Widget annotation (PDF 1.2) are used to represent the appearance of interactive form field and to manage user interactions with forms.

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

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 

This enum represents the circumstances under which the icon shall be scaled inside the annotation rectangle .

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

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 


Constructor & Destructor Documentation

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

Creates a widget annotation and initializes 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::Annots::Widget::Widget ( const Annot ann  )  [inline]

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

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


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.

Field pdftron::PDF::Annots::Widget::GetField (  )  const

Returns the field associated with the Widget.

Returns:
A Field object.

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.

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.

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.

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.

SDF::Obj pdftron::PDF::Annots::Widget::GetTriggerAction (  )  const

Returns the additional actions of the annotation.

Returns:
An SDF object representing the additional actions dictionary of the annotation.
Note:
An additional-actions dictionary defines the screen annotation’s behaviour in response to various trigger events. This corresponds to 'AA' entry of the annotation dictionary.

void pdftron::PDF::Annots::Widget::SetTriggerAction ( SDF::Obj  action  ) 

Assigns additional actions to the annotation (Optional; PDF 1.1 ).

Parameters:
action An SDF dictionary object representing the actions of the annotation.
Note:
An additional-actions dictionary defines the screen annotation’s behaviour in response to various trigger events. This corresponds to 'AA' entry of the annotation dictionary.

int pdftron::PDF::Annots::Widget::GetRotation (  )  const

Returns the rotation value of the annotation.

Note:
The functionality documented below is part of the appearance characteristics dictionary, the dictionary that shall be used in constructing a dynamic appearance stream specifying the annotation’s visual presentation on the page.
Returns:
An integer representing the rotation value of the annotation.
Note:
The Rotation specifies the number of degrees by which the annotation shall be rotated counterclockwise relative to the page. The value shall be a multiple of 90. Default value: 0.

void pdftron::PDF::Annots::Widget::SetRotation ( int  rot  ) 

Sets the rotation value of the annotation.

(Optional)

Parameters:
rot An integer representing the rotation value of the annotation.
Note:
the Rotation specifies the number of degrees by which the annotation shall be rotated counterclockwise relative to the page. The value shall be a multiple of 90. Default value: 0.

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.

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.

void pdftron::PDF::Annots::Widget::SetBorderColor ( const ColorPt c,
int  CompNum 
)

Sets the border color of the annotation.

(Optional)

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

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

void pdftron::PDF::Annots::Widget::SetBackgroundColor ( const ColorPt c,
int  CompNum 
)

Sets the background color of the annotation.

(Optional)

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

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.

void pdftron::PDF::Annots::Widget::SetStaticCaptionText ( const UString ct  ) 

Sets static caption text of the annotation.

(Optional; button fields only)

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

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.

void pdftron::PDF::Annots::Widget::SetRolloverCaptionText ( const UString ct  ) 

Sets the roll over caption text of the annotation.

(Optional; button fields only)

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

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.

void pdftron::PDF::Annots::Widget::SetMouseDownCaptionText ( const UString ct  ) 

Sets the button down caption text of the annotation.

(Optional; button fields only)

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

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

Sets the static icon associated with the annotation.

(Optional; button fields only)

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

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.

void pdftron::PDF::Annots::Widget::SetRolloverIcon ( SDF::Obj  ic  ) 

Sets the rollover icon associated with the annotation.

(Optional; button fields only)

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

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.

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

Sets the Mouse Down icon associated with the annotation.

(Optional; button fields only)

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

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

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

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

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.

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

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

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.

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.

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

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.

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.


© 2002-2010 PDFTron Systems Inc.