Aspose::Words::Fields::FieldOptions Class Referencefinal

Detailed Description

Represents options to control field handling in a document.

#include <Aspose.Words.Cpp/Fields/FieldOptions.h>

+ Inheritance diagram for Aspose::Words::Fields::FieldOptions:

Public Member Functions

const SharedPtr< IBarcodeGenerator > & get_BarcodeGenerator () const
 Gets or set custom barcode generator. More...
ArrayPtr< Stringget_BuiltInTemplatesPaths () const
 Gets or sets paths of MS Word built-in templates. More...
const SharedPtr< IComparisonExpressionEvaluator > & get_ComparisonExpressionEvaluator () const
 Gets or sets the field comparison expressions evaluator. More...
const SharedPtr< UserInformation > & get_CurrentUser () const
 Gets or sets the current user information. More...
String get_CustomTocStyleSeparator () const
 Gets or sets custom style separator for the \t switch in FieldToc field. More...
String get_DefaultDocumentAuthor () const
 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. More...
FieldIndexFormat get_FieldIndexFormat ()
 Gets or sets a FieldIndexFormat that represents the formatting for the FieldIndex fields in the document. More...
const SharedPtr< IFieldUpdateCultureProvider > & get_FieldUpdateCultureProvider () const
 Gets or sets a provider that returns a culture object specific for each particular field. More...
FieldUpdateCultureSource get_FieldUpdateCultureSource () const
 Specifies what culture to use to format the field result. More...
const SharedPtr< IFieldUpdatingCallback > & get_FieldUpdatingCallback () const
 Gets IFieldUpdatingCallback implementation. More...
String get_FileName () const
 Gets or sets the file name of the document. More...
bool get_IsBidiTextSupportedOnUpdate () const
 Gets or sets the value indicating whether bidirectional text is fully supported during field update or not. More...
bool get_LegacyNumberFormat () const
 Gets or sets the value indicating whether legacy (early than AW 13.10) number format for fields is enabled or not. More...
const SharedPtr< CultureInfo > & get_PreProcessCulture () const
 Gets or sets the culture to preprocess field values. More...
const SharedPtr< IFieldResultFormatter > & get_ResultFormatter () const
 Allows to control how the field result is formatted. More...
String get_TemplateName () const
 Gets or sets the file name of the template used by the document. More...
const SharedPtr< ToaCategories > & get_ToaCategories () const
 Gets or sets the table of authorities categories. More...
bool get_UseInvariantCultureNumberFormat () const
 Gets or sets the value indicating that number format is parsed using invariant culture or not. More...
const SharedPtr< IFieldUserPromptRespondent > & get_UserPromptRespondent () const
 Gets or sets the respondent to user prompts during field update. More...
virtual const TypeInfoGetType () const override
virtual bool Is (const TypeInfo &target) const override
void set_BarcodeGenerator (const SharedPtr< IBarcodeGenerator > &value)
 Gets or set custom barcode generator. More...
void set_BuiltInTemplatesPaths (const ArrayPtr< String > &value)
 Setter for get_BuiltInTemplatesPaths. More...
void set_ComparisonExpressionEvaluator (const SharedPtr< IComparisonExpressionEvaluator > &value)
 Setter for get_ComparisonExpressionEvaluator. More...
void set_CurrentUser (const SharedPtr< UserInformation > &value)
 Setter for get_CurrentUser. More...
void set_CustomTocStyleSeparator (const String &value)
 Setter for get_CustomTocStyleSeparator. More...
void set_DefaultDocumentAuthor (const String &value)
 Setter for get_DefaultDocumentAuthor. More...
void set_FieldIndexFormat (FieldIndexFormat value)
 Setter for get_FieldIndexFormat. More...
void set_FieldUpdateCultureProvider (const SharedPtr< IFieldUpdateCultureProvider > &value)
 Setter for get_FieldUpdateCultureProvider. More...
void set_FieldUpdateCultureSource (FieldUpdateCultureSource value)
 Setter for get_FieldUpdateCultureSource. More...
void set_FieldUpdatingCallback (const SharedPtr< IFieldUpdatingCallback > &value)
 Sets IFieldUpdatingCallback implementation. More...
void set_FileName (const String &value)
 Setter for get_FileName. More...
void set_IsBidiTextSupportedOnUpdate (bool value)
 Setter for get_IsBidiTextSupportedOnUpdate. More...
void set_LegacyNumberFormat (bool value)
 Setter for get_LegacyNumberFormat. More...
