com.aspose.words

Class FieldOptions

  • java.lang.Object
    • com.aspose.words.FieldOptions
public class FieldOptions 
extends java.lang.Object

Represents options to control field handling in a document.

Property Getters/Setters Summary
IBarcodeGeneratorgetBarcodeGenerator()
void
           Gets or set custom barcode generator.
java.lang.String[]getBuiltInTemplatesPaths()
void
setBuiltInTemplatesPaths(java.lang.String[]value)
           Gets or sets paths of MS Word built-in templates.
IComparisonExpressionEvaluatorgetComparisonExpressionEvaluator()
void
           Gets or sets the field comparison expressions evaluator.
UserInformationgetCurrentUser()
void
           Gets or sets the current user information.
java.lang.StringgetCustomTocStyleSeparator()
void
setCustomTocStyleSeparator(java.lang.Stringvalue)
           Gets or sets custom style separator for the \t switch in TOC field.
java.lang.StringgetDefaultDocumentAuthor()
void
setDefaultDocumentAuthor(java.lang.Stringvalue)
           Gets or sets default document author's name. If author's name is already specified in built-in document properties, this option is not considered.
intgetFieldIndexFormat()
void
           Gets or sets a FieldIndexFormat that represents the formatting for the FieldIndex fields in the document. The value of the property is FieldIndexFormat integer constant.
IFieldUpdateCultureProvidergetFieldUpdateCultureProvider()
void
           Gets or sets a provider that returns a culture object specific for each particular field.
intgetFieldUpdateCultureSource()
void
           Specifies what culture to use to format the field result. The value of the property is FieldUpdateCultureSource integer constant.
java.lang.StringgetFileName()
void
setFileName(java.lang.Stringvalue)
           Gets or sets the file name of the document.
booleanisBidiTextSupportedOnUpdate()
void
           Gets or sets the value indicating whether bidirectional text is fully supported during field update or not.
booleangetLegacyNumberFormat()
void
setLegacyNumberFormat(booleanvalue)
           Gets or sets the value indicating whether legacy (early than AW 13.10) number format for fields is enabled or not.
com.aspose.words.net.System.Globalization.CultureInfogetPreProcessCulture()
void
setPreProcessCulture(com.aspose.words.net.System.Globalization.CultureInfovalue)
           Gets or sets the culture to preprocess field values.
IFieldResultFormattergetResultFormatter()
void
           Allows to control how the field result is formatted.
ToaCategoriesgetToaCategories()
void
           Gets or sets the table of authorities categories.
booleangetUseInvariantCultureNumberFormat()
void
           Gets or sets the value indicating that number format is parsed using invariant culture or not
