Aspose::Words::Fields::FieldOptions Class Reference

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
SharedPtr< IBarcodeGenerator >	get_BarcodeGenerator () const
	Gets or set custom barcode generator. More...
ArrayPtr< String >	get_BuiltInTemplatesPaths () const
	Gets or sets paths of MS Word built-in templates. More...
SharedPtr< IComparisonExpressionEvaluator >	get_ComparisonExpressionEvaluator () const
	Gets or sets the field comparison expressions evaluator. More...
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 TOC 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...
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...
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...
SharedPtr< CultureInfo >	get_PreProcessCulture () const
	Gets or sets the culture to preprocess field values. More...
SharedPtr< IFieldResultFormatter >	get_ResultFormatter () const
	Allows to control how the field result is formatted. More...
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...
SharedPtr< IFieldUserPromptRespondent >	get_UserPromptRespondent () const
	Gets or sets the respondent to user prompts during field update. More...
virtual const TypeInfo &	GetType () const override
virtual bool	Is (const TypeInfo &target) const override
void	set_BarcodeGenerator (SharedPtr< IBarcodeGenerator > value)
	Gets or set custom barcode generator. More...
void	set_BuiltInTemplatesPaths (ArrayPtr< String > value)
	Setter for get_BuiltInTemplatesPaths. More...
void	set_ComparisonExpressionEvaluator (SharedPtr< IComparisonExpressionEvaluator > value)
	Setter for get_ComparisonExpressionEvaluator. More...
void	set_CurrentUser (SharedPtr< UserInformation > value)
	Setter for get_CurrentUser. More...
void	set_CustomTocStyleSeparator (String value)
	Setter for get_CustomTocStyleSeparator. More...
void	set_DefaultDocumentAuthor (String value)
	Setter for get_DefaultDocumentAuthor. More...
void	set_FieldIndexFormat (FieldIndexFormat value)
	Setter for get_FieldIndexFormat. More...
void	set_FieldUpdateCultureProvider (SharedPtr< IFieldUpdateCultureProvider > value)
	Setter for get_FieldUpdateCultureProvider. More...
void	set_FieldUpdateCultureSource (FieldUpdateCultureSource value)
	Setter for get_FieldUpdateCultureSource. More...
void	set_FileName (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 (SharedPtr< CultureInfo > value)
	Setter for get_PreProcessCulture. More...
void	set_ResultFormatter (SharedPtr< IFieldResultFormatter > value)
	Setter for get_ResultFormatter. More...
void	set_ToaCategories (SharedPtr< ToaCategories > value)
	Setter for get_ToaCategories. More...
void	set_UseInvariantCultureNumberFormat (bool value)
	Setter for get_UseInvariantCultureNumberFormat. More...
void	set_UserPromptRespondent (SharedPtr< IFieldUserPromptRespondent > value)
	Setter for get_UserPromptRespondent. More...

Static Public Member Functions
static const TypeInfo &	Type ()

Member Function Documentation

get_BarcodeGenerator()

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 AUTOTEXT and GLOSSARY fields, if referenced auto text entry is not found in the 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.

Examples

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.
doc->set_GlossaryDocument(MakeObject<GlossaryDocument>());
auto buildingBlock = MakeObject<BuildingBlock>(doc->get_GlossaryDocument());
buildingBlock->set_Name(u"MyBlock");
buildingBlock->set_Gallery(BuildingBlockGallery::AutoText);
buildingBlock->set_Category(u"General");
buildingBlock->set_Description(u"MyBlock description");
buildingBlock->set_Behavior(BuildingBlockBehavior::Paragraph);
doc->get_GlossaryDocument()->AppendChild(buildingBlock);
 
// 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);
buildingBlock->AppendChild(buildingBlockContent);
 
// 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));
fieldAutoText->set_EntryName(u"MyBlock");
 
ASSERT_EQ(u" AUTOTEXT  MyBlock", fieldAutoText->GetFieldCode());
 
// 2 -  Using a GLOSSARY field:
auto fieldGlossary = System::DynamicCast<FieldGlossary>(builder->InsertField(FieldType::FieldGlossary, true));
fieldGlossary->set_EntryName(u"MyBlock");
 
ASSERT_EQ(u" GLOSSARY  MyBlock", fieldGlossary->GetFieldCode());
 
doc->UpdateFields();
doc->Save(ArtifactsDir + u"Field.AUTOTEXT.GLOSSARY.dotx");

get_ComparisonExpressionEvaluator()

System::SharedPtr<Aspose::Words::Fields::IComparisonExpressionEvaluator> Aspose::Words::Fields::FieldOptions::get_ComparisonExpressionEvaluator

(

)

const

Gets or sets the field comparison expressions evaluator.

See also

Aspose::Words::Fields::IComparisonExpressionEvaluator

Examples

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);
    builder->get_Document()->get_FieldOptions()->set_ComparisonExpressionEvaluator(evaluator);
 
    builder->get_Document()->UpdateFields();
 
    ASSERT_EQ(expectedResult, field->get_Result());
    evaluator->AssertInvocationsCount(1)->AssertInvocationArguments(0, left, operator_, right);
}
 