void set_PreProcessCulture (const SharedPtr< CultureInfo > &value)
 Setter for get_PreProcessCulture. More...
void set_ResultFormatter (const SharedPtr< IFieldResultFormatter > &value)
 Setter for get_ResultFormatter. More...
void set_TemplateName (const String &value)
 Setter for get_TemplateName. More...
void set_ToaCategories (const SharedPtr< ToaCategories > &value)
 Setter for get_ToaCategories. More...
void set_UseInvariantCultureNumberFormat (bool value)
 Setter for get_UseInvariantCultureNumberFormat. More...
void set_UserPromptRespondent (const SharedPtr< IFieldUserPromptRespondent > &value)
 Setter for get_UserPromptRespondent. More...

Static Public Member Functions

static const TypeInfoType ()

Member Function Documentation

◆ get_BarcodeGenerator()

const System::SharedPtr<Aspose::Words::Fields::IBarcodeGenerator>& Aspose::Words::Fields::FieldOptions::get_BarcodeGenerator ( ) const

Gets or set custom barcode generator.

◆ get_BuiltInTemplatesPaths()

System::ArrayPtr<System::String> Aspose::Words::Fields::FieldOptions::get_BuiltInTemplatesPaths ( ) const

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


Shows how to display a building block with AUTOTEXT and GLOSSARY fields.

auto doc = MakeObject<Document>();
// Create a glossary document and add an AutoText building block to it.
auto buildingBlock = MakeObject<BuildingBlock>(doc->get_GlossaryDocument());
buildingBlock->set_Description(u"MyBlock description");
// Create a source and add it as text to our building block.
auto buildingBlockSource = MakeObject<Document>();
auto buildingBlockSourceBuilder = MakeObject<DocumentBuilder>(buildingBlockSource);
buildingBlockSourceBuilder->Writeln(u"Hello World!");
SharedPtr<Node> buildingBlockContent = doc->get_GlossaryDocument()->ImportNode(buildingBlockSource->get_FirstSection(), true);
// Set a file which contains parts that our document, or its attached template may not contain.
doc->get_FieldOptions()->set_BuiltInTemplatesPaths(MakeArray<String>({MyDir + u"Busniess brochure.dotx"}));
auto builder = MakeObject<DocumentBuilder>(doc);
// Below are two ways to use fields to display the contents of our building block.
// 1 - Using an AUTOTEXT field:
auto fieldAutoText = System::DynamicCast<FieldAutoText>(builder->InsertField(FieldType::FieldAutoText, true));
ASSERT_EQ(u" AUTOTEXT MyBlock", fieldAutoText->GetFieldCode());
// 2 - Using a GLOSSARY field:
auto fieldGlossary = System::DynamicCast<FieldGlossary>(builder->InsertField(FieldType::FieldGlossary, true));
ASSERT_EQ(u" GLOSSARY MyBlock", fieldGlossary->GetFieldCode());
doc->Save(ArtifactsDir + u"Field.AUTOTEXT.GLOSSARY.dotx");

◆ get_ComparisonExpressionEvaluator()

const System::SharedPtr<Aspose::Words::Fields::IComparisonExpressionEvaluator>& Aspose::Words::Fields::FieldOptions::get_ComparisonExpressionEvaluator ( ) const

Gets or sets the field comparison expressions evaluator.

See also

Shows how to implement custom evaluation for the IF and COMPARE fields.

