Aspose::Words::Fields::FormField Class Reference

Detailed Description

Represents a single form field.

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.

Examples

Shows how to work with form field name, type, and result.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Use a DocumentBuilder to insert a combo box form field
SharedPtr<Aspose::Words::Fields::FormField> comboBox = builder->InsertComboBox(u"MyComboBox", MakeArray<String>({u"One", u"Two", u"Three"}), 0);
// Verify some of our form field's attributes
ASSERT_EQ(u"MyComboBox", comboBox->get_Name());
ASSERT_EQ(Aspose::Words::Fields::FieldType::FieldFormDropDown, comboBox->get_Type());
ASSERT_EQ(u"One", comboBox->get_Result());

#include <Aspose.Words.Cpp/Model/Fields/FormFields/FormField.h>

+ Inheritance diagram for Aspose::Words::Fields::FormField:

Public Member Functions

bool Accept (SharedPtr< DocumentVisitor > visitor) override
 Accepts a visitor. More...
 
bool get_CalculateOnExit ()
 True if references to the specified form field are automatically updated whenever the field is exited. More...
 
double get_CheckBoxSize ()
 Gets or sets the size of the checkbox in points. Has effect only when IsCheckBoxExactSize is true. More...
 
bool get_Checked ()
 Gets or sets the checked status of the check box form field. Default value for this property is false. More...
 
bool get_Default ()
 Gets or sets the default value of the check box form field. Default value for this property is false. More...
 
SharedPtr< DropDownItemCollectionget_DropDownItems ()
 Provides access to the items of a dropdown form field. More...
 
int32_t get_DropDownSelectedIndex ()
 Gets the index specifying the currently selected item in a dropdown form field. More...
 
bool get_Enabled ()
 True if a form field is enabled. More...
 
String get_EntryMacro ()
 Returns or sets an entry macro name for the form field. More...
 
String get_ExitMacro ()
 Returns or sets an exit macro name for the form field. More...
 
String 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. More...
 
bool get_IsCheckBoxExactSize ()
 Gets or sets the boolean value that indicates whether the size of the textbox is automatic or specified explicitly. More...
 
int32_t get_MaxLength ()
 Maximum length for the text field. Zero when the length is not limited. More...
 
String get_Name ()
 Gets or sets the form field name. More...
 
NodeType get_NodeType () const override
 Returns NodeType.FormField. More...
 
bool 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. More...
 
bool get_OwnStatus ()
 Specifies the source of the text that's displayed in the status bar when a form field has the focus. More...
 
String get_Result ()
 Gets or sets a string that represents the result of this form field. More...
 
String get_StatusText ()
 Returns or sets the text that's displayed in the status bar when a form field has the focus. More...
 
String get_TextInputDefault ()
 Gets or sets the default string or a calculation expression of a text form field. More...
 
String get_TextInputFormat ()
 Returns or sets the text formatting for a text form field. More...
 
TextFormFieldType get_TextInputType ()
 Gets the type of a text form field. More...
 
FieldType get_Type ()
 Returns the form field type. More...
 
virtual const TypeInfoGetType () const override
 
virtual bool Is (const TypeInfo &target) const override
 
void RemoveField ()
 Removes the complete form field, not just the form field special character. More...
 
void set_CalculateOnExit (bool value)
 Setter for get_CalculateOnExit. More...
 
void set_CheckBoxSize (double value)
 Setter for get_CheckBoxSize. More...
 
void set_Checked (bool value)
 Setter for get_Checked. More...
 
void set_Default (bool value)
 Setter for get_Default. More...
 
void set_DropDownSelectedIndex (int32_t value)
 Sets the index specifying the currently selected item in a dropdown form field. More...
 
void set_Enabled (bool value)
 True if a form field is enabled. More...
 
void set_EntryMacro (String value)
 Setter for get_EntryMacro. More...
 
void set_ExitMacro (String value)
 Setter for get_ExitMacro. More...
 
void set_HelpText (String value)
 Setter for get_HelpText. More...
 
void set_IsCheckBoxExactSize (bool value)
 Setter for get_IsCheckBoxExactSize. More...
 
void set_MaxLength (int32_t value)
 Maximum length for the text field. Zero when the length is not limited. More...
 
void set_Name (String value)
 Setter for get_Name. More...
 
void set_OwnHelp (bool value)
 Setter for get_OwnHelp. More...
 
void set_OwnStatus (bool value)
 Setter for get_OwnStatus. More...
 
void set_Result (String value)
 Setter for get_Result. More...
 
