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.

Example:

Shows how to specify where the locale for date formatting during field update and mail merge is chosen from.
// Set the culture used during field update to the culture used by the field.
doc.getFieldOptions().setFieldUpdateCultureSource(FieldUpdateCultureSource.FIELD_CODE);
doc.getMailMerge().execute(new String[]{"Date2"}, new Object[]{new SimpleDateFormat("yyyy/MM/DD").parse("2011/01/01")});

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.
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.
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.
System.Globalization.CultureInfogetPreProcessCulture()
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 insert a building block into a document and display it with AUTOTEXT and GLOSSARY fields.
        Document doc = new Document();
        
        // Create a glossary document and add an AutoText building block
        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 content 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);
        
        // Create an advance field using document builder
        DocumentBuilder builder = new DocumentBuilder(doc);
        FieldAutoText fieldAutoText = (FieldAutoText) builder.insertField(FieldType.FIELD_AUTO_TEXT, true);
        
        // Refer to our building block by name
        fieldAutoText.setEntryName("MyBlock");
        
        Assert.assertEquals(fieldAutoText.getFieldCode(), " AUTOTEXT  MyBlock");
        
        // Put additional templates here
        doc.getFieldOptions().setBuiltInTemplatesPaths(new String[]{getMyDir() + "Document.BusinessBrochureTemplate.dotx"});
        
        // We can also display our building block with a GLOSSARY field
        FieldGlossary fieldGlossary = (FieldGlossary) builder.insertField(FieldType.FIELD_GLOSSARY, true);
        fieldGlossary.setEntryName("MyBlock");
        
        Assert.assertEquals(fieldGlossary.getFieldCode(), " GLOSSARY  MyBlock");
        
        // The text content of our building block will be visible in the output
        doc.updateFields();
        doc.save(getArtifactsDir() + "Field.AutoText.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 with fields.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // Set user information
        UserInformation userInformation = new UserInformation();
        userInformation.setName("John Doe");
        userInformation.setInitials("J. D.");
        userInformation.setAddress("123 Main Street");
        doc.getFieldOptions().setCurrentUser(userInformation);
        
        // Insert fields that reference our user information
        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 value that fields from many 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(builder.insertField(" USERNAME ").getResult(), "Default User");
        Assert.assertEquals(builder.insertField(" USERINITIALS ").getResult(), "D. U.");
        Assert.assertEquals(builder.insertField(" USERADDRESS ").getResult(), "One Microsoft Way");
      • 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);
        
            // The table of contents we will insert will accept entries that are only within the scope of this bookmark
            builder.startBookmark("MyBookmark");
        
            // Insert a list num field using a document builder
            FieldToc fieldToc = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);
        
            // Limit possible TOC entries to only those within the bookmark we name here
            fieldToc.setBookmarkName("MyBookmark");
        
            // Normally paragraphs with a "Heading n" style will be the only ones that will be added to a TOC as entries
            // We can set this attribute to include other styles, such as "Quote" and "Intense Quote" in this case
            fieldToc.setCustomStyles("Quote; 6; Intense Quote; 7");
        
            // Styles are normally separated by a comma (",") but we can use this property to set a custom delimiter
            doc.getFieldOptions().setCustomTocStyleSeparator(";");
        
            // Filter out any headings that are outside this range
            fieldToc.setHeadingLevelRange("1-3");
        
            // Headings in this range won't display their page number in their TOC entry
            fieldToc.setPageNumberOmittingLevelRange("2-5");
        
            fieldToc.setEntrySeparator("-");
            fieldToc.setInsertHyperlinks(true);
            fieldToc.setHideInWebLayout(false);
            fieldToc.setPreserveLineBreaks(true);
            fieldToc.setPreserveTabs(true);
            fieldToc.setUseParagraphOutlineLevel(false);
        
            insertNewPageWithHeading(builder, "First entry", "Heading 1");
            builder.writeln("Paragraph text.");
            insertNewPageWithHeading(builder, "Second entry", "Heading 1");
            insertNewPageWithHeading(builder, "Third entry", "Quote");
            insertNewPageWithHeading(builder, "Fourth entry", "Intense Quote");
        
            // These two headings will have the page numbers omitted because they are within the "2-5" range
            insertNewPageWithHeading(builder, "Fifth entry", "Heading 2");
            insertNewPageWithHeading(builder, "Sixth entry", "Heading 3");
        
            // This entry will be omitted because "Heading 4" is outside of the "1-3" range we set earlier
            insertNewPageWithHeading(builder, "Seventh entry", "Heading 4");
        
            builder.endBookmark("MyBookmark");
            builder.writeln("Paragraph text.");
        
            // This entry will be omitted because it is outside the bookmark specified by the TOC
            insertNewPageWithHeading(builder, "Eighth entry", "Heading 1");
        
            Assert.assertEquals(fieldToc.getFieldCode(), " TOC  \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w");
        
            fieldToc.updatePageNumbers();
            doc.updateFields();
            doc.save(getArtifactsDir() + "Field.FieldTOC.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 display a document creator's name with an AUTHOR field.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // If we open an existing document, the document's author's full name will be displayed by the field
        // If we create a document programmatically, we need to set this attribute to the author's name so our field has something to display
        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(field.getFieldCode(), " AUTHOR ");
        Assert.assertEquals(field.getResult(), "Joe Bloggs");
        
        // If this property has a value, it will supersede the one we set above
        doc.getBuiltInDocumentProperties().setAuthor("John Doe");
        field.update();
        
        Assert.assertEquals(field.getFieldCode(), " AUTHOR ");
        Assert.assertEquals(field.getResult(), "John Doe");
        
        // Our field can also override the document's built in author name like this
        field.setAuthorName("Jane Doe");
        field.update();
        
        Assert.assertEquals(field.getFieldCode(), " AUTHOR  \"Jane Doe\"");
        Assert.assertEquals(field.getResult(), "Jane Doe");
        
        // The author name in the built in properties was changed by the field, but the default document author stays the same
        Assert.assertEquals(doc.getBuiltInDocumentProperties().getAuthor(), "Jane Doe");
        Assert.assertEquals(doc.getFieldOptions().getDefaultDocumentAuthor(), "Joe Bloggs");
        
        doc.save(getArtifactsDir() + "Field.AUTHOR.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.

      • 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.

        Example:

        Shows how to specify where the locale for date formatting during field update and mail merge is chosen from.
        // Set the culture used during field update to the culture used by the field.
        doc.getFieldOptions().setFieldUpdateCultureSource(FieldUpdateCultureSource.FIELD_CODE);
        doc.getMailMerge().execute(new String[]{"Date2"}, new Object[]{new SimpleDateFormat("yyyy/MM/DD").parse("2011/01/01")});
      • 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 file name of the document we opened
        FieldFileName field = (FieldFileName) builder.insertField(FieldType.FIELD_FILE_NAME, true);
        field.update();
        
        Assert.assertEquals(field.getFieldCode(), " FILENAME ");
        Assert.assertEquals(field.getResult(), "Document.docx");
        
        builder.writeln();
        
        // By default, the FILENAME field does not show the full path, and we can change this
        field = (FieldFileName) builder.insertField(FieldType.FIELD_FILE_NAME, true);
        field.setIncludeFullPath(true);
        
        // We can override the values displayed by our FILENAME fields by setting this attribute
        Assert.assertNull(doc.getFieldOptions().getFileName());
        doc.getFieldOptions().setFileName("Field.FileName.docx");
        field.update();
        
        Assert.assertEquals(field.getFieldCode(), " FILENAME  \\p");
        Assert.assertEquals(field.getResult(), "Field.FileName.docx");
        
        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 bi-directional text is properly supported during the field update.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // Ensure that any field operation involving right-to-left text is performed correctly
        doc.getFieldOptions().isBidiTextSupportedOnUpdate(true);
        
        // Use a document builder to insert a field which contains right-to-left text
        FormField comboBox = builder.insertComboBox("MyComboBox", new String[]{"עֶשְׂרִים", "שְׁלוֹשִׁים", "אַרְבָּעִים", "חֲמִשִּׁים", "שִׁשִּׁים"}, 0);
        comboBox.setCalculateOnExit(true);
        
        doc.updateFields();
        doc.save(getArtifactsDir() + "Field.FieldOptionsBidi.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 use FieldOptions to change the number format.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        Field field = builder.insertField("= 2 + 3 \\# $##");
        
        Assert.assertEquals(field.getResult(), "$ 5");
        
        doc.getFieldOptions().setLegacyNumberFormat(true);
        field.update();
        
        Assert.assertEquals(field.getResult(), "$5");
      • getPreProcessCulture

        public System.Globalization.CultureInfo getPreProcessCulture()
        
        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.

      • getResultFormatter/setResultFormatter

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

        Example:

        Shows how to control how the field result is formatted.
        public void insertCustomFormattingField() throws Exception {
            Document doc = new Document();
            DocumentBuilder builder = new DocumentBuilder(doc);
        
            doc.getFieldOptions().setResultFormatter(new FieldResultFormatter("${0}", "Date: {0}", "Item # {0}:"));
        
            // Insert a field with a numeric format
            builder.insertField(" = 2 + 3 \\# $###", null);
        
            // Insert a field with a date/time format
            builder.insertField("DATE \\@ \"d MMMM yyyy\"", null);
        
            // Insert a field with a general format
            builder.insertField("QUOTE \"2\" \\* Ordinal", null);
        
            // Formats will be applied and recorded by the formatter during the field update
            doc.updateFields();
            ((FieldResultFormatter) doc.getFieldOptions().getResultFormatter()).printInvocations();
        
            // Our formatter has also overridden the formats that were originally applied in the fields
            Assert.assertEquals(doc.getRange().getFields().get(0).getResult(), "$5");
            Assert.assertTrue(doc.getRange().getFields().get(1).getResult().startsWith("Date: "));
            Assert.assertEquals(doc.getRange().getFields().get(2).getResult(), "Item # 2:");
        }
        
        /// <summary>
        /// Custom IFieldResult implementation that applies formats and tracks format invocations
        /// </summary>
        private static class FieldResultFormatter implements IFieldResultFormatter {
            public FieldResultFormatter(final String numberFormat, final String dateFormat, final String generalFormat) {
                mNumberFormat = numberFormat;
                mDateFormat = dateFormat;
                mGeneralFormat = generalFormat;
            }
        
            public String formatNumeric(final double value, final String format) {
                mNumberFormatInvocations.add(new Object[]{value, format});
        
                return (mNumberFormat == null || "".equals(mNumberFormat)) ? null : MessageFormat.format(mNumberFormat, value);
            }
        
            public String formatDateTime(final Date value, final String format, final int calendarType) {
                mDateFormatInvocations.add(new Object[]{value, format, calendarType});
        
                return (mDateFormat == null || "".equals(mDateFormat)) ? null : MessageFormat.format(mDateFormat, value);
            }
        
            public String format(final String value, final int format) {
                return format((Object) value, format);
            }
        
            public String format(final double value, final int format) {
                return format((Object) value, format);
            }
        
            private String format(final Object value, final int format) {
                mGeneralFormatInvocations.add(new Object[]{value, format});
        
                return (mGeneralFormat == null || "".equals(mGeneralFormat)) ? null : MessageFormat.format(mGeneralFormat, value);
            }
        
            public void printInvocations() {
                System.out.println(MessageFormat.format("Number format invocations ({0}):", mNumberFormatInvocations.size()));
                for (Object[] s : (Iterable<Object[]>) mNumberFormatInvocations) {
                    System.out.println("\tValue: " + s[0] + ", original format: " + s[1]);
                }
        
                System.out.println(MessageFormat.format("Date format invocations ({0}):", mDateFormatInvocations.size()));
                for (Object[] s : (Iterable<Object[]>) mDateFormatInvocations) {
                    System.out.println("\tValue: " + s[0] + ", original format: " + s[1] + ", calendar type: " + s[2]);
                }
        
                System.out.println(MessageFormat.format("General format invocations ({0}):", mGeneralFormatInvocations.size()));
                for (Object[] s : (Iterable<Object[]>) mGeneralFormatInvocations) {
                    System.out.println("\tValue: " + s[0] + ", original format: " + s[1]);
                }
            }
        
            private String mNumberFormat;
            private String mDateFormat;
            private String mGeneralFormat;
        
            private ArrayList mNumberFormatInvocations = new ArrayList();
            private ArrayList mDateFormatInvocations = new ArrayList();
            private ArrayList mGeneralFormatInvocations = new ArrayList();
        
        }
      • getToaCategories/setToaCategories

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

        Example:

        Shows how to specify a table of authorities categories for a document.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // There are default category values we can use, or we can make our own like this
        ToaCategories toaCategories = new ToaCategories();
        doc.getFieldOptions().setToaCategories(toaCategories);
        
        toaCategories.set(1, "My Category 1"); // Replaces default value "Cases"
        toaCategories.set(2, "My Category 2"); // Replaces default value "Statutes"
        
        // Even if we changed the categories in the FieldOptions object, the default categories are still available here
        Assert.assertEquals(ToaCategories.getDefaultCategories().get(1), "Cases");
        Assert.assertEquals(ToaCategories.getDefaultCategories().get(2), "Statutes");
        
        // Insert 2 tables of authorities, one per category
        builder.insertField("TOA \\c 1 \\h", null);
        builder.insertField("TOA \\c 2 \\h", null);
        builder.insertBreak(BreakType.PAGE_BREAK);
        
        // Insert table of authorities entries across 2 categories
        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() + "Field.TableOfAuthorities.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 defaultLocale = Locale.getDefault();
        Locale.setDefault(new Locale("de-DE"));
        
        Field field = builder.insertField(" = 1234567,89 \\# $#,###,###.##");
        field.update();
        
        // The combination of field, number format and thread culture can sometimes produce an unsuitable result
        Assert.assertFalse(doc.getFieldOptions().getUseInvariantCultureNumberFormat());
        Assert.assertEquals(field.getResult(), "$123,456,789.  ");
        
        // We can set this attribute to avoid changing the whole thread culture just for numeric formats
        doc.getFieldOptions().setUseInvariantCultureNumberFormat(true);
        field.update();
        Assert.assertEquals(field.getResult(), "$123,456,789.  ");
        
        Locale.setDefault(defaultLocale);
      • 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();
        
            // Insert the ASK field and edit its properties, making sure to reference our REF field
            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();
        
            // 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 take place during a mail merge
            doc.getFieldOptions().setUserPromptRespondent(new MyPromptRespondent());
            doc.getMailMerge().execute(table);
        
            doc.updateFields();
            doc.save(getArtifactsDir() + "Fields.AskField.docx");
        
            Assert.assertEquals(fieldAsk.getFieldCode(),
                    " ASK  MyAskField \"Please provide a response for this ASK field\" \\d \"Response from within the field.\" \\o");
        
        }
        
        /// <summary>
        /// IFieldUserPromptRespondent implementation that appends a line 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;
            }
        }