FormField

FormField class

Represents a single form field.

To learn more, visit the Working with Form Fields documentation article.

public class FormField : SpecialChar

Properties

Name	Description
CalculateOnExit { get; set; }	True if references to the specified form field are automatically updated whenever the field is exited.
CheckBoxSize { get; set; }	Gets or sets the size of the checkbox in points. Has effect only when `IsCheckBoxExactSize` is `true`.
Checked { get; set; }	Gets or sets the checked status of the check box form field. Default value for this property is `false`.
CustomNodeId { get; set; }	Specifies custom node identifier.
Default { get; set; }	Gets or sets the default value of the check box form field. Default value for this property is `false`.
virtual Document { get; }	Gets the document to which this node belongs.
DropDownItems { get; }	Provides access to the items of a dropdown form field.
DropDownSelectedIndex { get; set; }	Gets or sets the index specifying the currently selected item in a dropdown form field.
Enabled { get; set; }	True if a form field is enabled.
EntryMacro { get; set; }	Returns or sets an entry macro name for the form field.
ExitMacro { get; set; }	Returns or sets an exit macro name for the form field.
Font { get; }	Provides access to the font formatting of this object.
HelpText { get; set; }	Returns or sets the text that’s displayed in a message box when the form field has the focus and the user presses F1.
IsCheckBoxExactSize { get; set; }	Gets or sets the boolean value that indicates whether the size of the textbox is automatic or specified explicitly.
virtual IsComposite { get; }	Returns `true` if this node can contain other nodes.
IsDeleteRevision { get; }	Returns true if this object was deleted in Microsoft Word while change tracking was enabled.
IsFormatRevision { get; }	Returns true if formatting of the object was changed in Microsoft Word while change tracking was enabled.
IsInsertRevision { get; }	Returns true if this object was inserted in Microsoft Word while change tracking was enabled.
IsMoveFromRevision { get; }	Returns `true` if this object was moved (deleted) in Microsoft Word while change tracking was enabled.
IsMoveToRevision { get; }	Returns `true` if this object was moved (inserted) in Microsoft Word while change tracking was enabled.
MaxLength { get; set; }	Maximum length for the text field. Zero when the length is not limited.
Name { get; set; }	Gets or sets the form field name.
NextSibling { get; }	Gets the node immediately following this node.
override NodeType { get; }	Returns FormField.
OwnHelp { get; set; }	Specifies the source of the text that’s displayed in a message box when a form field has the focus and the user presses F1.
OwnStatus { get; set; }	Specifies the source of the text that’s displayed in the status bar when a form field has the focus.
ParentNode { get; }	Gets the immediate parent of this node.
ParentParagraph { get; }	Retrieves the parent `Paragraph` of this node.
PreviousSibling { get; }	Gets the node immediately preceding this node.
Range { get; }	Returns a `Range` object that represents the portion of a document that is contained in this node.
Result { get; set; }	Gets or sets a string that represents the result of this form field.
StatusText { get; set; }	Returns or sets the text that’s displayed in the status bar when a form field has the focus.
TextInputDefault { get; set; }	Gets or sets the default string or a calculation expression of a text form field.
TextInputFormat { get; set; }	Returns or sets the text formatting for a text form field.
TextInputType { get; set; }	Gets or sets the type of a text form field.
Type { get; }	Returns the form field type.

Methods

Name	Description
override Accept(DocumentVisitor)	Accepts a visitor.
Clone(bool)	Creates a duplicate of the node.
GetAncestor(NodeType)	Gets the first ancestor of the specified `NodeType`.
GetAncestor(Type)	Gets the first ancestor of the specified object type.
override GetText()	Gets the special character that this node represents.
NextPreOrder(Node)	Gets next node according to the pre-order tree traversal algorithm.
PreviousPreOrder(Node)	Gets the previous node according to the pre-order tree traversal algorithm.
Remove()	Removes itself from the parent.
RemoveField()	Removes the complete form field, not just the form field special character.
SetTextInputValue(object)	Applies the text format specified in `TextInputFormat` and stores the value in `Result`.
ToString(SaveFormat)	Exports the content of the node into a string in the specified format.
ToString(SaveOptions)	Exports the content of the node into a string using the specified save options.

Remarks

Microsoft Word provides the following form fields: checkbox, text input and dropdown (combobox).

FormField is an inline-node and can only be a child of Paragraph.

FormField is represented in a document by a special character and positioned as a character within a line of text.

A complete form field in a Word document is a complex structure represented by several nodes: field start, field code such as FORMTEXT, form field data, field separator, field result, field end and a bookmark. To programmatically create form fields in a Word document use InsertCheckBox, InsertTextInput and InsertComboBox which make sure all of the form field nodes are created in a correct order and in a suitable state.

Examples

Shows how to formatting the entire FormField, including the field value.

Document doc = new Document(MyDir + "Form fields.docx");

FormField formField = doc.Range.FormFields[0];
formField.Font.Bold = true;
formField.Font.Size = 24;
formField.Font.Color = Color.Red;

formField.Result = "Aspose.FormField";

doc = DocumentHelper.SaveOpen(doc);

Run formFieldRun = doc.FirstSection.Body.FirstParagraph.Runs[1];

Assert.That(formFieldRun.Text, Is.EqualTo("Aspose.FormField"));
Assert.That(formFieldRun.Font.Bold, Is.EqualTo(true));
Assert.That(formFieldRun.Font.Size, Is.EqualTo(24));
Assert.That(formFieldRun.Font.Color.ToArgb(), Is.EqualTo(Color.Red.ToArgb()));

Shows how to insert a combo box.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.Write("Please select a fruit: ");

// Insert a combo box which will allow a user to choose an option from a collection of strings.
FormField comboBox = builder.InsertComboBox("MyComboBox", new[] { "Apple", "Banana", "Cherry" }, 0);

Assert.That(comboBox.Name, Is.EqualTo("MyComboBox"));
Assert.That(comboBox.Type, Is.EqualTo(FieldType.FieldFormDropDown));
Assert.That(comboBox.Result, Is.EqualTo("Apple"));

// The form field will appear in the form of a "select" html tag.
doc.Save(ArtifactsDir + "FormFields.Create.html");