class ComparisonExpressionEvaluator : public IComparisonExpressionEvaluator
{
public:
    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);
    }
 
protected:
    virtual ~ComparisonExpressionEvaluator()
    {
    }
 
private:
    SharedPtr<ComparisonEvaluationResult> mResult;
    SharedPtr<System::Collections::Generic::List<ArrayPtr<String>>> mInvocations;
};

get_CurrentUser()

System::SharedPtr<Aspose::Words::Fields::UserInformation> Aspose::Words::Fields::FieldOptions::get_CurrentUser

(

)

const

Gets or sets the current user information.

Examples

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");
doc->get_FieldOptions()->set_CurrentUser(userInformation);
 
// 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");
doc->get_FieldOptions()->set_CurrentUser(UserInformation::get_DefaultUser());
 
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->UpdateFields();
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 TOC field.

Examples

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);
 
    builder->StartBookmark(u"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.
    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.
    field->set_BookmarkName(u"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->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.
    doc->get_FieldOptions()->set_CustomTocStyleSeparator(u";");
 
    // Configure the field to exclude any headings that have TOC levels outside of this range.
    field->set_HeadingLevelRange(u"1-3");
 
    // The TOC will not display the page numbers of headings whose TOC levels are within this range.
    field->set_PageNumberOmittingLevelRange(u"2-5");
 
    // Set a custom string that will separate every heading from its page number.
    field->set_EntrySeparator(u"-");
    field->set_InsertHyperlinks(true);
    field->set_HideInWebLayout(false);
    field->set_PreserveLineBreaks(true);
    field->set_PreserveTabs(true);
    field->set_UseParagraphOutlineLevel(false);
 
    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->EndBookmark(u"MyBookmark");
    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());
 
    field->UpdatePageNumbers();
    doc->UpdateFields();
    doc->Save(ArtifactsDir + u"Field.TOC.docx");
}
 
void InsertNewPageWithHeading(SharedPtr<DocumentBuilder> builder, String captionText, String styleName)
{
    builder->InsertBreak(BreakType::PageBreak);
    String originalStyle = builder->get_ParagraphFormat()->get_StyleName();
    builder->get_ParagraphFormat()->set_Style(builder->get_Document()->get_Styles()->idx_get(styleName));
    builder->Writeln(captionText);
    builder->get_ParagraphFormat()->set_Style(builder->get_Document()->get_Styles()->idx_get(originalStyle));
}

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.

Examples

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));
field->Update();
 
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");
field->Update();
 
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");
field->Update();
 
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.

Examples

Shows how to formatting FieldIndex fields.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->Write(u"A");
builder->InsertBreak(BreakType::LineBreak);
builder->InsertField(u"XE \"A\"");
builder->Write(u"B");
 
builder->InsertField(u" INDEX \\e \" · \" \\h \"A\" \\c \"2\" \\z \"1033\"", nullptr);
 
doc->get_FieldOptions()->set_FieldIndexFormat(FieldIndexFormat::Fancy);
doc->UpdateFields();
 
doc->Save(ArtifactsDir + u"Field.SetFieldIndexFormat.docx");

get_FieldUpdateCultureProvider()

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.

Examples

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);
 
    doc->get_FieldOptions()->set_FieldUpdateCultureSource(FieldUpdateCultureSource::FieldCode);
 
    // Set a provider that returns a culture object specific to each field.
    doc->get_FieldOptions()->set_FieldUpdateCultureProvider(MakeObject<ExFieldOptions::FieldUpdateCultureProvider>());
 
    auto fieldDate = System::DynamicCast<FieldTime>(doc->get_Range()->get_Fields()->idx_get(0));
    if (fieldDate->get_LocaleId() != (int)EditingLanguage::Russian)
    {
        fieldDate->set_LocaleId((int)EditingLanguage::Russian);
    }
 
    doc->Save(ArtifactsDir + u"FieldOptions.UpdateDateTimeFormatting.pdf");
}
 
