PTField

@interface PTField : NSObject

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.

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

    Declaration

    Objective-C

    - (instancetype)initWithField_dict:(PTObj *)field_dict;

    Swift

    init!(field_dict: PTObj!)

    Parameters

    field_dict

    the SDF dictionary to construct the field from.

  • Declaration

    Objective-C

    - (BOOL)IsValid;

    Swift

    func isValid() -> Bool

    Return Value

    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.

  • Declaration

    Objective-C

    - (PTFieldType)GetType;

    Swift

    func getType() -> PTFieldType

    Return Value

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

  • The format of field’s value varies depending on the field type.

    Declaration

    Objective-C

    - (PTObj *)GetValue;

    Swift

    func getValue() -> PTObj!

    Return Value

    the value of the Field (the value of its /V key) or NULL if the value is not specified.

  • Undocumented

    Declaration

    Objective-C

    - (NSString *)GetValueAsString;

    Swift

    func getValueAsString() -> String!

  • Note

    This method is usually for check-box and radio button fields.

    Declaration

    Objective-C

    - (BOOL)GetValueAsBool;

    Swift

    func getValueAsBool() -> Bool

    Return Value

    Field value as a boolean.

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

    Note

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

    Note

    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.

    Declaration

    Objective-C

    - (PTViewChangeCollection *)SetValueWithString:(NSString *)value;

    Swift

    func setValueWith(_ value: String!) -> PTViewChangeCollection!

    Parameters

    value

    the new field value.

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

    Note

    This method is usually for check-box and radio button fields.

    Declaration

    Objective-C

    - (PTViewChangeCollection *)SetValueWithObj:(PTObj *)value;

    Swift

    func setValueWith(_ value: PTObj!) -> PTViewChangeCollection!

    Parameters

    value

    If true, the filed will be set to ‘True’, if false the field will be set to ‘False’.

  • Undocumented

    Declaration

    Objective-C

    - (PTViewChangeCollection*)SetValueWithBool: (BOOL)value;

    Swift

    func setValueWith(_ value: Bool) -> PTViewChangeCollection!

  • Get the Action associated with the selected Field Trigger event.

    Declaration

    Objective-C

    - (PTObj *)GetTriggerAction:(PTFieldActionTriggerEvent)trigger;

    Swift

    func getTriggerAction(_ trigger: PTFieldActionTriggerEvent) -> PTObj!

    Parameters

    trigger

    the type of trigger event to get

    Return Value

    the Action Obj if present, otherwise NULL

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

    Note

    If this field contains text, and has been added to a rotated page, the text in the field may be rotated. If RefreshAppearance is called after the field is added to a rotated page, then any text will be rotated in the opposite direction of the page rotation. If this method is called before the field is added to any rotated page, then no counter rotation will be applied. If you wish to call RefreshAppearance on a field already added to a rotated page, but you don’t want the text to be rotated, you can do one of the following; temporarily un-rotate the page, or, temporarily remove the “P” object from the field.

    Declaration

    Objective-C

    - (void)RefreshAppearance;

    Swift

    func refreshAppearance()

  • Removes any appearances associated with the field.

    Declaration

    Objective-C

    - (void)EraseAppearance;

    Swift

    func eraseAppearance()

  • The format of field’s value varies depending on the field type.

    Declaration

    Objective-C

    - (PTObj *)GetDefaultValue;

    Swift

    func getDefaultValue() -> PTObj!

    Return Value

    The default value to which the field reverts when a reset-form action is executed or NULL if the default value is not specified.

  • Undocumented

    Declaration

    Objective-C

    - (NSString *)GetDefaultValueAsString;

    Swift

    func getDefaultValueAsString() -> String!

  • Declaration

    Objective-C

    - (NSString *)GetName;

    Swift

    func getName() -> String!

    Return Value

    a string representing the fully qualified name of the field (e.g. “employee.name.first”).

  • Declaration

    Objective-C

    - (NSString *)GetPartialName;

    Swift

    func getPartialName() -> String!

    Return Value

    a string representing the partial name of the field (e.g. “first” when “employee.name.first” is fully qualified name).

  • Modifies the field name.

    Declaration

    Objective-C

    - (void)Rename:(NSString *)field_name;

    Swift

    func rename(_ field_name: String!)

    Parameters

    field_name

    a string representing the fully qualified name of the field (e.g. “employee.name.first”).

  • Determines whether or not this Field is an Annotation.

    Declaration

    Objective-C

    - (BOOL)IsAnnot;

    Swift

    func isAnnot() -> Bool

    Return Value

    true if this Field is a Widget Annotation

  • Declaration

    Objective-C

    - (BOOL)GetFlag:(PTFieldFlag)flag;

    Swift

    func getFlag(_ flag: PTFieldFlag) -> Bool

    Return Value

    the value of given field flag

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

    Declaration

    Objective-C

    - (void)SetFlag:(PTFieldFlag)flag value:(BOOL)value;

    Swift

    func setFlag(_ flag: PTFieldFlag, value: Bool)

  • Declaration

    Objective-C

    - (PTTextJustification)GetJustification;

    Swift

    func getJustification() -> PTTextJustification

    Return Value

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

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

    Note

    This method is specific to a text field.

    Declaration

    Objective-C

    - (void)SetJustification:(PTTextJustification)j;

    Swift

    func setJustification(_ j: PTTextJustification)

    Parameters

    j

    enum representing justification to set the text field to, options are e_left_justified, e_centered and e_right_justified

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

    Note

    This method is specific to a text field.

    Declaration

    Objective-C

    - (void)SetMaxLen:(int)max_len;

    Swift

    func setMaxLen(_ max_len: Int32)

    Parameters

    max_len

    maximum length of a field’s text.

  • Returns the total number of options in a list or combo box.

    Declaration

    Objective-C

    - (int)GetOptCount;

    Swift

    func getOptCount() -> Int32

  • Note

    The index must be less than the value returned by GetOptCount().

    Declaration

    Objective-C

    - (NSString *)GetOpt:(int)index;

    Swift

    func getOpt(_ index: Int32) -> String!

    Parameters

    index

    index position of the option to retrieve.

    Return Value

    The string of the option at the givent index.

  • Note

    This method is specific to a text field.

    Declaration

    Objective-C

    - (int)GetMaxLen;

    Swift

    func getMaxLen() -> Int32

    Return Value

    The maximum length of the field’s text, in characters, or a negative number if the length is not limited.

  • Declaration

    Objective-C

    - (PTGState *)GetDefaultAppearance;

    Swift

    func getDefaultAppearance() -> PTGState!

    Return Value

    The default graphics state that should be used in formatting the text. The state corresponds to /DA entry in the field dictionary.

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

    Declaration

    Objective-C

    - (void)Flatten:(PTPage *)page;

    Swift

    func flatten(_ page: PTPage!)

    Parameters

    page

    page object to flatten

  • Declaration

    Objective-C

    - (PTPDFRect *)GetUpdateRect;

    Swift

    func getUpdateRect() -> PTPDFRect!

    Return Value

    The rectangle that should be refreshed after changing a field.

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

    Resources dictionary (Required; inheritable) MediaBox rectangle (Required; inheritable) CropBox rectangle (Optional; inheritable) Rotate integer (Optional; inheritable)

    Declaration

    Objective-C

    - (PTObj *)FindInheritedAttribute:(NSString *)attrib;

    Swift

    func findInheritedAttribute(_ attrib: String!) -> PTObj!

    Return Value

    The attribute value if the given attribute name was found or a NULL object if the given attribute name was not found.

  • Declaration

    Objective-C

    - (PTObj *)GetSDFObj;

    Swift

    func getSDFObj() -> PTObj!

    Return Value

    the underlying SDF/Cos object.

  • Sets the signature handler to use for adding a signature to this field. If the signature handler is not found in PDFDoc’s signature handlers list, this field will not be signed. To add signature handlers, use PDFDoc.AddSignatureHandler method.

    If a signature handler is already assigned to this field and this method is called once again, the associate signature handler for this field will be updated with the new handler.

    Declaration

    Objective-C

    - (PTObj *)UseSignatureHandler:(PTSignatureHandlerId)signature_handler_id;

    Swift

    func useSignatureHandler(_ signature_handler_id: PTSignatureHandlerId) -> PTObj!

    Parameters

    signature_handler_id

    The unique id of the SignatureHandler to use for adding signature in this field.

    Return Value

    The signature dictionary created using the SignatureHandler, or NULL pointer if the signature handler is not found.

  • Returns whether modifying this field would invalidate a digital signature in the document.

    Declaration

    Objective-C

    - (BOOL)IsLockedByDigitalSignature;

    Swift

    func isLockedByDigitalSignature() -> Bool

    Return Value

    whether modifying this field would invalidate a digital signature in the document