Field (Aspose.Words for Java API Reference)

java.lang.Object
- com.aspose.words.Field

Direct Known Subclasses:

FieldAddIn, FieldAddressBlock, FieldAdvance, FieldAsk, FieldAuthor, FieldAutoNum, FieldAutoNumLgl, FieldAutoNumOut, FieldAutoText, FieldAutoTextList, FieldBarcode, FieldBibliography, FieldBidiOutline, FieldCitation, FieldComments, FieldCompare, FieldCreateDate, FieldData, FieldDatabase, FieldDate, FieldDde, FieldDdeAuto, FieldDisplayBarcode, FieldDocProperty, FieldDocVariable, FieldEditTime, FieldEmbed, FieldEQ, FieldFileName, FieldFileSize, FieldFillIn, FieldFootnoteRef, FieldFormCheckBox, FieldFormDropDown, FieldFormText, FieldFormula, FieldGlossary, FieldGoToButton, FieldGreetingLine, FieldHyperlink, FieldIf, FieldImport, FieldInclude, FieldIncludePicture, FieldIncludeText, FieldIndex, FieldInfo, FieldKeywords, FieldLastSavedBy, FieldLink, FieldListNum, FieldMacroButton, FieldMergeBarcode, FieldMergeField, FieldMergeRec, FieldMergeSeq, FieldNext, FieldNextIf, FieldNoteRef, FieldNumChars, FieldNumPages, FieldNumWords, FieldOcx, FieldPage, FieldPageRef, FieldPrint, FieldPrintDate, FieldPrivate, FieldQuote, FieldRD, FieldRef, FieldRevNum, FieldSaveDate, FieldSection, FieldSectionPages, FieldSeq, FieldSet, FieldShape, FieldSkipIf, FieldStyleRef, FieldSubject, FieldSymbol, FieldTA, FieldTC, FieldTemplate, FieldTime, FieldTitle, FieldToa, FieldToc, FieldUnknown, FieldUserAddress, FieldUserInitials, FieldUserName, FieldXE
```
public class Field
extends java.lang.Object
```
Represents a Microsoft Word document field.
To learn more, visit the Working with Fields documentation article.

A field in a Word document is a complex structure consisting of multiple nodes that include field start, field code, field separator, field result and field end. Fields can be nested, contain rich content and span multiple paragraphs or sections in a document. The Field class is a "facade" object that provides properties and methods that allow to work with a field as a single object.

The getStart(), getSeparator() and getEnd() properties point to the field start, separator and end nodes of the field respectively.

The content between the field start and separator is the field code. The content between the field separator and field end is the field result. The field code typically consists of one or more Run objects that specify instructions. The processing application is expected to execute the field code to calculate the field result.

The process of calculating field results is called the field update. Aspose.Words can update field results of most of the field types in exactly the same way as Microsoft Word does it. Most notably, Aspose.Words can calculate results of even the most complex formula fields. To calculate the field result of a single field use the update() method. To update fields in the whole document use Document.updateFields().

You can get the plain text version of the field code using the getFieldCode(boolean) method. You can get and set the plain text version of the field result using the getResult() / setResult(java.lang.String) property. Both the field code and field result can contain complex content, such as nested fields, paragraphs, shapes, tables and in this case you might want to work with the field nodes directly if you need more control.

You do not create instances of the Field class directly. To create a new field use the DocumentBuilder.insertField(java.lang.String) method.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`java.lang.String`	`getDisplayResult()` Gets the text that represents the displayed field result.
`FieldEnd`	`getEnd()` Gets the node that represents the field end.
`java.lang.String`	`getFieldCode()` Returns text between field start and field separator (or field end if there is no separator).
`java.lang.String`	`getFieldCode(boolean includeChildFieldCodes)` Returns text between field start and field separator (or field end if there is no separator).
`FieldFormat`	`getFormat()` Gets a `FieldFormat` object that provides typed access to field's formatting.
`int`	`getLocaleId()` Gets the LCID of the field.
`java.lang.String`	`getResult()` Gets text that is between the field separator and field end.
`FieldSeparator`	`getSeparator()` Gets the node that represents the field separator.
`FieldStart`	`getStart()` Gets the node that represents the start of the field.
`int`	`getType()` Gets the Microsoft Word field type.
`boolean`	`isDirty()` Gets whether the current result of the field is no longer correct (stale) due to other modifications made to the document.
`void`	`isDirty(boolean value)` Sets whether the current result of the field is no longer correct (stale) due to other modifications made to the document.
`boolean`	`isLocked()` Gets whether the field is locked (should not recalculate its result).
`void`	`isLocked(boolean value)` Sets whether the field is locked (should not recalculate its result).
`protected boolean`	`needStoreOldResultNodes()`
`Node`	`remove()` Removes the field from the document.
`void`	`setLocaleId(int value)` Sets the LCID of the field.
`void`	`setResult(java.lang.String value)` Sets text that is between the field separator and field end.
`boolean`	`unlink()` Performs the field unlink.
`void`	`update()` Performs the field update.
`void`	`update(boolean ignoreMergeFormat)` Performs a field update.

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

