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.insert_check_box(), DocumentBuilder.insert_text_input() and DocumentBuilder.insert_combo_box() 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 |
|---|---|
| calculate_on_exit | True if references to the specified form field are automatically updated whenever the field is exited. |
| check_box_size | Gets or sets the size of the checkbox in points. Has effect only when FormField.is_check_box_exact_size is True. |
| checked | Gets or sets the checked status of the check box form field. Default value for this property is False. |
| custom_node_id | 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) |
| drop_down_items | Provides access to the items of a dropdown form field. |
| drop_down_selected_index | Gets or sets the index specifying the currently selected item in a dropdown form field. |
| enabled | True if a form field is enabled. |
| entry_macro | Returns or sets an entry macro name for the form field. |
| exit_macro | Returns or sets an exit macro name for the form field. |
| font | Provides access to the font formatting of this object. (Inherited from Inline) |
| help_text | Returns or sets the text that’s displayed in a message box when the form field has the focus and the user presses F1. |
| is_check_box_exact_size | Gets or sets the boolean value that indicates whether the size of the textbox is automatic or specified explicitly. |
| is_composite | Returns True if this node can contain other nodes.(Inherited from Node) |
| is_delete_revision | Returns true if this object was deleted in Microsoft Word while change tracking was enabled. (Inherited from Inline) |
| is_format_revision | Returns true if formatting of the object was changed in Microsoft Word while change tracking was enabled. (Inherited from Inline) |
| is_insert_revision | Returns true if this object was inserted in Microsoft Word while change tracking was enabled. (Inherited from Inline) |
| is_move_from_revision | Returns True if this object was moved (deleted) in Microsoft Word while change tracking was enabled.(Inherited from Inline) |
| is_move_to_revision | Returns True if this object was moved (inserted) in Microsoft Word while change tracking was enabled.(Inherited from Inline) |
| max_length | Maximum length for the text field. Zero when the length is not limited. |
| name | Gets or sets the form field name. |
| next_sibling | Gets the node immediately following this node. (Inherited from Node) |
| node_type | Returns NodeType.FORM_FIELD. |
| own_help | 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. |
| own_status | Specifies the source of the text that’s displayed in the status bar when a form field has the focus. |
| parent_node | Gets the immediate parent of this node. (Inherited from Node) |
| parent_paragraph | Retrieves the parent Paragraph of this node. (Inherited from Inline) |
| previous_sibling | 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. |
| status_text | Returns or sets the text that’s displayed in the status bar when a form field has the focus. |
| text_input_default | Gets or sets the default string or a calculation expression of a text form field. |
| text_input_format | Returns or sets the text formatting for a text form field. |
| text_input_type | Gets or sets the type of a text form field. |
| type | Returns the form field type. |
Methods
| Name | Description |
|---|---|
| accept(visitor) | Accepts a visitor. |
| clone(is_clone_children) | Creates a duplicate of the node. (Inherited from Node) |
| get_ancestor(ancestor_type) | Gets the first ancestor of the specified object type. (Inherited from Node) |
| get_ancestor(ancestor_type) | Gets the first ancestor of the specified NodeType. (Inherited from Node) |
| get_text() | Gets the text of this node and of all its children. (Inherited from Node) |
| next_pre_order(root_node) | Gets next node according to the pre-order tree traversal algorithm. (Inherited from Node) |
| node_type_to_string(node_type) | A utility method that converts a node type enum value into a user friendly string. (Inherited from Node) |
| previous_pre_order(root_node) | Gets the previous node according to the pre-order tree traversal algorithm. (Inherited from Node) |
| remove() | Removes itself from the parent. (Inherited from Node) |
| remove_field() | Removes the complete form field, not just the form field special character. |
| set_text_input_value(new_value) | Applies the text format specified in FormField.text_input_format and stores the value in FormField.result. |
| to_string(save_format) | Exports the content of the node into a string in the specified format. (Inherited from Node) |
| to_string(save_options) | 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.
doc = aw.Document()
builder = 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.
combo_box = builder.insert_combo_box("MyComboBox", ["Apple", "Banana", "Cherry"], 0)
self.assertEqual("MyComboBox", combo_box.name)
self.assertEqual(aw.fields.FieldType.FIELD_FORM_DROP_DOWN, combo_box.type)
self.assertEqual("Apple", combo_box.result)
# The form field will appear in the form of a "select" html tag.
doc.save(ARTIFACTS_DIR + "FormFields.create.html")
Shows how to formatting the entire FormField, including the field value.
doc = aw.Document(MY_DIR + "Form fields.docx")
form_field = doc.range.form_fields[0]
form_field.font.bold = True
form_field.font.size = 24
form_field.font.color = drawing.Color.red
form_field.result = "Aspose.FormField"
doc = DocumentHelper.save_open(doc)
form_field_run = doc.first_section.body.first_paragraph.runs[1]
self.assertEqual("Aspose.FormField", form_field_run.text)
self.assertEqual(True, form_field_run.font.bold)
self.assertEqual(24, form_field_run.font.size)
self.assertEqual(drawing.Color.red.to_argb(), form_field_run.font.color.to_argb())
See Also
- module aspose.words.fields
- class SpecialChar