public class FieldIndex extends Field
To learn more, visit the Working with Fields documentation article.
Remarks:
Builds an index using the index entries specified by XE fields, and inserts that index at this place in the document.
Examples:
Shows how to create an INDEX field, and then use XE fields to populate it with entries.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side
// and the page containing the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// Configure the INDEX field only to display XE fields that are within the bounds
// of a bookmark named "MainBookmark", and whose "EntryType" properties have a value of "A".
// For both INDEX and XE fields, the "EntryType" property only uses the first character of its string value.
index.setBookmarkName("MainBookmark");
index.setEntryType("A");
Assert.assertEquals(" INDEX \\b MainBookmark \\f A", index.getFieldCode());
// On a new page, start the bookmark with a name that matches the value
// of the INDEX field's "BookmarkName" property.
builder.insertBreak(BreakType.PAGE_BREAK);
builder.startBookmark("MainBookmark");
// The INDEX field will pick up this entry because it is inside the bookmark,
// and its entry type also matches the INDEX field's entry type.
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Index entry 1");
indexEntry.setEntryType("A");
Assert.assertEquals(" XE \"Index entry 1\" \\f A", indexEntry.getFieldCode());
// Insert an XE field that will not appear in the INDEX because the entry types do not match.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Index entry 2");
indexEntry.setEntryType("B");
// End the bookmark and insert an XE field afterwards.
// It is of the same type as the INDEX field, but will not appear
// since it is outside the bookmark's boundaries.
builder.endBookmark("MainBookmark");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Index entry 3");
indexEntry.setEntryType("A");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Filtering.docx");
Shows how to populate an INDEX field with entries using XE fields, and also modify its appearance.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
index.setLanguageId("1033");
// Setting this property's value to "A" will group all the entries by their first letter,
// and place that letter in uppercase above each group.
index.setHeading("A");
// Set the table created by the INDEX field to span over 2 columns.
index.setNumberOfColumns("2");
// Set any entries with starting letters outside the "a-c" character range to be omitted.
index.setLetterRange("a-c");
Assert.assertEquals(" INDEX \\z 1033 \\h A \\c 2 \\p a-c", index.getFieldCode());
// These next two XE fields will show up under the "A" heading,
// with their respective text stylings also applied to their page numbers.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apple");
indexEntry.isItalic(true);
Assert.assertEquals(" XE Apple \\i", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apricot");
indexEntry.isBold(true);
Assert.assertEquals(" XE Apricot \\b", indexEntry.getFieldCode());
// Both the next two XE fields will be under a "B" and "C" heading in the INDEX fields table of contents.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Banana");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cherry");
// INDEX fields sort all entries alphabetically, so this entry will show up under "A" with the other two.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Avocado");
// This entry will not appear because it starts with the letter "D",
// which is outside the "a-c" character range that the INDEX field's LetterRange property defines.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Durian");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Formatting.docx");
| Modifier and Type | Method and Description |
|---|---|
java.lang.String |
getBookmarkName()
Gets the name of the bookmark that marks the portion of the document used to build the index.
|
java.lang.String |
getCrossReferenceSeparator()
Gets the character sequence that is used to separate cross references and other entries.
|
java.lang.String |
getEntryType()
Gets an index entry type used to build the index.
|
java.lang.String |
getHeading()
Gets a heading that appears at the start of each set of entries for any given letter.
|
java.lang.String |
getLanguageId()
Gets the language ID used to generate the index.
|
java.lang.String |
getLetterRange()
Gets a range of letters to which limit the index.
|
java.lang.String |
getNumberOfColumns()
Gets the number of columns per page used when building the index.
|
java.lang.String |
getPageNumberListSeparator()
Gets the character sequence that is used to separate two page numbers in a page number list.
|
java.lang.String |
getPageNumberSeparator()
Gets the character sequence that is used to separate an index entry and its page number.
|
java.lang.String |
getPageRangeSeparator()
Gets the character sequence that is used to separate the start and end of a page range.
|
boolean |
getRunSubentriesOnSameLine()
Gets whether run subentries into the same line as the main entry.
|
java.lang.String |
getSequenceName()
Gets the name of a sequence whose number is included with the page number.
|
java.lang.String |
getSequenceSeparator()
Gets the character sequence that is used to separate sequence numbers and page numbers.
|
int |
getSwitchType(java.lang.String switchName) |
boolean |
getUseYomi()
Gets whether to enable the use of yomi text for index entries.
|
boolean |
hasPageNumberSeparator()
Gets a value indicating whether a page number separator is overridden through the field's code.
|
boolean |
hasSequenceName()
Gets a value indicating whether a sequence should be used while the field's result building.
|
void |
setBookmarkName(java.lang.String value)
Sets the name of the bookmark that marks the portion of the document used to build the index.
|
void |
setCrossReferenceSeparator(java.lang.String value)
Sets the character sequence that is used to separate cross references and other entries.
|
void |
setEntryType(java.lang.String value)
Sets an index entry type used to build the index.
|
void |
setHeading(java.lang.String value)
Sets a heading that appears at the start of each set of entries for any given letter.
|
void |
setLanguageId(java.lang.String value)
Sets the language ID used to generate the index.
|
void |
setLetterRange(java.lang.String value)
Sets a range of letters to which limit the index.
|
void |
setNumberOfColumns(java.lang.String value)
Sets the number of columns per page used when building the index.
|
void |
setPageNumberListSeparator(java.lang.String value)
Sets the character sequence that is used to separate two page numbers in a page number list.
|
void |
setPageNumberSeparator(java.lang.String value)
Sets the character sequence that is used to separate an index entry and its page number.
|
void |
setPageRangeSeparator(java.lang.String value)
Sets the character sequence that is used to separate the start and end of a page range.
|
void |
setRunSubentriesOnSameLine(boolean value)
Sets whether run subentries into the same line as the main entry.
|
void |
setSequenceName(java.lang.String value)
Sets the name of a sequence whose number is included with the page number.
|
void |
setSequenceSeparator(java.lang.String value)
Sets the character sequence that is used to separate sequence numbers and page numbers.
|
void |
setUseYomi(boolean value)
Sets whether to enable the use of yomi text for index entries.
|
getDisplayResult, getEnd, getFieldCode, getFieldCode, getFormat, getLocaleId, getResult, getSeparator, getStart, getType, isDirty, isDirty, isLocked, isLocked, needStoreOldResultNodes, remove, setLocaleId, setResult, unlink, update, updatepublic int getSwitchType(java.lang.String switchName)
public java.lang.String getBookmarkName()
Examples:
Shows how to create an INDEX field, and then use XE fields to populate it with entries.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side
// and the page containing the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// Configure the INDEX field only to display XE fields that are within the bounds
// of a bookmark named "MainBookmark", and whose "EntryType" properties have a value of "A".
// For both INDEX and XE fields, the "EntryType" property only uses the first character of its string value.
index.setBookmarkName("MainBookmark");
index.setEntryType("A");
Assert.assertEquals(" INDEX \\b MainBookmark \\f A", index.getFieldCode());
// On a new page, start the bookmark with a name that matches the value
// of the INDEX field's "BookmarkName" property.
builder.insertBreak(BreakType.PAGE_BREAK);
builder.startBookmark("MainBookmark");
// The INDEX field will pick up this entry because it is inside the bookmark,
// and its entry type also matches the INDEX field's entry type.
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Index entry 1");
indexEntry.setEntryType("A");
Assert.assertEquals(" XE \"Index entry 1\" \\f A", indexEntry.getFieldCode());
// Insert an XE field that will not appear in the INDEX because the entry types do not match.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Index entry 2");
indexEntry.setEntryType("B");
// End the bookmark and insert an XE field afterwards.
// It is of the same type as the INDEX field, but will not appear
// since it is outside the bookmark's boundaries.
builder.endBookmark("MainBookmark");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Index entry 3");
indexEntry.setEntryType("A");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Filtering.docx");
public void setBookmarkName(java.lang.String value)
throws java.lang.Exception
Examples:
Shows how to create an INDEX field, and then use XE fields to populate it with entries.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side
// and the page containing the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// Configure the INDEX field only to display XE fields that are within the bounds
// of a bookmark named "MainBookmark", and whose "EntryType" properties have a value of "A".
// For both INDEX and XE fields, the "EntryType" property only uses the first character of its string value.
index.setBookmarkName("MainBookmark");
index.setEntryType("A");
Assert.assertEquals(" INDEX \\b MainBookmark \\f A", index.getFieldCode());
// On a new page, start the bookmark with a name that matches the value
// of the INDEX field's "BookmarkName" property.
builder.insertBreak(BreakType.PAGE_BREAK);
builder.startBookmark("MainBookmark");
// The INDEX field will pick up this entry because it is inside the bookmark,
// and its entry type also matches the INDEX field's entry type.
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Index entry 1");
indexEntry.setEntryType("A");
Assert.assertEquals(" XE \"Index entry 1\" \\f A", indexEntry.getFieldCode());
// Insert an XE field that will not appear in the INDEX because the entry types do not match.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Index entry 2");
indexEntry.setEntryType("B");
// End the bookmark and insert an XE field afterwards.
// It is of the same type as the INDEX field, but will not appear
// since it is outside the bookmark's boundaries.
builder.endBookmark("MainBookmark");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Index entry 3");
indexEntry.setEntryType("A");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Filtering.docx");
value - The name of the bookmark that marks the portion of the document used to build the index.java.lang.Exceptionpublic java.lang.String getNumberOfColumns()
Examples:
Shows how to populate an INDEX field with entries using XE fields, and also modify its appearance.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
index.setLanguageId("1033");
// Setting this property's value to "A" will group all the entries by their first letter,
// and place that letter in uppercase above each group.
index.setHeading("A");
// Set the table created by the INDEX field to span over 2 columns.
index.setNumberOfColumns("2");
// Set any entries with starting letters outside the "a-c" character range to be omitted.
index.setLetterRange("a-c");
Assert.assertEquals(" INDEX \\z 1033 \\h A \\c 2 \\p a-c", index.getFieldCode());
// These next two XE fields will show up under the "A" heading,
// with their respective text stylings also applied to their page numbers.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apple");
indexEntry.isItalic(true);
Assert.assertEquals(" XE Apple \\i", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apricot");
indexEntry.isBold(true);
Assert.assertEquals(" XE Apricot \\b", indexEntry.getFieldCode());
// Both the next two XE fields will be under a "B" and "C" heading in the INDEX fields table of contents.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Banana");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cherry");
// INDEX fields sort all entries alphabetically, so this entry will show up under "A" with the other two.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Avocado");
// This entry will not appear because it starts with the letter "D",
// which is outside the "a-c" character range that the INDEX field's LetterRange property defines.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Durian");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Formatting.docx");
public void setNumberOfColumns(java.lang.String value)
throws java.lang.Exception
Examples:
Shows how to populate an INDEX field with entries using XE fields, and also modify its appearance.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
index.setLanguageId("1033");
// Setting this property's value to "A" will group all the entries by their first letter,
// and place that letter in uppercase above each group.
index.setHeading("A");
// Set the table created by the INDEX field to span over 2 columns.
index.setNumberOfColumns("2");
// Set any entries with starting letters outside the "a-c" character range to be omitted.
index.setLetterRange("a-c");
Assert.assertEquals(" INDEX \\z 1033 \\h A \\c 2 \\p a-c", index.getFieldCode());
// These next two XE fields will show up under the "A" heading,
// with their respective text stylings also applied to their page numbers.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apple");
indexEntry.isItalic(true);
Assert.assertEquals(" XE Apple \\i", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apricot");
indexEntry.isBold(true);
Assert.assertEquals(" XE Apricot \\b", indexEntry.getFieldCode());
// Both the next two XE fields will be under a "B" and "C" heading in the INDEX fields table of contents.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Banana");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cherry");
// INDEX fields sort all entries alphabetically, so this entry will show up under "A" with the other two.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Avocado");
// This entry will not appear because it starts with the letter "D",
// which is outside the "a-c" character range that the INDEX field's LetterRange property defines.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Durian");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Formatting.docx");
value - The number of columns per page used when building the index.java.lang.Exceptionpublic java.lang.String getSequenceSeparator()
Examples:
Shows how to split a document into portions by combining INDEX and SEQ fields.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// In the SequenceName property, name a SEQ field sequence. Each entry of this INDEX field will now also display
// the number that the sequence count is on at the XE field location that created this entry.
index.setSequenceName("MySequence");
// Set text that will around the sequence and page numbers to explain their meaning to the user.
// An entry created with this configuration will display something like "MySequence at 1 on page 1" at its page number.
// PageNumberSeparator and SequenceSeparator cannot be longer than 15 characters.
index.setPageNumberSeparator("\tMySequence at ");
index.setSequenceSeparator(" on page ");
Assert.assertTrue(index.hasSequenceName());
Assert.assertEquals(" INDEX \\s MySequence \\e \"\tMySequence at \" \\d \" on page \"", index.getFieldCode());
// SEQ fields display a count that increments at each SEQ field.
// These fields also maintain separate counts for each unique named sequence
// identified by the SEQ field's "SequenceIdentifier" property.
// Insert a SEQ field which moves the "MySequence" sequence to 1.
// This field no different from normal document text. It will not appear on an INDEX field's table of contents.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldSeq sequenceField = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
sequenceField.setSequenceIdentifier("MySequence");
Assert.assertEquals(" SEQ MySequence", sequenceField.getFieldCode());
// Insert an XE field which will create an entry in the INDEX field.
// Since "MySequence" is at 1 and this XE field is on page 2, along with the custom separators we defined above,
// this field's INDEX entry will display "Cat" on the left side, and "MySequence at 1 on page 2" on the right.
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cat");
Assert.assertEquals(" XE Cat", indexEntry.getFieldCode());
// Insert a page break, and use SEQ fields to advance "MySequence" to 3.
builder.insertBreak(BreakType.PAGE_BREAK);
sequenceField = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
sequenceField.setSequenceIdentifier("MySequence");
sequenceField = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
sequenceField.setSequenceIdentifier("MySequence");
// Insert an XE field with the same Text property as the one above.
// The INDEX entry will group XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
// Since we are on page 2 with "MySequence" at 3, ", 3 on page 3" will be appended to the same INDEX entry as above.
// The page number portion of that INDEX entry will now display "MySequence at 1 on page 2, 3 on page 3".
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cat");
// Insert an XE field with a new and unique Text property value.
// This will add a new entry, with MySequence at 3 on page 4.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Dog");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Sequence.docx");
public void setSequenceSeparator(java.lang.String value)
throws java.lang.Exception
Examples:
Shows how to split a document into portions by combining INDEX and SEQ fields.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// In the SequenceName property, name a SEQ field sequence. Each entry of this INDEX field will now also display
// the number that the sequence count is on at the XE field location that created this entry.
index.setSequenceName("MySequence");
// Set text that will around the sequence and page numbers to explain their meaning to the user.
// An entry created with this configuration will display something like "MySequence at 1 on page 1" at its page number.
// PageNumberSeparator and SequenceSeparator cannot be longer than 15 characters.
index.setPageNumberSeparator("\tMySequence at ");
index.setSequenceSeparator(" on page ");
Assert.assertTrue(index.hasSequenceName());
Assert.assertEquals(" INDEX \\s MySequence \\e \"\tMySequence at \" \\d \" on page \"", index.getFieldCode());
// SEQ fields display a count that increments at each SEQ field.
// These fields also maintain separate counts for each unique named sequence
// identified by the SEQ field's "SequenceIdentifier" property.
// Insert a SEQ field which moves the "MySequence" sequence to 1.
// This field no different from normal document text. It will not appear on an INDEX field's table of contents.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldSeq sequenceField = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
sequenceField.setSequenceIdentifier("MySequence");
Assert.assertEquals(" SEQ MySequence", sequenceField.getFieldCode());
// Insert an XE field which will create an entry in the INDEX field.
// Since "MySequence" is at 1 and this XE field is on page 2, along with the custom separators we defined above,
// this field's INDEX entry will display "Cat" on the left side, and "MySequence at 1 on page 2" on the right.
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cat");
Assert.assertEquals(" XE Cat", indexEntry.getFieldCode());
// Insert a page break, and use SEQ fields to advance "MySequence" to 3.
builder.insertBreak(BreakType.PAGE_BREAK);
sequenceField = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
sequenceField.setSequenceIdentifier("MySequence");
sequenceField = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
sequenceField.setSequenceIdentifier("MySequence");
// Insert an XE field with the same Text property as the one above.
// The INDEX entry will group XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
// Since we are on page 2 with "MySequence" at 3, ", 3 on page 3" will be appended to the same INDEX entry as above.
// The page number portion of that INDEX entry will now display "MySequence at 1 on page 2, 3 on page 3".
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cat");
// Insert an XE field with a new and unique Text property value.
// This will add a new entry, with MySequence at 3 on page 4.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Dog");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Sequence.docx");
value - The character sequence that is used to separate sequence numbers and page numbers.java.lang.Exceptionpublic java.lang.String getPageNumberSeparator()
Examples:
Shows how to edit the page number separator in an INDEX field.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will group XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// If our INDEX field has an entry for a group of XE fields,
// this entry will display the number of each page that contains an XE field that belongs to this group.
// We can set custom separators to customize the appearance of these page numbers.
index.setPageNumberSeparator(", on page(s) ");
index.setPageNumberListSeparator(" & ");
Assert.assertEquals(" INDEX \\e \", on page(s) \" \\l \" & \"", index.getFieldCode());
Assert.assertTrue(index.hasPageNumberSeparator());
// After we insert these XE fields, the INDEX field will display "First entry, on page(s) 2 & 3 & 4".
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("First entry");
Assert.assertEquals(" XE \"First entry\"", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("First entry");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("First entry");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.PageNumberList.docx");
public void setPageNumberSeparator(java.lang.String value)
throws java.lang.Exception
Examples:
Shows how to edit the page number separator in an INDEX field.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will group XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// If our INDEX field has an entry for a group of XE fields,
// this entry will display the number of each page that contains an XE field that belongs to this group.
// We can set custom separators to customize the appearance of these page numbers.
index.setPageNumberSeparator(", on page(s) ");
index.setPageNumberListSeparator(" & ");
Assert.assertEquals(" INDEX \\e \", on page(s) \" \\l \" & \"", index.getFieldCode());
Assert.assertTrue(index.hasPageNumberSeparator());
// After we insert these XE fields, the INDEX field will display "First entry, on page(s) 2 & 3 & 4".
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("First entry");
Assert.assertEquals(" XE \"First entry\"", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("First entry");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("First entry");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.PageNumberList.docx");
value - The character sequence that is used to separate an index entry and its page number.java.lang.Exceptionpublic boolean hasPageNumberSeparator()
Examples:
Shows how to edit the page number separator in an INDEX field.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will group XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// If our INDEX field has an entry for a group of XE fields,
// this entry will display the number of each page that contains an XE field that belongs to this group.
// We can set custom separators to customize the appearance of these page numbers.
index.setPageNumberSeparator(", on page(s) ");
index.setPageNumberListSeparator(" & ");
Assert.assertEquals(" INDEX \\e \", on page(s) \" \\l \" & \"", index.getFieldCode());
Assert.assertTrue(index.hasPageNumberSeparator());
// After we insert these XE fields, the INDEX field will display "First entry, on page(s) 2 & 3 & 4".
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("First entry");
Assert.assertEquals(" XE \"First entry\"", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("First entry");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("First entry");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.PageNumberList.docx");
public java.lang.String getEntryType()
Examples:
Shows how to create an INDEX field, and then use XE fields to populate it with entries.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side
// and the page containing the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// Configure the INDEX field only to display XE fields that are within the bounds
// of a bookmark named "MainBookmark", and whose "EntryType" properties have a value of "A".
// For both INDEX and XE fields, the "EntryType" property only uses the first character of its string value.
index.setBookmarkName("MainBookmark");
index.setEntryType("A");
Assert.assertEquals(" INDEX \\b MainBookmark \\f A", index.getFieldCode());
// On a new page, start the bookmark with a name that matches the value
// of the INDEX field's "BookmarkName" property.
builder.insertBreak(BreakType.PAGE_BREAK);
builder.startBookmark("MainBookmark");
// The INDEX field will pick up this entry because it is inside the bookmark,
// and its entry type also matches the INDEX field's entry type.
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Index entry 1");
indexEntry.setEntryType("A");
Assert.assertEquals(" XE \"Index entry 1\" \\f A", indexEntry.getFieldCode());
// Insert an XE field that will not appear in the INDEX because the entry types do not match.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Index entry 2");
indexEntry.setEntryType("B");
// End the bookmark and insert an XE field afterwards.
// It is of the same type as the INDEX field, but will not appear
// since it is outside the bookmark's boundaries.
builder.endBookmark("MainBookmark");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Index entry 3");
indexEntry.setEntryType("A");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Filtering.docx");
public void setEntryType(java.lang.String value)
throws java.lang.Exception
Examples:
Shows how to create an INDEX field, and then use XE fields to populate it with entries.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side
// and the page containing the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// Configure the INDEX field only to display XE fields that are within the bounds
// of a bookmark named "MainBookmark", and whose "EntryType" properties have a value of "A".
// For both INDEX and XE fields, the "EntryType" property only uses the first character of its string value.
index.setBookmarkName("MainBookmark");
index.setEntryType("A");
Assert.assertEquals(" INDEX \\b MainBookmark \\f A", index.getFieldCode());
// On a new page, start the bookmark with a name that matches the value
// of the INDEX field's "BookmarkName" property.
builder.insertBreak(BreakType.PAGE_BREAK);
builder.startBookmark("MainBookmark");
// The INDEX field will pick up this entry because it is inside the bookmark,
// and its entry type also matches the INDEX field's entry type.
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Index entry 1");
indexEntry.setEntryType("A");
Assert.assertEquals(" XE \"Index entry 1\" \\f A", indexEntry.getFieldCode());
// Insert an XE field that will not appear in the INDEX because the entry types do not match.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Index entry 2");
indexEntry.setEntryType("B");
// End the bookmark and insert an XE field afterwards.
// It is of the same type as the INDEX field, but will not appear
// since it is outside the bookmark's boundaries.
builder.endBookmark("MainBookmark");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Index entry 3");
indexEntry.setEntryType("A");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Filtering.docx");
value - An index entry type used to build the index.java.lang.Exceptionpublic java.lang.String getPageRangeSeparator()
Examples:
Shows how to specify a bookmark's spanned pages as a page range for an INDEX field entry.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will collect all XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// For INDEX entries that display page ranges, we can specify a separator string
// which will appear between the number of the first page, and the number of the last.
index.setPageNumberSeparator(", on page(s) ");
index.setPageRangeSeparator(" to ");
Assert.assertEquals(" INDEX \\e \", on page(s) \" \\g \" to \"", index.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("My entry");
// If an XE field names a bookmark using the PageRangeBookmarkName property,
// its INDEX entry will show the range of pages that the bookmark spans
// instead of the number of the page that contains the XE field.
indexEntry.setPageRangeBookmarkName("MyBookmark");
Assert.assertEquals(" XE \"My entry\" \\r MyBookmark", indexEntry.getFieldCode());
Assert.assertEquals(indexEntry.getPageRangeBookmarkName(), "MyBookmark");
// Insert a bookmark that starts on page 3 and ends on page 5.
// The INDEX entry for the XE field that references this bookmark will display this page range.
// In our table, the INDEX entry will display "My entry, on page(s) 3 to 5".
builder.insertBreak(BreakType.PAGE_BREAK);
builder.startBookmark("MyBookmark");
builder.write("Start of MyBookmark");
builder.insertBreak(BreakType.PAGE_BREAK);
builder.insertBreak(BreakType.PAGE_BREAK);
builder.write("End of MyBookmark");
builder.endBookmark("MyBookmark");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.PageRangeBookmark.docx");
public void setPageRangeSeparator(java.lang.String value)
throws java.lang.Exception
Examples:
Shows how to specify a bookmark's spanned pages as a page range for an INDEX field entry.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will collect all XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// For INDEX entries that display page ranges, we can specify a separator string
// which will appear between the number of the first page, and the number of the last.
index.setPageNumberSeparator(", on page(s) ");
index.setPageRangeSeparator(" to ");
Assert.assertEquals(" INDEX \\e \", on page(s) \" \\g \" to \"", index.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("My entry");
// If an XE field names a bookmark using the PageRangeBookmarkName property,
// its INDEX entry will show the range of pages that the bookmark spans
// instead of the number of the page that contains the XE field.
indexEntry.setPageRangeBookmarkName("MyBookmark");
Assert.assertEquals(" XE \"My entry\" \\r MyBookmark", indexEntry.getFieldCode());
Assert.assertEquals(indexEntry.getPageRangeBookmarkName(), "MyBookmark");
// Insert a bookmark that starts on page 3 and ends on page 5.
// The INDEX entry for the XE field that references this bookmark will display this page range.
// In our table, the INDEX entry will display "My entry, on page(s) 3 to 5".
builder.insertBreak(BreakType.PAGE_BREAK);
builder.startBookmark("MyBookmark");
builder.write("Start of MyBookmark");
builder.insertBreak(BreakType.PAGE_BREAK);
builder.insertBreak(BreakType.PAGE_BREAK);
builder.write("End of MyBookmark");
builder.endBookmark("MyBookmark");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.PageRangeBookmark.docx");
value - The character sequence that is used to separate the start and end of a page range.java.lang.Exceptionpublic java.lang.String getHeading()
Examples:
Shows how to populate an INDEX field with entries using XE fields, and also modify its appearance.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
index.setLanguageId("1033");
// Setting this property's value to "A" will group all the entries by their first letter,
// and place that letter in uppercase above each group.
index.setHeading("A");
// Set the table created by the INDEX field to span over 2 columns.
index.setNumberOfColumns("2");
// Set any entries with starting letters outside the "a-c" character range to be omitted.
index.setLetterRange("a-c");
Assert.assertEquals(" INDEX \\z 1033 \\h A \\c 2 \\p a-c", index.getFieldCode());
// These next two XE fields will show up under the "A" heading,
// with their respective text stylings also applied to their page numbers.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apple");
indexEntry.isItalic(true);
Assert.assertEquals(" XE Apple \\i", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apricot");
indexEntry.isBold(true);
Assert.assertEquals(" XE Apricot \\b", indexEntry.getFieldCode());
// Both the next two XE fields will be under a "B" and "C" heading in the INDEX fields table of contents.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Banana");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cherry");
// INDEX fields sort all entries alphabetically, so this entry will show up under "A" with the other two.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Avocado");
// This entry will not appear because it starts with the letter "D",
// which is outside the "a-c" character range that the INDEX field's LetterRange property defines.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Durian");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Formatting.docx");
public void setHeading(java.lang.String value)
throws java.lang.Exception
Examples:
Shows how to populate an INDEX field with entries using XE fields, and also modify its appearance.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
index.setLanguageId("1033");
// Setting this property's value to "A" will group all the entries by their first letter,
// and place that letter in uppercase above each group.
index.setHeading("A");
// Set the table created by the INDEX field to span over 2 columns.
index.setNumberOfColumns("2");
// Set any entries with starting letters outside the "a-c" character range to be omitted.
index.setLetterRange("a-c");
Assert.assertEquals(" INDEX \\z 1033 \\h A \\c 2 \\p a-c", index.getFieldCode());
// These next two XE fields will show up under the "A" heading,
// with their respective text stylings also applied to their page numbers.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apple");
indexEntry.isItalic(true);
Assert.assertEquals(" XE Apple \\i", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apricot");
indexEntry.isBold(true);
Assert.assertEquals(" XE Apricot \\b", indexEntry.getFieldCode());
// Both the next two XE fields will be under a "B" and "C" heading in the INDEX fields table of contents.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Banana");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cherry");
// INDEX fields sort all entries alphabetically, so this entry will show up under "A" with the other two.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Avocado");
// This entry will not appear because it starts with the letter "D",
// which is outside the "a-c" character range that the INDEX field's LetterRange property defines.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Durian");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Formatting.docx");
value - A heading that appears at the start of each set of entries for any given letter.java.lang.Exceptionpublic java.lang.String getCrossReferenceSeparator()
Examples:
Shows how to define cross references in an INDEX field.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will collect all XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// We can configure an XE field to get its INDEX entry to display a string instead of a page number.
// First, for entries that substitute a page number with a string,
// specify a custom separator between the XE field's Text property value and the string.
index.setCrossReferenceSeparator(", see: ");
Assert.assertEquals(" INDEX \\k \", see: \"", index.getFieldCode());
// Insert an XE field, which creates a regular INDEX entry which displays this field's page number,
// and does not invoke the CrossReferenceSeparator value.
// The entry for this XE field will display "Apple, 2".
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apple");
Assert.assertEquals(" XE Apple", indexEntry.getFieldCode());
// Insert another XE field on page 3 and set a value for the PageNumberReplacement property.
// This value will show up instead of the number of the page that this field is on,
// and the INDEX field's CrossReferenceSeparator value will appear in front of it.
// The entry for this XE field will display "Banana, see: Tropical fruit".
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Banana");
indexEntry.setPageNumberReplacement("Tropical fruit");
Assert.assertEquals(" XE Banana \\t \"Tropical fruit\"", indexEntry.getFieldCode());
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.CrossReferenceSeparator.docx");
public void setCrossReferenceSeparator(java.lang.String value)
throws java.lang.Exception
Examples:
Shows how to define cross references in an INDEX field.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will collect all XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// We can configure an XE field to get its INDEX entry to display a string instead of a page number.
// First, for entries that substitute a page number with a string,
// specify a custom separator between the XE field's Text property value and the string.
index.setCrossReferenceSeparator(", see: ");
Assert.assertEquals(" INDEX \\k \", see: \"", index.getFieldCode());
// Insert an XE field, which creates a regular INDEX entry which displays this field's page number,
// and does not invoke the CrossReferenceSeparator value.
// The entry for this XE field will display "Apple, 2".
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apple");
Assert.assertEquals(" XE Apple", indexEntry.getFieldCode());
// Insert another XE field on page 3 and set a value for the PageNumberReplacement property.
// This value will show up instead of the number of the page that this field is on,
// and the INDEX field's CrossReferenceSeparator value will appear in front of it.
// The entry for this XE field will display "Banana, see: Tropical fruit".
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Banana");
indexEntry.setPageNumberReplacement("Tropical fruit");
Assert.assertEquals(" XE Banana \\t \"Tropical fruit\"", indexEntry.getFieldCode());
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.CrossReferenceSeparator.docx");
value - The character sequence that is used to separate cross references and other entries.java.lang.Exceptionpublic java.lang.String getPageNumberListSeparator()
Examples:
Shows how to edit the page number separator in an INDEX field.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will group XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// If our INDEX field has an entry for a group of XE fields,
// this entry will display the number of each page that contains an XE field that belongs to this group.
// We can set custom separators to customize the appearance of these page numbers.
index.setPageNumberSeparator(", on page(s) ");
index.setPageNumberListSeparator(" & ");
Assert.assertEquals(" INDEX \\e \", on page(s) \" \\l \" & \"", index.getFieldCode());
Assert.assertTrue(index.hasPageNumberSeparator());
// After we insert these XE fields, the INDEX field will display "First entry, on page(s) 2 & 3 & 4".
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("First entry");
Assert.assertEquals(" XE \"First entry\"", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("First entry");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("First entry");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.PageNumberList.docx");
public void setPageNumberListSeparator(java.lang.String value)
throws java.lang.Exception
Examples:
Shows how to edit the page number separator in an INDEX field.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will group XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// If our INDEX field has an entry for a group of XE fields,
// this entry will display the number of each page that contains an XE field that belongs to this group.
// We can set custom separators to customize the appearance of these page numbers.
index.setPageNumberSeparator(", on page(s) ");
index.setPageNumberListSeparator(" & ");
Assert.assertEquals(" INDEX \\e \", on page(s) \" \\l \" & \"", index.getFieldCode());
Assert.assertTrue(index.hasPageNumberSeparator());
// After we insert these XE fields, the INDEX field will display "First entry, on page(s) 2 & 3 & 4".
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("First entry");
Assert.assertEquals(" XE \"First entry\"", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("First entry");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("First entry");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.PageNumberList.docx");
value - The character sequence that is used to separate two page numbers in a page number list.java.lang.Exceptionpublic java.lang.String getLetterRange()
Examples:
Shows how to populate an INDEX field with entries using XE fields, and also modify its appearance.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
index.setLanguageId("1033");
// Setting this property's value to "A" will group all the entries by their first letter,
// and place that letter in uppercase above each group.
index.setHeading("A");
// Set the table created by the INDEX field to span over 2 columns.
index.setNumberOfColumns("2");
// Set any entries with starting letters outside the "a-c" character range to be omitted.
index.setLetterRange("a-c");
Assert.assertEquals(" INDEX \\z 1033 \\h A \\c 2 \\p a-c", index.getFieldCode());
// These next two XE fields will show up under the "A" heading,
// with their respective text stylings also applied to their page numbers.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apple");
indexEntry.isItalic(true);
Assert.assertEquals(" XE Apple \\i", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apricot");
indexEntry.isBold(true);
Assert.assertEquals(" XE Apricot \\b", indexEntry.getFieldCode());
// Both the next two XE fields will be under a "B" and "C" heading in the INDEX fields table of contents.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Banana");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cherry");
// INDEX fields sort all entries alphabetically, so this entry will show up under "A" with the other two.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Avocado");
// This entry will not appear because it starts with the letter "D",
// which is outside the "a-c" character range that the INDEX field's LetterRange property defines.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Durian");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Formatting.docx");
public void setLetterRange(java.lang.String value)
throws java.lang.Exception
Examples:
Shows how to populate an INDEX field with entries using XE fields, and also modify its appearance.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
index.setLanguageId("1033");
// Setting this property's value to "A" will group all the entries by their first letter,
// and place that letter in uppercase above each group.
index.setHeading("A");
// Set the table created by the INDEX field to span over 2 columns.
index.setNumberOfColumns("2");
// Set any entries with starting letters outside the "a-c" character range to be omitted.
index.setLetterRange("a-c");
Assert.assertEquals(" INDEX \\z 1033 \\h A \\c 2 \\p a-c", index.getFieldCode());
// These next two XE fields will show up under the "A" heading,
// with their respective text stylings also applied to their page numbers.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apple");
indexEntry.isItalic(true);
Assert.assertEquals(" XE Apple \\i", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apricot");
indexEntry.isBold(true);
Assert.assertEquals(" XE Apricot \\b", indexEntry.getFieldCode());
// Both the next two XE fields will be under a "B" and "C" heading in the INDEX fields table of contents.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Banana");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cherry");
// INDEX fields sort all entries alphabetically, so this entry will show up under "A" with the other two.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Avocado");
// This entry will not appear because it starts with the letter "D",
// which is outside the "a-c" character range that the INDEX field's LetterRange property defines.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Durian");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Formatting.docx");
value - A range of letters to which limit the index.java.lang.Exceptionpublic boolean getRunSubentriesOnSameLine()
Examples:
Shows how to work with subentries in an INDEX field.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will collect all XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
index.setPageNumberSeparator(", see page ");
index.setHeading("A");
// XE fields that have a Text property whose value becomes the heading of the INDEX entry.
// If this value contains two string segments split by a colon (the INDEX entry will treat :) delimiter,
// the first segment is heading, and the second segment will become the subheading.
// The INDEX field first groups entries alphabetically, then, if there are multiple XE fields with the same
// headings, the INDEX field will further subgroup them by the values of these headings.
// There can be multiple subgrouping layers, depending on how many times
// the Text properties of XE fields get segmented like this.
// By default, an INDEX field entry group will create a new line for every subheading within this group.
// We can set the RunSubentriesOnSameLine flag to true to keep the heading,
// and every subheading for the group on one line instead, which will make the INDEX field more compact.
index.setRunSubentriesOnSameLine(runSubentriesOnTheSameLine);
if (runSubentriesOnTheSameLine)
Assert.assertEquals(" INDEX \\e \", see page \" \\h A \\r", index.getFieldCode());
else
Assert.assertEquals(" INDEX \\e \", see page \" \\h A", index.getFieldCode());
// Insert two XE fields, each on a new page, and with the same heading named "Heading 1",
// which the INDEX field will use to group them.
// If RunSubentriesOnSameLine is false, then the INDEX table will create three lines:
// one line for the grouping heading "Heading 1", and one more line for each subheading.
// If RunSubentriesOnSameLine is true, then the INDEX table will create a one-line
// entry that encompasses the heading and every subheading.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Heading 1:Subheading 1");
Assert.assertEquals(" XE \"Heading 1:Subheading 1\"", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Heading 1:Subheading 2");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Subheading.docx");
public void setRunSubentriesOnSameLine(boolean value)
throws java.lang.Exception
Examples:
Shows how to work with subentries in an INDEX field.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will collect all XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
index.setPageNumberSeparator(", see page ");
index.setHeading("A");
// XE fields that have a Text property whose value becomes the heading of the INDEX entry.
// If this value contains two string segments split by a colon (the INDEX entry will treat :) delimiter,
// the first segment is heading, and the second segment will become the subheading.
// The INDEX field first groups entries alphabetically, then, if there are multiple XE fields with the same
// headings, the INDEX field will further subgroup them by the values of these headings.
// There can be multiple subgrouping layers, depending on how many times
// the Text properties of XE fields get segmented like this.
// By default, an INDEX field entry group will create a new line for every subheading within this group.
// We can set the RunSubentriesOnSameLine flag to true to keep the heading,
// and every subheading for the group on one line instead, which will make the INDEX field more compact.
index.setRunSubentriesOnSameLine(runSubentriesOnTheSameLine);
if (runSubentriesOnTheSameLine)
Assert.assertEquals(" INDEX \\e \", see page \" \\h A \\r", index.getFieldCode());
else
Assert.assertEquals(" INDEX \\e \", see page \" \\h A", index.getFieldCode());
// Insert two XE fields, each on a new page, and with the same heading named "Heading 1",
// which the INDEX field will use to group them.
// If RunSubentriesOnSameLine is false, then the INDEX table will create three lines:
// one line for the grouping heading "Heading 1", and one more line for each subheading.
// If RunSubentriesOnSameLine is true, then the INDEX table will create a one-line
// entry that encompasses the heading and every subheading.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Heading 1:Subheading 1");
Assert.assertEquals(" XE \"Heading 1:Subheading 1\"", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Heading 1:Subheading 2");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Subheading.docx");
value - Whether run subentries into the same line as the main entry.java.lang.Exceptionpublic java.lang.String getSequenceName()
Examples:
Shows how to split a document into portions by combining INDEX and SEQ fields.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// In the SequenceName property, name a SEQ field sequence. Each entry of this INDEX field will now also display
// the number that the sequence count is on at the XE field location that created this entry.
index.setSequenceName("MySequence");
// Set text that will around the sequence and page numbers to explain their meaning to the user.
// An entry created with this configuration will display something like "MySequence at 1 on page 1" at its page number.
// PageNumberSeparator and SequenceSeparator cannot be longer than 15 characters.
index.setPageNumberSeparator("\tMySequence at ");
index.setSequenceSeparator(" on page ");
Assert.assertTrue(index.hasSequenceName());
Assert.assertEquals(" INDEX \\s MySequence \\e \"\tMySequence at \" \\d \" on page \"", index.getFieldCode());
// SEQ fields display a count that increments at each SEQ field.
// These fields also maintain separate counts for each unique named sequence
// identified by the SEQ field's "SequenceIdentifier" property.
// Insert a SEQ field which moves the "MySequence" sequence to 1.
// This field no different from normal document text. It will not appear on an INDEX field's table of contents.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldSeq sequenceField = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
sequenceField.setSequenceIdentifier("MySequence");
Assert.assertEquals(" SEQ MySequence", sequenceField.getFieldCode());
// Insert an XE field which will create an entry in the INDEX field.
// Since "MySequence" is at 1 and this XE field is on page 2, along with the custom separators we defined above,
// this field's INDEX entry will display "Cat" on the left side, and "MySequence at 1 on page 2" on the right.
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cat");
Assert.assertEquals(" XE Cat", indexEntry.getFieldCode());
// Insert a page break, and use SEQ fields to advance "MySequence" to 3.
builder.insertBreak(BreakType.PAGE_BREAK);
sequenceField = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
sequenceField.setSequenceIdentifier("MySequence");
sequenceField = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
sequenceField.setSequenceIdentifier("MySequence");
// Insert an XE field with the same Text property as the one above.
// The INDEX entry will group XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
// Since we are on page 2 with "MySequence" at 3, ", 3 on page 3" will be appended to the same INDEX entry as above.
// The page number portion of that INDEX entry will now display "MySequence at 1 on page 2, 3 on page 3".
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cat");
// Insert an XE field with a new and unique Text property value.
// This will add a new entry, with MySequence at 3 on page 4.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Dog");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Sequence.docx");
public void setSequenceName(java.lang.String value)
throws java.lang.Exception
Examples:
Shows how to split a document into portions by combining INDEX and SEQ fields.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// In the SequenceName property, name a SEQ field sequence. Each entry of this INDEX field will now also display
// the number that the sequence count is on at the XE field location that created this entry.
index.setSequenceName("MySequence");
// Set text that will around the sequence and page numbers to explain their meaning to the user.
// An entry created with this configuration will display something like "MySequence at 1 on page 1" at its page number.
// PageNumberSeparator and SequenceSeparator cannot be longer than 15 characters.
index.setPageNumberSeparator("\tMySequence at ");
index.setSequenceSeparator(" on page ");
Assert.assertTrue(index.hasSequenceName());
Assert.assertEquals(" INDEX \\s MySequence \\e \"\tMySequence at \" \\d \" on page \"", index.getFieldCode());
// SEQ fields display a count that increments at each SEQ field.
// These fields also maintain separate counts for each unique named sequence
// identified by the SEQ field's "SequenceIdentifier" property.
// Insert a SEQ field which moves the "MySequence" sequence to 1.
// This field no different from normal document text. It will not appear on an INDEX field's table of contents.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldSeq sequenceField = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
sequenceField.setSequenceIdentifier("MySequence");
Assert.assertEquals(" SEQ MySequence", sequenceField.getFieldCode());
// Insert an XE field which will create an entry in the INDEX field.
// Since "MySequence" is at 1 and this XE field is on page 2, along with the custom separators we defined above,
// this field's INDEX entry will display "Cat" on the left side, and "MySequence at 1 on page 2" on the right.
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cat");
Assert.assertEquals(" XE Cat", indexEntry.getFieldCode());
// Insert a page break, and use SEQ fields to advance "MySequence" to 3.
builder.insertBreak(BreakType.PAGE_BREAK);
sequenceField = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
sequenceField.setSequenceIdentifier("MySequence");
sequenceField = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
sequenceField.setSequenceIdentifier("MySequence");
// Insert an XE field with the same Text property as the one above.
// The INDEX entry will group XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
// Since we are on page 2 with "MySequence" at 3, ", 3 on page 3" will be appended to the same INDEX entry as above.
// The page number portion of that INDEX entry will now display "MySequence at 1 on page 2, 3 on page 3".
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cat");
// Insert an XE field with a new and unique Text property value.
// This will add a new entry, with MySequence at 3 on page 4.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Dog");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Sequence.docx");
value - The name of a sequence whose number is included with the page number.java.lang.Exceptionpublic boolean hasSequenceName()
Examples:
Shows how to split a document into portions by combining INDEX and SEQ fields.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// In the SequenceName property, name a SEQ field sequence. Each entry of this INDEX field will now also display
// the number that the sequence count is on at the XE field location that created this entry.
index.setSequenceName("MySequence");
// Set text that will around the sequence and page numbers to explain their meaning to the user.
// An entry created with this configuration will display something like "MySequence at 1 on page 1" at its page number.
// PageNumberSeparator and SequenceSeparator cannot be longer than 15 characters.
index.setPageNumberSeparator("\tMySequence at ");
index.setSequenceSeparator(" on page ");
Assert.assertTrue(index.hasSequenceName());
Assert.assertEquals(" INDEX \\s MySequence \\e \"\tMySequence at \" \\d \" on page \"", index.getFieldCode());
// SEQ fields display a count that increments at each SEQ field.
// These fields also maintain separate counts for each unique named sequence
// identified by the SEQ field's "SequenceIdentifier" property.
// Insert a SEQ field which moves the "MySequence" sequence to 1.
// This field no different from normal document text. It will not appear on an INDEX field's table of contents.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldSeq sequenceField = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
sequenceField.setSequenceIdentifier("MySequence");
Assert.assertEquals(" SEQ MySequence", sequenceField.getFieldCode());
// Insert an XE field which will create an entry in the INDEX field.
// Since "MySequence" is at 1 and this XE field is on page 2, along with the custom separators we defined above,
// this field's INDEX entry will display "Cat" on the left side, and "MySequence at 1 on page 2" on the right.
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cat");
Assert.assertEquals(" XE Cat", indexEntry.getFieldCode());
// Insert a page break, and use SEQ fields to advance "MySequence" to 3.
builder.insertBreak(BreakType.PAGE_BREAK);
sequenceField = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
sequenceField.setSequenceIdentifier("MySequence");
sequenceField = (FieldSeq) builder.insertField(FieldType.FIELD_SEQUENCE, true);
sequenceField.setSequenceIdentifier("MySequence");
// Insert an XE field with the same Text property as the one above.
// The INDEX entry will group XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
// Since we are on page 2 with "MySequence" at 3, ", 3 on page 3" will be appended to the same INDEX entry as above.
// The page number portion of that INDEX entry will now display "MySequence at 1 on page 2, 3 on page 3".
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cat");
// Insert an XE field with a new and unique Text property value.
// This will add a new entry, with MySequence at 3 on page 4.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Dog");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Sequence.docx");
public boolean getUseYomi()
Examples:
Shows how to sort INDEX field entries phonetically.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will collect all XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// The INDEX table automatically sorts its entries by the values of their Text properties in alphabetic order.
// Set the INDEX table to sort entries phonetically using Hiragana instead.
index.setUseYomi(sortEntriesUsingYomi);
if (sortEntriesUsingYomi)
Assert.assertEquals(" INDEX \\y", index.getFieldCode());
else
Assert.assertEquals(" INDEX ", index.getFieldCode());
// Insert 4 XE fields, which would show up as entries in the INDEX field's table of contents.
// The "Text" property may contain a word's spelling in Kanji, whose pronunciation may be ambiguous,
// while the "Yomi" version of the word will spell exactly how it is pronounced using Hiragana.
// If we set our INDEX field to use Yomi, it will sort these entries
// by the value of their Yomi properties, instead of their Text values.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("愛子");
indexEntry.setYomi("あ");
Assert.assertEquals(" XE 愛子 \\y あ", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("明美");
indexEntry.setYomi("あ");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("恵美");
indexEntry.setYomi("え");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("愛美");
indexEntry.setYomi("え");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Yomi.docx");
public void setUseYomi(boolean value)
throws java.lang.Exception
Examples:
Shows how to sort INDEX field entries phonetically.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// The INDEX entry will collect all XE fields with matching values in the "Text" property
// into one entry as opposed to making an entry for each XE field.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
// The INDEX table automatically sorts its entries by the values of their Text properties in alphabetic order.
// Set the INDEX table to sort entries phonetically using Hiragana instead.
index.setUseYomi(sortEntriesUsingYomi);
if (sortEntriesUsingYomi)
Assert.assertEquals(" INDEX \\y", index.getFieldCode());
else
Assert.assertEquals(" INDEX ", index.getFieldCode());
// Insert 4 XE fields, which would show up as entries in the INDEX field's table of contents.
// The "Text" property may contain a word's spelling in Kanji, whose pronunciation may be ambiguous,
// while the "Yomi" version of the word will spell exactly how it is pronounced using Hiragana.
// If we set our INDEX field to use Yomi, it will sort these entries
// by the value of their Yomi properties, instead of their Text values.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("愛子");
indexEntry.setYomi("あ");
Assert.assertEquals(" XE 愛子 \\y あ", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("明美");
indexEntry.setYomi("あ");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("恵美");
indexEntry.setYomi("え");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("愛美");
indexEntry.setYomi("え");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Yomi.docx");
value - Whether to enable the use of yomi text for index entries.java.lang.Exceptionpublic java.lang.String getLanguageId()
Examples:
Shows how to populate an INDEX field with entries using XE fields, and also modify its appearance.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
index.setLanguageId("1033");
// Setting this property's value to "A" will group all the entries by their first letter,
// and place that letter in uppercase above each group.
index.setHeading("A");
// Set the table created by the INDEX field to span over 2 columns.
index.setNumberOfColumns("2");
// Set any entries with starting letters outside the "a-c" character range to be omitted.
index.setLetterRange("a-c");
Assert.assertEquals(" INDEX \\z 1033 \\h A \\c 2 \\p a-c", index.getFieldCode());
// These next two XE fields will show up under the "A" heading,
// with their respective text stylings also applied to their page numbers.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apple");
indexEntry.isItalic(true);
Assert.assertEquals(" XE Apple \\i", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apricot");
indexEntry.isBold(true);
Assert.assertEquals(" XE Apricot \\b", indexEntry.getFieldCode());
// Both the next two XE fields will be under a "B" and "C" heading in the INDEX fields table of contents.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Banana");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cherry");
// INDEX fields sort all entries alphabetically, so this entry will show up under "A" with the other two.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Avocado");
// This entry will not appear because it starts with the letter "D",
// which is outside the "a-c" character range that the INDEX field's LetterRange property defines.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Durian");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Formatting.docx");
public void setLanguageId(java.lang.String value)
throws java.lang.Exception
Examples:
Shows how to populate an INDEX field with entries using XE fields, and also modify its appearance.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create an INDEX field which will display an entry for each XE field found in the document.
// Each entry will display the XE field's Text property value on the left side,
// and the number of the page that contains the XE field on the right.
// If the XE fields have the same value in their "Text" property,
// the INDEX field will group them into one entry.
FieldIndex index = (FieldIndex) builder.insertField(FieldType.FIELD_INDEX, true);
index.setLanguageId("1033");
// Setting this property's value to "A" will group all the entries by their first letter,
// and place that letter in uppercase above each group.
index.setHeading("A");
// Set the table created by the INDEX field to span over 2 columns.
index.setNumberOfColumns("2");
// Set any entries with starting letters outside the "a-c" character range to be omitted.
index.setLetterRange("a-c");
Assert.assertEquals(" INDEX \\z 1033 \\h A \\c 2 \\p a-c", index.getFieldCode());
// These next two XE fields will show up under the "A" heading,
// with their respective text stylings also applied to their page numbers.
builder.insertBreak(BreakType.PAGE_BREAK);
FieldXE indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apple");
indexEntry.isItalic(true);
Assert.assertEquals(" XE Apple \\i", indexEntry.getFieldCode());
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Apricot");
indexEntry.isBold(true);
Assert.assertEquals(" XE Apricot \\b", indexEntry.getFieldCode());
// Both the next two XE fields will be under a "B" and "C" heading in the INDEX fields table of contents.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Banana");
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Cherry");
// INDEX fields sort all entries alphabetically, so this entry will show up under "A" with the other two.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Avocado");
// This entry will not appear because it starts with the letter "D",
// which is outside the "a-c" character range that the INDEX field's LetterRange property defines.
builder.insertBreak(BreakType.PAGE_BREAK);
indexEntry = (FieldXE) builder.insertField(FieldType.FIELD_INDEX_ENTRY, true);
indexEntry.setText("Durian");
doc.updatePageLayout();
doc.updateFields();
doc.save(getArtifactsDir() + "Field.INDEX.XE.Formatting.docx");
value - The language ID used to generate the index.java.lang.Exception