FieldRef (Aspose.Words for Java API Reference)

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

public class FieldRef
extends Field

Implements the REF field.

To learn more, visit the Working with Fields documentation article.

Remarks:

Inserts the text or graphics represented by the specified bookmark.

Examples:

Shows how to create bookmarked text with a SET field, and then display it in the document using a REF field.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // Name bookmarked text with a SET field.
 // This field refers to the "bookmark" not a bookmark structure that appears within the text, but a named variable.
 FieldSet fieldSet = (FieldSet) builder.insertField(FieldType.FIELD_SET, false);
 fieldSet.setBookmarkName("MyBookmark");
 fieldSet.setBookmarkText("Hello world!");
 fieldSet.update();

 Assert.assertEquals(" SET  MyBookmark \"Hello world!\"", fieldSet.getFieldCode());

 // Refer to the bookmark by name in a REF field and display its contents.
 FieldRef fieldRef = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
 fieldRef.setBookmarkName("MyBookmark");
 fieldRef.update();

 Assert.assertEquals(" REF  MyBookmark", fieldRef.getFieldCode());
 Assert.assertEquals("Hello world!", fieldRef.getResult());

 doc.save(getArtifactsDir() + "Field.SET.REF.docx");

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`canWorkAsMergeField()`
`java.lang.String`	`getBookmarkName()` Gets the referenced bookmark's name.
`boolean`	`getIncludeNoteOrComment()` Gets whether to increment footnote, endnote, and annotation numbers that are marked by the bookmark, and insert the corresponding footnote, endnote, and comment text.
`boolean`	`getInsertHyperlink()` Gets whether to create a hyperlink to the bookmarked paragraph.
`boolean`	`getInsertParagraphNumber()` Gets whether to insert the paragraph number of the referenced paragraph exactly as it appears in the document.
`boolean`	`getInsertParagraphNumberInFullContext()` Gets whether to insert the paragraph number of the referenced paragraph in full context.
`boolean`	`getInsertParagraphNumberInRelativeContext()` Gets whether to insert the paragraph number of the referenced paragraph in relative context.
`boolean`	`getInsertRelativePosition()` Gets whether to insert the relative position of the referenced paragraph.
`java.lang.String`	`getMergeFieldName()`
`java.lang.String`	`getNumberSeparator()` Gets the character sequence that is used to separate sequence numbers and page numbers.
`boolean`	`getSuppressNonDelimiters()` Gets whether to suppress non-delimiter characters.
`int`	`getSwitchType(java.lang.String switchName)`
`boolean`	`isMergeValueRequired()`
`void`	`setBookmarkName(java.lang.String value)` Sets the referenced bookmark's name.
`void`	`setIncludeNoteOrComment(boolean value)` Sets whether to increment footnote, endnote, and annotation numbers that are marked by the bookmark, and insert the corresponding footnote, endnote, and comment text.
`void`	`setInsertHyperlink(boolean value)` Sets whether to create a hyperlink to the bookmarked paragraph.
`void`	`setInsertParagraphNumber(boolean value)` Sets whether to insert the paragraph number of the referenced paragraph exactly as it appears in the document.
`void`	`setInsertParagraphNumberInFullContext(boolean value)` Sets whether to insert the paragraph number of the referenced paragraph in full context.
`void`	`setInsertParagraphNumberInRelativeContext(boolean value)` Sets whether to insert the paragraph number of the referenced paragraph in relative context.
`void`	`setInsertRelativePosition(boolean value)` Sets whether to insert the relative position of the referenced paragraph.
`void`	`setNumberSeparator(java.lang.String value)` Sets the character sequence that is used to separate sequence numbers and page numbers.
`void`	`setSuppressNonDelimiters(boolean value)` Sets whether to suppress non-delimiter characters.

Methods inherited from class com.aspose.words.Field
getDisplayResult, getEnd, getFieldCode, getFieldCode, getFormat, getLocaleId, getResult, getSeparator, getStart, getType, isDirty, isDirty, isLocked, isLocked, needStoreOldResultNodes, remove, setLocaleId, setResult, unlink, update, update

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

Method Detail

getSwitchType

public int getSwitchType(java.lang.String switchName)

getMergeFieldName

public java.lang.String getMergeFieldName()

canWorkAsMergeField
```
public boolean canWorkAsMergeField()
```

isMergeValueRequired
```
public boolean isMergeValueRequired()
```

getBookmarkName

public java.lang.String getBookmarkName()

Gets the referenced bookmark's name.

Examples:

Shows how to create bookmarked text with a SET field, and then display it in the document using a REF field.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // Name bookmarked text with a SET field.
 // This field refers to the "bookmark" not a bookmark structure that appears within the text, but a named variable.
 FieldSet fieldSet = (FieldSet) builder.insertField(FieldType.FIELD_SET, false);
 fieldSet.setBookmarkName("MyBookmark");
 fieldSet.setBookmarkText("Hello world!");
 fieldSet.update();

 Assert.assertEquals(" SET  MyBookmark \"Hello world!\"", fieldSet.getFieldCode());

 // Refer to the bookmark by name in a REF field and display its contents.
 FieldRef fieldRef = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
 fieldRef.setBookmarkName("MyBookmark");
 fieldRef.update();

 Assert.assertEquals(" REF  MyBookmark", fieldRef.getFieldCode());
 Assert.assertEquals("Hello world!", fieldRef.getResult());

 doc.save(getArtifactsDir() + "Field.SET.REF.docx");

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Returns:: The referenced bookmark's name.

setBookmarkName

public void setBookmarkName(java.lang.String value)
                     throws java.lang.Exception

Sets the referenced bookmark's name.

Examples:

Shows how to create bookmarked text with a SET field, and then display it in the document using a REF field.

 
 Document doc = new Document();
 DocumentBuilder builder = new DocumentBuilder(doc);

 // Name bookmarked text with a SET field.
 // This field refers to the "bookmark" not a bookmark structure that appears within the text, but a named variable.
 FieldSet fieldSet = (FieldSet) builder.insertField(FieldType.FIELD_SET, false);
 fieldSet.setBookmarkName("MyBookmark");
 fieldSet.setBookmarkText("Hello world!");
 fieldSet.update();

 Assert.assertEquals(" SET  MyBookmark \"Hello world!\"", fieldSet.getFieldCode());

 // Refer to the bookmark by name in a REF field and display its contents.
 FieldRef fieldRef = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
 fieldRef.setBookmarkName("MyBookmark");
 fieldRef.update();

 Assert.assertEquals(" REF  MyBookmark", fieldRef.getFieldCode());
 Assert.assertEquals("Hello world!", fieldRef.getResult());

 doc.save(getArtifactsDir() + "Field.SET.REF.docx");

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Parameters:: value - The referenced bookmark's name.
Throws:: java.lang.Exception

getNumberSeparator

public java.lang.String getNumberSeparator()

Gets the character sequence that is used to separate sequence numbers and page numbers.

Examples:

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Returns:: The character sequence that is used to separate sequence numbers and page numbers.

setNumberSeparator

public void setNumberSeparator(java.lang.String value)
                        throws java.lang.Exception

Sets the character sequence that is used to separate sequence numbers and page numbers.

Examples:

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Parameters:: value - The character sequence that is used to separate sequence numbers and page numbers.
Throws:: java.lang.Exception

getIncludeNoteOrComment

public boolean getIncludeNoteOrComment()

Gets whether to increment footnote, endnote, and annotation numbers that are marked by the bookmark, and insert the corresponding footnote, endnote, and comment text.

Examples:

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Returns:: Whether to increment footnote, endnote, and annotation numbers that are marked by the bookmark, and insert the corresponding footnote, endnote, and comment text.

setIncludeNoteOrComment

public void setIncludeNoteOrComment(boolean value)
                             throws java.lang.Exception

Sets whether to increment footnote, endnote, and annotation numbers that are marked by the bookmark, and insert the corresponding footnote, endnote, and comment text.

Examples:

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Parameters:: value - Whether to increment footnote, endnote, and annotation numbers that are marked by the bookmark, and insert the corresponding footnote, endnote, and comment text.
Throws:: java.lang.Exception

getInsertHyperlink

public boolean getInsertHyperlink()

Gets whether to create a hyperlink to the bookmarked paragraph.

Examples:

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Returns:: Whether to create a hyperlink to the bookmarked paragraph.

setInsertHyperlink

public void setInsertHyperlink(boolean value)
                        throws java.lang.Exception

Sets whether to create a hyperlink to the bookmarked paragraph.

Examples:

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Parameters:: value - Whether to create a hyperlink to the bookmarked paragraph.
Throws:: java.lang.Exception

getInsertParagraphNumber

public boolean getInsertParagraphNumber()

Gets whether to insert the paragraph number of the referenced paragraph exactly as it appears in the document.

Examples:

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Returns:: Whether to insert the paragraph number of the referenced paragraph exactly as it appears in the document.

setInsertParagraphNumber

public void setInsertParagraphNumber(boolean value)
                              throws java.lang.Exception

Sets whether to insert the paragraph number of the referenced paragraph exactly as it appears in the document.

Examples:

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Parameters:: value - Whether to insert the paragraph number of the referenced paragraph exactly as it appears in the document.
Throws:: java.lang.Exception

getInsertRelativePosition

public boolean getInsertRelativePosition()

Gets whether to insert the relative position of the referenced paragraph.

Examples:

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Returns:: Whether to insert the relative position of the referenced paragraph.

setInsertRelativePosition

public void setInsertRelativePosition(boolean value)
                               throws java.lang.Exception

Sets whether to insert the relative position of the referenced paragraph.

Examples:

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Parameters:: value - Whether to insert the relative position of the referenced paragraph.
Throws:: java.lang.Exception

getInsertParagraphNumberInRelativeContext