- Method Detail
  - getFieldCode
```
public java.lang.String getFieldCode()
```
    Returns text between field start and field separator (or field end if there is no separator). Both field code and field result of child fields are included.
  - getFieldCode
```
public java.lang.String getFieldCode(boolean includeChildFieldCodes)
```
    Returns text between field start and field separator (or field end if there is no separator).
    
    Parameters:
    
    includeChildFieldCodes - True if child field codes should be included.
  - remove
```
public Node remove()
            throws java.lang.Exception
```
    Removes the field from the document. Returns a node right after the field. If the field's end is the last child of its parent node, returns its parent paragraph. If the field is already removed, returns null.
    
    Throws:
    
    java.lang.Exception
  - update
```
public void update()
            throws java.lang.Exception
```
    Performs the field update. Throws if the field is being updated already.
    
    Throws:
    
    java.lang.Exception
  - update
```
public void update(boolean ignoreMergeFormat)
            throws java.lang.Exception
```
    Performs a field update. Throws if the field is being updated already.
    
    Parameters:
    
    ignoreMergeFormat - If true then direct field result formatting is abandoned, regardless of the MERGEFORMAT switch, otherwise normal update is performed.
    
    Throws:
    
    java.lang.Exception
  - unlink
```
public boolean unlink()
               throws java.lang.Exception
```
    Performs the field unlink.
    Replaces the field with its most recent result.
    
    Some fields, such as XE (Index Entry) fields and SEQ (Sequence) fields, cannot be unlinked.
    
    Returns:
    
    True if the field has been unlinked, otherwise false.
    
    Throws:
    
    java.lang.Exception
  - needStoreOldResultNodes
```
protected boolean needStoreOldResultNodes()
```
  - getStart
```
public FieldStart getStart()
```
    Gets the node that represents the start of the field.
    
    Returns:
    
    The node that represents the start of the field.
  - getSeparator
```
public FieldSeparator getSeparator()
```
    Gets the node that represents the field separator. Can be null.
    
    Returns:
    
    The node that represents the field separator.
  - getEnd
```
public FieldEnd getEnd()
```
    Gets the node that represents the field end.
    
    Returns:
    
    The node that represents the field end.
  - getType
```
public int getType()
```
    Gets the Microsoft Word field type.
    
    Returns:
    
    The Microsoft Word field type. The returned value is one of FieldType constants.
  - getResult
```
public java.lang.String getResult()
```
    Gets text that is between the field separator and field end.
    
    Returns:
    
    Text that is between the field separator and field end.
  - setResult
```
public void setResult(java.lang.String value)
               throws java.lang.Exception
```
    Sets text that is between the field separator and field end.
    
    Parameters:
    
    value - Text that is between the field separator and field end.
    
    Throws:
    
    java.lang.Exception
  - getDisplayResult
```
public java.lang.String getDisplayResult()
                                  throws java.lang.Exception
```
    Gets the text that represents the displayed field result. The Document.updateListLabels() method must be called to obtain correct value for the FieldListNum, FieldAutoNum, FieldAutoNumOut and FieldAutoNumLgl fields.
    
    Returns:
    
    The text that represents the displayed field result.
    
    Throws:
    
    java.lang.Exception
  - isLocked
```
public boolean isLocked()
```
    Gets whether the field is locked (should not recalculate its result).
    
    Returns:
    
    Whether the field is locked (should not recalculate its result).
  - isLocked
```
public void isLocked(boolean value)
```
    Sets whether the field is locked (should not recalculate its result).
    
    Parameters:
    
    value - Whether the field is locked (should not recalculate its result).
  - isDirty
```
public boolean isDirty()
```
    Gets whether the current result of the field is no longer correct (stale) due to other modifications made to the document.
    
    Returns:
    
    Whether the current result of the field is no longer correct (stale) due to other modifications made to the document.
  - isDirty
```
public void isDirty(boolean value)
```
    Sets whether the current result of the field is no longer correct (stale) due to other modifications made to the document.
    
    Parameters:
    
    value - Whether the current result of the field is no longer correct (stale) due to other modifications made to the document.
  - getFormat
```
public FieldFormat getFormat()
```
    Gets a FieldFormat object that provides typed access to field's formatting.
    
    Returns:
    
    A FieldFormat object that provides typed access to field's formatting.
  - getLocaleId
```
public int getLocaleId()
```
    Gets the LCID of the field.
    
    Returns:
    
    The LCID of the field.
    
    See Also:
    
    FieldUpdateCultureSource.FIELD_CODE
  - setLocaleId
```
public void setLocaleId(int value)
```
    Sets the LCID of the field.
    
    Parameters:
    
    value - The LCID of the field.
    
    See Also:
    
    FieldUpdateCultureSource.FIELD_CODE

Class Field

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getFieldCode

getFieldCode

remove

update

update

unlink

needStoreOldResultNodes

getStart

getSeparator

getEnd

getType

getResult

setResult

getDisplayResult

isLocked

isLocked

isDirty

isDirty

getFormat

getLocaleId

setLocaleId