IFieldUserPromptRespondentgetUserPromptRespondent()
void
           Gets or sets the respondent to user prompts during field update.
 

    • Property Getters/Setters Detail

      • getBarcodeGenerator/setBarcodeGenerator

        public IBarcodeGenerator getBarcodeGenerator() / public void setBarcodeGenerator(IBarcodeGenerator value)
        
        Gets or set custom barcode generator. Custom barcode generator should implement public interface IBarcodeGenerator.
      • getBuiltInTemplatesPaths/setBuiltInTemplatesPaths

        public java.lang.String[] getBuiltInTemplatesPaths() / public void setBuiltInTemplatesPaths(java.lang.String[] value)
        
        Gets or sets paths of MS Word built-in templates.

        This property is used by the AUTOTEXT and GLOSSARY fields, if referenced auto text entry is not found in the Document.AttachedTemplate template.

        By defalut MS Word stores built-in templates in c:\Users\<username>\AppData\Roaming\Microsoft\Document Building Blocks\1033\16\Built-In Building Blocks.dotx and C:\Users\<username>\AppData\Roaming\Microsoft\Templates\Normal.dotm files.

        Example:

        Shows how to display a building block with AUTOTEXT and GLOSSARY fields.
        Document doc = new Document();
        
        // Create a glossary document, and add an AutoText building block to it.
        doc.setGlossaryDocument(new GlossaryDocument());
        BuildingBlock buildingBlock = new BuildingBlock(doc.getGlossaryDocument());
        buildingBlock.setName("MyBlock");
        buildingBlock.setGallery(BuildingBlockGallery.AUTO_TEXT);
        buildingBlock.setCategory("General");
        buildingBlock.setDescription("MyBlock description");
        buildingBlock.setBehavior(BuildingBlockBehavior.PARAGRAPH);
        doc.getGlossaryDocument().appendChild(buildingBlock);
        
        // Create a source, and add it as text to our building block.
        Document buildingBlockSource = new Document();
        DocumentBuilder buildingBlockSourceBuilder = new DocumentBuilder(buildingBlockSource);
        buildingBlockSourceBuilder.writeln("Hello World!");
        
        Node buildingBlockContent = doc.getGlossaryDocument().importNode(buildingBlockSource.getFirstSection(), true);
        buildingBlock.appendChild(buildingBlockContent);
        
        // Set a file which contains parts that our document, or its attached template may not contain.
        doc.getFieldOptions().setBuiltInTemplatesPaths(new String[]{getMyDir() + "Busniess brochure.dotx"});
        
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // Below are two ways to use fields to display the contents of our building block.
        // 1 -  Using an AUTOTEXT field:
        FieldAutoText fieldAutoText = (FieldAutoText) builder.insertField(FieldType.FIELD_AUTO_TEXT, true);
        fieldAutoText.setEntryName("MyBlock");
        
        Assert.assertEquals(" AUTOTEXT  MyBlock", fieldAutoText.getFieldCode());
        
        // 2 -  Using a GLOSSARY field:
        FieldGlossary fieldGlossary = (FieldGlossary) builder.insertField(FieldType.FIELD_GLOSSARY, true);
        fieldGlossary.setEntryName("MyBlock");
        
        Assert.assertEquals(fieldGlossary.getFieldCode(), " GLOSSARY  MyBlock");
        
        doc.updateFields();
        doc.save(getArtifactsDir() + "Field.AUTOTEXT.GLOSSARY.dotx");
      • getCurrentUser/setCurrentUser

        public UserInformation getCurrentUser() / public void setCurrentUser(UserInformation value)
        
        Gets or sets the current user information.

        Example:

        Shows how to set user details, and display them using fields.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // Create a UserInformation object and set it as the data source for fields that display user information.
        UserInformation userInformation = new UserInformation();
        userInformation.setName("John Doe");
        userInformation.setInitials("J. D.");
        userInformation.setAddress("123 Main Street");
        doc.getFieldOptions().setCurrentUser(userInformation);
        
        // Insert USERNAME, USERINITIALS, and USERADDRESS fields, which display values of
        // the respective properties of the UserInformation object that we have created above. 
        Assert.assertEquals(userInformation.getName(), builder.insertField(" USERNAME ").getResult());
        Assert.assertEquals(userInformation.getInitials(), builder.insertField(" USERINITIALS ").getResult());
        Assert.assertEquals(userInformation.getAddress(), builder.insertField(" USERADDRESS ").getResult());
        
        // The field options object also has a static default user that fields from all documents can refer to.
        UserInformation.getDefaultUser().setName("Default User");
        UserInformation.getDefaultUser().setInitials("D. U.");
        UserInformation.getDefaultUser().setAddress("One Microsoft Way");
        doc.getFieldOptions().setCurrentUser(UserInformation.getDefaultUser());
        
        Assert.assertEquals("Default User", builder.insertField(" USERNAME ").getResult());
        Assert.assertEquals("D. U.", builder.insertField(" USERINITIALS ").getResult());
        Assert.assertEquals("One Microsoft Way", builder.insertField(" USERADDRESS ").getResult());
        
        doc.updateFields();
        doc.save(getArtifactsDir() + "FieldOptions.CurrentUser.docx");
      • getCustomTocStyleSeparator/setCustomTocStyleSeparator

        public java.lang.String getCustomTocStyleSeparator() / public void setCustomTocStyleSeparator(java.lang.String value)
        
        Gets or sets custom style separator for the \t switch in TOC field. By default, custom styles defined by the \t switch in the TOC field are separated by a delimiter taken from the current culture. This property overrides that behaviour by specifying a user defined delimiter.

        Example:

        Shows how to insert a TOC, and populate it with entries based on heading styles.
        public void fieldToc() throws Exception {
            Document doc = new Document();
            DocumentBuilder builder = new DocumentBuilder(doc);
        
            builder.startBookmark("MyBookmark");
        
            // Insert a TOC field, which will compile all headings into a table of contents.
            // For each heading, this field will create a line with the text in that heading style to the left,
            // and the page the heading appears on to the right.
            FieldToc field = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
        
            // Use the BookmarkName attribute to only list headings
            // that appear within the bounds of a bookmark with the "MyBookmark" name.
            field.setBookmarkName("MyBookmark");
        
            // Text with a built-in heading style, such as "Heading 1", applied to it will count as a heading.
            // We can name additional styles to be picked up as headings by the TOC in this attribute and their TOC levels.
            field.setCustomStyles("Quote; 6; Intense Quote; 7");
        
            // By default, Styles/TOC levels are separated in the CustomStyles attribute by a comma,
            // but we can set a custom delimiter in this attribute.
            doc.getFieldOptions().setCustomTocStyleSeparator(";");
        
            // Configure the field to exclude any headings that have TOC levels outside of this range.
            field.setHeadingLevelRange("1-3");
        
            // The TOC will not display the page numbers of headings whose TOC levels are within this range.
            field.setPageNumberOmittingLevelRange("2-5");
        
            // Set a custom string that will separate every heading from its page number. 
            field.setEntrySeparator("-");
            field.setInsertHyperlinks(true);
            field.setHideInWebLayout(false);
            field.setPreserveLineBreaks(true);
            field.setPreserveTabs(true);
            field.setUseParagraphOutlineLevel(false);
        
            insertNewPageWithHeading(builder, "First entry", "Heading 1");
            builder.writeln("Paragraph text.");
            insertNewPageWithHeading(builder, "Second entry", "Heading 1");
            insertNewPageWithHeading(builder, "Third entry", "Quote");
            insertNewPageWithHeading(builder, "Fourth entry", "Intense Quote");
        
            // These two headings will have the page numbers omitted because they are within the "2-5" range.
            insertNewPageWithHeading(builder, "Fifth entry", "Heading 2");
            insertNewPageWithHeading(builder, "Sixth entry", "Heading 3");
        
            // This entry not appear because "Heading 4" is outside of the "1-3" range that we have set earlier.
            insertNewPageWithHeading(builder, "Seventh entry", "Heading 4");
        
            builder.endBookmark("MyBookmark");
            builder.writeln("Paragraph text.");
        
            // This entry not appear because it is outside the bookmark specified by the TOC.
            insertNewPageWithHeading(builder, "Eighth entry", "Heading 1");
        
            Assert.assertEquals(" TOC  \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w", field.getFieldCode());
        
            field.updatePageNumbers();
            doc.updateFields();
            doc.save(getArtifactsDir() + "Field.TOC.docx");
        }
        
        /// <summary>
        /// Start a new page and insert a paragraph of a specified style.
        /// </summary>
        @Test(enabled = false)
        public void insertNewPageWithHeading(final DocumentBuilder builder, final String captionText, final String styleName) {
            builder.insertBreak(BreakType.PAGE_BREAK);
            String originalStyle = builder.getParagraphFormat().getStyleName();
            builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(styleName));
            builder.writeln(captionText);
            builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(originalStyle));
        }
      • getDefaultDocumentAuthor/setDefaultDocumentAuthor

        public java.lang.String getDefaultDocumentAuthor() / public void setDefaultDocumentAuthor(java.lang.String value)
        
        Gets or sets default document author's name. If author's name is already specified in built-in document properties, this option is not considered.

        Example:

        Shows how to use an AUTHOR field to display a document creator's name.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // AUTHOR fields source their results from the built-in document property called "Author".
        // If we create and save a document in Microsoft Word,
        // it will have our username in that property.
        // However, if we create a document programmatically using Aspose.Words,
        // the "Author" property, by default, will be an empty string. 
        Assert.assertEquals("", doc.getBuiltInDocumentProperties().getAuthor());
        
        // Set a backup author name for AUTHOR fields to use
        // if the "Author" property contains an empty string.
        doc.getFieldOptions().setDefaultDocumentAuthor("Joe Bloggs");
        
        builder.write("This document was created by ");
        FieldAuthor field = (FieldAuthor) builder.insertField(FieldType.FIELD_AUTHOR, true);
        field.update();
        
        Assert.assertEquals(" AUTHOR ", field.getFieldCode());
        Assert.assertEquals("Joe Bloggs", field.getResult());
        
        // Updating an AUTHOR field that contains a value
        // will apply that value to the "Author" built-in property.
        Assert.assertEquals("Joe Bloggs", doc.getBuiltInDocumentProperties().getAuthor());
        
        // Changing this property, then updating the AUTHOR field will apply this value to the field.
        doc.getBuiltInDocumentProperties().setAuthor("John Doe");
        field.update();
        
        Assert.assertEquals(" AUTHOR ", field.getFieldCode());
        Assert.assertEquals("John Doe", field.getResult());
        
        // If we give an AUTHOR field a different name again and then update it,
        // the field will apply it to the built-in property.
        field.setAuthorName("Jane Doe");
        field.update();
        
        Assert.assertEquals(field.getFieldCode(), " AUTHOR  \"Jane Doe\"");
        Assert.assertEquals(field.getResult(), "Jane Doe");
        
        // AUTHOR fields do not affect the DefaultDocumentAuthor property.
        Assert.assertEquals("Jane Doe", doc.getBuiltInDocumentProperties().getAuthor());
        Assert.assertEquals("Joe Bloggs", doc.getFieldOptions().getDefaultDocumentAuthor());
        
        doc.save(getArtifactsDir() + "Field.AUTHOR.docx");
      • getFieldIndexFormat/setFieldIndexFormat

        public int getFieldIndexFormat() / public void setFieldIndexFormat(int value)
        
        Gets or sets a FieldIndexFormat that represents the formatting for the FieldIndex fields in the document. The value of the property is FieldIndexFormat integer constant.

        Example:

        Shows how to formatting FieldIndex fields.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        builder.write("A");
        builder.insertBreak(BreakType.LINE_BREAK);
        builder.insertField("XE \"A\"");
        builder.write("B");
        
        builder.insertField(" INDEX \\e \" · \" \\h \"A\" \\c \"2\" \\z \"1033\"", null);
        
        doc.getFieldOptions().setFieldIndexFormat(FieldIndexFormat.FANCY);
        doc.updateFields();
        
        doc.save(getArtifactsDir() + "Field.SetFieldIndexFormat.docx");
      • getFieldUpdateCultureProvider/setFieldUpdateCultureProvider

        public IFieldUpdateCultureProvider getFieldUpdateCultureProvider() / public void setFieldUpdateCultureProvider(IFieldUpdateCultureProvider value)
        
        Gets or sets a provider that returns a culture object specific for each particular field.

        The provider is requested when the value of FieldUpdateCultureSource is FieldUpdateCultureSource.FieldCode.

        If the provider is present, then the culture object it returns is used for the field update. Otherwise, a system culture is used.

        Example:

        Shows how to specify a culture which parses date/time formatting for each field.
        public void defineDateTimeFormatting() throws Exception {
            Document doc = new Document();
            DocumentBuilder builder = new DocumentBuilder(doc);
        
            builder.insertField(FieldType.FIELD_TIME, true);
        
            doc.getFieldOptions().setFieldUpdateCultureSource(FieldUpdateCultureSource.FIELD_CODE);
        
            // Set a provider that returns a culture object specific to each field.
            doc.getFieldOptions().setFieldUpdateCultureProvider(new FieldUpdateCultureProvider());
        
            FieldTime fieldDate = (FieldTime) doc.getRange().getFields().get(0);
            if (fieldDate.getLocaleId() != EditingLanguage.RUSSIAN)
                fieldDate.setLocaleId(EditingLanguage.RUSSIAN);
        
            doc.save(getArtifactsDir() + "FieldOptions.UpdateDateTimeFormatting.pdf");
        }
        
        /// <summary>
        /// Provides a CultureInfo object that should be used during the update of a particular field.
        /// </summary>
        private static class FieldUpdateCultureProvider implements IFieldUpdateCultureProvider {
            /// <summary>
            /// Returns a CultureInfo object to be used during the field's update.
            /// </summary>
            public CultureInfo getCulture(String name, Field field) {
                switch (name) {
                    case "ru-RU":
                        CultureInfo culture = new CultureInfo(new Locale(name));
                        DateTimeFormatInfo format = culture.getDateTimeFormat();
        
                        format.setMonthNames(new String[]{"месяц 1", "месяц 2", "месяц 3", "месяц 4", "месяц 5", "месяц 6", "месяц 7", "месяц 8", "месяц 9", "месяц 10", "месяц 11", "месяц 12", ""});
                        format.setMonthGenitiveNames(format.getMonthNames());
                        format.setAbbreviatedMonthNames(new String[]{"мес 1", "мес 2", "мес 3", "мес 4", "мес 5", "мес 6", "мес 7", "мес 8", "мес 9", "мес 10", "мес 11", "мес 12", ""});
                        format.setAbbreviatedMonthGenitiveNames(format.getAbbreviatedMonthNames());
        
                        format.setDayNames(new String[]{"день недели 7", "день недели 1", "день недели 2", "день недели 3", "день недели 4", "день недели 5", "день недели 6"});
                        format.setAbbreviatedDayNames(new String[]{"день 7", "день 1", "день 2", "день 3", "день 4", "день 5", "день 6"});
                        format.setShortestDayNames(new String[]{"д7", "д1", "д2", "д3", "д4", "д5", "д6"});
        
                        format.setAMDesignator("До полудня");
                        format.setPMDesignator("После полудня");
        
                        final String PATTERN = "yyyy MM (MMMM) dd (dddd) hh:mm:ss tt";
                        format.setLongDatePattern(PATTERN);
                        format.setLongTimePattern(PATTERN);
                        format.setShortDatePattern(PATTERN);
                        format.setShortTimePattern(PATTERN);
        
                        return culture;
                    case "en-US":
                        return new CultureInfo(new Locale(name));
                    default:
                        return null;
                }
            }
        }
      • getFieldUpdateCultureSource/setFieldUpdateCultureSource

        public int getFieldUpdateCultureSource() / public void setFieldUpdateCultureSource(int value)
        
        Specifies what culture to use to format the field result. The value of the property is FieldUpdateCultureSource integer constant.

        By default, the culture of the current thread is used.

        The setting affects only date/time fields with \\@ format switch.

      • getFileName/setFileName

        public java.lang.String getFileName() / public void setFileName(java.lang.String value)
        
        Gets or sets the file name of the document.

        This property is used by the FILENAME field with higher priority than the Document.OriginalFileName property.

        Example:

        Shows how to use FieldOptions to override the default value for the FILENAME field.
        Document doc = new Document(getMyDir() + "Document.docx");
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        builder.moveToDocumentEnd();
        builder.writeln();
        
        // This FILENAME field will display the local system file name of the document we loaded.
        FieldFileName field = (FieldFileName) builder.insertField(FieldType.FIELD_FILE_NAME, true);
        field.update();
        
        Assert.assertEquals(" FILENAME ", field.getFieldCode());
        Assert.assertEquals("Document.docx", field.getResult());
        
        builder.writeln();
        
        // By default, the FILENAME field shows the file's name, but not its full local file system path.
        // We can set a flag to make it show the full file path.
        field = (FieldFileName) builder.insertField(FieldType.FIELD_FILE_NAME, true);
        field.setIncludeFullPath(true);
        field.update();
        
        Assert.assertEquals(getMyDir() + "Document.docx", field.getResult());
        
        // We can also set a value for this property to
        // override the value that the FILENAME field displays.
        doc.getFieldOptions().setFileName("FieldOptions.FILENAME.docx");
        field.update();
        
        Assert.assertEquals(" FILENAME  \\p", field.getFieldCode());
        Assert.assertEquals("FieldOptions.FILENAME.docx", field.getResult());
        
        doc.updateFields();
        doc.save(getArtifactsDir() + doc.getFieldOptions().getFileName());
      • isBidiTextSupportedOnUpdate/isBidiTextSupportedOnUpdate

        public boolean isBidiTextSupportedOnUpdate() / public void isBidiTextSupportedOnUpdate(boolean value)
        
        Gets or sets the value indicating whether bidirectional text is fully supported during field update or not.

        When this property is set to true, additional steps are performed to produce Right-To-Left language (i.e. Arabic or Hebrew) compatible field result during its update.

        When this property is set to false and Right-To-Left language is used, correctness of field result after its update is not guaranteed.

        The default value is false.

        Example:

        Shows how to use FieldOptions to ensure that field updating fully supports bi-directional text.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // Ensure that any field operation involving right-to-left text is performs as expected. 
        doc.getFieldOptions().isBidiTextSupportedOnUpdate(true);
        
        // Use a document builder to insert a field that contains the right-to-left text.
        FormField comboBox = builder.insertComboBox("MyComboBox", new String[]{"עֶשְׂרִים", "שְׁלוֹשִׁים", "אַרְבָּעִים", "חֲמִשִּׁים", "שִׁשִּׁים"}, 0);
        comboBox.setCalculateOnExit(true);
        
        doc.updateFields();
        doc.save(getArtifactsDir() + "FieldOptions.Bidi.docx");
      • getLegacyNumberFormat/setLegacyNumberFormat

        public boolean getLegacyNumberFormat() / public void setLegacyNumberFormat(boolean value)
        
        Gets or sets the value indicating whether legacy (early than AW 13.10) number format for fields is enabled or not.

        When this property is set to true, template symbol "#" worked as in .net: Replaces the pound sign with the corresponding digit if one is present; otherwise, no symbols appears in the result string.

        When this property is set to false, template symbol "#" works as MS Word: This format item specifies the requisite numeric places to display in the result. If the result does not include a digit in that place, MS Word displays a space. For example, { = 9 + 6 \# $### } displays $ 15.

        The default value is false.

        Example:

        Shows how enable legacy number formatting for fields.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        Field field = builder.insertField("= 2 + 3 \\# $##");
        
        Assert.assertEquals("$ 5", field.getResult());
        
        doc.getFieldOptions().setLegacyNumberFormat(true);
        field.update();
        
        Assert.assertEquals("$5", field.getResult());
      • getPreProcessCulture/setPreProcessCulture

        public com.aspose.words.net.System.Globalization.CultureInfo getPreProcessCulture() / public void setPreProcessCulture(com.aspose.words.net.System.Globalization.CultureInfo value)
        
        Gets or sets the culture to preprocess field values.

        Currently this property only affects value of the DOCPROPERTY field.

        The default value is null. When this property is set to null, the DOCPROPERTY field's value is preprocessed with the culture controlled by the FieldUpdateCultureSource property.

        Example:

        Shows how to set the preprocess culture.
        Document doc = new Document(getMyDir() + "Document.docx");
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // Set the culture according to which some fields will format their displayed values.
        doc.getFieldOptions().setPreProcessCulture(new CultureInfo("de-DE"));
        
        Field field = builder.insertField(" DOCPROPERTY CreateTime");
        
        // The DOCPROPERTY field will display its result formatted according to the preprocess culture
        // we have set to German. The field will display the date/time using the "dd.mm.yyyy hh:mm" format.
        Assert.assertTrue(field.getResult().matches("\\d{2}[.]\\d{2}[.]\\d{4} \\d{2}[:]\\d{2}"));
        
        doc.getFieldOptions().setPreProcessCulture(new CultureInfo(Locale.ROOT));
        field.update();
        
        // After switching to the invariant culture, the DOCPROPERTY field will use the "mm/dd/yyyy hh:mm" format.
        Assert.assertTrue(field.getResult().matches("\\d{2}[/]\\d{2}[/]\\d{4} \\d{2}[:]\\d{2}"));
      • getToaCategories/setToaCategories

        public ToaCategories getToaCategories() / public void setToaCategories(ToaCategories value)
        
        Gets or sets the table of authorities categories.

        Example:

        Shows how to specify a set of categories for TOA fields.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // TOA fields can filter their entries by categories defined in this collection.
        ToaCategories toaCategories = new ToaCategories();
        doc.getFieldOptions().setToaCategories(toaCategories);
        
        // This collection of categories comes with default values, which we can overwrite with custom values.
        Assert.assertEquals("Cases", toaCategories.get(1));
        Assert.assertEquals("Statutes", toaCategories.get(2));
        
        toaCategories.set(1, "My Category 1");
        toaCategories.set(2, "My Category 2");
        
        // We can always access the default values via this collection.
        Assert.assertEquals("Cases", ToaCategories.getDefaultCategories().get(1));
        Assert.assertEquals("Statutes", ToaCategories.getDefaultCategories().get(2));
        
        // Insert 2 TOA fields. TOA fields create an entry for each TA field in the document.
        // Use the "\c" switch to select the index of a category from our collection.
        //  With this switch, a TOA field will only pick up entries from TA fields that
        // also have a "\c" switch with a matching category index. Each TOA field will also display
        // the name of the category that its "\c" switch points to.
        builder.insertField("TOA \\c 1 \\h", null);
        builder.insertField("TOA \\c 2 \\h", null);
        builder.insertBreak(BreakType.PAGE_BREAK);
        
        // Insert TOA entries across 2 categories. Our first TOA field will receive one entry,
        // from the second TA field whose "\c" switch also points to the first category.
        // The second TOA field will have two entries from the other two TA fields.
        builder.insertField("TA \\c 2 \\l \"entry 1\"");
        builder.insertBreak(BreakType.PAGE_BREAK);
        builder.insertField("TA \\c 1 \\l \"entry 2\"");
        builder.insertBreak(BreakType.PAGE_BREAK);
        builder.insertField("TA \\c 2 \\l \"entry 3\"");
        
        doc.updateFields();
        doc.save(getArtifactsDir() + "FieldOptions.TOA.Categories.docx");
      • getUseInvariantCultureNumberFormat/setUseInvariantCultureNumberFormat

        public boolean getUseInvariantCultureNumberFormat() / public void setUseInvariantCultureNumberFormat(boolean value)
        
        Gets or sets the value indicating that number format is parsed using invariant culture or not

        When this property is set to true, number format is taken from an invariant culture.

        When this property is set to false, number format is taken from the current thread's culture.

        The default value is false.

        Example:

        Shows how to format numbers according to the invariant culture.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        Locale.setDefault(new Locale("de-DE"));
        Field field = builder.insertField(" = 1234567,89 \\# $#,###,###.##");
        field.update();
        
        // Sometimes, fields may not format their numbers correctly under certain cultures. 
        Assert.assertFalse(doc.getFieldOptions().getUseInvariantCultureNumberFormat());
        Assert.assertEquals("$123,456,789.  ", field.getResult());
        
        // To fix this, we could change the culture for the entire thread.
        // Another way to fix this is to set this flag,
        // which gets all fields to use the invariant culture when formatting numbers.
        // This way allows us to avoid changing the culture for the entire thread.
        doc.getFieldOptions().setUseInvariantCultureNumberFormat(true);
        field.update();
        Assert.assertEquals("$123,456,789.  ", field.getResult());
      • getUserPromptRespondent/setUserPromptRespondent

        public IFieldUserPromptRespondent getUserPromptRespondent() / public void setUserPromptRespondent(IFieldUserPromptRespondent value)
        
        Gets or sets the respondent to user prompts during field update.

        If the value of this property is set to null, the fields that require user response on prompting (such as ASK or FILLIN) are not updated.

        The default value is null.

        Example:

        Shows how to create an ASK field, and set its properties.
        @Test
        public void fieldAsk() throws Exception {
            Document doc = new Document();
            DocumentBuilder builder = new DocumentBuilder(doc);
        
            // Place a field where the response to our ASK field will be placed.
            FieldRef fieldRef = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
            fieldRef.setBookmarkName("MyAskField");
            builder.writeln();
        
            Assert.assertEquals(" REF  MyAskField", fieldRef.getFieldCode());
        
            // Insert the ASK field and edit its properties to reference our REF field by bookmark name.
            FieldAsk fieldAsk = (FieldAsk) builder.insertField(FieldType.FIELD_ASK, true);
            fieldAsk.setBookmarkName("MyAskField");
            fieldAsk.setPromptText("Please provide a response for this ASK field");
            fieldAsk.setDefaultResponse("Response from within the field.");
            fieldAsk.setPromptOnceOnMailMerge(true);
            builder.writeln();
        
            Assert.assertEquals(
                    " ASK  MyAskField \"Please provide a response for this ASK field\" \\d \"Response from within the field.\" \\o",
                    fieldAsk.getFieldCode());
        
            // ASK fields apply the default response to their respective REF fields during a mail merge.
            DataTable table = new DataTable("My Table");
            table.getColumns().add("Column 1");
            table.getRows().add("Row 1");
            table.getRows().add("Row 2");
        
            FieldMergeField fieldMergeField = (FieldMergeField) builder.insertField(FieldType.FIELD_MERGE_FIELD, true);
            fieldMergeField.setFieldName("Column 1");
        
            // We can modify or override the default response in our ASK fields with a custom prompt responder,
            // which will occur during a mail merge.
            doc.getFieldOptions().setUserPromptRespondent(new MyPromptRespondent());
            doc.getMailMerge().execute(table);
        
            doc.updateFields();
            doc.save(getArtifactsDir() + "Field.ASK.docx");
        }
        
        /// <summary>
        /// Prepends text to the default response of an ASK field during a mail merge.
        /// </summary>
        private static class MyPromptRespondent implements IFieldUserPromptRespondent {
            public String respond(final String promptText, final String defaultResponse) {
                return "Response from MyPromptRespondent. " + defaultResponse;
            }
        }