void set_StatusText (String value)
 Setter for get_StatusText. More...
 
void set_TextInputDefault (String value)
 Setter for get_TextInputDefault. More...
 
void set_TextInputFormat (String value)
 Setter for get_TextInputFormat. More...
 
void set_TextInputType (TextFormFieldType value)
 Sets the type of a text form field. More...
 
void SetTextInputValue (SharedPtr< Object > newValue)
 Applies the text format specified in TextInputFormat and stores the value in Result. More...
 
- Public Member Functions inherited from SpecialChar
bool Accept (SharedPtr< DocumentVisitor > visitor) override
 Accepts a visitor. More...
 
NodeType get_NodeType () const override
 Returns NodeType.SpecialChar. More...
 
String GetText () override
 Gets the special character that this node represents. More...
 
- Public Member Functions inherited from Inline
SharedPtr< Fontget_Font ()
 Provides access to the font formatting of this object. More...
 
bool get_IsDeleteRevision ()
 Returns true if this object was deleted in Microsoft Word while change tracking was enabled. More...
 
bool get_IsFormatRevision ()
 Returns true if formatting of the object was changed in Microsoft Word while change tracking was enabled. More...
 
bool get_IsInsertRevision ()
 Returns true if this object was inserted in Microsoft Word while change tracking was enabled. More...
 
bool get_IsMoveFromRevision ()
 Returns true if this object was moved (deleted) in Microsoft Word while change tracking was enabled. More...
 
bool get_IsMoveToRevision ()
 Returns true if this object was moved (inserted) in Microsoft Word while change tracking was enabled. More...
 
SharedPtr< Paragraphget_ParentParagraph ()
 Retrieves the parent Paragraph of this node. More...
 
- Public Member Functions inherited from Node
SharedPtr< NodeClone (bool isCloneChildren)
 Creates a duplicate of the node. More...
 
virtual SharedPtr< DocumentBaseget_Document () const
 Gets the document to which this node belongs. More...
 
virtual bool get_IsComposite ()
 Returns true if this node can contain other nodes. More...
 
SharedPtr< Nodeget_NextSibling ()
 Gets the node immediately following this node. More...
 
SharedPtr< CompositeNodeget_ParentNode ()
 Gets the immediate parent of this node. More...
 
SharedPtr< Nodeget_PreviousSibling ()
 Gets the node immediately preceding this node. More...
 
SharedPtr< Rangeget_Range ()
 Returns a Range object that represents the portion of a document that is contained in this node. More...
 
SharedPtr< CompositeNodeGetAncestor (NodeType ancestorType)
 Gets the first ancestor of the specified NodeType. More...
 
template<typename T >
GetAncestorOf ()
 
SharedPtr< NodeNextPreOrder (SharedPtr< Node > rootNode)
 Gets next node according to the pre-order tree traversal algorithm. More...
 
SharedPtr< NodePreviousPreOrder (SharedPtr< Node > rootNode)
 Gets the previous node according to the pre-order tree traversal algorithm. More...
 
void Remove ()
 Removes itself from the parent. More...
 
String ToString (SaveFormat saveFormat)
 Exports the content of the node into a string in the specified format. More...
 
String ToString (SharedPtr< SaveOptions > saveOptions)
 Exports the content of the node into a string using the specified save options. More...
 
- Public Member Functions inherited from Object
ASPOSECPP_SHARED_API Object ()
 
ASPOSECPP_SHARED_API Object (Object const &x)
 
virtual ASPOSECPP_SHARED_API ~Object ()
 
virtual ASPOSECPP_SHARED_API bool Equals (ptr obj)
 
Detail::SmartPtrCounter * GetCounter ()
 
virtual ASPOSECPP_SHARED_API int GetHashCode () const
 
ASPOSECPP_SHARED_API void Lock ()
 
virtual ASPOSECPP_SHARED_API ptr MemberwiseClone () const
 
Objectoperator= (Object const &x)
 
bool ReferenceEquals (String const &str, std::nullptr_t)
 
bool ReferenceEquals (String const &str1, String const &str2)
 
int RemovedSharedRefs (int count)
 
virtual ASPOSECPP_SHARED_API void SetTemplateWeakPtr (unsigned int argument)
 
int SharedCount () const
 
ObjectSharedRefAdded ()
 
int SharedRefRemovedSafe ()
 
virtual ASPOSECPP_SHARED_API String ToString () const
 
ASPOSECPP_SHARED_API void Unlock ()
 
Detail::SmartPtrCounter * WeakRefAdded ()
 
void WeakRefRemoved ()
 