void ConditionEvaluationExtensionPoint(String fieldCode, int8_t comparisonResult, String comparisonError, String expectedResult)
const String left = u"\"left expression\"";
const String operator_ = u"<>";
const String right = u"\"right expression\"";
auto builder = MakeObject<DocumentBuilder>();
// Field codes that we use in this example:
// 1. " IF {0} {1} {2} \"true argument\" \"false argument\" ".
// 2. " COMPARE {0} {1} {2} ".
SharedPtr<Field> field = builder->InsertField(String::Format(fieldCode, left, operator_, right), nullptr);
// If the "comparisonResult" is undefined, we create "ComparisonEvaluationResult" with string, instead of bool.
SharedPtr<ComparisonEvaluationResult> result = comparisonResult != -1 ? MakeObject<ComparisonEvaluationResult>(comparisonResult == 1)
: comparisonError != nullptr ? MakeObject<ComparisonEvaluationResult>(comparisonError)
: nullptr;
auto evaluator = MakeObject<ExField::ComparisonExpressionEvaluator>(result);
ASSERT_EQ(expectedResult, field->get_Result());
evaluator->AssertInvocationsCount(1)->AssertInvocationArguments(0, left, operator_, right);
class ComparisonExpressionEvaluator : public IComparisonExpressionEvaluator
ComparisonExpressionEvaluator(SharedPtr<ComparisonEvaluationResult> result)
: mInvocations(MakeObject<System::Collections::Generic::List<ArrayPtr<String>>>())
mResult = result;
SharedPtr<ComparisonEvaluationResult> Evaluate(SharedPtr<Field> field, SharedPtr<ComparisonExpression> expression) override
mInvocations->Add(MakeArray<String>({expression->get_LeftExpression(), expression->get_ComparisonOperator(), expression->get_RightExpression()}));
return mResult;
SharedPtr<ExField::ComparisonExpressionEvaluator> AssertInvocationsCount(int expected)
EXPECT_EQ(expected, mInvocations->get_Count());
return System::MakeSharedPtr(this);
SharedPtr<ExField::ComparisonExpressionEvaluator> AssertInvocationArguments(int invocationIndex, String expectedLeftExpression,
String expectedComparisonOperator, String expectedRightExpression)
ArrayPtr<String> arguments = mInvocations->idx_get(invocationIndex);
EXPECT_EQ(expectedLeftExpression, arguments[0]);
EXPECT_EQ(expectedComparisonOperator, arguments[1]);
EXPECT_EQ(expectedRightExpression, arguments[2]);
return System::MakeSharedPtr(this);
virtual ~ComparisonExpressionEvaluator()
SharedPtr<ComparisonEvaluationResult> mResult;
SharedPtr<System::Collections::Generic::List<ArrayPtr<String>>> mInvocations;

◆ get_CurrentUser()

const System::SharedPtr<Aspose::Words::Fields::UserInformation>& Aspose::Words::Fields::FieldOptions::get_CurrentUser ( ) const

Gets or sets the current user information.


Shows how to set user details, and display them using fields.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Create a UserInformation object and set it as the data source for fields that display user information.
auto userInformation = MakeObject<UserInformation>();
userInformation->set_Name(u"John Doe");
userInformation->set_Initials(u"J. D.");
userInformation->set_Address(u"123 Main Street");
// Insert USERNAME, USERINITIALS, and USERADDRESS fields, which display values of
// the respective properties of the UserInformation object that we have created above.
ASSERT_EQ(userInformation->get_Name(), builder->InsertField(u" USERNAME ")->get_Result());
ASSERT_EQ(userInformation->get_Initials(), builder->InsertField(u" USERINITIALS ")->get_Result());
ASSERT_EQ(userInformation->get_Address(), builder->InsertField(u" USERADDRESS ")->get_Result());
// The field options object also has a static default user that fields from all documents can refer to.
UserInformation::get_DefaultUser()->set_Name(u"Default User");
UserInformation::get_DefaultUser()->set_Initials(u"D. U.");
UserInformation::get_DefaultUser()->set_Address(u"One Microsoft Way");
ASSERT_EQ(u"Default User", builder->InsertField(u" USERNAME ")->get_Result());
ASSERT_EQ(u"D. U.", builder->InsertField(u" USERINITIALS ")->get_Result());
ASSERT_EQ(u"One Microsoft Way", builder->InsertField(u" USERADDRESS ")->get_Result());
doc->Save(ArtifactsDir + u"FieldOptions.CurrentUser.docx");

◆ get_CustomTocStyleSeparator()

System::String Aspose::Words::Fields::FieldOptions::get_CustomTocStyleSeparator ( ) const

Gets or sets custom style separator for the \t switch in FieldToc field.


Shows how to insert a TOC, and populate it with entries based on heading styles.

