FormField (Aspose.Words for Java API Reference)

java.lang.Object
- com.aspose.words.Node
- - com.aspose.words.Inline
  - - com.aspose.words.SpecialChar
    - - com.aspose.words.FormField

All Implemented Interfaces:

java.lang.Cloneable
```
public class FormField
extends SpecialChar
```
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(java.lang.String, boolean, int), M:Aspose.Words.DocumentBuilder.InsertTextInput(System.String,Aspose.Words.Fields.TextFormFieldType,System.String,System.String,System.Int32) and DocumentBuilder.insertComboBox(java.lang.String, java.lang.String[], int) which make sure all of the form field nodes are created in a correct order and in a suitable state.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`accept(DocumentVisitor visitor)` Accepts a visitor.
`boolean`	`getCalculateOnExit()` True if references to the specified form field are automatically updated whenever the field is exited.
`double`	`getCheckBoxSize()` Gets the size of the checkbox in points.
`boolean`	`getChecked()` Gets the checked status of the check box form field.
`boolean`	`getDefault()` Gets the default value of the check box form field.
`DropDownItemCollection`	`getDropDownItems()` Provides access to the items of a dropdown form field.
`int`	`getDropDownSelectedIndex()` Gets the index specifying the currently selected item in a dropdown form field.
`boolean`	`getEnabled()` True if a form field is enabled.
`java.lang.String`	`getEntryMacro()` Gets an entry macro name for the form field.
`java.lang.String`	`getExitMacro()` Gets an exit macro name for the form field.
`java.lang.String`	`getHelpText()` Gets the text that's displayed in a message box when the form field has the focus and the user presses F1.
`int`	`getMaxLength()` Maximum length for the text field.
`java.lang.String`	`getName()` Gets the form field name.
`int`	`getNodeType()` Returns NodeType.FormField.
`boolean`	`getOwnHelp()` 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.
`boolean`	`getOwnStatus()` Specifies the source of the text that's displayed in the status bar when a form field has the focus.
`java.lang.String`	`getResult()` Gets a string that represents the result of this form field.
`java.lang.String`	`getStatusText()` Gets the text that's displayed in the status bar when a form field has the focus.
`java.lang.String`	`getTextInputDefault()` Gets the default string or a calculation expression of a text form field.
`java.lang.String`	`getTextInputFormat()` Gets the text formatting for a text form field.
`int`	`getTextInputType()` Gets the type of a text form field.
`int`	`getType()` Returns the form field type.
`boolean`	`isCheckBoxExactSize()` Gets the boolean value that indicates whether the size of the textbox is automatic or specified explicitly.
`void`	`isCheckBoxExactSize(boolean value)` Sets the boolean value that indicates whether the size of the textbox is automatic or specified explicitly.
`void`	`removeField()` Removes the complete form field, not just the form field special character.
`void`	`setCalculateOnExit(boolean value)` True if references to the specified form field are automatically updated whenever the field is exited.
`void`	`setCheckBoxSize(double value)` Sets the size of the checkbox in points.
`void`	`setChecked(boolean value)` Sets the checked status of the check box form field.
`void`	`setDefault(boolean value)` Sets the default value of the check box form field.
`void`	`setDropDownSelectedIndex(int value)` Sets the index specifying the currently selected item in a dropdown form field.
`void`	`setEnabled(boolean value)` True if a form field is enabled.
`void`	`setEntryMacro(java.lang.String value)` Sets an entry macro name for the form field.
`void`	`setExitMacro(java.lang.String value)` Sets an exit macro name for the form field.
`void`	`setHelpText(java.lang.String value)` Sets the text that's displayed in a message box when the form field has the focus and the user presses F1.
`void`	`setMaxLength(int value)` Maximum length for the text field.
`void`	`setName(java.lang.String value)` Sets the form field name.
`void`	`setOwnHelp(boolean value)` 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.
`void`	`setOwnStatus(boolean value)` Specifies the source of the text that's displayed in the status bar when a form field has the focus.
`void`	`setResult(java.lang.String value)` Sets a string that represents the result of this form field.
`void`	`setRunAttr(int key, java.lang.Object value)`
`void`	`setStatusText(java.lang.String value)` Sets the text that's displayed in the status bar when a form field has the focus.
`void`	`setTextInputDefault(java.lang.String value)` Sets the default string or a calculation expression of a text form field.
`void`	`setTextInputFormat(java.lang.String value)` Sets the text formatting for a text form field.
`void`	`setTextInputType(int value)` Sets the type of a text form field.
`void`	`setTextInputValue(java.lang.Object newValue)` Applies the text format specified in `getTextInputFormat()` / `setTextInputFormat(java.lang.String)` and stores the value in `getResult()` / `setResult(java.lang.String)`.

