FormField class
FormField class
Represents a single form field. To learn more, visit the Working with Form Fields documentation article.
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 DocumentBuilder.insertCheckBox(), DocumentBuilder.insertTextInput() and DocumentBuilder.insertComboBox() which make sure all of the form field nodes are created in a correct order and in a suitable state.
Inheritance: FormField → SpecialChar → Inline → Node
Properties
| Name | Description |
|---|---|
| calculateOnExit | True if references to the specified form field are automatically updated whenever the field is exited. |
| checkBoxSize | Gets or sets the size of the checkbox in points. Has effect only when FormField.isCheckBoxExactSize is true. |
| checked | Gets or sets the checked status of the check box form field. Default value for this property is false. |
| customNodeId | Specifies custom node identifier. (Inherited from Node) |
| default | Gets or sets the default value of the check box form field. Default value for this property is false. |
| document | Gets the document to which this node belongs. (Inherited from Node) |
| dropDownItems | Provides access to the items of a dropdown form field. |
| dropDownSelectedIndex | Gets or sets the index specifying the currently selected item in a dropdown form field. |
| enabled | True if a form field is enabled. |
| entryMacro | Returns or sets an entry macro name for the form field. |
| exitMacro | Returns or sets an exit macro name for the form field. |
| font | Provides access to the font formatting of this object. (Inherited from Inline) |
| helpText | 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 | Gets or sets the boolean value that indicates whether the size of the textbox is automatic or specified explicitly. |
| isComposite | Returns true if this node can contain other nodes.(Inherited from Node) |
| isDeleteRevision | Returns true if this object was deleted in Microsoft Word while change tracking was enabled. (Inherited from Inline) |
| isFormatRevision | Returns true if formatting of the object was changed in Microsoft Word while change tracking was enabled. (Inherited from Inline) |
| isInsertRevision | Returns true if this object was inserted in Microsoft Word while change tracking was enabled. (Inherited from Inline) |
| isMoveFromRevision | Returns true if this object was moved (deleted) in Microsoft Word while change tracking was enabled.(Inherited from Inline) |
| isMoveToRevision | Returns true if this object was moved (inserted) in Microsoft Word while change tracking was enabled.(Inherited from Inline) |
| maxLength | Maximum length for the text field. Zero when the length is not limited. |
| name | Gets or sets the form field name. |
| nextSibling | Gets the node immediately following this node. (Inherited from Node) |
| nodeType | Returns NodeType.FormField. |
| ownHelp | 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 | Specifies the source of the text that’s displayed in the status bar when a form field has the focus. |
| parentNode | Gets the immediate parent of this node. (Inherited from Node) |
| parentParagraph | Retrieves the parent Paragraph of this node. (Inherited from Inline) |
| previousSibling | Gets the node immediately preceding this node. (Inherited from Node) |
| range | Returns a Range object that represents the portion of a document that is contained in this node. (Inherited from Node) |
| result | Gets or sets a string that represents the result of this form field. |
| statusText | Returns or sets the text that’s displayed in the status bar when a form field has the focus. |
| textInputDefault | Gets or sets the default string or a calculation expression of a text form field. |
| textInputFormat | Returns or sets the text formatting for a text form field. |
| textInputType | Gets or sets the type of a text form field. |
| type | Returns the form field type. |
Methods
| Name | Description |
|---|---|
| accept(visitor) | Accepts a visitor. |
| asBody() | Cast node to Body. (Inherited from Node) |
| asBookmarkEnd() | Cast node to BookmarkEnd. (Inherited from Node) |
| asBookmarkStart() | Cast node to BookmarkStart. (Inherited from Node) |
| asBuildingBlock() | Cast node to BuildingBlock. (Inherited from Node) |
| asCell() | Cast node to Cell. (Inherited from Node) |
| asComment() | Cast node to Comment. (Inherited from Node) |
| asCommentRangeEnd() | Cast node to CommentRangeEnd. (Inherited from Node) |
| asCommentRangeStart() | Cast node to CommentRangeStart. (Inherited from Node) |
| asCompositeNode() | Cast node to CompositeNode. (Inherited from Node) |
| asDocument() | Cast node to Node.document. (Inherited from Node) |
| asEditableRangeEnd() | Cast node to EditableRangeEnd. (Inherited from Node) |
| asEditableRangeStart() | Cast node to EditableRangeStart. (Inherited from Node) |
| asFieldEnd() | Cast node to FieldEnd. (Inherited from Node) |
| asFieldSeparator() | Cast node to FieldSeparator. (Inherited from Node) |
| asFieldStart() | Cast node to FieldStart. (Inherited from Node) |
| asFootnote() | Cast node to Footnote. (Inherited from Node) |
| asFormField() | Cast node to FormField. (Inherited from Node) |
| asGlossaryDocument() | Cast node to GlossaryDocument. (Inherited from Node) |
| asGroupShape() | Cast node to GroupShape. (Inherited from Node) |
| asHeaderFooter() | Cast node to HeaderFooter. (Inherited from Node) |
| asOfficeMath() | Cast node to OfficeMath. (Inherited from Node) |
| asParagraph() | Cast node to Paragraph. (Inherited from Node) |
| asRow() | Cast node to Row. (Inherited from Node) |
| asRun() | Cast node to Run. (Inherited from Node) |
| asSection() | Cast node to Section. (Inherited from Node) |
| asShape() | Cast node to Shape. (Inherited from Node) |
| asSmartTag() | Cast node to SmartTag. (Inherited from Node) |
| asSpecialChar() | Cast node to SpecialChar. (Inherited from Node) |
| asStructuredDocumentTag() | Cast node to StructuredDocumentTag. (Inherited from Node) |
| asStructuredDocumentTagRangeEnd() | Cast node to StructuredDocumentTagRangeEnd. (Inherited from Node) |
| asStructuredDocumentTagRangeStart() | Cast node to StructuredDocumentTagRangeStart. (Inherited from Node) |
| asSubDocument() | Cast node to SubDocument. (Inherited from Node) |
| asTable() | Cast node to Table. (Inherited from Node) |
| clone(isCloneChildren) | Creates a duplicate of the node. (Inherited from Node) |
| getAncestor(ancestorType) | Gets the first ancestor of the specified NodeType. (Inherited from Node) |
| getText() | Gets the text of this node and of all its children. (Inherited from Node) |
| nextPreOrder(rootNode) | Gets next node according to the pre-order tree traversal algorithm. (Inherited from Node) |
| nodeTypeToString(nodeType) | A utility method that converts a node type enum value into a user friendly string. (Inherited from Node) |
| previousPreOrder(rootNode) | Gets the previous node according to the pre-order tree traversal algorithm. (Inherited from Node) |
| referenceEquals(other) | (Inherited from Node) |
| remove() | Removes itself from the parent. (Inherited from Node) |
| removeField() | Removes the complete form field, not just the form field special character. |
| setTextInputValue(newValue) | Applies the text format specified in FormField.textInputFormat and stores the value in FormField.result. |
| toString(saveFormat) | Exports the content of the node into a string in the specified format. (Inherited from Node) |
| toString(saveOptions) | Exports the content of the node into a string using the specified save options. (Inherited from Node) |
Examples
Shows how to insert a combo box.
let doc = new aw.Document();
let builder = new aw.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.
let comboBox = builder.insertComboBox("MyComboBox", ["Apple", "Banana", "Cherry"], 0);
expect(comboBox.name).toEqual("MyComboBox");
expect(comboBox.type).toEqual(aw.Fields.FieldType.FieldFormDropDown);
expect(comboBox.result).toEqual("Apple");
// The form field will appear in the form of a "select" html tag.
doc.save(base.artifactsDir + "FormFields.create.html");
Shows how to formatting the entire FormField, including the field value.
let doc = new aw.Document(base.myDir + "Form fields.docx");
let formField = doc.range.formFields.at(0);
formField.font.bold = true;
formField.font.size = 24;
formField.font.color = "#FF0000";
formField.result = "Aspose.formField";
doc = DocumentHelper.saveOpen(doc);
let formFieldRun = doc.firstSection.body.firstParagraph.runs.at(1);
expect(formFieldRun.text).toEqual("Aspose.formField");
expect(formFieldRun.font.bold).toEqual(true);
expect(formFieldRun.font.size).toEqual(24);
expect(formFieldRun.font.color).toEqual("#FF0000");
See Also
- module Aspose.Words.Fields
- class SpecialChar