void FieldToc_()
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// 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.
auto field = System::DynamicCast<FieldToc>(builder->InsertField(FieldType::FieldTOC, true));
// Use the BookmarkName property to only list headings
// that appear within the bounds of a bookmark with the "MyBookmark" name.
// 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->set_CustomStyles(u"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.
// Configure the field to exclude any headings that have TOC levels outside of this range.
// The TOC will not display the page numbers of headings whose TOC levels are within this range.
// Set a custom string that will separate every heading from its page number.
InsertNewPageWithHeading(builder, u"First entry", u"Heading 1");
builder->Writeln(u"Paragraph text.");
InsertNewPageWithHeading(builder, u"Second entry", u"Heading 1");
InsertNewPageWithHeading(builder, u"Third entry", u"Quote");
InsertNewPageWithHeading(builder, u"Fourth entry", u"Intense Quote");
// These two headings will have the page numbers omitted because they are within the "2-5" range.
InsertNewPageWithHeading(builder, u"Fifth entry", u"Heading 2");
InsertNewPageWithHeading(builder, u"Sixth entry", u"Heading 3");
// This entry does not appear because "Heading 4" is outside of the "1-3" range that we have set earlier.
InsertNewPageWithHeading(builder, u"Seventh entry", u"Heading 4");
builder->Writeln(u"Paragraph text.");
// This entry does not appear because it is outside the bookmark specified by the TOC.
InsertNewPageWithHeading(builder, u"Eighth entry", u"Heading 1");
ASSERT_EQ(u" TOC \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w", field->GetFieldCode());
doc->Save(ArtifactsDir + u"Field.TOC.docx");
void InsertNewPageWithHeading(SharedPtr<DocumentBuilder> builder, String captionText, String styleName)
String originalStyle = builder->get_ParagraphFormat()->get_StyleName();

◆ get_DefaultDocumentAuthor()

System::String Aspose::Words::Fields::FieldOptions::get_DefaultDocumentAuthor ( ) const

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.


Shows how to use an AUTHOR field to display a document creator's name.

auto doc = MakeObject<Document>();
auto builder = MakeObject<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_EQ(String::Empty, doc->get_BuiltInDocumentProperties()->get_Author());
// Set a backup author name for AUTHOR fields to use
// if the "Author" property contains an empty string.
doc->get_FieldOptions()->set_DefaultDocumentAuthor(u"Joe Bloggs");
builder->Write(u"This document was created by ");
auto field = System::DynamicCast<FieldAuthor>(builder->InsertField(FieldType::FieldAuthor, true));
ASSERT_EQ(u" AUTHOR ", field->GetFieldCode());
ASSERT_EQ(u"Joe Bloggs", field->get_Result());
// Updating an AUTHOR field that contains a value
// will apply that value to the "Author" built-in property.
ASSERT_EQ(u"Joe Bloggs", doc->get_BuiltInDocumentProperties()->get_Author());
// Changing this property, then updating the AUTHOR field will apply this value to the field.
doc->get_BuiltInDocumentProperties()->set_Author(u"John Doe");
ASSERT_EQ(u" AUTHOR ", field->GetFieldCode());
ASSERT_EQ(u"John Doe", field->get_Result());
// 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->set_AuthorName(u"Jane Doe");
ASSERT_EQ(u" AUTHOR \"Jane Doe\"", field->GetFieldCode());
ASSERT_EQ(u"Jane Doe", field->get_Result());
// AUTHOR fields do not affect the DefaultDocumentAuthor property.
ASSERT_EQ(u"Jane Doe", doc->get_BuiltInDocumentProperties()->get_Author());
ASSERT_EQ(u"Joe Bloggs", doc->get_FieldOptions()->get_DefaultDocumentAuthor());
doc->Save(ArtifactsDir + u"Field.AUTHOR.docx");

◆ get_FieldIndexFormat()

Aspose::Words::Fields::FieldIndexFormat Aspose::Words::Fields::FieldOptions::get_FieldIndexFormat ( )

Gets or sets a FieldIndexFormat that represents the formatting for the FieldIndex fields in the document.


Shows how to formatting FieldIndex fields.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->InsertField(u"XE \"A\"");
builder->InsertField(u" INDEX \\e \" · \" \\h \"A\" \\c \"2\" \\z \"1033\"", nullptr);
doc->Save(ArtifactsDir + u"Field.SetFieldIndexFormat.docx");

◆ get_FieldUpdateCultureProvider()

const System::SharedPtr<Aspose::Words::Fields::IFieldUpdateCultureProvider>& Aspose::Words::Fields::FieldOptions::get_FieldUpdateCultureProvider ( ) const

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.


Shows how to specify a culture which parses date/time formatting for each field.