Methods inherited from class com.aspose.words.SpecialChar
getText

Methods inherited from class com.aspose.words.Inline
clearRunAttrs, fetchInheritedRunAttr, getDirectRunAttr, getDocument_IInline, getFont, getParentParagraph_IInline, getParentParagraph, isDeleteRevision, isFormatRevision, isInsertRevision, isMoveFromRevision, isMoveToRevision, removeMoveRevisions, removeRunAttr

Methods inherited from class com.aspose.words.Node
dd, deepClone, getAncestor, getAncestor, getCustomNodeId, getDocument, getNextSibling, getParentNode, getPreviousSibling, getRange, isComposite, memberwiseClone, nextPreOrder, nodeTypeToString, previousPreOrder, remove, setCustomNodeId, toString, toString, toString, visitorActionToBool

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - setRunAttr
```
public void setRunAttr(int key,
                       java.lang.Object value)
```
    Overrides:
    
    setRunAttr in class Inline
  - accept
```
public boolean accept(DocumentVisitor visitor)
               throws java.lang.Exception
```
    Accepts a visitor.
    Calls DocumentVisitor.VisitFormField.
    
    For more info see the Visitor design pattern.
    
    Overrides:
    
    accept in class SpecialChar
    
    Parameters:
    
    visitor - The visitor that will visit the node.
    
    Returns:
    
    False if the visitor requested the enumeration to stop.
    
    Throws:
    
    java.lang.Exception
  - removeField
```
public void removeField()
                 throws java.lang.Exception
```
    Removes the complete form field, not just the form field special character. If there is a bookmark associated with the form field, the bookmark is not removed.
    
    Throws:
    
    java.lang.Exception
  - setTextInputValue
```
public void setTextInputValue(java.lang.Object newValue)
                       throws java.lang.Exception
```
    Applies the text format specified in getTextInputFormat() / setTextInputFormat(java.lang.String) and stores the value in getResult() / setResult(java.lang.String).
    
    Parameters:
    
    newValue - Can be a string, number or a DateTime object.
    
    Throws:
    
    java.lang.Exception
  - getNodeType
```
public int getNodeType()
```
    Returns NodeType.FormField.
    
    Overrides:
    
    getNodeType in class SpecialChar
    
    Returns:
    
    NodeType.FormField. The returned value is one of NodeType constants.
  - getName
```
public java.lang.String getName()
```
    Gets the form field name. Microsoft Word allows strings with at most 20 characters.
    
    Returns:
    
    The form field name.
  - setName
```
public void setName(java.lang.String value)
             throws java.lang.Exception
```
    Sets the form field name. Microsoft Word allows strings with at most 20 characters.
    
    Parameters:
    
    value - The form field name.
    
    Throws:
    
    java.lang.Exception
  - getType
```
public int getType()
```
    Returns the form field type.
    
    Returns:
    
    The form field type. The returned value is one of FieldType constants.
  - getResult
```
public java.lang.String getResult()
```
    Gets 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 getResult() / setResult(java.lang.String) for a text form field does not apply the text format specified in getTextInputFormat() / setTextInputFormat(java.lang.String). If you want to set a value and apply the format, use the setTextInputValue(java.lang.Object) method.
    
    For a text form field the getTextInputDefault() / setTextInputDefault(java.lang.String) value is applied if value is null.
    
    Returns:
    
    A string that represents the result of this form field.
  - setResult
```
public void setResult(java.lang.String value)
               throws java.lang.Exception
```
    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 getResult() / setResult(java.lang.String) for a text form field does not apply the text format specified in getTextInputFormat() / setTextInputFormat(java.lang.String). If you want to set a value and apply the format, use the setTextInputValue(java.lang.Object) method.
    
    For a text form field the getTextInputDefault() / setTextInputDefault(java.lang.String) value is applied if value is null.
    
    Parameters:
    
    value - A string that represents the result of this form field.
    
    Throws:
    
    java.lang.Exception
  - getStatusText