Static Public Member Functions

static const TypeInfoType ()
 
- Static Public Member Functions inherited from SpecialChar
static const TypeInfoType ()
 
- Static Public Member Functions inherited from Inline
static const TypeInfoType ()
 
- Static Public Member Functions inherited from Node
static String NodeTypeToString (NodeType nodeType)
 A utility method that converts a node type enum value into a user friendly string. More...
 
static const TypeInfoType ()
 
- Static Public Member Functions inherited from Object
bool Equals (double const &objA, double const &objB)
 
bool Equals (float const &objA, float const &objB)
 
static std::enable_if<!IsSmartPtr< T1 >::value &&!IsSmartPtr< T2 >::value, bool >::type Equals (T1 const &objA, T2 const &objB)
 
static std::enable_if< IsSmartPtr< T1 >::value &&IsSmartPtr< T2 >::value, bool >::type Equals (T1 const &objA, T2 const &objB)
 
static bool ReferenceEquals (ptr const &objA, ptr const &objB)
 
static std::enable_if<!IsSmartPtr< T >::value, bool >::type ReferenceEquals (T const &objA, std::nullptr_t)
 
static std::enable_if<!IsSmartPtr< T >::value, bool >::type ReferenceEquals (T const &objA, T const &objB)
 
static const TypeInfoType ()
 

Additional Inherited Members

- Public Types inherited from Object
typedef SmartPtr< Objectptr
 
typedef System::Details::SharedMembersType shared_members_type
 

Member Function Documentation

◆ Accept()

bool Aspose::Words::Fields::FormField::Accept ( System::SharedPtr< Aspose::Words::DocumentVisitor visitor)
overridevirtual

Accepts a visitor.

Calls DocumentVisitor.VisitFormField.

For more info see the Visitor design pattern.

Parameters
visitorThe visitor that will visit the node.
Returns
False if the visitor requested the enumeration to stop.

Implements Aspose::Words::Node.

◆ get_CalculateOnExit()

bool Aspose::Words::Fields::FormField::get_CalculateOnExit ( )

True if references to the specified form field are automatically updated whenever the field is exited.

Setting CalculateOnExit only affects the behavior of the form field when the document is opened in Microsoft Word. Aspose.Words never updates references to the form field.

◆ get_CheckBoxSize()

double Aspose::Words::Fields::FormField::get_CheckBoxSize ( )

Gets or sets the size of the checkbox in points. Has effect only when IsCheckBoxExactSize is true.

Applicable for a check box form field only.

See also
Aspose::Words::Fields::FormField::get_IsCheckBoxExactSize

◆ get_Checked()

bool Aspose::Words::Fields::FormField::get_Checked ( )

Gets or sets the checked status of the check box form field. Default value for this property is false.

Applicable for a check box form field only.

◆ get_Default()

bool Aspose::Words::Fields::FormField::get_Default ( )

Gets or sets the default value of the check box form field. Default value for this property is false.

Applicable for a check box form field only.

◆ get_DropDownItems()

System::SharedPtr<Aspose::Words::Fields::DropDownItemCollection> Aspose::Words::Fields::FormField::get_DropDownItems ( )

Provides access to the items of a dropdown form field.

Microsoft Word allows maximum 25 items in a dropdown form field.

◆ get_DropDownSelectedIndex()

int32_t Aspose::Words::Fields::FormField::get_DropDownSelectedIndex ( )

Gets the index specifying the currently selected item in a dropdown form field.

◆ get_Enabled()

bool Aspose::Words::Fields::FormField::get_Enabled ( )

True if a form field is enabled.

If a form field is enabled, its contents can be changed as the form is filled in.

◆ get_EntryMacro()

System::String Aspose::Words::Fields::FormField::get_EntryMacro ( )

Returns or sets an entry macro name for the form field.

The entry macro runs when the form field gets the focus in Microsoft Word.

Microsoft Word allows strings with at most 32 characters.

◆ get_ExitMacro()

System::String Aspose::Words::Fields::FormField::get_ExitMacro ( )

Returns or sets an exit macro name for the form field.

The exit macro runs when the form field loses the focus in Microsoft Word.

Microsoft Word allows strings with at most 32 characters.

◆ get_HelpText()

System::String Aspose::Words::Fields::FormField::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.

If the OwnHelp property is set to True, HelpText specifies the text string value. If OwnHelp is set to False, HelpText specifies the name of an AutoText entry that contains help text for the form field.

Microsoft Word allows strings with at most 255 characters.

◆ get_IsCheckBoxExactSize()

