Class Field

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.

Inheritance

object

Field

Implements

IDisposable

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.MemberwiseClone()

Namespace: pdftron.PDF

Assembly: PDFNet.dll

Syntax

public class Field : IDisposable

Remarks

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 FlattenField() operation can not be programatically reversed.

Constructors

Field(Obj)

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

Declaration

public Field(Obj field_dict)

Parameters

Type	Name	Description
Obj	field_dict	the field_dict

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Methods

Dispose()

Releases all resources used by the Field

Declaration

public override sealed void Dispose()

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Dispose(bool)

Declaration

[HandleProcessCorruptedStateExceptions]
protected virtual void Dispose(bool A_0)

Parameters

Type	Name	Description
bool	A_0

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

EraseAppearance()

Removes any appearances associated with the field.

Declaration

public void EraseAppearance()

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

~Field()

Allows a Field to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.

Declaration

protected ~Field()

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

FindInheritedAttribute(string)

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 inhritance tree in search for specified attribute.

Declaration

public Obj FindInheritedAttribute(string attrib)

Parameters

Type	Name	Description
string	attrib	the attrib

Returns

Type	Description
Obj	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)

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Flatten(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.

Declaration

public void Flatten(Page page)

Parameters

Type	Name	Description
Page	page	the page

Remarks

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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetDefaultAppearance()

Gets the default graphics state.

Declaration

public GState GetDefaultAppearance()

Returns

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

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetDefaultValue()

Gets the default value.

Declaration

public Obj GetDefaultValue()

Returns

Type	Description
Obj	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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetDefaultValueAsString()

Gets the default value as string.

Declaration

public string GetDefaultValueAsString()

Returns

Type	Description
string	the default value as string

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetFlag(Flag)

Gets the flag.

Declaration

public bool GetFlag(Field.Flag flag)

Parameters

Type	Name	Description
Field.Flag	flag	the flag

Returns

Type	Description
bool	the value of given field flag

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetJustification()

Gets the justification.

Declaration

public Field.TextJustification GetJustification()

Returns

Type	Description
Field.TextJustification	the form of quadding (justification) to be used in displaying the text fields.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetMaxLen()

Gets the maximum length.

Declaration

public int GetMaxLen()

Returns

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

Remarks

This method is specific to a text field.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetName()

Gets the name.

Declaration

public string GetName()

Returns

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

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetOpts()

Returns an array of strings corresponding to the options in a list or combo box.

Declaration

public string[] GetOpts()

Returns

Type	Description
string[]

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetPartialName()

Gets the partial name.

Declaration

public string GetPartialName()

Returns

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

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetSDFObj()

Gets the SDFObj.

Declaration

public Obj GetSDFObj()

Returns

Type	Description
Obj	the underlying SDF/Cos object.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetTriggerAction(EventType)

Get the Action associated with the selected Field Trigger event

Declaration

public Obj GetTriggerAction(Field.EventType trigger)

Parameters

Type	Name	Description
Field.EventType	trigger	the type of trigger event to get

Returns

Type	Description
Obj	The action Obj if present, otherwise NULL

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetType()

Gets the type.

Declaration

public Field.Type GetType()

Returns

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

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetUpdateRect()

Return the rectangle that should be refreshed after changing a field.

Declaration

public Rect GetUpdateRect()

Returns

Type	Description
Rect

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetValue()

Gets the value.

Declaration

public Obj GetValue()

Returns

Type	Description
Obj	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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetValueAsBool()

Gets the value as bool.

Declaration

public bool GetValueAsBool()

Returns

Type	Description
bool	the value as bool

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetValueAsString()

Gets the value as string.

Declaration

public string GetValueAsString()

Returns

Type	Description
string	the value as string

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsAnnot()

Checks if is annot.

Declaration

public bool IsAnnot()

Returns

Type	Description
bool	true if this Field is a Widget Annotation Determines whether or not this Field is an Annotation.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsLockedByDigitalSignature()

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

Declaration

public bool IsLockedByDigitalSignature()

Returns

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

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsValid()

Checks if current field is valid.

Declaration

public bool IsValid()

Returns

Type	Description
bool	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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

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.

Declaration

public void RefreshAppearance()

Remarks

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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Rename(string)

Modifies the field name.

Declaration

public void Rename(string field_name)

Parameters

Type	Name	Description
string	field_name	a string representing the fully qualified name of the field (e.g. "employee.name.first").

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Set(Field)

Sets to given Field object

Declaration

public void Set(Field p)

Parameters

Type	Name	Description
Field	p	a Field object

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetFlag(Flag, bool)

Set the value of given FieldFlag.

Declaration

public void SetFlag(Field.Flag flag, bool value)

Parameters

Type	Name	Description
Field.Flag	flag	the flag
bool	value	the value

Remarks

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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetJustification(TextJustification)

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

Declaration

public void SetJustification(Field.TextJustification j)

Parameters

Type	Name	Description
Field.TextJustification	j	the new justification

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetMaxLen(int)

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

Declaration

public void SetMaxLen(int max_len)

Parameters

Type	Name	Description
int	max_len	the new maximum length

Remarks

This method is specific to a text field.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetValue(bool)

Sets the value.

Declaration

public ViewChangeCollection SetValue(bool is_checked)

Parameters

Type	Name	Description
bool	is_checked	the new value

Returns

Type	Description
ViewChangeCollection	A collection of modified fields and regions

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetValue(string)

Sets the value.

Declaration

public ViewChangeCollection SetValue(string value)

Parameters

Type	Name	Description
string	value	the new value

Returns

Type	Description
ViewChangeCollection	A collection of modified fields and regions

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetValue(Obj)

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.

Declaration

public ViewChangeCollection SetValue(Obj value)

Parameters

Type	Name	Description
Obj	value	the new value

Returns

Type	Description
ViewChangeCollection	A collection of modified fields and regions

Remarks

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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

UseSignatureHandler(SignatureHandlerId)

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

public Obj UseSignatureHandler(SignatureHandlerId signature_handler_id)

Parameters

Type	Name	Description
SignatureHandlerId	signature_handler_id	The unique id of the SignatureHandler to use for adding signature in this field.

Returns

Type	Description
Obj	The signature dictionary created using the SignatureHandler, or null if the signature handler is not found.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

op_Assign(Field)

Assignment operator

Declaration

public Field op_Assign(Field r)

Parameters

Type	Name	Description
Field	r	a Field object

Returns

Type	Description
Field	a Field object equals to given object

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Implements

IDisposable