```
public java.lang.String getStatusText()
```
    Gets 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.
    
    Returns:
    
    The text that's displayed in the status bar when a form field has the focus.
  - setStatusText
```
public void setStatusText(java.lang.String value)
```
    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.
    
    Parameters:
    
    value - The text that's displayed in the status bar when a form field has the focus.
  - getOwnStatus
```
public boolean getOwnStatus()
```
    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.
    
    Returns:
    
    The corresponding boolean value.
  - setOwnStatus
```
public void setOwnStatus(boolean value)
```
    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.
    
    Parameters:
    
    value - The corresponding boolean value.
  - getHelpText
```
public java.lang.String getHelpText()
```
    Gets 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.
    
    Returns:
    
    The text that's displayed in a message box when the form field has the focus and the user presses F1.
  - setHelpText
```
public void setHelpText(java.lang.String value)
```
    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.
    
    Parameters:
    
    value - The text that's displayed in a message box when the form field has the focus and the user presses F1.
  - getOwnHelp
```
public boolean getOwnHelp()
```
    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.
    
    Returns:
    
    The corresponding boolean value.
  - setOwnHelp
```
public void setOwnHelp(boolean value)
```
    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.
    
    Parameters:
    
    value - The corresponding boolean value.
  - getCalculateOnExit
```
public boolean getCalculateOnExit()
```
    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.
    
    Returns:
    
    The corresponding boolean value.
  - setCalculateOnExit
```
public void setCalculateOnExit(boolean value)
```
    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.
    
    Parameters:
    
    value - The corresponding boolean value.
  - getEntryMacro
```
public java.lang.String getEntryMacro()
```
    Gets 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.
    
    Returns:
    
    An entry macro name for the form field.
  - setEntryMacro
```
public void setEntryMacro(java.lang.String value)
```
    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.
    
    Parameters:
    
    value - An entry macro name for the form field.
  - getExitMacro
```
public java.lang.String getExitMacro()
```
    Gets 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.
    
    Returns:
    
    An exit macro name for the form field.
  - setExitMacro
```
public void setExitMacro(java.lang.String value)
```
    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.
    
    Parameters:
    
    value - An exit macro name for the form field.
  - getEnabled
```
public boolean getEnabled()
```
    True if a form field is enabled.
    If a form field is enabled, its contents can be changed as the form is filled in.
    
    Returns:
    
    The corresponding boolean value.
  - setEnabled
```
public void setEnabled(boolean 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.
    
    Parameters:
    
    value - The corresponding boolean value.
  - getTextInputFormat
```
public java.lang.String getTextInputFormat()
```
    Gets 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.
    
    Returns:
    
    The text formatting for a text form field.
  - setTextInputFormat
```
public void setTextInputFormat(java.lang.String value)
```
    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.
    
    Parameters:
    
    value - The text formatting for a text form field.
  - getTextInputType
```
public int getTextInputType()
```
    Gets the type of a text form field.
    
    Returns:
    
    The type of a text form field. The returned value is one of TextFormFieldType constants.
  - setTextInputType
```
public void setTextInputType(int value)
```
    Sets the type of a text form field.
    
    Parameters:
    
    value - The type of a text form field. The value must be one of TextFormFieldType constants.
  - getTextInputDefault
```
public java.lang.String getTextInputDefault()
```
    Gets the default string or a calculation expression of a text form field.
    The meaning of this property depends on the value of the getTextInputType() / setTextInputType(int) property.
    
    When getTextInputType() / setTextInputType(int) is TextFormFieldType.REGULAR or TextFormFieldType.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 getTextInputType() / setTextInputType(int) is TextFormFieldType.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.
    
    Returns:
    
    The default string or a calculation expression of a text form field.
  - setTextInputDefault
```
public void setTextInputDefault(java.lang.String value)
                         throws java.lang.Exception
