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 FieldToc 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.
IFieldUpdatingCallbackgetFieldUpdatingCallback()
void
           Gets or sets IFieldUpdatingCallback implementation
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.
java.lang.StringgetTemplateName()
void
setTemplateName(java.lang.Stringvalue)
           Gets or sets the file name of the template used by the document.
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.

        Example:

        Shows how to use a barcode generator.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // We can use a custom IBarcodeGenerator implementation to generate barcodes,
        // and then insert them into the document as images.
        doc.getFieldOptions().setBarcodeGenerator(new CustomBarcodeGenerator());
        
        // Below are four examples of different barcode types that we can create using our generator.
        // For each barcode, we specify a new set of barcode parameters, and then generate the image.
        // Afterwards, we can insert the image into the document, or save it to the local file system.
        // 1 -  QR code:
        BarcodeParameters barcodeParameters = new BarcodeParameters();
        {
            barcodeParameters.setBarcodeType("QR");
            barcodeParameters.setBarcodeValue("ABC123");
            barcodeParameters.setBackgroundColor("0xF8BD69");
            barcodeParameters.setForegroundColor("0xB5413B");
            barcodeParameters.setErrorCorrectionLevel("3");
            barcodeParameters.setScalingFactor("250");
            barcodeParameters.setSymbolHeight("1000");
            barcodeParameters.setSymbolRotation("0");
        }
        
        BufferedImage img = doc.getFieldOptions().getBarcodeGenerator().getBarcodeImage(barcodeParameters);
        ImageIO.write(img, "jpg", new File(getArtifactsDir() + "FieldOptions.BarcodeGenerator.QR.jpg"));
        
        builder.insertImage(img);
        
        // 2 -  EAN13 barcode:
        barcodeParameters = new BarcodeParameters();
        {
            barcodeParameters.setBarcodeType("EAN13");
            barcodeParameters.setBarcodeValue("501234567890");
            barcodeParameters.setDisplayText(true);
            barcodeParameters.setPosCodeStyle("CASE");
            barcodeParameters.setFixCheckDigit(true);
        }
        
        img = doc.getFieldOptions().getBarcodeGenerator().getBarcodeImage(barcodeParameters);
        ImageIO.write(img, "jpg", new File(getArtifactsDir() + "FieldOptions.BarcodeGenerator.EAN13.jpg"));
        builder.insertImage(img);
        
        // 3 -  CODE39 barcode:
        barcodeParameters = new BarcodeParameters();
        {
            barcodeParameters.setBarcodeType("CODE39");
            barcodeParameters.setBarcodeValue("12345ABCDE");
            barcodeParameters.setAddStartStopChar(true);
        }
        
        img = doc.getFieldOptions().getBarcodeGenerator().getBarcodeImage(barcodeParameters);
        ImageIO.write(img, "jpg", new File(getArtifactsDir() + "FieldOptions.BarcodeGenerator.CODE39.jpg"));
        builder.insertImage(img);
        
        // 4 -  ITF14 barcode:
        barcodeParameters = new BarcodeParameters();
        {
            barcodeParameters.setBarcodeType("ITF14");
            barcodeParameters.setBarcodeValue("09312345678907");
            barcodeParameters.setCaseCodeStyle("STD");
        }
        
        img = doc.getFieldOptions().getBarcodeGenerator().getBarcodeImage(barcodeParameters);
        ImageIO.write(img, "jpg", new File(getArtifactsDir() + "FieldOptions.BarcodeGenerator.ITF14.jpg"));
        builder.insertImage(img);
        
        doc.save(getArtifactsDir() + "FieldOptions.BarcodeGenerator.docx");
      • 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 FieldAutoText and FieldGlossary fields, if referenced auto text entry is not found in the Document.AttachedTemplate template.

        By default 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");
      • getComparisonExpressionEvaluator/setComparisonExpressionEvaluator

        public IComparisonExpressionEvaluator getComparisonExpressionEvaluator() / public void setComparisonExpressionEvaluator(IComparisonExpressionEvaluator value)
        
        Gets or sets the field comparison expressions evaluator.

        Example:

        Shows how to implement custom evaluation for the IF and COMPARE fields.
        String expectedResult) throws Exception {
            final String LEFT = "\"left expression\"";
            final String _OPERATOR = "<>";
            final String RIGHT = "\"right expression\"";
        
            DocumentBuilder builder = new DocumentBuilder();
        
            // Field codes that we use in this example:
            // 1.   " IF %s %s %s \"true argument\" \"false argument\" ".
            // 2.   " COMPARE %s %s %s ".
            Field field = builder.insertField(String.format(fieldCode, LEFT, _OPERATOR, RIGHT), null);
        
            // If the "comparisonResult" is undefined, we create "ComparisonEvaluationResult" with string, instead of bool.
            ComparisonEvaluationResult result = comparisonResult != -1
                    ? new ComparisonEvaluationResult(comparisonResult == 1)
                    : comparisonError != null ? new ComparisonEvaluationResult(comparisonError) : null;
        
            ComparisonExpressionEvaluator evaluator = new ComparisonExpressionEvaluator(result);
            builder.getDocument().getFieldOptions().setComparisonExpressionEvaluator(evaluator);
        
            builder.getDocument().updateFields();
        
            Assert.assertEquals(expectedResult, field.getResult());
            evaluator.assertInvocationsCount(1).assertInvocationArguments(0, LEFT, _OPERATOR, RIGHT);
        }
        
        @DataProvider(name = "conditionEvaluationExtensionPointDataProvider")
        public static Object[][] conditionEvaluationExtensionPointDataProvider() {
            return new Object[][]
                    {
                            {" IF %s %s %s \"true argument\" \"false argument\" ", (byte) 1, null, "true argument"},
                            {" IF %s %s %s \"true argument\" \"false argument\" ", (byte) 0, null, "false argument"},
                            {" IF %s %s %s \"true argument\" \"false argument\" ", (byte) -1, "Custom Error", "Custom Error"},
                            {" IF %s %s %s \"true argument\" \"false argument\" ", (byte) -1, null, "true argument"},
                            {" COMPARE %s %s %s ", (byte) 1, null, "1"},
                            {" COMPARE %s %s %s ", (byte) 0, null, "0"},
                            {" COMPARE %s %s %s ", (byte) -1, "Custom Error", "Custom Error"},
                            {" COMPARE %s %s %s ", (byte) -1, null, "1"},
                    };
        }
        
        /// <summary>
        /// Comparison expressions evaluation for the FieldIf and FieldCompare.
        /// </summary>
        private static class ComparisonExpressionEvaluator implements IComparisonExpressionEvaluator {
            public ComparisonExpressionEvaluator(ComparisonEvaluationResult result) {
                mResult = result;
            }
        
            public ComparisonEvaluationResult evaluate(Field field, ComparisonExpression expression) {
                mInvocations.add(new String[]
                        {
                                expression.getLeftExpression(),
                                expression.getComparisonOperator(),
                                expression.getRightExpression()
                        });
        
                return mResult;
            }
        
            public ComparisonExpressionEvaluator assertInvocationsCount(int expected) {
                Assert.assertEquals(expected, mInvocations.size());
                return this;
            }
        
            public ComparisonExpressionEvaluator assertInvocationArguments(
                    int invocationIndex,
                    String expectedLeftExpression,
                    String expectedComparisonOperator,
                    String expectedRightExpression) {
                String[] arguments = mInvocations.get(invocationIndex);
        
                Assert.assertEquals(expectedLeftExpression, arguments[0]);
                Assert.assertEquals(expectedComparisonOperator, arguments[1]);
                Assert.assertEquals(expectedRightExpression, arguments[2]);
        
                return this;
            }
        
            private final ComparisonEvaluationResult mResult;
            private final ArrayList<String[]> mInvocations = new ArrayList<>();
        }
        See Also:
        IComparisonExpressionEvaluator
      • 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 FieldToc field. By default, custom styles defined by the \t switch in the FieldToc 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.
        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 property 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 property and their TOC levels.
            field.setCustomStyles("Quote; 6; Intense Quote; 7");
        
            // By default, Styles/TOC levels are separated in the CustomStyles property by a comma,
            // but we can set a custom delimiter in this property.
            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 does 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 does 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 update an AUTHOR field after changing its "Name" property,
        // then the field will display the new name and apply the new name 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 FieldFileName 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 FieldDocProperty field.

        The default value is null. When this property is set to null, the FieldDocProperty 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}"));
      • getResultFormatter/setResultFormatter

        public IFieldResultFormatter getResultFormatter() / public void setResultFormatter(IFieldResultFormatter value)
        
        Allows to control how the field result is formatted.

        Example:

        Shows how to automatically apply a custom format to field results as the fields are updated.
        public void fieldResultFormatting() throws Exception {
            Document doc = new Document();
            DocumentBuilder builder = new DocumentBuilder(doc);
            FieldResultFormatter formatter = new FieldResultFormatter("$%d", "Date: %tb", "Item # %s:");
            doc.getFieldOptions().setResultFormatter(formatter);
        
            // Our field result formatter applies a custom format to newly created fields of three types of formats.
            // Field result formatters apply new formatting to fields as they are updated,
            // which happens as soon as we create them using this InsertField method overload.
            // 1 -  Numeric:
            builder.insertField(" = 2 + 3 \\# $###");
        
            Assert.assertEquals("$5", doc.getRange().getFields().get(0).getResult());
            Assert.assertEquals(1, formatter.countFormatInvocations(FieldResultFormatter.FormatInvocationType.NUMERIC));
        
            // 2 -  Date/time:
            builder.insertField("DATE \\@ \"d MMMM yyyy\"");
        
            Assert.assertTrue(doc.getRange().getFields().get(1).getResult().startsWith("Date: "));
            Assert.assertEquals(1, formatter.countFormatInvocations(FieldResultFormatter.FormatInvocationType.DATE_TIME));
        
            // 3 -  General:
            builder.insertField("QUOTE \"2\" \\* Ordinal");
        
            Assert.assertEquals("Item # 2:", doc.getRange().getFields().get(2).getResult());
            Assert.assertEquals(1, formatter.countFormatInvocations(FieldResultFormatter.FormatInvocationType.GENERAL));
        
            formatter.printFormatInvocations();
        }
        
        /// <summary>
        /// When fields with formatting are updated, this formatter will override their formatting
        /// with a custom format, while tracking every invocation.
        /// </summary>
        private static class FieldResultFormatter implements IFieldResultFormatter {
            public FieldResultFormatter(String numberFormat, String dateFormat, String generalFormat) {
                mNumberFormat = numberFormat;
                mDateFormat = dateFormat;
                mGeneralFormat = generalFormat;
            }
        
            public String formatNumeric(double value, String format) {
                if (mNumberFormat.isEmpty())
                    return null;
        
                String newValue = String.format(mNumberFormat, (long) value);
                mFormatInvocations.add(new FormatInvocation(FormatInvocationType.NUMERIC, value, format, newValue));
                return newValue;
            }
        
            public String formatDateTime(Date value, String format, int calendarType) {
                if (mDateFormat.isEmpty())
                    return null;
        
                String newValue = String.format(mDateFormat, value);
                mFormatInvocations.add(new FormatInvocation(FormatInvocationType.DATE_TIME, MessageFormat.format("{0} ({1})", value, calendarType), format, newValue));
                return newValue;
            }
        
            public String format(String value, int format) {
                return format((Object) value, format);
            }
        
            public String format(double value, int format) {
                return format((Object) value, format);
            }
        
            private String format(Object value, int format) {
                if (mGeneralFormat.isEmpty())
                    return null;
        
                String newValue = String.format(mGeneralFormat, new DecimalFormat("#.####").format(value));
                mFormatInvocations.add(new FormatInvocation(FormatInvocationType.GENERAL, value, GeneralFormat.toString(format), newValue));
                return newValue;
            }
        
            public int countFormatInvocations(int formatInvocationType) {
                if (formatInvocationType == FormatInvocationType.ALL)
                    return getFormatInvocations().size();
        
                return (int) IterableUtils.countMatches(getFormatInvocations(), i -> i.getFormatInvocationType() == formatInvocationType);
            }
        
            public void printFormatInvocations() {
                for (FormatInvocation f : getFormatInvocations())
                    System.out.println(MessageFormat.format("Invocation type:\t{0}\n" +
                            "\tOriginal value:\t\t{1}\n" +
                            "\tOriginal format:\t{2}\n" +
                            "\tNew value:\t\t\t{3}\n", f.getFormatInvocationType(), f.getValue(), f.getOriginalFormat(), f.getNewValue()));
            }
        
            private final String mNumberFormat;
            private final String mDateFormat;
            private final String mGeneralFormat;
        
            private ArrayList<FormatInvocation> getFormatInvocations() {
                return mFormatInvocations;
            }
        
            private final ArrayList<FormatInvocation> mFormatInvocations = new ArrayList<>();
        
            private static class FormatInvocation {
                public int getFormatInvocationType() {
                    return mFormatInvocationType;
                }
        
                private final int mFormatInvocationType;
        
                public Object getValue() {
                    return mValue;
                }
        
                private final Object mValue;
        
                public String getOriginalFormat() {
                    return mOriginalFormat;
                }
        
                private final String mOriginalFormat;
        
                public String getNewValue() {
                    return mNewValue;
                }
        
                private final String mNewValue;
        
                public FormatInvocation(int formatInvocationType, Object value, String originalFormat, String newValue) {
                    mValue = value;
                    mFormatInvocationType = formatInvocationType;
                    mOriginalFormat = originalFormat;
                    mNewValue = newValue;
                }
            }
        
            public final class FormatInvocationType {
                private FormatInvocationType() {
                }
        
                public static final int NUMERIC = 0;
                public static final int DATE_TIME = 1;
                public static final int GENERAL = 2;
                public static final int ALL = 3;
        
                public static final int length = 4;
            }
        }
      • getTemplateName/setTemplateName

        public java.lang.String getTemplateName() / public void setTemplateName(java.lang.String value)
        
        Gets or sets the file name of the template used by the document.

        This property is used by the FieldTemplate field if the Document.AttachedTemplate property is empty.

        If this property is empty, the default template file name Normal.dotm is used.

        Example:

        Shows how to use a TEMPLATE field to display the local file system location of a document's template.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // We can set a template name using by the fields. This property is used when the "doc.AttachedTemplate" is empty.
        // If this property is empty the default template file name "Normal.dotm" is used.
        doc.getFieldOptions().setTemplateName("");
        
        FieldTemplate field = (FieldTemplate) builder.insertField(FieldType.FIELD_TEMPLATE, false);
        Assert.assertEquals(field.getFieldCode(), " TEMPLATE ");
        
        builder.writeln();
        field = (FieldTemplate) builder.insertField(FieldType.FIELD_TEMPLATE, false);
        field.setIncludeFullPath(true);
        
        Assert.assertEquals(field.getFieldCode(), " TEMPLATE  \\p");
        
        doc.updateFields();
        doc.save(getArtifactsDir() + "Field.TEMPLATE.docx");
      • 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 FieldAsk or FieldFillIn) 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;
            }
        }