class FieldUpdateCultureProvider : public IFieldUpdateCultureProvider
{
public:
    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""}));
            format->set_MonthGenitiveNames(format->get_MonthNames());
            format->set_AbbreviatedMonthNames(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""}));
            format->set_AbbreviatedMonthGenitiveNames(format->get_AbbreviatedMonthNames());
            format->set_DayNames(MakeArray<String>(
                {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";
            format->set_LongDatePattern(pattern);
            format->set_LongTimePattern(pattern);
            format->set_ShortDatePattern(pattern);
            format->set_ShortTimePattern(pattern);
            return culture;
        }
        else if (name == u"en-US")
        {
            return MakeObject<System::Globalization::CultureInfo>(name, false);
        }
        else
        {
            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_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 FILENAME field with higher priority than the OriginalFileName property.

Examples

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);
 
builder->MoveToDocumentEnd();
builder->Writeln();
 
// 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));
field->Update();
 
ASSERT_EQ(u" FILENAME ", field->GetFieldCode());
ASSERT_EQ(u"Document.docx", field->get_Result());
 
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 = System::DynamicCast<FieldFileName>(builder->InsertField(FieldType::FieldFileName, true));
field->set_IncludeFullPath(true);
field->Update();
 
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.
doc->get_FieldOptions()->set_FileName(u"FieldOptions.FILENAME.docx");
field->Update();
 
ASSERT_EQ(u" FILENAME  \\p", field->GetFieldCode());
ASSERT_EQ(u"FieldOptions.FILENAME.docx", field->get_Result());
 
doc->UpdateFields();
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.

Examples

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.
doc->get_FieldOptions()->set_IsBidiTextSupportedOnUpdate(true);
 
// 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);
comboBox->set_CalculateOnExit(true);
 
doc->UpdateFields();
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.

Examples

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());
 
doc->get_FieldOptions()->set_LegacyNumberFormat(true);
field->Update();
 
ASSERT_EQ(u"$5", field->get_Result());

get_PreProcessCulture()

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

Examples

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.
doc->get_FieldOptions()->set_PreProcessCulture(MakeObject<System::Globalization::CultureInfo>(u"de-DE"));
 
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 "dd.mm.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());
 
doc->get_FieldOptions()->set_PreProcessCulture(System::Globalization::CultureInfo::get_InvariantCulture());
field->Update();
 
// 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()

System::SharedPtr<Aspose::Words::Fields::IFieldResultFormatter> Aspose::Words::Fields::FieldOptions::get_ResultFormatter

(

)

const

Allows to control how the field result is formatted.

Examples

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}:");
    doc->get_FieldOptions()->set_ResultFormatter(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(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));
 
    formatter->PrintFormatInvocations();
}
 
class FieldResultFormatter : public IFieldResultFormatter
{
public:
    enum class FormatInvocationType
    {
        Numeric,
        DateTime,
        General,
        All
    };
 
private:
    class FormatInvocation : public System::Object
    {
    public:
        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;
        }
 
    private:
        ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType pr_FormatInvocationType;
        SharedPtr<System::Object> pr_Value;
        String pr_OriginalFormat;
        String pr_NewValue;
    };
 
public:
    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);
        get_FormatInvocations()->Add(MakeObject<ExDocumentBuilder::FieldResultFormatter::FormatInvocation>(
            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);
        get_FormatInvocations()->Add(MakeObject<ExDocumentBuilder::FieldResultFormatter::FormatInvocation>(
            ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType::DateTime,
            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;
        }
    }
 
private:
    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);
        get_FormatInvocations()->Add(MakeObject<ExDocumentBuilder::FieldResultFormatter::FormatInvocation>(
            ApiExamples::ExDocumentBuilder::FieldResultFormatter::FormatInvocationType::General, value, System::ObjectExt::ToString(format), newValue));
        return newValue;
    }
};

get_ToaCategories()

System::SharedPtr<Aspose::Words::Fields::ToaCategories> Aspose::Words::Fields::FieldOptions::get_ToaCategories

(

)

const

Gets or sets the table of authorities categories.

Examples

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>();
doc->get_FieldOptions()->set_ToaCategories(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);
builder->InsertBreak(BreakType::PageBreak);
 
// 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->InsertBreak(BreakType::PageBreak);
builder->InsertField(u"TA \\c 1 \\l \"entry 2\"");
builder->InsertBreak(BreakType::PageBreak);
builder->InsertField(u"TA \\c 2 \\l \"entry 3\"");
 
doc->UpdateFields();
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.

Examples

Shows how to format numbers according to the invariant culture.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
System::Threading::Thread::get_CurrentThread()->set_CurrentCulture(MakeObject<System::Globalization::CultureInfo>(u"de-DE"));
SharedPtr<Field> field = builder->InsertField(u" = 1234567,89 \\# $#,###,###.##");
field->Update();
 
// Sometimes, fields may not format their numbers correctly under certain cultures.
ASSERT_FALSE(doc->get_FieldOptions()->get_UseInvariantCultureNumberFormat());
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.
doc->get_FieldOptions()->set_UseInvariantCultureNumberFormat(true);
field->Update();
ASSERT_EQ(u"$1.234.567,89", field->get_Result());

get_UserPromptRespondent()

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 ASK or FILLIN) are not updated.

The default value is null.

GetType()

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

overridevirtual