```
    Sets the default string or a calculation expression of a text form field.
    The meaning of this property depends on the value of the getTextInputType() / setTextInputType(int) property.
    
    When getTextInputType() / setTextInputType(int) is TextFormFieldType.REGULAR or TextFormFieldType.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 getTextInputType() / setTextInputType(int) is TextFormFieldType.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.
    
    Parameters:
    
    value - The default string or a calculation expression of a text form field.
    
    Throws:
    
    java.lang.Exception
  - getMaxLength
```
public int getMaxLength()
```
    Maximum length for the text field. Zero when the length is not limited.
    
    Returns:
    
    The corresponding int value.
  - setMaxLength
```
public void setMaxLength(int value)
```
    Maximum length for the text field. Zero when the length is not limited.
    
    Parameters:
    
    value - The corresponding int value.
  - getDropDownItems
```
public DropDownItemCollection getDropDownItems()
```
    Provides access to the items of a dropdown form field.
    Microsoft Word allows maximum 25 items in a dropdown form field.
    
    Returns:
    
    The corresponding DropDownItemCollection value.
  - getDropDownSelectedIndex
```
public int getDropDownSelectedIndex()
```
    Gets the index specifying the currently selected item in a dropdown form field.
    
    Returns:
    
    The index specifying the currently selected item in a dropdown form field.
  - setDropDownSelectedIndex
```
public void setDropDownSelectedIndex(int value)
```
    Sets the index specifying the currently selected item in a dropdown form field.
    
    Parameters:
    
    value - The index specifying the currently selected item in a dropdown form field.
  - getChecked
```
public boolean getChecked()
```
    Gets the checked status of the check box form field. Default value for this property is false.
    Applicable for a check box form field only.
    
    Returns:
    
    The checked status of the check box form field.
  - setChecked
```
public void setChecked(boolean value)
```
    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.
    
    Parameters:
    
    value - The checked status of the check box form field.
  - getDefault
```
public boolean getDefault()
```
    Gets the default value of the check box form field. Default value for this property is false.
    Applicable for a check box form field only.
    
    Returns:
    
    The default value of the check box form field.
  - setDefault
```
public void setDefault(boolean value)
```
    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.
    
    Parameters:
    
    value - The default value of the check box form field.
  - isCheckBoxExactSize
```
public boolean isCheckBoxExactSize()
```
    Gets the boolean value that indicates whether the size of the textbox is automatic or specified explicitly.
    Applicable for a check box form field only.
    
    Returns:
    
    The boolean value that indicates whether the size of the textbox is automatic or specified explicitly.
    
    See Also:
    
    getCheckBoxSize(), setCheckBoxSize(double)
  - isCheckBoxExactSize
```
public void isCheckBoxExactSize(boolean value)
```
    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.
    
    Parameters:
    
    value - The boolean value that indicates whether the size of the textbox is automatic or specified explicitly.
    
    See Also:
    
    getCheckBoxSize(), setCheckBoxSize(double)
  - getCheckBoxSize
```
public double getCheckBoxSize()
```
    Gets the size of the checkbox in points. Has effect only when isCheckBoxExactSize() / isCheckBoxExactSize(boolean) is true.
    Applicable for a check box form field only.
    
    Returns:
    
    The size of the checkbox in points.
    
    See Also:
    
    isCheckBoxExactSize(), isCheckBoxExactSize(boolean)
  - setCheckBoxSize
```
public void setCheckBoxSize(double value)
```
    Sets the size of the checkbox in points. Has effect only when isCheckBoxExactSize() / isCheckBoxExactSize(boolean) is true.
    Applicable for a check box form field only.
    
    Parameters:
    
    value - The size of the checkbox in points.
    
    See Also:
    
    isCheckBoxExactSize(), isCheckBoxExactSize(boolean)

Class FormField

Method Summary

Methods inherited from class com.aspose.words.SpecialChar

Methods inherited from class com.aspose.words.Inline

Methods inherited from class com.aspose.words.Node

Methods inherited from class java.lang.Object

Method Detail

setRunAttr

accept

removeField

setTextInputValue

getNodeType

getName

setName

getType

getResult

setResult

getStatusText

setStatusText

getOwnStatus

setOwnStatus

getHelpText

setHelpText

getOwnHelp

setOwnHelp

getCalculateOnExit

setCalculateOnExit

getEntryMacro

setEntryMacro

getExitMacro

setExitMacro

getEnabled

setEnabled

getTextInputFormat

setTextInputFormat

getTextInputType

setTextInputType

getTextInputDefault

setTextInputDefault

getMaxLength

setMaxLength

getDropDownItems

getDropDownSelectedIndex

setDropDownSelectedIndex

getChecked

setChecked

getDefault

setDefault

isCheckBoxExactSize

isCheckBoxExactSize

getCheckBoxSize

setCheckBoxSize