java.lang.Object
Field
com.aspose.words.FieldToc
public class FieldToc
- extends Field
Implements the TOC field.
Builds a table of contents (which can also be a table of figures) using the entries specified by TC fields,
their heading levels, and specified styles, and inserts that table at this place in the document.
Example:
Shows how to populate a TOC field with entries using SEQ fields.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a TOC field that creates a table of contents entry for each paragraph
// that contains a SEQ field with a sequence identifier of "MySequence" with the number of the page which contains that field
FieldToc fieldToc = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
fieldToc.setTableOfFiguresLabel("MySequence");
// This identifier is for a parallel SEQ sequence,
// the number that it is at will be displayed in front of the page number of the paragraph with the other sequence,
// separated by a sequence separator character also defined below
fieldToc.setPrefixedSequenceIdentifier("PrefixSequence");
fieldToc.setSequenceSeparator(">");
Assert.assertEquals(" TOC \\c MySequence \\s PrefixSequence \\d >", fieldToc.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
// Insert a SEQ field to increment the sequence counter of "PrefixSequence" to 1
// Since this paragraph doesn't contain a SEQ field of the "MySequence" sequence,
// this will not appear as an entry in the TOC
FieldSeq fieldSeq = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
fieldSeq.setSequenceIdentifier("PrefixSequence");
builder.insertParagraph();
Assert.assertEquals(" SEQ PrefixSequence", fieldSeq.getFieldCode());
// Insert two SEQ fields, one for each of the sequences we defined above
// The "MySequence" SEQ appears on page 2 and the "PrefixSequence" is at number 1 in this paragraph,
// which means that our TOC will display this as an entry with the contents on the left and "1>2" on the right
builder.write("First TOC entry, MySequence #");
fieldSeq = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
fieldSeq.setSequenceIdentifier("MySequence");
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TOC.SEQ.docx");
Example:
Shows how to insert a TOC and populate it with entries based on heading styles.
public void fieldToc() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// The table of contents we will insert will accept entries that are only within the scope of this bookmark
builder.startBookmark("MyBookmark");
// Insert a list num field using a document builder
FieldToc field = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
// Limit possible TOC entries to only those within the bookmark we name here
field.setBookmarkName("MyBookmark");
// Normally paragraphs with a "Heading n" style will be the only ones that will be added to a TOC as entries
// We can set this attribute to include other styles, such as "Quote" and "Intense Quote" in this case
field.setCustomStyles("Quote; 6; Intense Quote; 7");
// Styles are normally separated by a comma (",") but we can use this property to set a custom delimiter
doc.getFieldOptions().setCustomTocStyleSeparator(";");
// Filter out any headings that are outside this range
field.setHeadingLevelRange("1-3");
// Headings in this range won't display their page number in their TOC entry
field.setPageNumberOmittingLevelRange("2-5");
field.setEntrySeparator("-");
field.setInsertHyperlinks(true);
field.setHideInWebLayout(false);
field.setPreserveLineBreaks(true);
field.setPreserveTabs(true);
field.setUseParagraphOutlineLevel(false);
insertNewPageWithHeading(builder, "First entry", "Heading 1");
builder.writeln("Paragraph text.");
insertNewPageWithHeading(builder, "Second entry", "Heading 1");
insertNewPageWithHeading(builder, "Third entry", "Quote");
insertNewPageWithHeading(builder, "Fourth entry", "Intense Quote");
// These two headings will have the page numbers omitted because they are within the "2-5" range
insertNewPageWithHeading(builder, "Fifth entry", "Heading 2");
insertNewPageWithHeading(builder, "Sixth entry", "Heading 3");
// This entry will be omitted because "Heading 4" is outside of the "1-3" range we set earlier
insertNewPageWithHeading(builder, "Seventh entry", "Heading 4");
builder.endBookmark("MyBookmark");
builder.writeln("Paragraph text.");
// This entry will be omitted because it is outside the bookmark specified by the TOC
insertNewPageWithHeading(builder, "Eighth entry", "Heading 1");
Assert.assertEquals(" TOC \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w", field.getFieldCode());
field.updatePageNumbers();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TOC.docx");
}
/// <summary>
/// Start a new page and insert a paragraph of a specified style.
/// </summary>
@Test(enabled = false)
public void insertNewPageWithHeading(final DocumentBuilder builder, final String captionText, final String styleName) {
builder.insertBreak(BreakType.PAGE_BREAK);
String originalStyle = builder.getParagraphFormat().getStyleName();
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(styleName));
builder.writeln(captionText);
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(originalStyle));
}
Method Summary |
java.lang.String | getFieldCode() | → inherited from Field |
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.
|
java.lang.String | getFieldCode(boolean includeChildFieldCodes) | → inherited from Field |
Returns text between field start and field separator (or field end if there is no separator).
|
Node | remove() | → inherited from Field |
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.
|
boolean | unlink() | → inherited from Field |
Performs the field unlink.
|
void | update() | → inherited from Field |
Performs the field update. Throws if the field is being updated already.
|
void | update(boolean ignoreMergeFormat) | → inherited from Field |
Performs a field update. Throws if the field is being updated already.
|
boolean | updatePageNumbers() | |
Updates the page numbers for items in this table of contents.
|
FieldToc
public FieldToc()
-
Property Getters/Setters Detail |
getBookmarkName/setBookmarkName | |
public java.lang.String getBookmarkName() / public void setBookmarkName(java.lang.String value)
|
-
Gets or sets the name of the bookmark that marks the portion of the document used to build the table.
Example:
Shows how to insert a TOC and populate it with entries based on heading styles.
public void fieldToc() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// The table of contents we will insert will accept entries that are only within the scope of this bookmark
builder.startBookmark("MyBookmark");
// Insert a list num field using a document builder
FieldToc field = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
// Limit possible TOC entries to only those within the bookmark we name here
field.setBookmarkName("MyBookmark");
// Normally paragraphs with a "Heading n" style will be the only ones that will be added to a TOC as entries
// We can set this attribute to include other styles, such as "Quote" and "Intense Quote" in this case
field.setCustomStyles("Quote; 6; Intense Quote; 7");
// Styles are normally separated by a comma (",") but we can use this property to set a custom delimiter
doc.getFieldOptions().setCustomTocStyleSeparator(";");
// Filter out any headings that are outside this range
field.setHeadingLevelRange("1-3");
// Headings in this range won't display their page number in their TOC entry
field.setPageNumberOmittingLevelRange("2-5");
field.setEntrySeparator("-");
field.setInsertHyperlinks(true);
field.setHideInWebLayout(false);
field.setPreserveLineBreaks(true);
field.setPreserveTabs(true);
field.setUseParagraphOutlineLevel(false);
insertNewPageWithHeading(builder, "First entry", "Heading 1");
builder.writeln("Paragraph text.");
insertNewPageWithHeading(builder, "Second entry", "Heading 1");
insertNewPageWithHeading(builder, "Third entry", "Quote");
insertNewPageWithHeading(builder, "Fourth entry", "Intense Quote");
// These two headings will have the page numbers omitted because they are within the "2-5" range
insertNewPageWithHeading(builder, "Fifth entry", "Heading 2");
insertNewPageWithHeading(builder, "Sixth entry", "Heading 3");
// This entry will be omitted because "Heading 4" is outside of the "1-3" range we set earlier
insertNewPageWithHeading(builder, "Seventh entry", "Heading 4");
builder.endBookmark("MyBookmark");
builder.writeln("Paragraph text.");
// This entry will be omitted because it is outside the bookmark specified by the TOC
insertNewPageWithHeading(builder, "Eighth entry", "Heading 1");
Assert.assertEquals(" TOC \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w", field.getFieldCode());
field.updatePageNumbers();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TOC.docx");
}
/// <summary>
/// Start a new page and insert a paragraph of a specified style.
/// </summary>
@Test(enabled = false)
public void insertNewPageWithHeading(final DocumentBuilder builder, final String captionText, final String styleName) {
builder.insertBreak(BreakType.PAGE_BREAK);
String originalStyle = builder.getParagraphFormat().getStyleName();
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(styleName));
builder.writeln(captionText);
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(originalStyle));
}
getCaptionlessTableOfFiguresLabel/setCaptionlessTableOfFiguresLabel | |
public java.lang.String getCaptionlessTableOfFiguresLabel() / public void setCaptionlessTableOfFiguresLabel(java.lang.String value)
|
-
Gets or sets the name of the sequence identifier used when building a table of figures that does not include caption's
label and number.
getCustomStyles/setCustomStyles | |
public java.lang.String getCustomStyles() / public void setCustomStyles(java.lang.String value)
|
-
Gets or sets a list of styles other than the built-in heading styles to include in the table of contents.
Example:
Shows how to insert a TOC and populate it with entries based on heading styles.
public void fieldToc() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// The table of contents we will insert will accept entries that are only within the scope of this bookmark
builder.startBookmark("MyBookmark");
// Insert a list num field using a document builder
FieldToc field = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
// Limit possible TOC entries to only those within the bookmark we name here
field.setBookmarkName("MyBookmark");
// Normally paragraphs with a "Heading n" style will be the only ones that will be added to a TOC as entries
// We can set this attribute to include other styles, such as "Quote" and "Intense Quote" in this case
field.setCustomStyles("Quote; 6; Intense Quote; 7");
// Styles are normally separated by a comma (",") but we can use this property to set a custom delimiter
doc.getFieldOptions().setCustomTocStyleSeparator(";");
// Filter out any headings that are outside this range
field.setHeadingLevelRange("1-3");
// Headings in this range won't display their page number in their TOC entry
field.setPageNumberOmittingLevelRange("2-5");
field.setEntrySeparator("-");
field.setInsertHyperlinks(true);
field.setHideInWebLayout(false);
field.setPreserveLineBreaks(true);
field.setPreserveTabs(true);
field.setUseParagraphOutlineLevel(false);
insertNewPageWithHeading(builder, "First entry", "Heading 1");
builder.writeln("Paragraph text.");
insertNewPageWithHeading(builder, "Second entry", "Heading 1");
insertNewPageWithHeading(builder, "Third entry", "Quote");
insertNewPageWithHeading(builder, "Fourth entry", "Intense Quote");
// These two headings will have the page numbers omitted because they are within the "2-5" range
insertNewPageWithHeading(builder, "Fifth entry", "Heading 2");
insertNewPageWithHeading(builder, "Sixth entry", "Heading 3");
// This entry will be omitted because "Heading 4" is outside of the "1-3" range we set earlier
insertNewPageWithHeading(builder, "Seventh entry", "Heading 4");
builder.endBookmark("MyBookmark");
builder.writeln("Paragraph text.");
// This entry will be omitted because it is outside the bookmark specified by the TOC
insertNewPageWithHeading(builder, "Eighth entry", "Heading 1");
Assert.assertEquals(" TOC \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w", field.getFieldCode());
field.updatePageNumbers();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TOC.docx");
}
/// <summary>
/// Start a new page and insert a paragraph of a specified style.
/// </summary>
@Test(enabled = false)
public void insertNewPageWithHeading(final DocumentBuilder builder, final String captionText, final String styleName) {
builder.insertBreak(BreakType.PAGE_BREAK);
String originalStyle = builder.getParagraphFormat().getStyleName();
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(styleName));
builder.writeln(captionText);
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(originalStyle));
}
getDisplayResult | → inherited from Field |
public java.lang.String getDisplayResult()
|
-
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.
Example:
Shows how to get the text that represents the displayed field result.
Document document = new Document(getMyDir() + "Various fields.docx");
FieldCollection fields = document.getRange().getFields();
Assert.assertEquals("111", fields.get(0).getDisplayResult());
Assert.assertEquals("222", fields.get(1).getDisplayResult());
Assert.assertEquals("Multi\rLine\rText", fields.get(2).getDisplayResult());
Assert.assertEquals("%", fields.get(3).getDisplayResult());
Assert.assertEquals("Macro Button Text", fields.get(4).getDisplayResult());
Assert.assertEquals("", fields.get(5).getDisplayResult());
// Method must be called to obtain correct value for the "FieldListNum", "FieldAutoNum",
// "FieldAutoNumOut" and "FieldAutoNumLgl" fields
document.updateListLabels();
Assert.assertEquals("1)", fields.get(5).getDisplayResult());
-
Gets the node that represents the field end.
Example:
Shows how to work with a document's field collection.
public void fieldCollection() throws Exception {
// Create a new document and insert some fields
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertField(" DATE \\@ \"dddd, d MMMM yyyy\" ");
builder.insertField(" TIME ");
builder.insertField(" REVNUM ");
builder.insertField(" AUTHOR \"John Doe\" ");
builder.insertField(" SUBJECT \"My Subject\" ");
builder.insertField(" QUOTE \"Hello world!\" ");
doc.updateFields();
// Get the collection that contains all the fields in a document
FieldCollection fields = doc.getRange().getFields();
Assert.assertEquals(fields.getCount(), 6);
// Iterate over the field collection and print contents and type of every field using a custom visitor implementation
FieldVisitor fieldVisitor = new FieldVisitor();
Iterator<Field> fieldEnumerator = fields.iterator();
while (fieldEnumerator.hasNext()) {
if (fieldEnumerator.next() != null) {
Field currentField = fieldEnumerator.next();
currentField.getStart().accept(fieldVisitor);
if (currentField.getSeparator() != null) {
currentField.getSeparator().accept(fieldVisitor);
}
currentField.getEnd().accept(fieldVisitor);
} else {
System.out.println("There are no fields in the document.");
}
}
System.out.println(fieldVisitor.getText());
// Get a field to remove itself
fields.get(0).remove();
Assert.assertEquals(fields.getCount(), 5);
// Remove a field by reference
Field lastField = fields.get(3);
fields.remove(lastField);
Assert.assertEquals(fields.getCount(), 4);
// Remove a field by index
fields.removeAt(2);
Assert.assertEquals(fields.getCount(), 3);
// Remove all fields from the document
fields.clear();
Assert.assertEquals(fields.getCount(), 0);
}
/// <summary>
/// Document visitor implementation that prints field info.
/// </summary>
public static class FieldVisitor extends DocumentVisitor {
public FieldVisitor() {
mBuilder = new StringBuilder();
}
/// <summary>
/// Gets the plain text of the document that was accumulated by the visitor.
/// </summary>
public String getText() {
return mBuilder.toString();
}
/// <summary>
/// Called when a FieldStart node is encountered in the document.
/// </summary>
public int visitFieldStart(final FieldStart fieldStart) {
mBuilder.append("Found field: " + fieldStart.getFieldType() + "\r\n");
mBuilder.append("\tField code: " + fieldStart.getField().getFieldCode() + "\r\n");
mBuilder.append("\tDisplayed as: " + fieldStart.getField().getResult() + "\r\n");
return VisitorAction.CONTINUE;
}
/// <summary>
/// Called when a FieldSeparator node is encountered in the document.
/// </summary>
public int visitFieldSeparator(final FieldSeparator fieldSeparator) {
mBuilder.append("\tFound separator: " + fieldSeparator.getText() + "\r\n");
return VisitorAction.CONTINUE;
}
/// <summary>
/// Called when a FieldEnd node is encountered in the document.
/// </summary>
public int visitFieldEnd(final FieldEnd fieldEnd) {
mBuilder.append("End of field: " + fieldEnd.getFieldType() + "\r\n");
return VisitorAction.CONTINUE;
}
private StringBuilder mBuilder;
}
getEntryIdentifier/setEntryIdentifier | |
public java.lang.String getEntryIdentifier() / public void setEntryIdentifier(java.lang.String value)
|
-
Gets or sets a string that should match type identifiers of TC fields being included.
Example:
Shows how to insert a TOC field and filter which TC fields end up as entries.
public void fieldTocEntryIdentifier() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.startBookmark("MyBookmark");
// Insert a list num field using a document builder
FieldToc fieldToc = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
fieldToc.setEntryIdentifier("A");
fieldToc.setEntryLevelRange("1-3");
Assert.assertEquals(" TOC \\f A \\l 1-3", fieldToc.getFieldCode());
// These two entries will appear in the table
builder.insertBreak(BreakType.PAGE_BREAK);
insertTocEntry(builder, "TC field 1", "A", "1");
insertTocEntry(builder, "TC field 2", "A", "2");
Assert.assertEquals(" TC \"TC field 1\" \\n \\f A \\l 1", doc.getRange().getFields().get(1).getFieldCode());
// These two entries will be omitted because of an incorrect type identifier
insertTocEntry(builder, "TC field 3", "B", "1");
// ...and an out-of-range entry level
insertTocEntry(builder, "TC field 4", "A", "5");
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TC.docx");
}
/// <summary>
/// Insert a table of contents entry via a document builder.
/// </summary>
@Test(enabled = false)
public void insertTocEntry(final DocumentBuilder builder, final String text, final String typeIdentifier, final String entryLevel) throws Exception {
FieldTC fieldTc = (FieldTC) builder.insertField(FieldType.FIELD_TOC_ENTRY, true);
fieldTc.setOmitPageNumber(true);
fieldTc.setText(text);
fieldTc.setTypeIdentifier(typeIdentifier);
fieldTc.setEntryLevel(entryLevel);
}
getEntryLevelRange/setEntryLevelRange | |
public java.lang.String getEntryLevelRange() / public void setEntryLevelRange(java.lang.String value)
|
-
Gets or sets a range of levels of the table of contents entries to be included.
Example:
Shows how to insert a TOC field and filter which TC fields end up as entries.
public void fieldTocEntryIdentifier() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.startBookmark("MyBookmark");
// Insert a list num field using a document builder
FieldToc fieldToc = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
fieldToc.setEntryIdentifier("A");
fieldToc.setEntryLevelRange("1-3");
Assert.assertEquals(" TOC \\f A \\l 1-3", fieldToc.getFieldCode());
// These two entries will appear in the table
builder.insertBreak(BreakType.PAGE_BREAK);
insertTocEntry(builder, "TC field 1", "A", "1");
insertTocEntry(builder, "TC field 2", "A", "2");
Assert.assertEquals(" TC \"TC field 1\" \\n \\f A \\l 1", doc.getRange().getFields().get(1).getFieldCode());
// These two entries will be omitted because of an incorrect type identifier
insertTocEntry(builder, "TC field 3", "B", "1");
// ...and an out-of-range entry level
insertTocEntry(builder, "TC field 4", "A", "5");
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TC.docx");
}
/// <summary>
/// Insert a table of contents entry via a document builder.
/// </summary>
@Test(enabled = false)
public void insertTocEntry(final DocumentBuilder builder, final String text, final String typeIdentifier, final String entryLevel) throws Exception {
FieldTC fieldTc = (FieldTC) builder.insertField(FieldType.FIELD_TOC_ENTRY, true);
fieldTc.setOmitPageNumber(true);
fieldTc.setText(text);
fieldTc.setTypeIdentifier(typeIdentifier);
fieldTc.setEntryLevel(entryLevel);
}
getEntrySeparator/setEntrySeparator | |
public java.lang.String getEntrySeparator() / public void setEntrySeparator(java.lang.String value)
|
-
Gets or sets a sequence of characters that separate an entry and its page number.
Example:
Shows how to insert a TOC and populate it with entries based on heading styles.
public void fieldToc() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// The table of contents we will insert will accept entries that are only within the scope of this bookmark
builder.startBookmark("MyBookmark");
// Insert a list num field using a document builder
FieldToc field = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
// Limit possible TOC entries to only those within the bookmark we name here
field.setBookmarkName("MyBookmark");
// Normally paragraphs with a "Heading n" style will be the only ones that will be added to a TOC as entries
// We can set this attribute to include other styles, such as "Quote" and "Intense Quote" in this case
field.setCustomStyles("Quote; 6; Intense Quote; 7");
// Styles are normally separated by a comma (",") but we can use this property to set a custom delimiter
doc.getFieldOptions().setCustomTocStyleSeparator(";");
// Filter out any headings that are outside this range
field.setHeadingLevelRange("1-3");
// Headings in this range won't display their page number in their TOC entry
field.setPageNumberOmittingLevelRange("2-5");
field.setEntrySeparator("-");
field.setInsertHyperlinks(true);
field.setHideInWebLayout(false);
field.setPreserveLineBreaks(true);
field.setPreserveTabs(true);
field.setUseParagraphOutlineLevel(false);
insertNewPageWithHeading(builder, "First entry", "Heading 1");
builder.writeln("Paragraph text.");
insertNewPageWithHeading(builder, "Second entry", "Heading 1");
insertNewPageWithHeading(builder, "Third entry", "Quote");
insertNewPageWithHeading(builder, "Fourth entry", "Intense Quote");
// These two headings will have the page numbers omitted because they are within the "2-5" range
insertNewPageWithHeading(builder, "Fifth entry", "Heading 2");
insertNewPageWithHeading(builder, "Sixth entry", "Heading 3");
// This entry will be omitted because "Heading 4" is outside of the "1-3" range we set earlier
insertNewPageWithHeading(builder, "Seventh entry", "Heading 4");
builder.endBookmark("MyBookmark");
builder.writeln("Paragraph text.");
// This entry will be omitted because it is outside the bookmark specified by the TOC
insertNewPageWithHeading(builder, "Eighth entry", "Heading 1");
Assert.assertEquals(" TOC \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w", field.getFieldCode());
field.updatePageNumbers();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TOC.docx");
}
/// <summary>
/// Start a new page and insert a paragraph of a specified style.
/// </summary>
@Test(enabled = false)
public void insertNewPageWithHeading(final DocumentBuilder builder, final String captionText, final String styleName) {
builder.insertBreak(BreakType.PAGE_BREAK);
String originalStyle = builder.getParagraphFormat().getStyleName();
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(styleName));
builder.writeln(captionText);
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(originalStyle));
}
-
Gets a FieldFormat object that provides typed access to field's formatting.
Example:
Shows how to format fields.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Use a document builder to insert field with no format
Field field = builder.insertField("= 2 + 3");
// We can format our field here instead of in the field code
FieldFormat format = field.getFormat();
format.setNumericFormat("$###.00");
field.update();
Assert.assertEquals("$ 5.00", field.getResult());
// Apply a date/time format
field = builder.insertField("DATE");
format = field.getFormat();
format.setDateTimeFormat("dddd, MMMM dd, yyyy");
field.update();
System.out.println("Today's date, in {format.DateTimeFormat} format:\n\t{field.Result}");
// Apply 2 general formats at the same time
field = builder.insertField("= 25 + 33");
format = field.getFormat();
format.getGeneralFormats().add(GeneralFormat.LOWERCASE_ROMAN);
format.getGeneralFormats().add(GeneralFormat.UPPER);
field.update();
int index = 0;
Iterator<Integer> generalFormatEnumerator = format.getGeneralFormats().iterator();
while (generalFormatEnumerator.hasNext()) {
System.out.println(MessageFormat.format("General format index {0}: {1}", index++, generalFormatEnumerator.toString()));
}
Assert.assertEquals("LVIII", field.getResult());
Assert.assertEquals(2, format.getGeneralFormats().getCount());
Assert.assertEquals(format.getGeneralFormats().get(0), GeneralFormat.LOWERCASE_ROMAN);
// Removing field formats
format.getGeneralFormats().remove(GeneralFormat.LOWERCASE_ROMAN);
format.getGeneralFormats().removeAt(0);
Assert.assertEquals(format.getGeneralFormats().getCount(), 0);
field.update();
// Our field has no general formats left and is back to default form
Assert.assertEquals(field.getResult(), "58");
getHeadingLevelRange/setHeadingLevelRange | |
public java.lang.String getHeadingLevelRange() / public void setHeadingLevelRange(java.lang.String value)
|
-
Gets or sets a range of heading levels to include.
Example:
Shows how to insert a TOC and populate it with entries based on heading styles.
public void fieldToc() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// The table of contents we will insert will accept entries that are only within the scope of this bookmark
builder.startBookmark("MyBookmark");
// Insert a list num field using a document builder
FieldToc field = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
// Limit possible TOC entries to only those within the bookmark we name here
field.setBookmarkName("MyBookmark");
// Normally paragraphs with a "Heading n" style will be the only ones that will be added to a TOC as entries
// We can set this attribute to include other styles, such as "Quote" and "Intense Quote" in this case
field.setCustomStyles("Quote; 6; Intense Quote; 7");
// Styles are normally separated by a comma (",") but we can use this property to set a custom delimiter
doc.getFieldOptions().setCustomTocStyleSeparator(";");
// Filter out any headings that are outside this range
field.setHeadingLevelRange("1-3");
// Headings in this range won't display their page number in their TOC entry
field.setPageNumberOmittingLevelRange("2-5");
field.setEntrySeparator("-");
field.setInsertHyperlinks(true);
field.setHideInWebLayout(false);
field.setPreserveLineBreaks(true);
field.setPreserveTabs(true);
field.setUseParagraphOutlineLevel(false);
insertNewPageWithHeading(builder, "First entry", "Heading 1");
builder.writeln("Paragraph text.");
insertNewPageWithHeading(builder, "Second entry", "Heading 1");
insertNewPageWithHeading(builder, "Third entry", "Quote");
insertNewPageWithHeading(builder, "Fourth entry", "Intense Quote");
// These two headings will have the page numbers omitted because they are within the "2-5" range
insertNewPageWithHeading(builder, "Fifth entry", "Heading 2");
insertNewPageWithHeading(builder, "Sixth entry", "Heading 3");
// This entry will be omitted because "Heading 4" is outside of the "1-3" range we set earlier
insertNewPageWithHeading(builder, "Seventh entry", "Heading 4");
builder.endBookmark("MyBookmark");
builder.writeln("Paragraph text.");
// This entry will be omitted because it is outside the bookmark specified by the TOC
insertNewPageWithHeading(builder, "Eighth entry", "Heading 1");
Assert.assertEquals(" TOC \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w", field.getFieldCode());
field.updatePageNumbers();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TOC.docx");
}
/// <summary>
/// Start a new page and insert a paragraph of a specified style.
/// </summary>
@Test(enabled = false)
public void insertNewPageWithHeading(final DocumentBuilder builder, final String captionText, final String styleName) {
builder.insertBreak(BreakType.PAGE_BREAK);
String originalStyle = builder.getParagraphFormat().getStyleName();
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(styleName));
builder.writeln(captionText);
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(originalStyle));
}
getHideInWebLayout/setHideInWebLayout | |
public boolean getHideInWebLayout() / public void setHideInWebLayout(boolean value)
|
-
Gets or sets whether to hide tab leader and page numbers in Web layout view.
Example:
Shows how to insert a TOC and populate it with entries based on heading styles.
public void fieldToc() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// The table of contents we will insert will accept entries that are only within the scope of this bookmark
builder.startBookmark("MyBookmark");
// Insert a list num field using a document builder
FieldToc field = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
// Limit possible TOC entries to only those within the bookmark we name here
field.setBookmarkName("MyBookmark");
// Normally paragraphs with a "Heading n" style will be the only ones that will be added to a TOC as entries
// We can set this attribute to include other styles, such as "Quote" and "Intense Quote" in this case
field.setCustomStyles("Quote; 6; Intense Quote; 7");
// Styles are normally separated by a comma (",") but we can use this property to set a custom delimiter
doc.getFieldOptions().setCustomTocStyleSeparator(";");
// Filter out any headings that are outside this range
field.setHeadingLevelRange("1-3");
// Headings in this range won't display their page number in their TOC entry
field.setPageNumberOmittingLevelRange("2-5");
field.setEntrySeparator("-");
field.setInsertHyperlinks(true);
field.setHideInWebLayout(false);
field.setPreserveLineBreaks(true);
field.setPreserveTabs(true);
field.setUseParagraphOutlineLevel(false);
insertNewPageWithHeading(builder, "First entry", "Heading 1");
builder.writeln("Paragraph text.");
insertNewPageWithHeading(builder, "Second entry", "Heading 1");
insertNewPageWithHeading(builder, "Third entry", "Quote");
insertNewPageWithHeading(builder, "Fourth entry", "Intense Quote");
// These two headings will have the page numbers omitted because they are within the "2-5" range
insertNewPageWithHeading(builder, "Fifth entry", "Heading 2");
insertNewPageWithHeading(builder, "Sixth entry", "Heading 3");
// This entry will be omitted because "Heading 4" is outside of the "1-3" range we set earlier
insertNewPageWithHeading(builder, "Seventh entry", "Heading 4");
builder.endBookmark("MyBookmark");
builder.writeln("Paragraph text.");
// This entry will be omitted because it is outside the bookmark specified by the TOC
insertNewPageWithHeading(builder, "Eighth entry", "Heading 1");
Assert.assertEquals(" TOC \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w", field.getFieldCode());
field.updatePageNumbers();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TOC.docx");
}
/// <summary>
/// Start a new page and insert a paragraph of a specified style.
/// </summary>
@Test(enabled = false)
public void insertNewPageWithHeading(final DocumentBuilder builder, final String captionText, final String styleName) {
builder.insertBreak(BreakType.PAGE_BREAK);
String originalStyle = builder.getParagraphFormat().getStyleName();
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(styleName));
builder.writeln(captionText);
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(originalStyle));
}
getInsertHyperlinks/setInsertHyperlinks | |
public boolean getInsertHyperlinks() / public void setInsertHyperlinks(boolean value)
|
-
Gets or sets whether to make the table of contents entries hyperlinks.
Example:
Shows how to insert a TOC and populate it with entries based on heading styles.
public void fieldToc() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// The table of contents we will insert will accept entries that are only within the scope of this bookmark
builder.startBookmark("MyBookmark");
// Insert a list num field using a document builder
FieldToc field = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
// Limit possible TOC entries to only those within the bookmark we name here
field.setBookmarkName("MyBookmark");
// Normally paragraphs with a "Heading n" style will be the only ones that will be added to a TOC as entries
// We can set this attribute to include other styles, such as "Quote" and "Intense Quote" in this case
field.setCustomStyles("Quote; 6; Intense Quote; 7");
// Styles are normally separated by a comma (",") but we can use this property to set a custom delimiter
doc.getFieldOptions().setCustomTocStyleSeparator(";");
// Filter out any headings that are outside this range
field.setHeadingLevelRange("1-3");
// Headings in this range won't display their page number in their TOC entry
field.setPageNumberOmittingLevelRange("2-5");
field.setEntrySeparator("-");
field.setInsertHyperlinks(true);
field.setHideInWebLayout(false);
field.setPreserveLineBreaks(true);
field.setPreserveTabs(true);
field.setUseParagraphOutlineLevel(false);
insertNewPageWithHeading(builder, "First entry", "Heading 1");
builder.writeln("Paragraph text.");
insertNewPageWithHeading(builder, "Second entry", "Heading 1");
insertNewPageWithHeading(builder, "Third entry", "Quote");
insertNewPageWithHeading(builder, "Fourth entry", "Intense Quote");
// These two headings will have the page numbers omitted because they are within the "2-5" range
insertNewPageWithHeading(builder, "Fifth entry", "Heading 2");
insertNewPageWithHeading(builder, "Sixth entry", "Heading 3");
// This entry will be omitted because "Heading 4" is outside of the "1-3" range we set earlier
insertNewPageWithHeading(builder, "Seventh entry", "Heading 4");
builder.endBookmark("MyBookmark");
builder.writeln("Paragraph text.");
// This entry will be omitted because it is outside the bookmark specified by the TOC
insertNewPageWithHeading(builder, "Eighth entry", "Heading 1");
Assert.assertEquals(" TOC \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w", field.getFieldCode());
field.updatePageNumbers();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TOC.docx");
}
/// <summary>
/// Start a new page and insert a paragraph of a specified style.
/// </summary>
@Test(enabled = false)
public void insertNewPageWithHeading(final DocumentBuilder builder, final String captionText, final String styleName) {
builder.insertBreak(BreakType.PAGE_BREAK);
String originalStyle = builder.getParagraphFormat().getStyleName();
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(styleName));
builder.writeln(captionText);
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(originalStyle));
}
isDirty/isDirty | → inherited from Field |
public boolean isDirty() / public void isDirty(boolean value)
|
-
Gets or sets whether the current result of the field is no longer correct (stale) due to other modifications made to the document.
Example:
Shows how to use special property for updating field result.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Give the document's built in property "Author" a value and display it with a field
doc.getBuiltInDocumentProperties().setAuthor("John Doe");
FieldAuthor field = (FieldAuthor) builder.insertField(FieldType.FIELD_AUTHOR, true);
Assert.assertFalse(field.isDirty());
Assert.assertEquals("John Doe", field.getResult());
// Update the "Author" property
doc.getBuiltInDocumentProperties().setAuthor("John & Jane Doe");
// AUTHOR is one of the field types whose fields do not update according to their source values in real time,
// and need to be updated manually beforehand every time an accurate value is required
Assert.assertEquals("John Doe", field.getResult());
// Since the field's value is out of date, we can mark it as "Dirty"
field.isDirty(true);
OutputStream docStream = new FileOutputStream(getArtifactsDir() + "Filed.UpdateDirtyFields.docx");
try {
doc.save(docStream, SaveFormat.DOCX);
// Re-open the document from the stream while using a LoadOptions object to specify
// whether to update all fields marked as "Dirty" in the process, so they can display accurate values immediately
LoadOptions options = new LoadOptions();
options.setUpdateDirtyFields(doUpdateDirtyFields);
doc = new Document(String.valueOf(docStream), options);
Assert.assertEquals("John & Jane Doe", doc.getBuiltInDocumentProperties().getAuthor());
field = (FieldAuthor) doc.getRange().getFields().get(0);
if (doUpdateDirtyFields) {
Assert.assertEquals("John & Jane Doe", field.getResult());
Assert.assertFalse(field.isDirty());
} else {
Assert.assertEquals("John Doe", field.getResult());
Assert.assertTrue(field.isDirty());
}
} finally {
if (docStream != null) docStream.close();
}
isLocked/isLocked | → inherited from Field |
public boolean isLocked() / public void isLocked(boolean value)
|
-
Gets or sets whether the field is locked (should not recalculate its result).
Example:
Demonstrates how to retrieve the field class from an existing FieldStart node in the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
FieldDate field = (FieldDate) builder.insertField(FieldType.FIELD_DATE, true);
field.getFormat().setDateTimeFormat("dddd, MMMM dd, yyyy");
field.update();
FieldChar fieldStart = field.getStart();
Assert.assertEquals(FieldType.FIELD_DATE, fieldStart.getFieldType());
Assert.assertEquals(false, fieldStart.isDirty());
Assert.assertEquals(false, fieldStart.isLocked());
// Retrieve the facade object which represents the field in the document
field = (FieldDate) fieldStart.getField();
Assert.assertEquals(false, field.isLocked());
Assert.assertEquals(" DATE \\@ \"dddd, MMMM dd, yyyy\"", field.getFieldCode());
// This updates only this field in the document
field.update();
isPageNumberOmittingLevelRangeSpecified | |
@Deprecated
public boolean isPageNumberOmittingLevelRangeSpecified()
|
- Deprecated.
getLocaleId/setLocaleId | → inherited from Field |
public int getLocaleId() / public void setLocaleId(int value)
|
-
Gets or sets the LCID of the field.
Example:
Shows how to insert a field and work with its locale.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a DATE field and print the date it will display, formatted according to your thread's current culture
Field field = builder.insertField("DATE");
System.out.println(MessageFormat.format("Today's date, as displayed in the \"{0}\" culture: {1}", Locale.getDefault().getDisplayName(), field.getResult()));
Assert.assertEquals(1033, field.getLocaleId());
// We can get the field to display a date in a different format if we change the current thread's culture
// If we want to avoid making such an all encompassing change,
// we can set this option to get the document's fields to get their culture from themselves
// Then, we can change a field's LocaleId and it will display its result in any culture we choose
doc.getFieldOptions().setFieldUpdateCultureSource(FieldUpdateCultureSource.FIELD_CODE);
field.setLocaleId(1031);
field.update();
System.out.println(MessageFormat.format("Today's date, as displayed according to the \"{0}\" culture: {1}", field.getLocaleId(), field.getResult()));
- See Also:
- FieldUpdateCultureSource.FIELD_CODE
getPageNumberOmittingLevelRange/setPageNumberOmittingLevelRange | |
public java.lang.String getPageNumberOmittingLevelRange() / public void setPageNumberOmittingLevelRange(java.lang.String value)
|
-
Gets or sets a range of levels of the table of contents entries from which to omits page numbers.
Example:
Shows how to insert a TOC and populate it with entries based on heading styles.
public void fieldToc() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// The table of contents we will insert will accept entries that are only within the scope of this bookmark
builder.startBookmark("MyBookmark");
// Insert a list num field using a document builder
FieldToc field = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
// Limit possible TOC entries to only those within the bookmark we name here
field.setBookmarkName("MyBookmark");
// Normally paragraphs with a "Heading n" style will be the only ones that will be added to a TOC as entries
// We can set this attribute to include other styles, such as "Quote" and "Intense Quote" in this case
field.setCustomStyles("Quote; 6; Intense Quote; 7");
// Styles are normally separated by a comma (",") but we can use this property to set a custom delimiter
doc.getFieldOptions().setCustomTocStyleSeparator(";");
// Filter out any headings that are outside this range
field.setHeadingLevelRange("1-3");
// Headings in this range won't display their page number in their TOC entry
field.setPageNumberOmittingLevelRange("2-5");
field.setEntrySeparator("-");
field.setInsertHyperlinks(true);
field.setHideInWebLayout(false);
field.setPreserveLineBreaks(true);
field.setPreserveTabs(true);
field.setUseParagraphOutlineLevel(false);
insertNewPageWithHeading(builder, "First entry", "Heading 1");
builder.writeln("Paragraph text.");
insertNewPageWithHeading(builder, "Second entry", "Heading 1");
insertNewPageWithHeading(builder, "Third entry", "Quote");
insertNewPageWithHeading(builder, "Fourth entry", "Intense Quote");
// These two headings will have the page numbers omitted because they are within the "2-5" range
insertNewPageWithHeading(builder, "Fifth entry", "Heading 2");
insertNewPageWithHeading(builder, "Sixth entry", "Heading 3");
// This entry will be omitted because "Heading 4" is outside of the "1-3" range we set earlier
insertNewPageWithHeading(builder, "Seventh entry", "Heading 4");
builder.endBookmark("MyBookmark");
builder.writeln("Paragraph text.");
// This entry will be omitted because it is outside the bookmark specified by the TOC
insertNewPageWithHeading(builder, "Eighth entry", "Heading 1");
Assert.assertEquals(" TOC \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w", field.getFieldCode());
field.updatePageNumbers();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TOC.docx");
}
/// <summary>
/// Start a new page and insert a paragraph of a specified style.
/// </summary>
@Test(enabled = false)
public void insertNewPageWithHeading(final DocumentBuilder builder, final String captionText, final String styleName) {
builder.insertBreak(BreakType.PAGE_BREAK);
String originalStyle = builder.getParagraphFormat().getStyleName();
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(styleName));
builder.writeln(captionText);
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(originalStyle));
}
getPrefixedSequenceIdentifier/setPrefixedSequenceIdentifier | |
public java.lang.String getPrefixedSequenceIdentifier() / public void setPrefixedSequenceIdentifier(java.lang.String value)
|
-
Gets or sets the identifier of a sequence for which a prefix should be added to the entry's page number.
Example:
Shows how to populate a TOC field with entries using SEQ fields.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a TOC field that creates a table of contents entry for each paragraph
// that contains a SEQ field with a sequence identifier of "MySequence" with the number of the page which contains that field
FieldToc fieldToc = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
fieldToc.setTableOfFiguresLabel("MySequence");
// This identifier is for a parallel SEQ sequence,
// the number that it is at will be displayed in front of the page number of the paragraph with the other sequence,
// separated by a sequence separator character also defined below
fieldToc.setPrefixedSequenceIdentifier("PrefixSequence");
fieldToc.setSequenceSeparator(">");
Assert.assertEquals(" TOC \\c MySequence \\s PrefixSequence \\d >", fieldToc.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
// Insert a SEQ field to increment the sequence counter of "PrefixSequence" to 1
// Since this paragraph doesn't contain a SEQ field of the "MySequence" sequence,
// this will not appear as an entry in the TOC
FieldSeq fieldSeq = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
fieldSeq.setSequenceIdentifier("PrefixSequence");
builder.insertParagraph();
Assert.assertEquals(" SEQ PrefixSequence", fieldSeq.getFieldCode());
// Insert two SEQ fields, one for each of the sequences we defined above
// The "MySequence" SEQ appears on page 2 and the "PrefixSequence" is at number 1 in this paragraph,
// which means that our TOC will display this as an entry with the contents on the left and "1>2" on the right
builder.write("First TOC entry, MySequence #");
fieldSeq = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
fieldSeq.setSequenceIdentifier("MySequence");
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TOC.SEQ.docx");
getPreserveLineBreaks/setPreserveLineBreaks | |
public boolean getPreserveLineBreaks() / public void setPreserveLineBreaks(boolean value)
|
-
Gets or sets whether to preserve newline characters within table entries.
Example:
Shows how to insert a TOC and populate it with entries based on heading styles.
public void fieldToc() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// The table of contents we will insert will accept entries that are only within the scope of this bookmark
builder.startBookmark("MyBookmark");
// Insert a list num field using a document builder
FieldToc field = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
// Limit possible TOC entries to only those within the bookmark we name here
field.setBookmarkName("MyBookmark");
// Normally paragraphs with a "Heading n" style will be the only ones that will be added to a TOC as entries
// We can set this attribute to include other styles, such as "Quote" and "Intense Quote" in this case
field.setCustomStyles("Quote; 6; Intense Quote; 7");
// Styles are normally separated by a comma (",") but we can use this property to set a custom delimiter
doc.getFieldOptions().setCustomTocStyleSeparator(";");
// Filter out any headings that are outside this range
field.setHeadingLevelRange("1-3");
// Headings in this range won't display their page number in their TOC entry
field.setPageNumberOmittingLevelRange("2-5");
field.setEntrySeparator("-");
field.setInsertHyperlinks(true);
field.setHideInWebLayout(false);
field.setPreserveLineBreaks(true);
field.setPreserveTabs(true);
field.setUseParagraphOutlineLevel(false);
insertNewPageWithHeading(builder, "First entry", "Heading 1");
builder.writeln("Paragraph text.");
insertNewPageWithHeading(builder, "Second entry", "Heading 1");
insertNewPageWithHeading(builder, "Third entry", "Quote");
insertNewPageWithHeading(builder, "Fourth entry", "Intense Quote");
// These two headings will have the page numbers omitted because they are within the "2-5" range
insertNewPageWithHeading(builder, "Fifth entry", "Heading 2");
insertNewPageWithHeading(builder, "Sixth entry", "Heading 3");
// This entry will be omitted because "Heading 4" is outside of the "1-3" range we set earlier
insertNewPageWithHeading(builder, "Seventh entry", "Heading 4");
builder.endBookmark("MyBookmark");
builder.writeln("Paragraph text.");
// This entry will be omitted because it is outside the bookmark specified by the TOC
insertNewPageWithHeading(builder, "Eighth entry", "Heading 1");
Assert.assertEquals(" TOC \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w", field.getFieldCode());
field.updatePageNumbers();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TOC.docx");
}
/// <summary>
/// Start a new page and insert a paragraph of a specified style.
/// </summary>
@Test(enabled = false)
public void insertNewPageWithHeading(final DocumentBuilder builder, final String captionText, final String styleName) {
builder.insertBreak(BreakType.PAGE_BREAK);
String originalStyle = builder.getParagraphFormat().getStyleName();
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(styleName));
builder.writeln(captionText);
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(originalStyle));
}
getPreserveTabs/setPreserveTabs | |
public boolean getPreserveTabs() / public void setPreserveTabs(boolean value)
|
-
Gets or sets whether to preserve tab entries within table entries.
Example:
Shows how to insert a TOC and populate it with entries based on heading styles.
public void fieldToc() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// The table of contents we will insert will accept entries that are only within the scope of this bookmark
builder.startBookmark("MyBookmark");
// Insert a list num field using a document builder
FieldToc field = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
// Limit possible TOC entries to only those within the bookmark we name here
field.setBookmarkName("MyBookmark");
// Normally paragraphs with a "Heading n" style will be the only ones that will be added to a TOC as entries
// We can set this attribute to include other styles, such as "Quote" and "Intense Quote" in this case
field.setCustomStyles("Quote; 6; Intense Quote; 7");
// Styles are normally separated by a comma (",") but we can use this property to set a custom delimiter
doc.getFieldOptions().setCustomTocStyleSeparator(";");
// Filter out any headings that are outside this range
field.setHeadingLevelRange("1-3");
// Headings in this range won't display their page number in their TOC entry
field.setPageNumberOmittingLevelRange("2-5");
field.setEntrySeparator("-");
field.setInsertHyperlinks(true);
field.setHideInWebLayout(false);
field.setPreserveLineBreaks(true);
field.setPreserveTabs(true);
field.setUseParagraphOutlineLevel(false);
insertNewPageWithHeading(builder, "First entry", "Heading 1");
builder.writeln("Paragraph text.");
insertNewPageWithHeading(builder, "Second entry", "Heading 1");
insertNewPageWithHeading(builder, "Third entry", "Quote");
insertNewPageWithHeading(builder, "Fourth entry", "Intense Quote");
// These two headings will have the page numbers omitted because they are within the "2-5" range
insertNewPageWithHeading(builder, "Fifth entry", "Heading 2");
insertNewPageWithHeading(builder, "Sixth entry", "Heading 3");
// This entry will be omitted because "Heading 4" is outside of the "1-3" range we set earlier
insertNewPageWithHeading(builder, "Seventh entry", "Heading 4");
builder.endBookmark("MyBookmark");
builder.writeln("Paragraph text.");
// This entry will be omitted because it is outside the bookmark specified by the TOC
insertNewPageWithHeading(builder, "Eighth entry", "Heading 1");
Assert.assertEquals(" TOC \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w", field.getFieldCode());
field.updatePageNumbers();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TOC.docx");
}
/// <summary>
/// Start a new page and insert a paragraph of a specified style.
/// </summary>
@Test(enabled = false)
public void insertNewPageWithHeading(final DocumentBuilder builder, final String captionText, final String styleName) {
builder.insertBreak(BreakType.PAGE_BREAK);
String originalStyle = builder.getParagraphFormat().getStyleName();
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(styleName));
builder.writeln(captionText);
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(originalStyle));
}
getResult/setResult | → inherited from Field |
public java.lang.String getResult() / public void setResult(java.lang.String value)
|
-
Gets or sets text that is between the field separator and field end.
Example:
Shows how to insert a field into a document by FieldCode.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a simple Date field into the document
// When we insert a field through the DocumentBuilder class we can get the
// special Field object which contains information about the field
Field dateField = builder.insertField("DATE \\* MERGEFORMAT");
// Update this particular field in the document so we can get the FieldResult
dateField.update();
// Display some information from this field
// The field result is where the last evaluated value is stored. This is what is displayed in the document
// When field codes are not showing
Assert.assertEquals(LocalDate.now().format(DateTimeFormatter.ofPattern("M/d/YYYY")), dateField.getResult());
// Display the field code which defines the behavior of the field. This can been seen in Microsoft Word by pressing ALT+F9
Assert.assertEquals("DATE \\* MERGEFORMAT", dateField.getFieldCode());
// The field type defines what type of field in the Document this is. In this case the type is "FieldDate"
Assert.assertEquals(FieldType.FIELD_DATE, dateField.getType());
// Finally let's completely remove the field from the document. This can easily be done by invoking the Remove method on the object
dateField.remove();
-
Gets the node that represents the field separator. Can be null.
Example:
Shows how to work with a document's field collection.
public void fieldCollection() throws Exception {
// Create a new document and insert some fields
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertField(" DATE \\@ \"dddd, d MMMM yyyy\" ");
builder.insertField(" TIME ");
builder.insertField(" REVNUM ");
builder.insertField(" AUTHOR \"John Doe\" ");
builder.insertField(" SUBJECT \"My Subject\" ");
builder.insertField(" QUOTE \"Hello world!\" ");
doc.updateFields();
// Get the collection that contains all the fields in a document
FieldCollection fields = doc.getRange().getFields();
Assert.assertEquals(fields.getCount(), 6);
// Iterate over the field collection and print contents and type of every field using a custom visitor implementation
FieldVisitor fieldVisitor = new FieldVisitor();
Iterator<Field> fieldEnumerator = fields.iterator();
while (fieldEnumerator.hasNext()) {
if (fieldEnumerator.next() != null) {
Field currentField = fieldEnumerator.next();
currentField.getStart().accept(fieldVisitor);
if (currentField.getSeparator() != null) {
currentField.getSeparator().accept(fieldVisitor);
}
currentField.getEnd().accept(fieldVisitor);
} else {
System.out.println("There are no fields in the document.");
}
}
System.out.println(fieldVisitor.getText());
// Get a field to remove itself
fields.get(0).remove();
Assert.assertEquals(fields.getCount(), 5);
// Remove a field by reference
Field lastField = fields.get(3);
fields.remove(lastField);
Assert.assertEquals(fields.getCount(), 4);
// Remove a field by index
fields.removeAt(2);
Assert.assertEquals(fields.getCount(), 3);
// Remove all fields from the document
fields.clear();
Assert.assertEquals(fields.getCount(), 0);
}
/// <summary>
/// Document visitor implementation that prints field info.
/// </summary>
public static class FieldVisitor extends DocumentVisitor {
public FieldVisitor() {
mBuilder = new StringBuilder();
}
/// <summary>
/// Gets the plain text of the document that was accumulated by the visitor.
/// </summary>
public String getText() {
return mBuilder.toString();
}
/// <summary>
/// Called when a FieldStart node is encountered in the document.
/// </summary>
public int visitFieldStart(final FieldStart fieldStart) {
mBuilder.append("Found field: " + fieldStart.getFieldType() + "\r\n");
mBuilder.append("\tField code: " + fieldStart.getField().getFieldCode() + "\r\n");
mBuilder.append("\tDisplayed as: " + fieldStart.getField().getResult() + "\r\n");
return VisitorAction.CONTINUE;
}
/// <summary>
/// Called when a FieldSeparator node is encountered in the document.
/// </summary>
public int visitFieldSeparator(final FieldSeparator fieldSeparator) {
mBuilder.append("\tFound separator: " + fieldSeparator.getText() + "\r\n");
return VisitorAction.CONTINUE;
}
/// <summary>
/// Called when a FieldEnd node is encountered in the document.
/// </summary>
public int visitFieldEnd(final FieldEnd fieldEnd) {
mBuilder.append("End of field: " + fieldEnd.getFieldType() + "\r\n");
return VisitorAction.CONTINUE;
}
private StringBuilder mBuilder;
}
getSequenceSeparator/setSequenceSeparator | |
public java.lang.String getSequenceSeparator() / public void setSequenceSeparator(java.lang.String value)
|
-
Gets or sets the character sequence that is used to separate sequence numbers and page numbers.
Example:
Shows how to populate a TOC field with entries using SEQ fields.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a TOC field that creates a table of contents entry for each paragraph
// that contains a SEQ field with a sequence identifier of "MySequence" with the number of the page which contains that field
FieldToc fieldToc = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
fieldToc.setTableOfFiguresLabel("MySequence");
// This identifier is for a parallel SEQ sequence,
// the number that it is at will be displayed in front of the page number of the paragraph with the other sequence,
// separated by a sequence separator character also defined below
fieldToc.setPrefixedSequenceIdentifier("PrefixSequence");
fieldToc.setSequenceSeparator(">");
Assert.assertEquals(" TOC \\c MySequence \\s PrefixSequence \\d >", fieldToc.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
// Insert a SEQ field to increment the sequence counter of "PrefixSequence" to 1
// Since this paragraph doesn't contain a SEQ field of the "MySequence" sequence,
// this will not appear as an entry in the TOC
FieldSeq fieldSeq = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
fieldSeq.setSequenceIdentifier("PrefixSequence");
builder.insertParagraph();
Assert.assertEquals(" SEQ PrefixSequence", fieldSeq.getFieldCode());
// Insert two SEQ fields, one for each of the sequences we defined above
// The "MySequence" SEQ appears on page 2 and the "PrefixSequence" is at number 1 in this paragraph,
// which means that our TOC will display this as an entry with the contents on the left and "1>2" on the right
builder.write("First TOC entry, MySequence #");
fieldSeq = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
fieldSeq.setSequenceIdentifier("MySequence");
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TOC.SEQ.docx");
-
Gets the node that represents the start of the field.
Example:
Shows how to work with a document's field collection.
public void fieldCollection() throws Exception {
// Create a new document and insert some fields
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertField(" DATE \\@ \"dddd, d MMMM yyyy\" ");
builder.insertField(" TIME ");
builder.insertField(" REVNUM ");
builder.insertField(" AUTHOR \"John Doe\" ");
builder.insertField(" SUBJECT \"My Subject\" ");
builder.insertField(" QUOTE \"Hello world!\" ");
doc.updateFields();
// Get the collection that contains all the fields in a document
FieldCollection fields = doc.getRange().getFields();
Assert.assertEquals(fields.getCount(), 6);
// Iterate over the field collection and print contents and type of every field using a custom visitor implementation
FieldVisitor fieldVisitor = new FieldVisitor();
Iterator<Field> fieldEnumerator = fields.iterator();
while (fieldEnumerator.hasNext()) {
if (fieldEnumerator.next() != null) {
Field currentField = fieldEnumerator.next();
currentField.getStart().accept(fieldVisitor);
if (currentField.getSeparator() != null) {
currentField.getSeparator().accept(fieldVisitor);
}
currentField.getEnd().accept(fieldVisitor);
} else {
System.out.println("There are no fields in the document.");
}
}
System.out.println(fieldVisitor.getText());
// Get a field to remove itself
fields.get(0).remove();
Assert.assertEquals(fields.getCount(), 5);
// Remove a field by reference
Field lastField = fields.get(3);
fields.remove(lastField);
Assert.assertEquals(fields.getCount(), 4);
// Remove a field by index
fields.removeAt(2);
Assert.assertEquals(fields.getCount(), 3);
// Remove all fields from the document
fields.clear();
Assert.assertEquals(fields.getCount(), 0);
}
/// <summary>
/// Document visitor implementation that prints field info.
/// </summary>
public static class FieldVisitor extends DocumentVisitor {
public FieldVisitor() {
mBuilder = new StringBuilder();
}
/// <summary>
/// Gets the plain text of the document that was accumulated by the visitor.
/// </summary>
public String getText() {
return mBuilder.toString();
}
/// <summary>
/// Called when a FieldStart node is encountered in the document.
/// </summary>
public int visitFieldStart(final FieldStart fieldStart) {
mBuilder.append("Found field: " + fieldStart.getFieldType() + "\r\n");
mBuilder.append("\tField code: " + fieldStart.getField().getFieldCode() + "\r\n");
mBuilder.append("\tDisplayed as: " + fieldStart.getField().getResult() + "\r\n");
return VisitorAction.CONTINUE;
}
/// <summary>
/// Called when a FieldSeparator node is encountered in the document.
/// </summary>
public int visitFieldSeparator(final FieldSeparator fieldSeparator) {
mBuilder.append("\tFound separator: " + fieldSeparator.getText() + "\r\n");
return VisitorAction.CONTINUE;
}
/// <summary>
/// Called when a FieldEnd node is encountered in the document.
/// </summary>
public int visitFieldEnd(final FieldEnd fieldEnd) {
mBuilder.append("End of field: " + fieldEnd.getFieldType() + "\r\n");
return VisitorAction.CONTINUE;
}
private StringBuilder mBuilder;
}
getTableOfFiguresLabel/setTableOfFiguresLabel | |
public java.lang.String getTableOfFiguresLabel() / public void setTableOfFiguresLabel(java.lang.String value)
|
-
Gets or sets the name of the sequence identifier used when building a table of figures.
Example:
Shows how to populate a TOC field with entries using SEQ fields.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a TOC field that creates a table of contents entry for each paragraph
// that contains a SEQ field with a sequence identifier of "MySequence" with the number of the page which contains that field
FieldToc fieldToc = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
fieldToc.setTableOfFiguresLabel("MySequence");
// This identifier is for a parallel SEQ sequence,
// the number that it is at will be displayed in front of the page number of the paragraph with the other sequence,
// separated by a sequence separator character also defined below
fieldToc.setPrefixedSequenceIdentifier("PrefixSequence");
fieldToc.setSequenceSeparator(">");
Assert.assertEquals(" TOC \\c MySequence \\s PrefixSequence \\d >", fieldToc.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
// Insert a SEQ field to increment the sequence counter of "PrefixSequence" to 1
// Since this paragraph doesn't contain a SEQ field of the "MySequence" sequence,
// this will not appear as an entry in the TOC
FieldSeq fieldSeq = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
fieldSeq.setSequenceIdentifier("PrefixSequence");
builder.insertParagraph();
Assert.assertEquals(" SEQ PrefixSequence", fieldSeq.getFieldCode());
// Insert two SEQ fields, one for each of the sequences we defined above
// The "MySequence" SEQ appears on page 2 and the "PrefixSequence" is at number 1 in this paragraph,
// which means that our TOC will display this as an entry with the contents on the left and "1>2" on the right
builder.write("First TOC entry, MySequence #");
fieldSeq = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
fieldSeq.setSequenceIdentifier("MySequence");
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TOC.SEQ.docx");
getType | → inherited from Field |
public int getType()
|
-
Gets the Microsoft Word field type.
The value of the property is FieldType integer constant.
Example:
Shows how to insert a field into a document by FieldCode.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a simple Date field into the document
// When we insert a field through the DocumentBuilder class we can get the
// special Field object which contains information about the field
Field dateField = builder.insertField("DATE \\* MERGEFORMAT");
// Update this particular field in the document so we can get the FieldResult
dateField.update();
// Display some information from this field
// The field result is where the last evaluated value is stored. This is what is displayed in the document
// When field codes are not showing
Assert.assertEquals(LocalDate.now().format(DateTimeFormatter.ofPattern("M/d/YYYY")), dateField.getResult());
// Display the field code which defines the behavior of the field. This can been seen in Microsoft Word by pressing ALT+F9
Assert.assertEquals("DATE \\* MERGEFORMAT", dateField.getFieldCode());
// The field type defines what type of field in the Document this is. In this case the type is "FieldDate"
Assert.assertEquals(FieldType.FIELD_DATE, dateField.getType());
// Finally let's completely remove the field from the document. This can easily be done by invoking the Remove method on the object
dateField.remove();
getUseParagraphOutlineLevel/setUseParagraphOutlineLevel | |
public boolean getUseParagraphOutlineLevel() / public void setUseParagraphOutlineLevel(boolean value)
|
-
Gets or sets whether to use the applied paragraph outline level.
Example:
Shows how to insert a TOC and populate it with entries based on heading styles.
public void fieldToc() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// The table of contents we will insert will accept entries that are only within the scope of this bookmark
builder.startBookmark("MyBookmark");
// Insert a list num field using a document builder
FieldToc field = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
// Limit possible TOC entries to only those within the bookmark we name here
field.setBookmarkName("MyBookmark");
// Normally paragraphs with a "Heading n" style will be the only ones that will be added to a TOC as entries
// We can set this attribute to include other styles, such as "Quote" and "Intense Quote" in this case
field.setCustomStyles("Quote; 6; Intense Quote; 7");
// Styles are normally separated by a comma (",") but we can use this property to set a custom delimiter
doc.getFieldOptions().setCustomTocStyleSeparator(";");
// Filter out any headings that are outside this range
field.setHeadingLevelRange("1-3");
// Headings in this range won't display their page number in their TOC entry
field.setPageNumberOmittingLevelRange("2-5");
field.setEntrySeparator("-");
field.setInsertHyperlinks(true);
field.setHideInWebLayout(false);
field.setPreserveLineBreaks(true);
field.setPreserveTabs(true);
field.setUseParagraphOutlineLevel(false);
insertNewPageWithHeading(builder, "First entry", "Heading 1");
builder.writeln("Paragraph text.");
insertNewPageWithHeading(builder, "Second entry", "Heading 1");
insertNewPageWithHeading(builder, "Third entry", "Quote");
insertNewPageWithHeading(builder, "Fourth entry", "Intense Quote");
// These two headings will have the page numbers omitted because they are within the "2-5" range
insertNewPageWithHeading(builder, "Fifth entry", "Heading 2");
insertNewPageWithHeading(builder, "Sixth entry", "Heading 3");
// This entry will be omitted because "Heading 4" is outside of the "1-3" range we set earlier
insertNewPageWithHeading(builder, "Seventh entry", "Heading 4");
builder.endBookmark("MyBookmark");
builder.writeln("Paragraph text.");
// This entry will be omitted because it is outside the bookmark specified by the TOC
insertNewPageWithHeading(builder, "Eighth entry", "Heading 1");
Assert.assertEquals(" TOC \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w", field.getFieldCode());
field.updatePageNumbers();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TOC.docx");
}
/// <summary>
/// Start a new page and insert a paragraph of a specified style.
/// </summary>
@Test(enabled = false)
public void insertNewPageWithHeading(final DocumentBuilder builder, final String captionText, final String styleName) {
builder.insertBreak(BreakType.PAGE_BREAK);
String originalStyle = builder.getParagraphFormat().getStyleName();
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(styleName));
builder.writeln(captionText);
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(originalStyle));
}
getFieldCode | → inherited from Field |
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.
Example:
Shows how to insert a field into a document by FieldCode.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a simple Date field into the document
// When we insert a field through the DocumentBuilder class we can get the
// special Field object which contains information about the field
Field dateField = builder.insertField("DATE \\* MERGEFORMAT");
// Update this particular field in the document so we can get the FieldResult
dateField.update();
// Display some information from this field
// The field result is where the last evaluated value is stored. This is what is displayed in the document
// When field codes are not showing
Assert.assertEquals(LocalDate.now().format(DateTimeFormatter.ofPattern("M/d/YYYY")), dateField.getResult());
// Display the field code which defines the behavior of the field. This can been seen in Microsoft Word by pressing ALT+F9
Assert.assertEquals("DATE \\* MERGEFORMAT", dateField.getFieldCode());
// The field type defines what type of field in the Document this is. In this case the type is "FieldDate"
Assert.assertEquals(FieldType.FIELD_DATE, dateField.getType());
// Finally let's completely remove the field from the document. This can easily be done by invoking the Remove method on the object
dateField.remove();
Example:
Shows how to get text between field start and field separator (or field end if there is no separator).
// Open a document which contains a MERGEFIELD inside an IF field
Document doc = new Document(getMyDir() + "Nested fields.docx");
// Get the outer IF field and print its full field code
FieldIf fieldIf = (FieldIf) doc.getRange().getFields().get(0);
System.out.println("Full field code including child fields:\n\t{fieldIf.GetFieldCode()}");
// All inner nested fields are printed by default
Assert.assertEquals(fieldIf.getFieldCode(), fieldIf.getFieldCode(true));
// Print the field code again but this time without the inner MERGEFIELD
System.out.println("Field code with nested fields omitted:\n\t{fieldIf.GetFieldCode(false)}");
getFieldCode | → inherited from Field |
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.
Example:
Shows how to get text between field start and field separator (or field end if there is no separator).
// Open a document which contains a MERGEFIELD inside an IF field
Document doc = new Document(getMyDir() + "Nested fields.docx");
// Get the outer IF field and print its full field code
FieldIf fieldIf = (FieldIf) doc.getRange().getFields().get(0);
System.out.println("Full field code including child fields:\n\t{fieldIf.GetFieldCode()}");
// All inner nested fields are printed by default
Assert.assertEquals(fieldIf.getFieldCode(), fieldIf.getFieldCode(true));
// Print the field code again but this time without the inner MERGEFIELD
System.out.println("Field code with nested fields omitted:\n\t{fieldIf.GetFieldCode(false)}");
remove | → inherited from Field |
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.
Example:
Shows how to work with a document's field collection.
public void fieldCollection() throws Exception {
// Create a new document and insert some fields
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertField(" DATE \\@ \"dddd, d MMMM yyyy\" ");
builder.insertField(" TIME ");
builder.insertField(" REVNUM ");
builder.insertField(" AUTHOR \"John Doe\" ");
builder.insertField(" SUBJECT \"My Subject\" ");
builder.insertField(" QUOTE \"Hello world!\" ");
doc.updateFields();
// Get the collection that contains all the fields in a document
FieldCollection fields = doc.getRange().getFields();
Assert.assertEquals(fields.getCount(), 6);
// Iterate over the field collection and print contents and type of every field using a custom visitor implementation
FieldVisitor fieldVisitor = new FieldVisitor();
Iterator<Field> fieldEnumerator = fields.iterator();
while (fieldEnumerator.hasNext()) {
if (fieldEnumerator.next() != null) {
Field currentField = fieldEnumerator.next();
currentField.getStart().accept(fieldVisitor);
if (currentField.getSeparator() != null) {
currentField.getSeparator().accept(fieldVisitor);
}
currentField.getEnd().accept(fieldVisitor);
} else {
System.out.println("There are no fields in the document.");
}
}
System.out.println(fieldVisitor.getText());
// Get a field to remove itself
fields.get(0).remove();
Assert.assertEquals(fields.getCount(), 5);
// Remove a field by reference
Field lastField = fields.get(3);
fields.remove(lastField);
Assert.assertEquals(fields.getCount(), 4);
// Remove a field by index
fields.removeAt(2);
Assert.assertEquals(fields.getCount(), 3);
// Remove all fields from the document
fields.clear();
Assert.assertEquals(fields.getCount(), 0);
}
/// <summary>
/// Document visitor implementation that prints field info.
/// </summary>
public static class FieldVisitor extends DocumentVisitor {
public FieldVisitor() {
mBuilder = new StringBuilder();
}
/// <summary>
/// Gets the plain text of the document that was accumulated by the visitor.
/// </summary>
public String getText() {
return mBuilder.toString();
}
/// <summary>
/// Called when a FieldStart node is encountered in the document.
/// </summary>
public int visitFieldStart(final FieldStart fieldStart) {
mBuilder.append("Found field: " + fieldStart.getFieldType() + "\r\n");
mBuilder.append("\tField code: " + fieldStart.getField().getFieldCode() + "\r\n");
mBuilder.append("\tDisplayed as: " + fieldStart.getField().getResult() + "\r\n");
return VisitorAction.CONTINUE;
}
/// <summary>
/// Called when a FieldSeparator node is encountered in the document.
/// </summary>
public int visitFieldSeparator(final FieldSeparator fieldSeparator) {
mBuilder.append("\tFound separator: " + fieldSeparator.getText() + "\r\n");
return VisitorAction.CONTINUE;
}
/// <summary>
/// Called when a FieldEnd node is encountered in the document.
/// </summary>
public int visitFieldEnd(final FieldEnd fieldEnd) {
mBuilder.append("End of field: " + fieldEnd.getFieldType() + "\r\n");
return VisitorAction.CONTINUE;
}
private StringBuilder mBuilder;
}
Example:
Shows how to insert a field into a document by FieldCode.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a simple Date field into the document
// When we insert a field through the DocumentBuilder class we can get the
// special Field object which contains information about the field
Field dateField = builder.insertField("DATE \\* MERGEFORMAT");
// Update this particular field in the document so we can get the FieldResult
dateField.update();
// Display some information from this field
// The field result is where the last evaluated value is stored. This is what is displayed in the document
// When field codes are not showing
Assert.assertEquals(LocalDate.now().format(DateTimeFormatter.ofPattern("M/d/YYYY")), dateField.getResult());
// Display the field code which defines the behavior of the field. This can been seen in Microsoft Word by pressing ALT+F9
Assert.assertEquals("DATE \\* MERGEFORMAT", dateField.getFieldCode());
// The field type defines what type of field in the Document this is. In this case the type is "FieldDate"
Assert.assertEquals(FieldType.FIELD_DATE, dateField.getType());
// Finally let's completely remove the field from the document. This can easily be done by invoking the Remove method on the object
dateField.remove();
unlink | → inherited from Field |
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
.
Example:
Shows how to unlink specific field.
Document doc = new Document(getMyDir() + "Linked fields.docx");
doc.getRange().getFields().get(1).unlink();
update | → inherited from Field |
public void update()
throws java.lang.Exception |
-
Performs the field update. Throws if the field is being updated already.
Example:
Shows how to insert a field into a document by FieldCode.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a simple Date field into the document
// When we insert a field through the DocumentBuilder class we can get the
// special Field object which contains information about the field
Field dateField = builder.insertField("DATE \\* MERGEFORMAT");
// Update this particular field in the document so we can get the FieldResult
dateField.update();
// Display some information from this field
// The field result is where the last evaluated value is stored. This is what is displayed in the document
// When field codes are not showing
Assert.assertEquals(LocalDate.now().format(DateTimeFormatter.ofPattern("M/d/YYYY")), dateField.getResult());
// Display the field code which defines the behavior of the field. This can been seen in Microsoft Word by pressing ALT+F9
Assert.assertEquals("DATE \\* MERGEFORMAT", dateField.getFieldCode());
// The field type defines what type of field in the Document this is. In this case the type is "FieldDate"
Assert.assertEquals(FieldType.FIELD_DATE, dateField.getType());
// Finally let's completely remove the field from the document. This can easily be done by invoking the Remove method on the object
dateField.remove();
update | → inherited from Field |
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.
Example:
Shows a way to update a field ignoring the MERGEFORMAT switch.
LoadOptions loadOptions = new LoadOptions();
{
loadOptions.setPreserveIncludePictureField(true);
}
Document doc = new Document(getMyDir() + "Field sample - INCLUDEPICTURE.docx", loadOptions);
for (Field field : doc.getRange().getFields()) {
if (((field.getType()) == (FieldType.FIELD_INCLUDE_PICTURE))) {
FieldIncludePicture includePicture = (FieldIncludePicture) field;
includePicture.setSourceFullName(getImageDir() + "Transparent background logo.png");
includePicture.update(true);
doc.updateFields();
doc.save(getArtifactsDir() + "Field.UpdateFieldIgnoringMergeFormat.docx");
updatePageNumbers | |
public boolean updatePageNumbers()
throws java.lang.Exception |
-
Updates the page numbers for items in this table of contents.
- Returns:
-
True if the operation is successful. If any of the related TOC bookmarks was removed, false will be returned.
Example:
Shows how to insert a TOC and populate it with entries based on heading styles.
public void fieldToc() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// The table of contents we will insert will accept entries that are only within the scope of this bookmark
builder.startBookmark("MyBookmark");
// Insert a list num field using a document builder
FieldToc field = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
// Limit possible TOC entries to only those within the bookmark we name here
field.setBookmarkName("MyBookmark");
// Normally paragraphs with a "Heading n" style will be the only ones that will be added to a TOC as entries
// We can set this attribute to include other styles, such as "Quote" and "Intense Quote" in this case
field.setCustomStyles("Quote; 6; Intense Quote; 7");
// Styles are normally separated by a comma (",") but we can use this property to set a custom delimiter
doc.getFieldOptions().setCustomTocStyleSeparator(";");
// Filter out any headings that are outside this range
field.setHeadingLevelRange("1-3");
// Headings in this range won't display their page number in their TOC entry
field.setPageNumberOmittingLevelRange("2-5");
field.setEntrySeparator("-");
field.setInsertHyperlinks(true);
field.setHideInWebLayout(false);
field.setPreserveLineBreaks(true);
field.setPreserveTabs(true);
field.setUseParagraphOutlineLevel(false);
insertNewPageWithHeading(builder, "First entry", "Heading 1");
builder.writeln("Paragraph text.");
insertNewPageWithHeading(builder, "Second entry", "Heading 1");
insertNewPageWithHeading(builder, "Third entry", "Quote");
insertNewPageWithHeading(builder, "Fourth entry", "Intense Quote");
// These two headings will have the page numbers omitted because they are within the "2-5" range
insertNewPageWithHeading(builder, "Fifth entry", "Heading 2");
insertNewPageWithHeading(builder, "Sixth entry", "Heading 3");
// This entry will be omitted because "Heading 4" is outside of the "1-3" range we set earlier
insertNewPageWithHeading(builder, "Seventh entry", "Heading 4");
builder.endBookmark("MyBookmark");
builder.writeln("Paragraph text.");
// This entry will be omitted because it is outside the bookmark specified by the TOC
insertNewPageWithHeading(builder, "Eighth entry", "Heading 1");
Assert.assertEquals(" TOC \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w", field.getFieldCode());
field.updatePageNumbers();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.TOC.docx");
}
/// <summary>
/// Start a new page and insert a paragraph of a specified style.
/// </summary>
@Test(enabled = false)
public void insertNewPageWithHeading(final DocumentBuilder builder, final String captionText, final String styleName) {
builder.insertBreak(BreakType.PAGE_BREAK);
String originalStyle = builder.getParagraphFormat().getStyleName();
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(styleName));
builder.writeln(captionText);
builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(originalStyle));
}
See Also:
Aspose.Words Documentation - the home page for the Aspose.Words Product Documentation.
Aspose.Words Support Forum - our preferred method of support.