Reimplemented from System::Object.

Is()

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

overridevirtual

Reimplemented from System::Object.

set_BarcodeGenerator()

void Aspose::Words::Fields::FieldOptions::set_BarcodeGenerator

(

System::SharedPtr< Aspose::Words::Fields::IBarcodeGenerator >

value

)

Gets or set custom barcode generator.

set_BuiltInTemplatesPaths()

void Aspose::Words::Fields::FieldOptions::set_BuiltInTemplatesPaths

(

System::ArrayPtr< System::String >

value

)

Setter for Aspose::Words::Fields::FieldOptions::get_BuiltInTemplatesPaths.

set_ComparisonExpressionEvaluator()

void Aspose::Words::Fields::FieldOptions::set_ComparisonExpressionEvaluator

(

System::SharedPtr< Aspose::Words::Fields::IComparisonExpressionEvaluator >

value

)

Setter for Aspose::Words::Fields::FieldOptions::get_ComparisonExpressionEvaluator.

set_CurrentUser()

void Aspose::Words::Fields::FieldOptions::set_CurrentUser

(

System::SharedPtr< Aspose::Words::Fields::UserInformation >

value

)

Setter for Aspose::Words::Fields::FieldOptions::get_CurrentUser.

set_CustomTocStyleSeparator()

void Aspose::Words::Fields::FieldOptions::set_CustomTocStyleSeparator

(

System::String

value

)

Setter for Aspose::Words::Fields::FieldOptions::get_CustomTocStyleSeparator.

set_DefaultDocumentAuthor()

void Aspose::Words::Fields::FieldOptions::set_DefaultDocumentAuthor

(

System::String

value

)

Setter for Aspose::Words::Fields::FieldOptions::get_DefaultDocumentAuthor.

set_FieldIndexFormat()

void Aspose::Words::Fields::FieldOptions::set_FieldIndexFormat

(

Aspose::Words::Fields::FieldIndexFormat

value

)

Setter for Aspose::Words::Fields::FieldOptions::get_FieldIndexFormat.

set_FieldUpdateCultureProvider()

void Aspose::Words::Fields::FieldOptions::set_FieldUpdateCultureProvider

(

System::SharedPtr< Aspose::Words::Fields::IFieldUpdateCultureProvider >

value

)

Setter for Aspose::Words::Fields::FieldOptions::get_FieldUpdateCultureProvider.

set_FieldUpdateCultureSource()

void Aspose::Words::Fields::FieldOptions::set_FieldUpdateCultureSource

(

Aspose::Words::Fields::FieldUpdateCultureSource

value

)

Setter for Aspose::Words::Fields::FieldOptions::get_FieldUpdateCultureSource.

set_FileName()

void Aspose::Words::Fields::FieldOptions::set_FileName

(

System::String

value

)

Setter for Aspose::Words::Fields::FieldOptions::get_FileName.

set_IsBidiTextSupportedOnUpdate()

void Aspose::Words::Fields::FieldOptions::set_IsBidiTextSupportedOnUpdate

(

bool

value

)

Setter for Aspose::Words::Fields::FieldOptions::get_IsBidiTextSupportedOnUpdate.

set_LegacyNumberFormat()

void Aspose::Words::Fields::FieldOptions::set_LegacyNumberFormat

(

bool

value

)

Setter for Aspose::Words::Fields::FieldOptions::get_LegacyNumberFormat.

set_PreProcessCulture()

void Aspose::Words::Fields::FieldOptions::set_PreProcessCulture

(

System::SharedPtr< System::Globalization::CultureInfo >

value

)

Setter for Aspose::Words::Fields::FieldOptions::get_PreProcessCulture.

set_ResultFormatter()

void Aspose::Words::Fields::FieldOptions::set_ResultFormatter

(

System::SharedPtr< Aspose::Words::Fields::IFieldResultFormatter >

value

)

Setter for Aspose::Words::Fields::FieldOptions::get_ResultFormatter.

set_ToaCategories()

void Aspose::Words::Fields::FieldOptions::set_ToaCategories

(

System::SharedPtr< Aspose::Words::Fields::ToaCategories >

value

)

Setter for Aspose::Words::Fields::FieldOptions::get_ToaCategories.

set_UseInvariantCultureNumberFormat()

void Aspose::Words::Fields::FieldOptions::set_UseInvariantCultureNumberFormat

(

bool

value

)

Setter for Aspose::Words::Fields::FieldOptions::get_UseInvariantCultureNumberFormat.

set_UserPromptRespondent()

void Aspose::Words::Fields::FieldOptions::set_UserPromptRespondent

(

System::SharedPtr< Aspose::Words::Fields::IFieldUserPromptRespondent >

value

)

Setter for Aspose::Words::Fields::FieldOptions::get_UserPromptRespondent.

Type()

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

static