Aspose::Words::Fields::FormField class

FormField class

Represents a single form field. To learn more, visit the Working with Form Fields documentation article.

class FormField : public Aspose::Words::SpecialChar

Methods

MethodDescription
Accept(System::SharedPtr<Aspose::Words::DocumentVisitor>) overrideAccepts a visitor.
Clone(bool)Creates a duplicate of the node.
get_CalculateOnExit()True if references to the specified form field are automatically updated whenever the field is exited.
get_CheckBoxSize()Gets or sets the size of the checkbox in points. Has effect only when IsCheckBoxExactSize is true.
get_Checked()Gets or sets the checked status of the check box form field. Default value for this property is false.
get_CustomNodeId() constSpecifies custom node identifier.
get_Default()Gets or sets the default value of the check box form field. Default value for this property is false.
virtual get_Document() constGets the document to which this node belongs.
get_DropDownItems()Provides access to the items of a dropdown form field.
get_DropDownSelectedIndex()Gets or sets the index specifying the currently selected item in a dropdown form field.
get_Enabled()True if a form field is enabled.
get_EntryMacro()Returns or sets an entry macro name for the form field.
get_ExitMacro()Returns or sets an exit macro name for the form field.
get_Font()Provides access to the font formatting of this object.
get_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.
get_IsCheckBoxExactSize()Gets or sets the boolean value that indicates whether the size of the textbox is automatic or specified explicitly.
virtual get_IsComposite()Returns true if this node can contain other nodes.
get_IsDeleteRevision()Returns true if this object was deleted in Microsoft Word while change tracking was enabled.
get_IsFormatRevision()Returns true if formatting of the object was changed in Microsoft Word while change tracking was enabled.
get_IsInsertRevision()Returns true if this object was inserted in Microsoft Word while change tracking was enabled.
get_IsMoveFromRevision()Returns true if this object was moved (deleted) in Microsoft Word while change tracking was enabled.
get_IsMoveToRevision()Returns true if this object was moved (inserted) in Microsoft Word while change tracking was enabled.
get_MaxLength()Maximum length for the text field. Zero when the length is not limited.
get_Name()Gets or sets the form field name.
get_NextNode() const
get_NextSibling()Gets the node immediately following this node.
get_NodeType() const overrideReturns FormField.
get_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.
get_OwnStatus()Specifies the source of the text that’s displayed in the status bar when a form field has the focus.
get_ParentNode()Gets the immediate parent of this node.
get_ParentParagraph()Retrieves the parent Paragraph of this node.
get_PreviousSibling()Gets the node immediately preceding this node.
get_PrevNode() const
get_Range()Returns a Range object that represents the portion of a document that is contained in this node.
get_Result()Gets or sets a string that represents the result of this form field.
get_StatusText()Returns or sets the text that’s displayed in the status bar when a form field has the focus.
get_TextInputDefault()Gets or sets the default string or a calculation expression of a text form field.
get_TextInputFormat()Returns or sets the text formatting for a text form field.
get_TextInputType()Gets or sets the type of a text form field.
get_Type()Returns the form field type.
GetAncestor(Aspose::Words::NodeType)Gets the first ancestor of the specified NodeType.
GetAncestorOf()
GetText() overrideGets the special character that this node represents.
GetType() const override
Is(const System::TypeInfo&) const override
IsAncestorNode(const System::SharedPtr<Aspose::Words::Node>&)
NextPreOrder(const System::SharedPtr<Aspose::Words::Node>&)Gets next node according to the pre-order tree traversal algorithm.
static NodeTypeToString(Aspose::Words::NodeType)A utility method that converts a node type enum value into a user friendly string.
PreviousPreOrder(const System::SharedPtr<Aspose::Words::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.
set_CalculateOnExit(bool)Setter for Aspose::Words::Fields::FormField::get_CalculateOnExit.
set_CheckBoxSize(double)Setter for Aspose::Words::Fields::FormField::get_CheckBoxSize.
set_Checked(bool)Setter for Aspose::Words::Fields::FormField::get_Checked.
set_CustomNodeId(int32_t)Setter for Aspose::Words::Node::get_CustomNodeId.
set_Default(bool)Setter for Aspose::Words::Fields::FormField::get_Default.
set_DropDownSelectedIndex(int32_t)Setter for Aspose::Words::Fields::FormField::get_DropDownSelectedIndex.
set_Enabled(bool)Setter for Aspose::Words::Fields::FormField::get_Enabled.
set_EntryMacro(const System::String&)Setter for Aspose::Words::Fields::FormField::get_EntryMacro.
set_ExitMacro(const System::String&)Setter for Aspose::Words::Fields::FormField::get_ExitMacro.
set_HelpText(const System::String&)Setter for Aspose::Words::Fields::FormField::get_HelpText.
set_IsCheckBoxExactSize(bool)Setter for Aspose::Words::Fields::FormField::get_IsCheckBoxExactSize.
set_MaxLength(int32_t)Setter for Aspose::Words::Fields::FormField::get_MaxLength.
set_Name(const System::String&)Setter for Aspose::Words::Fields::FormField::get_Name.
set_NextNode(const System::SharedPtr<Aspose::Words::Node>&)
set_OwnHelp(bool)Setter for Aspose::Words::Fields::FormField::get_OwnHelp.
set_OwnStatus(bool)Setter for Aspose::Words::Fields::FormField::get_OwnStatus.
set_PrevNode(const System::SharedPtr<Aspose::Words::Node>&)
set_Result(const System::String&)Setter for Aspose::Words::Fields::FormField::get_Result.
set_StatusText(const System::String&)Setter for Aspose::Words::Fields::FormField::get_StatusText.
set_TextInputDefault(const System::String&)Setter for Aspose::Words::Fields::FormField::get_TextInputDefault.
set_TextInputFormat(const System::String&)Setter for Aspose::Words::Fields::FormField::get_TextInputFormat.
set_TextInputType(Aspose::Words::Fields::TextFormFieldType)Setter for Aspose::Words::Fields::FormField::get_TextInputType.
SetParent(const System::SharedPtr<Aspose::Words::Node>&)
SetTextInputValue(const System::SharedPtr<System::Object>&)Applies the text format specified in TextInputFormat and stores the value in Result.
ToString(Aspose::Words::SaveFormat)Exports the content of the node into a string in the specified format.
ToString(const System::SharedPtr<Aspose::Words::Saving::SaveOptions>&)Exports the content of the node into a string using the specified save options.
static Type()

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 insert a combo box.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);