bool Aspose::Words::Fields::FormField::get_IsCheckBoxExactSize ( )

Gets or sets the boolean value that indicates whether the size of the textbox is automatic or specified explicitly.

Applicable for a check box form field only.

See also
Aspose::Words::Fields::FormField::get_CheckBoxSize

◆ get_MaxLength()

int32_t Aspose::Words::Fields::FormField::get_MaxLength ( )

Maximum length for the text field. Zero when the length is not limited.

◆ get_Name()

System::String Aspose::Words::Fields::FormField::get_Name ( )

Gets or sets the form field name.

Examples

Shows how to work with form field name, type, and result.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Use a DocumentBuilder to insert a combo box form field
SharedPtr<Aspose::Words::Fields::FormField> comboBox = builder->InsertComboBox(u"MyComboBox", MakeArray<String>({u"One", u"Two", u"Three"}), 0);
// Verify some of our form field's attributes
ASSERT_EQ(u"MyComboBox", comboBox->get_Name());
ASSERT_EQ(Aspose::Words::Fields::FieldType::FieldFormDropDown, comboBox->get_Type());
ASSERT_EQ(u"One", comboBox->get_Result());

◆ get_NodeType()

Aspose::Words::NodeType Aspose::Words::Fields::FormField::get_NodeType ( ) const
overridevirtual

◆ get_OwnHelp()

bool Aspose::Words::Fields::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.

If True, the text specified by the HelpText property is displayed. If False, the text in the AutoText entry specified by the HelpText property is displayed.

◆ get_OwnStatus()

bool Aspose::Words::Fields::FormField::get_OwnStatus ( )

Specifies the source of the text that's displayed in the status bar when a form field has the focus.

If true, the text specified by the StatusText property is displayed. If false, the text of the AutoText entry specified by the StatusText property is displayed.

◆ get_Result()

System::String Aspose::Words::Fields::FormField::get_Result ( )

Gets or sets a string that represents the result of this form field.

For a text form field the result is the text that is in the field.

For a checkbox form field the result can be "1" or "0" to indicate checked or unchecked.

For a dropdown form field the result is the string selected in the dropdown.

Setting Result for a text form field does not apply the text format specified in TextInputFormat. If you want to set a value and apply the format, use the SetTextInputValue() method.

Examples

Shows how to work with form field name, type, and result.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Use a DocumentBuilder to insert a combo box form field
SharedPtr<Aspose::Words::Fields::FormField> comboBox = builder->InsertComboBox(u"MyComboBox", MakeArray<String>({u"One", u"Two", u"Three"}), 0);
// Verify some of our form field's attributes
ASSERT_EQ(u"MyComboBox", comboBox->get_Name());
ASSERT_EQ(Aspose::Words::Fields::FieldType::FieldFormDropDown, comboBox->get_Type());
ASSERT_EQ(u"One", comboBox->get_Result());

◆ get_StatusText()

System::String Aspose::Words::Fields::FormField::get_StatusText ( )

Returns or sets the text that's displayed in the status bar when a form field has the focus.

If the OwnStatus property is set to true, the StatusText property specifies the status bar text. If the OwnStatus property is set to false, the StatusText property specifies the name of an AutoText entry that contains status bar text for the form field.

Microsoft Word allows strings with at most 138 characters.

◆ get_TextInputDefault()

System::String Aspose::Words::Fields::FormField::get_TextInputDefault ( )

Gets or sets the default string or a calculation expression of a text form field.

The meaning of this property depends on the value of the TextInputType property.

When TextInputType is Regular or Number, this string specifies the default string for the text form field. This string is the content that Microsoft Word will display in the document when the form field is empty.

When TextInputType is Calculated, then this string holds the expression to be calculated. The expression needs to be a formula valid according to Microsoft Word formula field requirements. When you set a new expression using this property, Aspose.Words calculates the formula result automatically and inserts it into the form field.

Microsoft Word allows strings with at most 255 characters.

◆ get_TextInputFormat()

System::String Aspose::Words::Fields::FormField::get_TextInputFormat ( )

Returns or sets the text formatting for a text form field.

If the text form field contains regular text, then valid format strings are "", "UPPERCASE", "LOWERCASE", "FIRST CAPITAL" and "TITLE CASE". The strings are case-insensitive.

If the text form field contains a number or a date/time value, then valid format strings are number or date and time format strings.

Microsoft Word allows strings with at most 64 characters.

◆ get_TextInputType()

Aspose::Words::Fields::TextFormFieldType Aspose::Words::Fields::FormField::get_TextInputType ( )

