FormField

FormField class

Represents a single form field.

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

public class FormField : SpecialChar

Properties

NameDescription
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

NameDescription
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.AreEqual("Aspose.FormField", formFieldRun.Text);
Assert.AreEqual(true, formFieldRun.Font.Bold);
Assert.AreEqual(24, formFieldRun.Font.Size);
Assert.AreEqual(Color.Red.ToArgb(), formFieldRun.Font.Color.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.AreEqual("MyComboBox", comboBox.Name);
Assert.AreEqual(FieldType.FieldFormDropDown, comboBox.Type);
Assert.AreEqual("Apple", comboBox.Result);

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

See Also