pdftron::PDF::Field Class Reference

An interactive form (sometimes referred to as an AcroForm) is a collection of fields for gathering information interactively from the user. More...

#include <Field.h>

List of all members.

Public Types

enum  Type {
  e_button, e_check, e_radio, e_text,
  e_choice, e_signature, e_null
}
 Interactive forms support the following field types:
  • Button fields represent interactive controls on the screen that the user can manipulate with the mouse.
More...
enum  Flag {
  e_read_only, e_required, e_no_export, e_pushbutton_flag,
  e_radio_flag, e_toggle_to_off, e_radios_in_unison, e_multiline,
  e_password, e_file_select, e_no_spellcheck, e_no_scroll,
  e_comb, e_rich_text, e_combo, e_edit,
  e_sort, e_multiselect, e_commit_on_sel_change
}
 Flags specifying various characteristics of the fields. More...
enum  TextJustification { e_left_justified, e_centered, e_right_justified }

Public Member Functions

 Field (SDF::Obj field_dict)
 Construct a PDF::Field from a SDF dictionary representing a terminal field node.
 Field (const Field &p)
Fieldoperator= (const Field &p)
 ~Field ()
bool IsValid () const
Type GetType () const
SDF::Obj GetValue ()
UString GetValueAsString ()
bool GetValueAsBool ()
void SetValue (const UString &value)
 Sets the value of the field (i.e.
void SetValue (SDF::Obj value)
void SetValue (const char *value)
void SetValue (bool value)
 Sets the value of a check-box or radio-button field.
void RefreshAppearance ()
 Regenerates the appearance stream for the Widget Annotation containing variable text.
void EraseAppearance ()
 Removes any appearances associated with the field.
SDF::Obj GetDefaultValue ()
UString GetDefaultValueAsString ()
UString GetName ()
UString GetPartialName ()
void Rename (const UString &field_name)
 Modifies the field name.
bool IsAnnot () const
bool GetFlag (Flag flag) const
void SetFlag (Flag flag, bool value)
 Set the value of given FieldFlag.
TextJustification GetJustification ()
void SetJustification (TextJustification j)
 Sets the justification to be used in displaying the text field.
void SetMaxLen (int max_len)
 Sets the maximum length of the field's text, in characters.
int GetMaxLen () const
void Flatten (class Page page)
 Flatten/Merge existing form field appearances with the page content and remove widget annotation.
SDF::Obj FindInheritedAttribute (const char *attrib) const
 Some of the Field attributes are designated as inheritable.
SDF::Obj GetSDFObj () const
 operator bool ()


Detailed Description

An interactive form (sometimes referred to as an AcroForm) is a collection of fields for gathering information interactively from the user.

A PDF document may contain any number of Fields appearing on any combination of pages, all of which make up a single, global interactive form spanning the entire document.

PDFNet fully supports reading, writing, and editing PDF forms and provides many utility methods so that work with forms is simple and efficient. Using PDFNet forms API arbitrary subsets of form fields can be imported or exported from the document, new forms can be created from scratch, and the appearance of existing forms can be modified.

In PDFNet Fields are accessed through FieldIterator-s. The list of all Fields present in the document can be traversed as follows:

 FieldIterator itr = pdfdoc.GetFieldIterator();
 for(; itr.HasNext(); itr.Next()) {
   Field field = itr.Current();
   Console.WriteLine("Field name: {0}", field.GetName());
  }

For a full sample, please refer to 'InteractiveForms' sample project.

To search field by name use FieldFind method. For example:

 FieldIterator itr = pdfdoc.FieldFind("name");
 if (itr.HasNext()) {
   Console.WriteLine("Field name: {0}", itr.Current().GetName());
 }
 else { ...field was not found... }

If a given field name was not found or if the end of the field list was reached the iterator HasNext() will return false.

If you have a valid iterator you can access the Field using Current() method. For example: Field field = itr.Current();

Using Flatten(...) method it is possible to merge field appearances with the page content. Form 'flattening' refers to the operation that changes active form fields into a static area that is part of the PDF document, just like the other text and images in the document. A completely flattened PDF form does not have any widget annotations or interactive fields.


Member Enumeration Documentation

Interactive forms support the following field types:

  • Button fields represent interactive controls on the screen that the user can manipulate with the mouse.

They include pushbuttons, check-boxes, and radio buttons.

  • Text fields are boxes or spaces in which the user can enter text from the keyboard.
  • Choice fields contain several text items, at most one of which may be selected as the field value. They include scrollable list boxes and combo boxes.
  • Signature fields represent electronic 'signatures' for authenticating the identity of a user and the validity of the document’s contents.
Enumerator:
e_button 
e_check 
e_radio 
e_text 
e_choice 
e_signature 
e_null 

Flags specifying various characteristics of the fields.

Field flags common to all field types: ----------------------------------------------

  • If e_read_only flag is set the user may not change the value of the field. Any associated widget annotations will not interact with the user; that is, they will not respond to mouse clicks or change their appearance in response to mouse motions. This flag is useful for fields whose values are computed or imported from a database.

  • If e_required flag is set, the field must have a value at the time it is exported by a submit-form action.

  • If e_no_export flag is set, the field must not be exported by a submit-form action.

Field flags specific to radio buttons: ----------------------------------------------

  • If e_toggle_to_off is clear, exactly one radio button must be selected at all times; clicking the currently selected button has no effect. If set, clicking the selected button deselects it, leaving no button selected.

  • If e_radios_in_unison is set, a group of radio buttons within a radio button field that use the same value for the on state will turn on and off in unison; that is if one is checked, they are all checked. If clear, the buttons are mutually exclusive (the same behavior as HTML radio buttons).

Field flags specific to text fields: ----------------------------------------------

  • If e_multiline is set, the field can contain multiple lines of text; if clear, the field’s text is restricted to a single line.

  • If e_password If set, the field is intended for entering a secure password that should not be echoed visibly to the screen. Characters typed from the keyboard should instead be echoed in some unreadable form, such as asterisks or bullet characters. The value is not stored if this flag is set.

  • If e_file_select is set, the text entered in the field represents the pathname of a file whose contents are to be submitted as the value of the field.

  • If e_no_spellcheck is set, text entered in the field is not spell-checked.

  • If e_no_scroll is set, the field does not scroll (horizontally for single-line fields, vertically for multiple-line fields) to accommodate more text than fits within its annotation rectangle. Once the field is full, no further text is accepted.

  • If e_comb is set, the field is automatically divided into as many equally spaced positions, or combs, as the value of MaxLen, and the text is laid out into those combs. Meaningful only if the MaxLen entry is present in the text field and if the Multiline, Password, and FileSelect flags are clear.

  • If e_rich_text is set, the value of this field should be represented as a rich text string. If the field has a value, the RV entry of the field dictionary specifies the rich text string.

Field flags specific to choice fields: ----------------------------------------------

  • If e_combo is set, the field is a combo box; if clear, the field is a list box.

  • If e_edit is set, the combo box includes an editable text box as well as a dropdown list; if clear, it includes only a drop-down list. This flag is meaningful only if the e_combo flag is set.

  • If e_sort is set, the field’s option items should be sorted alphabetically. This flag is intended for use by form authoring tools, not by PDF viewer applications. Viewers should simply display the options in the order in which they occur in the Opt array.

  • If e_multiselect is set, more than one of the field’s option items may be selected simultaneously; if clear, no more than one item at a time may be selected.

  • If e_commit_on_sel_change is set, the new value is committed as soon as a selection is made with the pointing device. This option enables applications to perform an action once a selection is made, without requiring the user to exit the field. If clear, the new value is not committed until the user exits the field.
Enumerator:
e_read_only 
e_required 
e_no_export 
e_pushbutton_flag 
e_radio_flag 
e_toggle_to_off 
e_radios_in_unison 
e_multiline 
e_password 
e_file_select 
e_no_spellcheck 
e_no_scroll 
e_comb 
e_rich_text 
e_combo 
e_edit 
e_sort 
e_multiselect 
e_commit_on_sel_change 

Enumerator:
e_left_justified 
e_centered 
e_right_justified 


Constructor & Destructor Documentation

pdftron::PDF::Field::Field ( SDF::Obj  field_dict  ) 

Construct a PDF::Field from a SDF dictionary representing a terminal field node.

pdftron::PDF::Field::Field ( const Field p  ) 

pdftron::PDF::Field::~Field (  ) 


Member Function Documentation

Field& pdftron::PDF::Field::operator= ( const Field p  ) 

bool pdftron::PDF::Field::IsValid (  )  const

Returns:
whether this is a valid (non-null) Field. If the function returns false the underlying SDF/Cos object is null and the Field object should be treated as null as well.

Referenced by operator bool().

Type pdftron::PDF::Field::GetType (  )  const

Returns:
The field’s value, whose type/format varies depending on the field type. See the descriptions of individual field types for further information.

SDF::Obj pdftron::PDF::Field::GetValue (  ) 

Returns:
the value of the Field (the value of its /V key) or NULL if the value is not specified.
The format of field’s value varies depending on the field type.

UString pdftron::PDF::Field::GetValueAsString (  ) 

bool pdftron::PDF::Field::GetValueAsBool (  ) 

Returns:
Field value as a boolean.
Note:
This method is usually for check-box and radio button fields.

void pdftron::PDF::Field::SetValue ( const UString value  ) 

Sets the value of the field (i.e.

the value of the field's /V key). The format of field's value varies depending on the field type.

Parameters:
value the new field value.
Note:
in order to remove/erase the existing value use pass a SDF::Null object to SetValue().

In PDF, Field's value is separate from its annotation (i.e. how the field appears on the page). After you modify Field's value you need to refresh Field's appearance using RefreshAppearance() method.

Alternatively, you can delete "AP" entry from the Widget annotation and set "NeedAppearances" flag in AcroForm dictionary (i.e. doc.GetAcroForm().Put("NeedAppearances", Obj.CreateBool(true)); ) This will force viewer application to auto-generate new field appearances every time the document is opened.

Yet another option is to generate a custom annotation appearance using ElementBuilder and ElementWriter and then set the "AP" entry in the widget dictionary to the new appearance stream. This functionality is useful in applications that need advanced control over how the form fields are rendered.

void pdftron::PDF::Field::SetValue ( SDF::Obj  value  ) 

void pdftron::PDF::Field::SetValue ( const char *  value  ) 

void pdftron::PDF::Field::SetValue ( bool  value  ) 

Sets the value of a check-box or radio-button field.

Parameters:
value If true, the filed will be set to 'True', if false the field will be set to 'False'.
Note:
This method is usually for check-box and radio button fields.

void pdftron::PDF::Field::RefreshAppearance (  ) 

Regenerates the appearance stream for the Widget Annotation containing variable text.

Call this method if you modified field's value and would like to update field's appearance.

void pdftron::PDF::Field::EraseAppearance (  ) 

Removes any appearances associated with the field.

SDF::Obj pdftron::PDF::Field::GetDefaultValue (  ) 

Returns:
The default value to which the field reverts when a reset-form action is executed or NULL if the default value is not specified.
The format of field’s value varies depending on the field type.

UString pdftron::PDF::Field::GetDefaultValueAsString (  ) 

UString pdftron::PDF::Field::GetName (  ) 

Returns:
a string representing the fully qualified name of the field (e.g. "employee.name.first").

UString pdftron::PDF::Field::GetPartialName (  ) 

Returns:
a string representing the partial name of the field (e.g. "first" when "employee.name.first" is fully qualified name).

void pdftron::PDF::Field::Rename ( const UString field_name  ) 

Modifies the field name.

Parameters:
field_name a string representing the fully qualified name of the field (e.g. "employee.name.first").

bool pdftron::PDF::Field::IsAnnot (  )  const

Returns:
true if this Field is a Widget Annotation
Determines whether or not this Field is an Annotation.

bool pdftron::PDF::Field::GetFlag ( Flag  flag  )  const

Returns:
the value of given field flag

void pdftron::PDF::Field::SetFlag ( Flag  flag,
bool  value 
)

Set the value of given FieldFlag.

Note:
You can use this method to set the field as read-only. An alternative approach to set the field as read only is using Page.Flatten(...) method. Unlike Flatten(...), the result of SetFlag(...) can be programatically reversed.

TextJustification pdftron::PDF::Field::GetJustification (  ) 

Returns:
the form of quadding (justification) to be used in displaying the text fields.

void pdftron::PDF::Field::SetJustification ( TextJustification  j  ) 

Sets the justification to be used in displaying the text field.

Note:
This method is specific to a text field.

void pdftron::PDF::Field::SetMaxLen ( int  max_len  ) 

Sets the maximum length of the field's text, in characters.

Note:
This method is specific to a text field.

int pdftron::PDF::Field::GetMaxLen (  )  const

Returns:
The maximum length of the field's text, in characters, or a negative number if the length is not limited.
Note:
This method is specific to a text field.

void pdftron::PDF::Field::Flatten ( class Page  page  ) 

Flatten/Merge existing form field appearances with the page content and remove widget annotation.

Form 'flattening' refers to the operation that changes active form fields into a static area that is part of the PDF document, just like the other text and images in the document. A completely flattened PDF form does not have any widget annotations or interactive fields.

Note:
an alternative approach to set the field as read only is using Field.SetFlag(Field::e_read_only, true) method. Unlike Field.SetFlag(...), the result of Flatten() operation can not be programatically reversed.

SDF::Obj pdftron::PDF::Field::FindInheritedAttribute ( const char *  attrib  )  const

Some of the Field attributes are designated as inheritable.

If such an attribute is omitted from a Field object, its value is inherited from an ancestor node in the Field tree. If the attribute is a required one, a value must be supplied in an ancestor node; if it is optional and no inherited value is specified, the default value should be used.

The function walks up the Field inheritance tree in search for specified attribute.

Returns:
The attribute value if the given attribute name was found or a NULL object if the given attribute name was not found.
Resources dictionary (Required; inheritable) MediaBox rectangle (Required; inheritable) CropBox rectangle (Optional; inheritable) Rotate integer (Optional; inheritable)

SDF::Obj pdftron::PDF::Field::GetSDFObj (  )  const

Returns:
the underlying SDF/Cos object.

pdftron::PDF::Field::operator bool (  )  [inline]

Returns:
true if the object is not null, false otherwise.

References IsValid().


© 2002-2010 PDFTron Systems Inc.