Gets the type of a text form field.

◆ get_Type()

Aspose::Words::Fields::FieldType Aspose::Words::Fields::FormField::get_Type ( )

Returns the form field type.

Examples

Shows how to work with form field name, type, and result.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Use a DocumentBuilder to insert a combo box form field
SharedPtr<Aspose::Words::Fields::FormField> comboBox = builder->InsertComboBox(u"MyComboBox", MakeArray<String>({u"One", u"Two", u"Three"}), 0);
// Verify some of our form field's attributes
ASSERT_EQ(u"MyComboBox", comboBox->get_Name());
ASSERT_EQ(Aspose::Words::Fields::FieldType::FieldFormDropDown, comboBox->get_Type());
ASSERT_EQ(u"One", comboBox->get_Result());

◆ GetType()

virtual const System::TypeInfo& Aspose::Words::Fields::FormField::GetType ( ) const
overridevirtual

Reimplemented from Aspose::Words::SpecialChar.

◆ Is()

virtual bool Aspose::Words::Fields::FormField::Is ( const System::TypeInfo target) const
overridevirtual

Reimplemented from Aspose::Words::SpecialChar.

◆ RemoveField()

void Aspose::Words::Fields::FormField::RemoveField ( )

Removes the complete form field, not just the form field special character.

Examples

Shows how to delete complete form field.

auto doc = MakeObject<Document>(MyDir + u"Form fields.docx");
SharedPtr<Aspose::Words::Fields::FormField> formField = doc->get_Range()->get_FormFields()->idx_get(3);
formField->RemoveField();

◆ set_CalculateOnExit()

void Aspose::Words::Fields::FormField::set_CalculateOnExit ( bool  value)

◆ set_CheckBoxSize()

void Aspose::Words::Fields::FormField::set_CheckBoxSize ( double  value)

◆ set_Checked()

void Aspose::Words::Fields::FormField::set_Checked ( bool  value)

◆ set_Default()

void Aspose::Words::Fields::FormField::set_Default ( bool  value)

◆ set_DropDownSelectedIndex()

void Aspose::Words::Fields::FormField::set_DropDownSelectedIndex ( int32_t  value)

Sets the index specifying the currently selected item in a dropdown form field.

◆ set_Enabled()

void Aspose::Words::Fields::FormField::set_Enabled ( bool  value)

True if a form field is enabled.

If a form field is enabled, its contents can be changed as the form is filled in.

◆ set_EntryMacro()

void Aspose::Words::Fields::FormField::set_EntryMacro ( System::String  value)

◆ set_ExitMacro()

void Aspose::Words::Fields::FormField::set_ExitMacro ( System::String  value)

◆ set_HelpText()

void Aspose::Words::Fields::FormField::set_HelpText ( System::String  value)

◆ set_IsCheckBoxExactSize()

void Aspose::Words::Fields::FormField::set_IsCheckBoxExactSize ( bool  value)

◆ set_MaxLength()

void Aspose::Words::Fields::FormField::set_MaxLength ( int32_t  value)

Maximum length for the text field. Zero when the length is not limited.

◆ set_Name()

void Aspose::Words::Fields::FormField::set_Name ( System::String  value)

◆ set_OwnHelp()

void Aspose::Words::Fields::FormField::set_OwnHelp ( bool  value)

◆ set_OwnStatus()

void Aspose::Words::Fields::FormField::set_OwnStatus ( bool  value)

◆ set_Result()

void Aspose::Words::Fields::FormField::set_Result ( System::String  value)

◆ set_StatusText()

void Aspose::Words::Fields::FormField::set_StatusText ( System::String  value)

◆ set_TextInputDefault()

void Aspose::Words::Fields::FormField::set_TextInputDefault ( System::String  value)

◆ set_TextInputFormat()

void Aspose::Words::Fields::FormField::set_TextInputFormat ( System::String  value)

◆ set_TextInputType()

void Aspose::Words::Fields::FormField::set_TextInputType ( Aspose::Words::Fields::TextFormFieldType  value)

Sets the type of a text form field.

◆ SetTextInputValue()

void Aspose::Words::Fields::FormField::SetTextInputValue ( System::SharedPtr< System::Object newValue)

Applies the text format specified in TextInputFormat and stores the value in Result.

Parameters
newValueCan be a string, number or a DateTime object.

◆ Type()

static const System::TypeInfo& Aspose::Words::Fields::FormField::Type ( )
static
@ FieldFormDropDown
Specifies the FORMDROPDOWN field.