public boolean getInsertParagraphNumberInRelativeContext()

Gets whether to insert the paragraph number of the referenced paragraph in relative context.

Examples:

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Returns:: Whether to insert the paragraph number of the referenced paragraph in relative context.

setInsertParagraphNumberInRelativeContext

public void setInsertParagraphNumberInRelativeContext(boolean value)
                                               throws java.lang.Exception

Sets whether to insert the paragraph number of the referenced paragraph in relative context.

Examples:

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Parameters:: value - Whether to insert the paragraph number of the referenced paragraph in relative context.
Throws:: java.lang.Exception

getSuppressNonDelimiters

public boolean getSuppressNonDelimiters()

Gets whether to suppress non-delimiter characters.

Examples:

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Returns:: Whether to suppress non-delimiter characters.

setSuppressNonDelimiters

public void setSuppressNonDelimiters(boolean value)
                              throws java.lang.Exception

Sets whether to suppress non-delimiter characters.

Examples:

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Parameters:: value - Whether to suppress non-delimiter characters.
Throws:: java.lang.Exception

getInsertParagraphNumberInFullContext

public boolean getInsertParagraphNumberInFullContext()

Gets whether to insert the paragraph number of the referenced paragraph in full context.

Examples:

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Returns:: Whether to insert the paragraph number of the referenced paragraph in full context.

setInsertParagraphNumberInFullContext

public void setInsertParagraphNumberInFullContext(boolean value)
                                           throws java.lang.Exception

Sets whether to insert the paragraph number of the referenced paragraph in full context.

Examples:

Shows how to insert REF fields to reference bookmarks.

 
 public void fieldRef() throws Exception {
     Document doc = new Document();
     DocumentBuilder builder = new DocumentBuilder(doc);

     builder.startBookmark("MyBookmark");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #1");
     builder.write("Text that will appear in REF field");
     builder.insertFootnote(FootnoteType.FOOTNOTE, "MyBookmark footnote #2");
     builder.endBookmark("MyBookmark");
     builder.moveToDocumentStart();

     // We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
     builder.getListFormat().applyNumberDefault();
     builder.getListFormat().getListLevel().setNumberFormat("> ");

     // Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
     FieldRef field = insertFieldRef(builder, "MyBookmark", "", "\n");
     field.setIncludeNoteOrComment(true);
     field.setInsertHyperlink(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\f \\h");

     // Insert a REF field, and display whether the referenced bookmark is above or below it.
     field = insertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
     field.setInsertRelativePosition(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\p");

     // Display the list number of the bookmark as it appears in the document.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
     field.setInsertParagraphNumber(true);

     Assert.assertEquals(" REF  MyBookmark \\n", field.getFieldCode());

     // Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
     field.setInsertParagraphNumber(true);
     field.setSuppressNonDelimiters(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\n \\t");

     // Move down one list level.
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">> ");

     // Display the list number of the bookmark and the numbers of all the list levels above it.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
     field.setInsertParagraphNumberInFullContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\w");

     builder.insertBreak(BreakType.PAGE_BREAK);

     // Display the list level numbers between this REF field, and the bookmark that it is referencing.
     field = insertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
     field.setInsertParagraphNumberInRelativeContext(true);

     Assert.assertEquals(field.getFieldCode(), " REF  MyBookmark \\r");

     // At the end of the document, the bookmark will show up as a list item here.
     builder.writeln("List level above bookmark");
     builder.getListFormat().setListLevelNumber(builder.getListFormat().getListLevelNumber() + 1);
     builder.getListFormat().getListLevel().setNumberFormat(">>> ");

     doc.updateFields();
     doc.save(getArtifactsDir() + "Field.REF.docx");
 }

 /// <summary>
 /// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
 /// </summary>
 private FieldRef insertFieldRef(final DocumentBuilder builder, final String bookmarkName,
                                 final String textBefore, final String textAfter) throws Exception {
     builder.write(textBefore);
     FieldRef field = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
     field.setBookmarkName(bookmarkName);
     builder.write(textAfter);
     return field;
 }

Parameters:: value - Whether to insert the paragraph number of the referenced paragraph in full context.
Throws:: java.lang.Exception

Class FieldRef

Method Summary

Methods inherited from class com.aspose.words.Field

Methods inherited from class java.lang.Object

Method Detail

getSwitchType

getMergeFieldName

canWorkAsMergeField

isMergeValueRequired

getBookmarkName

setBookmarkName

getNumberSeparator

setNumberSeparator

getIncludeNoteOrComment

setIncludeNoteOrComment

getInsertHyperlink

setInsertHyperlink

getInsertParagraphNumber

setInsertParagraphNumber

getInsertRelativePosition

setInsertRelativePosition

getInsertParagraphNumberInRelativeContext

setInsertParagraphNumberInRelativeContext

getSuppressNonDelimiters

setSuppressNonDelimiters

getInsertParagraphNumberInFullContext

setInsertParagraphNumberInFullContext