void DefineDateTimeFormatting()
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->InsertField(FieldType::FieldTime, true);
// Set a provider that returns a culture object specific to each field.
auto fieldDate = System::DynamicCast<FieldTime>(doc->get_Range()->get_Fields()->idx_get(0));
if (fieldDate->get_LocaleId() != (int)EditingLanguage::Russian)
doc->Save(ArtifactsDir + u"FieldOptions.UpdateDateTimeFormatting.pdf");
class FieldUpdateCultureProvider : public IFieldUpdateCultureProvider
SharedPtr<System::Globalization::CultureInfo> GetCulture(String name, SharedPtr<Field> field) override
if (name == u"ru-RU")
auto culture = MakeObject<System::Globalization::CultureInfo>(name, false);
SharedPtr<System::Globalization::DateTimeFormatInfo> format = culture->get_DateTimeFormat();
format->set_MonthNames(MakeArray<String>({u"месяц 1", u"месяц 2", u"месяц 3", u"месяц 4", u"месяц 5", u"месяц 6", u"месяц 7", u"месяц 8",
u"месяц 9", u"месяц 10", u"месяц 11", u"месяц 12", u""}));
{u"мес 1", u"мес 2", u"мес 3", u"мес 4", u"мес 5", u"мес 6", u"мес 7", u"мес 8", u"мес 9", u"мес 10", u"мес 11", u"мес 12", u""}));
{u"день недели 7", u"день недели 1", u"день недели 2", u"день недели 3", u"день недели 4", u"день недели 5", u"день недели 6"}));
format->set_AbbreviatedDayNames(MakeArray<String>({u"день 7", u"день 1", u"день 2", u"день 3", u"день 4", u"день 5", u"день 6"}));
format->set_ShortestDayNames(MakeArray<String>({u"д7", u"д1", u"д2", u"д3", u"д4", u"д5", u"д6"}));
format->set_AMDesignator(u"До полудня");
format->set_PMDesignator(u"После полудня");
const String pattern = u"yyyy MM (MMMM) dd (dddd) hh:mm:ss tt";
return culture;
else if (name == u"en-US")
return MakeObject<System::Globalization::CultureInfo>(name, false);
return nullptr;

◆ get_FieldUpdateCultureSource()

Aspose::Words::Fields::FieldUpdateCultureSource Aspose::Words::Fields::FieldOptions::get_FieldUpdateCultureSource ( ) const

Specifies what culture to use to format the field result.

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

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

◆ get_FieldUpdatingCallback()

const System::SharedPtr<Aspose::Words::Fields::IFieldUpdatingCallback>& Aspose::Words::Fields::FieldOptions::get_FieldUpdatingCallback ( ) const

Gets IFieldUpdatingCallback implementation.

◆ get_FileName()

System::String Aspose::Words::Fields::FieldOptions::get_FileName ( ) const

Gets or sets the file name of the document.

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


Shows how to use FieldOptions to override the default value for the FILENAME field.

auto doc = MakeObject<Document>(MyDir + u"Document.docx");
auto builder = MakeObject<DocumentBuilder>(doc);
// This FILENAME field will display the local system file name of the document we loaded.
auto field = System::DynamicCast<FieldFileName>(builder->InsertField(FieldType::FieldFileName, true));
ASSERT_EQ(u" FILENAME ", field->GetFieldCode());
ASSERT_EQ(u"Document.docx", field->get_Result());
// 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 = System::DynamicCast<FieldFileName>(builder->InsertField(FieldType::FieldFileName, true));
ASSERT_EQ(MyDir + u"Document.docx", field->get_Result());
// We can also set a value for this property to
// override the value that the FILENAME field displays.
ASSERT_EQ(u" FILENAME \\p", field->GetFieldCode());
ASSERT_EQ(u"FieldOptions.FILENAME.docx", field->get_Result());
doc->Save(ArtifactsDir + doc->get_FieldOptions()->get_FileName());

◆ get_IsBidiTextSupportedOnUpdate()

bool Aspose::Words::Fields::FieldOptions::get_IsBidiTextSupportedOnUpdate ( ) const

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.


Shows how to use FieldOptions to ensure that field updating fully supports bi-directional text.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Ensure that any field operation involving right-to-left text is performs as expected.
// Use a document builder to insert a field that contains the right-to-left text.
SharedPtr<FormField> comboBox = builder->InsertComboBox(u"MyComboBox", MakeArray<String>({u"עֶשְׂרִים", u"שְׁלוֹשִׁים", u"אַרְבָּעִים", u"חֲמִשִּׁים", u"שִׁשִּׁים"}), 0);
doc->Save(ArtifactsDir + u"FieldOptions.Bidi.docx");

◆ get_LegacyNumberFormat()

bool Aspose::Words::Fields::FieldOptions::get_LegacyNumberFormat ( ) const

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.


Shows how enable legacy number formatting for fields.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Field> field = builder->InsertField(u"= 2 + 3 \\# $##");
ASSERT_EQ(u"$ 5", field->get_Result());
ASSERT_EQ(u"$5", field->get_Result());