builder->Write(u"Please select a fruit: ");

// Insert a combo box which will allow a user to choose an option from a collection of strings.
SharedPtr<FormField> comboBox = builder->InsertComboBox(u"MyComboBox", MakeArray<String>({u"Apple", u"Banana", u"Cherry"}), 0);

ASSERT_EQ(u"MyComboBox", comboBox->get_Name());
ASSERT_EQ(FieldType::FieldFormDropDown, comboBox->get_Type());
ASSERT_EQ(u"Apple", comboBox->get_Result());

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

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

auto doc = MakeObject<Document>(MyDir + u"Form fields.docx");

SharedPtr<FormField> formField = doc->get_Range()->get_FormFields()->idx_get(0);
formField->get_Font()->set_Bold(true);
formField->get_Font()->set_Size(24);
formField->get_Font()->set_Color(System::Drawing::Color::get_Red());

formField->set_Result(u"Aspose.FormField");

doc = DocumentHelper::SaveOpen(doc);

SharedPtr<Run> formFieldRun = doc->get_FirstSection()->get_Body()->get_FirstParagraph()->get_Runs()->idx_get(1);

ASSERT_EQ(u"Aspose.FormField", formFieldRun->get_Text());
ASPOSE_ASSERT_EQ(true, formFieldRun->get_Font()->get_Bold());
ASPOSE_ASSERT_EQ(24, formFieldRun->get_Font()->get_Size());
ASSERT_EQ(System::Drawing::Color::get_Red().ToArgb(), formFieldRun->get_Font()->get_Color().ToArgb());

See Also