◆ get_PreProcessCulture()

const System::SharedPtr<System::Globalization::CultureInfo>& Aspose::Words::Fields::FieldOptions::get_PreProcessCulture ( ) const

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.


Shows how to set the preprocess culture.

auto doc = MakeObject<Document>(MyDir + u"Document.docx");
auto builder = MakeObject<DocumentBuilder>(doc);
// Set the culture according to which some fields will format their displayed values.
SharedPtr<Field> field = builder->InsertField(u" 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 " hh:mm" format.
ASSERT_TRUE(System::Text::RegularExpressions::Regex::Match(field->get_Result(), u"\\d{2}[.]\\d{2}[.]\\d{4} \\d{2}[:]\\d{2}")->get_Success());
// After switching to the invariant culture, the DOCPROPERTY field will use the "mm/dd/yyyy hh:mm" format.
ASSERT_TRUE(System::Text::RegularExpressions::Regex::Match(field->get_Result(), u"\\d{2}[/]\\d{2}[/]\\d{4} \\d{2}[:]\\d{2}")->get_Success());

◆ get_ResultFormatter()

const System::SharedPtr<Aspose::Words::Fields::IFieldResultFormatter>& Aspose::Words::Fields::FieldOptions::get_ResultFormatter ( ) const

Allows to control how the field result is formatted.


Shows how to automatically apply a custom format to field results as the fields are updated.

void FieldResultFormatting_()
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
auto formatter = MakeObject<ExDocumentBuilder::FieldResultFormatter>(u"${0}", u"Date: {0}", u"Item # {0}:");
// 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(u" = 2 + 3 \\# $###");
ASSERT_EQ(u"$5", doc->get_Range()->get_Fields()->idx_get(0)->get_Result());
ASSERT_EQ(1, formatter->CountFormatInvocations(ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType::Numeric));
// 2 - Date/time:
builder->InsertField(u"DATE \\@ \"d MMMM yyyy\"");
ASSERT_TRUE(doc->get_Range()->get_Fields()->idx_get(1)->get_Result().StartsWith(u"Date: "));
ASSERT_EQ(1, formatter->CountFormatInvocations(ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType::DateTime));
// 3 - General:
builder->InsertField(u"QUOTE \"2\" \\* Ordinal");
ASSERT_EQ(u"Item # 2:", doc->get_Range()->get_Fields()->idx_get(2)->get_Result());
ASSERT_EQ(1, formatter->CountFormatInvocations(ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType::General));
class FieldResultFormatter : public IFieldResultFormatter
enum class FormatInvocationType
class FormatInvocation : public System::Object
ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType get_FormatInvocationType()
return pr_FormatInvocationType;
SharedPtr<System::Object> get_Value()
return pr_Value;
String get_OriginalFormat()
return pr_OriginalFormat;
String get_NewValue()
return pr_NewValue;
FormatInvocation(ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType formatInvocationType, SharedPtr<System::Object> value,
String originalFormat, String newValue)
: pr_FormatInvocationType(((ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType)0))
pr_Value = value;
pr_FormatInvocationType = formatInvocationType;
pr_OriginalFormat = originalFormat;
pr_NewValue = newValue;
ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType pr_FormatInvocationType;
SharedPtr<System::Object> pr_Value;
String pr_OriginalFormat;
String pr_NewValue;
FieldResultFormatter(String numberFormat, String dateFormat, String generalFormat)
: mFormatInvocations(MakeObject<System::Collections::Generic::List<SharedPtr<ExDocumentBuilder::FieldResultFormatter::FormatInvocation>>>())
mNumberFormat = numberFormat;
mDateFormat = dateFormat;
mGeneralFormat = generalFormat;
String FormatNumeric(double value, String format) override
if (String::IsNullOrEmpty(mNumberFormat))
return nullptr;
String newValue = String::Format(mNumberFormat, value);
ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType::Numeric, System::ObjectExt::Box<double>(value), format, newValue));
return newValue;
String FormatDateTime(System::DateTime value, String format, CalendarType calendarType) override
if (String::IsNullOrEmpty(mDateFormat))
return nullptr;
String newValue = String::Format(mDateFormat, value);
System::ObjectExt::Box<String>(String::Format(u"{0} ({1})", value, calendarType)), format, newValue));
return newValue;
String Format(String value, GeneralFormat format) override
return Format(System::ObjectExt::Box<String>(value), format);
String Format(double value, GeneralFormat format) override
return Format(System::ObjectExt::Box<double>(value), format);
int CountFormatInvocations(ExDocumentBuilder::FieldResultFormatter::FormatInvocationType formatInvocationType)
if (formatInvocationType == ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType::All)
return get_FormatInvocations()->get_Count();
std::function<bool(SharedPtr<FormatInvocation> f)> hasValidFormatInvocationType = [&formatInvocationType](SharedPtr<FormatInvocation> f)
return f->get_FormatInvocationType() == formatInvocationType;
return get_FormatInvocations()->LINQ_Count(hasValidFormatInvocationType);
void PrintFormatInvocations()
for (const auto& f : get_FormatInvocations())
std::cout << (String::Format(u"Invocation type:\t{0}\n", f->get_FormatInvocationType()) +
String::Format(u"\tOriginal value:\t\t{0}\n", f->get_Value()) +
String::Format(u"\tOriginal format:\t{0}\n", f->get_OriginalFormat()) +
String::Format(u"\tNew value:\t\t\t{0}\n", f->get_NewValue()))
<< std::endl;
String mNumberFormat;
String mDateFormat;
String mGeneralFormat;
SharedPtr<System::Collections::Generic::List<SharedPtr<ExDocumentBuilder::FieldResultFormatter::FormatInvocation>>> mFormatInvocations;
SharedPtr<System::Collections::Generic::List<SharedPtr<ExDocumentBuilder::FieldResultFormatter::FormatInvocation>>> get_FormatInvocations()
return mFormatInvocations;
String Format(SharedPtr<System::Object> value, GeneralFormat format)
if (String::IsNullOrEmpty(mGeneralFormat))
return nullptr;
String newValue = String::Format(mGeneralFormat, value);
ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType::General, value, System::ObjectExt::ToString(format), newValue));
return newValue;

◆ get_TemplateName()

System::String Aspose::Words::Fields::FieldOptions::get_TemplateName ( ) const

Gets or sets the file name of the template used by the document.

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

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


Shows how to use a TEMPLATE field to display the local file system location of a document's template.

auto doc = MakeObject<Document>();
auto builder = MakeObject<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.
auto field = System::DynamicCast<FieldTemplate>(builder->InsertField(FieldType::FieldTemplate, false));
ASSERT_EQ(u" TEMPLATE ", field->GetFieldCode());
field = System::DynamicCast<FieldTemplate>(builder->InsertField(FieldType::FieldTemplate, false));
ASSERT_EQ(u" TEMPLATE \\p", field->GetFieldCode());
doc->Save(ArtifactsDir + u"Field.TEMPLATE.docx");

◆ get_ToaCategories()

const System::SharedPtr<Aspose::Words::Fields::ToaCategories>& Aspose::Words::Fields::FieldOptions::get_ToaCategories ( ) const

Gets or sets the table of authorities categories.


Shows how to specify a set of categories for TOA fields.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// TOA fields can filter their entries by categories defined in this collection.
auto toaCategories = MakeObject<ToaCategories>();
// This collection of categories comes with default values, which we can overwrite with custom values.
ASSERT_EQ(u"Cases", toaCategories->idx_get(1));
ASSERT_EQ(u"Statutes", toaCategories->idx_get(2));
toaCategories->idx_set(1, u"My Category 1");
toaCategories->idx_set(2, u"My Category 2");
// We can always access the default values via this collection.
ASSERT_EQ(u"Cases", ToaCategories::get_DefaultCategories()->idx_get(1));
ASSERT_EQ(u"Statutes", ToaCategories::get_DefaultCategories()->idx_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(u"TOA \\c 1 \\h", nullptr);
builder->InsertField(u"TOA \\c 2 \\h", nullptr);
// 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(u"TA \\c 2 \\l \"entry 1\"");
builder->InsertField(u"TA \\c 1 \\l \"entry 2\"");
builder->InsertField(u"TA \\c 2 \\l \"entry 3\"");
doc->Save(ArtifactsDir + u"FieldOptions.TOA.Categories.docx");

◆ get_UseInvariantCultureNumberFormat()

bool Aspose::Words::Fields::FieldOptions::get_UseInvariantCultureNumberFormat ( ) const

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.


Shows how to format numbers according to the invariant culture.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Field> field = builder->InsertField(u" = 1234567,89 \\# $#,###,###.##");
// Sometimes, fields may not format their numbers correctly under certain cultures.
ASSERT_EQ(u"$1234567,89 . ", field->get_Result());
// 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.
ASSERT_EQ(u"$1.234.567,89", field->get_Result());

◆ get_UserPromptRespondent()

const System::SharedPtr<Aspose::Words::Fields::IFieldUserPromptRespondent>& Aspose::Words::Fields::FieldOptions::get_UserPromptRespondent ( ) const

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.

◆ GetType()

virtual const System::TypeInfo& Aspose::Words::Fields::FieldOptions::GetType ( ) const

Reimplemented from System::Object.

◆ Is()

virtual bool Aspose::Words::Fields::FieldOptions::Is ( const System::TypeInfo target) const

Reimplemented from System::Object.

◆ set_BarcodeGenerator()

void Aspose::Words::Fields::FieldOptions::set_BarcodeGenerator ( const System::SharedPtr< Aspose::Words::Fields::IBarcodeGenerator > &  value)

Gets or set custom barcode generator.

◆ set_BuiltInTemplatesPaths()

void Aspose::Words::Fields::FieldOptions::set_BuiltInTemplatesPaths ( const System::ArrayPtr< System::String > &  value)

◆ set_ComparisonExpressionEvaluator()

void Aspose::Words::Fields::FieldOptions::set_ComparisonExpressionEvaluator ( const System::SharedPtr< Aspose::Words::Fields::IComparisonExpressionEvaluator > &  value)

◆ set_CurrentUser()

void Aspose::Words::Fields::FieldOptions::set_CurrentUser ( const System::SharedPtr< Aspose::Words::Fields::UserInformation > &  value)

◆ set_CustomTocStyleSeparator()

void Aspose::Words::Fields::FieldOptions::set_CustomTocStyleSeparator ( const System::String value)

◆ set_DefaultDocumentAuthor()

void Aspose::Words::Fields::FieldOptions::set_DefaultDocumentAuthor ( const System::String value)

◆ set_FieldIndexFormat()

void Aspose::Words::Fields::FieldOptions::set_FieldIndexFormat ( Aspose::Words::Fields::FieldIndexFormat  value)

◆ set_FieldUpdateCultureProvider()

void Aspose::Words::Fields::FieldOptions::set_FieldUpdateCultureProvider ( const System::SharedPtr< Aspose::Words::Fields::IFieldUpdateCultureProvider > &  value)

◆ set_FieldUpdateCultureSource()

void Aspose::Words::Fields::FieldOptions::set_FieldUpdateCultureSource ( Aspose::Words::Fields::FieldUpdateCultureSource  value)

◆ set_FieldUpdatingCallback()

void Aspose::Words::Fields::FieldOptions::set_FieldUpdatingCallback ( const System::SharedPtr< Aspose::Words::Fields::IFieldUpdatingCallback > &  value)

Sets IFieldUpdatingCallback implementation.

◆ set_FileName()

void Aspose::Words::Fields::FieldOptions::set_FileName ( const System::String value)

◆ set_IsBidiTextSupportedOnUpdate()

void Aspose::Words::Fields::FieldOptions::set_IsBidiTextSupportedOnUpdate ( bool  value)

◆ set_LegacyNumberFormat()

void Aspose::Words::Fields::FieldOptions::set_LegacyNumberFormat ( bool  value)

◆ set_PreProcessCulture()

void Aspose::Words::Fields::FieldOptions::set_PreProcessCulture ( const System::SharedPtr< System::Globalization::CultureInfo > &  value)

◆ set_ResultFormatter()

void Aspose::Words::Fields::FieldOptions::set_ResultFormatter ( const System::SharedPtr< Aspose::Words::Fields::IFieldResultFormatter > &  value)

◆ set_TemplateName()

void Aspose::Words::Fields::FieldOptions::set_TemplateName ( const System::String value)

◆ set_ToaCategories()

void Aspose::Words::Fields::FieldOptions::set_ToaCategories ( const System::SharedPtr< Aspose::Words::Fields::ToaCategories > &  value)

◆ set_UseInvariantCultureNumberFormat()

void Aspose::Words::Fields::FieldOptions::set_UseInvariantCultureNumberFormat ( bool  value)

◆ set_UserPromptRespondent()

void Aspose::Words::Fields::FieldOptions::set_UserPromptRespondent ( const System::SharedPtr< Aspose::Words::Fields::IFieldUserPromptRespondent > &  value)

◆ Type()

static const System::TypeInfo& Aspose::Words::Fields::FieldOptions::Type ( )